Skip to content

Commit

Permalink
docs: 📝 first paragraph isn't relevant, plus reformatted the Markdown
Browse files Browse the repository at this point in the history 
Closes #134
  • Loading branch information
@lwjohnst86
lwjohnst86 committed Oct 4, 2024
1 parent 92cefbd commit c70c070
Show file tree
Hide file tree
Showing 2 changed files with 78 additions and 87 deletions.
124 changes: 61 additions & 63 deletions README.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,42 +13,42 @@ knitr::opts_chunk$set(
)
```

# Project creation with prodigenr: A component of reproducible and open scientific projects <img src="man/figures/logo.png" style='text-align: right;' />
# Project creation with prodigenr: A component of reproducible and open scientific projects <img src="man/figures/logo.png" style="text-align: right;"/>

<!-- badges: start -->
[![CRAN Status Badge](http://www.r-pkg.org/badges/version/prodigenr)](https://cran.r-project.org/package=prodigenr)

[![CRAN Status
Badge](http://www.r-pkg.org/badges/version/prodigenr)](https://cran.r-project.org/package=prodigenr)
[![R-CMD-check](https://github.com/rostools/prodigenr/workflows/R-CMD-check/badge.svg)](https://github.com/rostools/prodigenr/actions)
[![lifecycle](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://lifecycle.r-lib.org/articles/stages.html)
[![CRAN RStudio mirror downloads](http://cranlogs.r-pkg.org/badges/prodigenr)](https://www.r-pkg.org:443/pkg/prodigenr)
[![CRAN RStudio mirror
downloads](http://cranlogs.r-pkg.org/badges/prodigenr)](https://www.r-pkg.org:443/pkg/prodigenr)

<!-- badges: end -->

This [R] package is part of a [series][rostools-github] of (planned) packages that are aimed at
creating a toolkit for doing reproducible and open science. Many researchers
(especially in biomedicine, medicine, or health, which is my area of research)
have little to no knowledge on what open science is or what reproducibility is,
let alone how to do it. Our goal is create an [(opinionated) toolkit][rostools-manifesto] to automate
and simplify the process of doing open and reproducible science.

This package has a simple aim of being a *pro*ject *di*rectory *gen*erato*r*
(prodigenr), with a simple focus on:

1. Creating a standardized project folder structure with a few template files
needed for beginning a data analysis project
2. Following a "one project, one (main) output" principle, such as a
report/manuscript in the case of scientific output or a book or website for things
like courses or workshops
3. Adhering to established best practices that make it easier for the project to
be reproducible and open

This standardized approach to how a scientific project is structured helps ensure
that the final code and documents are fairly modular, self-contained, easy to share
and make public, and be as reproducible as possible. The structure also
makes use of the existing and established applications and workflows ([RStudio],
[devtools], and [usethis]).
This package has a simple aim of being a *pro*ject *di*rectory
*gen*erato*r* (prodigenr), with a simple focus on:

1. Creating a standardized project folder structure with a few template
files needed for beginning a data analysis project.
2. Following a "one project, one (main) output" principle, such as a
report/manuscript in the case of scientific output or a book or
website for things like courses or workshops.
3. Adhering to established best practices that make it easier for the
project to be reproducible and open.

This standardized approach to how a scientific project is structured
helps ensure that the final code and documents are fairly modular,
self-contained, easy to share and make public, and be as reproducible as
possible. The structure also makes use of the existing and established
applications and workflows ([RStudio](https://www.rstudio.com/),
[devtools](https://CRAN.R-project.org/package=devtools), and
[usethis](https://CRAN.R-project.org/package=usethis)).

## Installation

You can install the released version of prodigenr from [CRAN] with:
You can install the released version of prodigenr from
[CRAN](https://cran.r-project.org) with:

``` r
install.packages("prodigenr")
Expand All @@ -57,38 +57,40 @@ install.packages("prodigenr")
And the development version from [GitHub](https://github.com/) with:

``` r
# install.packages("remotes")
remotes::install_github("rostools/prodigenr")
# install.packages("pak")
pak::pak("rostools/prodigenr")
```

## Usage

There are two ways of creating a new project: using the R console or using the
RStudio "New Project" menu option.
There are two ways of creating a new project: using the R console or
using the RStudio "New Project" menu option.

Through the console, use the `setup_project()` command. So, for instance, if you
want a manuscript project, type out:
Through the console, use the `setup_project()` command. So, for
instance, if you want a manuscript project, type out:

``` r
library(prodigenr)
setup_project("~/Desktop/DiseaseDiet")
```

This then creates a directory tree, with template files for starting
your analysis! Open the newly created project via the `.Rproj` file. For the
RStudio approach, go to "File -> New Project", then "New directory" and find the
prodigenr project in the list:
your analysis! Open the newly created project via the `.Rproj` file. For
the RStudio approach, go to "File -\> New Project", then "New directory"
and find the prodigenr project in the list:

![Creating a prodigenr project in RStudio](man/figures/rstudio-projects.gif)
![Creating a prodigenr project in
RStudio](man/figures/rstudio-projects.gif)

Once in the project, you can add a manuscript R Markdown file using:
Once in the project, you can add a manuscript/report
[Quarto](https://quarto.org/) file using:

``` r
create_manuscript()
create_report()
```

The main secondary function is the `template_list` command, which lists the
available template files (submit a PR if you want another template included!):
The main secondary function is the `template_list` command, which lists
the available template files:

```{r, include=FALSE}
library(prodigenr)
Expand All @@ -98,39 +100,35 @@ library(prodigenr)
template_list
```

<!-- TODO: Add gif for using RStudio "new file" -->

For a more detailed tutorial, see the introduction vignette:

```r
``` r
vignette('prodigenr', 'prodigenr')
```

## Related packages or projects

There are several existing packages for creating projects, each of which has
it's own pros and cons. Check out the last section of the `vignette("prodigenr")`
for more details. Try them out and see which you like!
There are several existing packages for creating projects, each of which
has it's own pros and cons. Check out the last section of the
`vignette("prodigenr")` for more details. Try them out and see which you
like!

prodigenr tries to use ideas from R packages/[devtools] while still being as simple
as possible and to be more specific to academic researchers primarily in
biomedical/non-computer science fields. However, it can always improve! I
welcome any suggestions, just submit a
prodigenr tries to use ideas from R
packages/[devtools](https://CRAN.R-project.org/package=devtools) while
still being as simple as possible and to be more specific to academic
researchers primarily in biomedical/non-computer science fields.
However, it can always improve! I welcome any suggestions, just submit a
[GitHub issue](https://github.com/rostools/prodigenr/issues).

## Interested in contributing?

See the [contributing documentation](https://rostools.github.io/prodigenr/CONTRIBUTING.html) for information on how to
contribute. Please note that this project is released with a
[Contributor Code of Conduct](https://rostools.github.io/prodigenr/CODE_OF_CONDUCT.html). By participating in this project you
agree to abide by its terms.
See the [contributing
documentation](https://rostools.github.io/prodigenr/CONTRIBUTING.html)
for information on how to contribute. Please note that this project is
released with a [Contributor Code of
Conduct](https://rostools.github.io/prodigenr/CODE_OF_CONDUCT.html). By
participating in this project you agree to abide by its terms.

[R]: https://cran.r-project.org
[RStudio]: https://www.rstudio.com/
[devtools]: https://CRAN.R-project.org/package=devtools
[usethis]: https://CRAN.R-project.org/package=usethis
[CRAN]: https://cran.r-project.org
[rostools-github]: https://github.com/rostools
[rostools-manifesto]: https://rostools.gitlab.io/manifesto
Special thanks to [\@zsemnani](https://twitter.com/zsemnani?lang=en) for
creating the logo!

Special thanks to [@zsemnani](https://twitter.com/zsemnani?lang=en) for creating the logo!
41 changes: 17 additions & 24 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@

<!-- README.md is generated from README.Rmd. Please edit that file -->

# Project creation with prodigenr: A component of reproducible and open scientific projects <img src="man/figures/logo.png" style='text-align: right;' />
# Project creation with prodigenr: A component of reproducible and open scientific projects <img src="man/figures/logo.png" style="text-align: right;"/>

<!-- badges: start -->

Expand All @@ -11,28 +11,19 @@ Badge](http://www.r-pkg.org/badges/version/prodigenr)](https://cran.r-project.or
[![lifecycle](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://lifecycle.r-lib.org/articles/stages.html)
[![CRAN RStudio mirror
downloads](http://cranlogs.r-pkg.org/badges/prodigenr)](https://www.r-pkg.org:443/pkg/prodigenr)
<!-- badges: end -->

This [R](https://cran.r-project.org) package is part of a
[series](https://github.com/rostools) of (planned) packages that are
aimed at creating a toolkit for doing reproducible and open science.
Many researchers (especially in biomedicine, medicine, or health, which
is my area of research) have little to no knowledge on what open science
is or what reproducibility is, let alone how to do it. Our goal is
create an [(opinionated) toolkit](https://rostools.gitlab.io/manifesto)
to automate and simplify the process of doing open and reproducible
science.
<!-- badges: end -->

This package has a simple aim of being a *pro*ject *di*rectory
*gen*erato*r* (prodigenr), with a simple focus on:

1. Creating a standardized project folder structure with a few template
files needed for beginning a data analysis project
files needed for beginning a data analysis project.
2. Following a “one project, one (main) output” principle, such as a
report/manuscript in the case of scientific output or a book or
website for things like courses or workshops
website for things like courses or workshops.
3. Adhering to established best practices that make it easier for the
project to be reproducible and open
project to be reproducible and open.

This standardized approach to how a scientific project is structured
helps ensure that the final code and documents are fairly modular,
Expand All @@ -54,8 +45,8 @@ install.packages("prodigenr")
And the development version from [GitHub](https://github.com/) with:

``` r
# install.packages("remotes")
remotes::install_github("rostools/prodigenr")
# install.packages("pak")
pak::pak("rostools/prodigenr")
```

## Usage
Expand All @@ -76,26 +67,28 @@ your analysis! Open the newly created project via the `.Rproj` file. For
the RStudio approach, go to “File -\> New Project”, then “New directory”
and find the prodigenr project in the list:

![Creating a prodigenr project in
RStudio](man/figures/rstudio-projects.gif)
<figure>
<img src="man/figures/rstudio-projects.gif"
alt="Creating a prodigenr project in RStudio" />
<figcaption aria-hidden="true">Creating a prodigenr project in
RStudio</figcaption>
</figure>

Once in the project, you can add a manuscript R Markdown file using:
Once in the project, you can add a manuscript/report
[Quarto](https://quarto.org/) file using:

``` r
create_manuscript()
create_report()
```

The main secondary function is the `template_list` command, which lists
the available template files (submit a PR if you want another template
included!):
the available template files:

``` r
template_list
#> [1] "report" "slides"
```

<!-- TODO: Add gif for using RStudio "new file" -->

For a more detailed tutorial, see the introduction vignette:

``` r
Expand Down

0 comments on commit c70c070

Please sign in to comment.