Share your R work following good dev practices from a single notebook

· 1178 words. · 6 minute read.
r-scripts · packages
rstats · fusen · development

You write R scripts and you would like to share them with other users, in a sustainable and maintainable way. You already write your code in a notebook (Rmarkdown or Quarto) and share its HTML output. You would like to document the chunks, and make this documentation visible in a separate HTML page. Writing a R package seems to be overkill and you would like to experiment good practices for an alternative. Let me show you how {fusen} can help present and share R work following good development practices like doc and test, while starting from a unique place that you already know: the Rmarkdown (or Quarto) notebook.

A fully documented and tested R project, from a notebook to a website in five steps

In the next section, you’ll see the five steps to prepare your project and write your notebook following the template here…

…to create this website there

Create your scripts with {fusen} and share them on a GitHub website

You’ll need to install {fusen} from r-universe
You could also install it from CRAN but one of the functionality below is not included on CRAN yet

install.packages("fusen", repos = 'https://thinkr-open.r-universe.dev')

1. Create a new project locally

  • Create a new project with {fusen} using git

    • Use template = "full" if you want explanations on how to fill the sections, or explore {fusen} documentation there: https://thinkr-open.github.io/fusen. Otherwise, template = "minimal" should be enough.
    path_project <- "your/path/where/to/start/your/project/project_name"
fusen::create_fusen(path = path_project, template = "minimal", with_git = TRUE, open = TRUE)

2. Describe your project

  • Follow the “dev/0-dev_history.Rmd” to describe your project

    • At least, you will have to fill the fusen::fill_description() function with your identity as below
    # Describe your project
fusen::fill_description(
  pkg = here::here(),
  fields = list(
    Title = "Share Your Project Following Good Development Practices From a Rmarkdown File",
    Description = "Use Rmarkdown First method. Strengthen your work with documentation and tests. Everything can be set from a Rmarkdown file in your project.",
    `Authors@R` = c(
      person("John", "Doe", email = "john@email.me", role = c("aut", "cre"), comment = c(ORCID = "0000-0000-0000-0000"))
    )
  )
)
# Define License with use_*_license()
usethis::use_mit_license("John Doe")

3. Write your notebook following the skeleton

The first time, you can let the content as is.

  • Open the “dev/flat_full.Rmd”

    • This is the skeleton to follow if you want a properly documented and tested work
      • Write what the code is supposed to do in plain markdown
      • Separate the function from the example and test chunks
      • Create new sections below in your flat template with the Addin > add {fusen} chunk

4. Inflate the notebook with {fusen}

  • inflate() the flat template to build the proper structure of the project

    • Sections will be transferred in the correct places to get a proper project
    • A set of checks will be run to verify that your work is properly documented and tested
    fusen::inflate(flat_file = "dev/flat_full.Rmd", vignette_name = "Get started")

5. Share your work on a GitHub website

This is only available on the development version of {fusen} for now

  • You may need to run usethis::create_github_token(), then gitcreds::gitcreds_set() before, if you do not have a registered GitHub token yet.

  • Run fusen::init_share_on_github() to create everything needed to set up your website on GitHub. You will be asked multiple times if you want to commit, you can say “yes” each time.

    fusen::init_share_on_github()

Carefully read instructions in the console to be able to properly set your GitHub website.

That’s it.
You created a properly documented and tested R project and shared it on a website accessible to everyone.
Every changes pushed to the “main” branch will update the website.

You can see the target website of the project I created for this blog post: https://statnmap.github.io/fusen.github.0.4.1.9000/ and the source repository: https://github.com/statnmap/fusen.github.0.4.1.9000/

Welcome page
Functions reference
Vignette articles
NEWS changelog

How to continue the development with the flat template?

Write in plain text what the code is supposed to do before writing any R code.

Then, you will need to factor your code to make it fit in R functions format.
This allows to document and test your code, to make it usable by others, and robust to future changes.

  • Start by only capture the whole code in the curly brackets of myfun <- function() {}
  • Then use the function in the example chunk to create a reproducible example
  • When the example is working, you can use it for a unit test in the test chunk

If you never factorized code or transformed into functions before, I would suggest to follow this presentation: Build reproducible and shareable data analyses using R packages

Use the RStudio Addins “add {fusen} chunks” to add a new set of chunks in your flat file and continue with new features.

Remember to follow the same skeleton as proposed in the flat template to write functions:

  • Chunk named function gets the code and documentation of a function
  • Chunk named example gets the code for examples of using the function. This will be used for function @examples and will be kept for the vignette
  • Chunk named tests gets the code for unit testing
  • Chunk named development gets the code for development purposes, usually only used once like {usethis} functions

Read the different articles in the {fusen} pkgdown website to guide you during the next steps: https://thinkr-open.github.io/fusen/dev/index.html

Yes, I must admit that you created a R package. And its corresponding website with {pkgdown}.
Now, the most difficult part for you is to find a proper hex logo. {fusen} cannot help with that, but {hexmake} can: https://connect.thinkr.fr/hexmake/

How to share my analysis if the flat file presents the documentation of my functions but not my analysis itself?

Indeed, the flat file is not exactly the notebook you want to share. What you want is a report presenting your data. The flat file, along with the website, is more the documentation on how to use the functions you created to analyse your data and the results of the analysis.
This makes the whole work reproducible for other similar analyses. And that’s the whole point! Sharing your work.

In the presentation Build reproducible and shareable data analyses using R packages, there is a specific chapter about What about data analyses in a package?. You will see that I propose two possible ways to build your analysis reports:

  • Classical package: Use external projects to use your package functions in Rmd/Quarto reports. This is probably what you already do now. However, with {fusen}, you can write your R functions inside your package realised with {fusen}, so that they are documented, tested and shared as a website for your future work and for the community.
  • Compendium-like: Include the Rmd/Quarto reports inside the package development project, in a specific folder.

In both cases, you can think of your flat template to follow the same steps as in your report (e.g. data preparation, exploration, model output…). So that the vignette of your package, resulting from inflating your template, is your skeleton to present your analysis. This also means that for a new analysis, you can copy the source vignette as a start.

Note: I followed the switch to Mastodon, you can follow me on @statnmap@mastodon.social


Citation:

For attribution, please cite this work as:
Rochette Sébastien. (2022, Oct. 28). "Share your R work following good dev practices from a single notebook". Retrieved from https://statnmap.com/2022-10-28-share-your-r-work-following-good-dev-practices-from-a-single-notebook/.


BibTex citation: 
@misc{Roche2022Share,
    author = {Rochette Sébastien},
    title = {Share your R work following good dev practices from a single notebook},
    url = {https://statnmap.com/2022-10-28-share-your-r-work-following-good-dev-practices-from-a-single-notebook/},
    year = {2022}
  }

Related articles