Introduction to Reproducible Publications with Quarto

This workshop explores the powerful combination of Quarto and RStudio to author scientific publications. Our aim is to enhance researchers' adoption of open and reproducible practices while improving their project and data management skills.

This workshop is structured into three modules. The modular format encourages instructors to view the workshop as a comprehensive but flexible curriculum, allowing them to focus on specific areas of interest. Recognizing variations in proficiency levels and familiarity with RStudio among learners, we have designed this workshop to be flexible, allowing for the abbreviation or skipping of episodes to cater to specific needs:

• Module 1 - Reproducibility and Project Organization: This module consists of two episodes introducing learners to reproducible research and project management fundamentals. It lays the groundwork for a robust and transparent workflow, ensuring that all participants, whether beginners or those seeking a refresher, are on the same page before delving into the specifics of Quarto and RStudio Posit.
• Module 2 - Quarto and RStudio: This module focuses on Quarto and its features for creating dynamic and reproducible documents. We guide learners through the ins and outs of Quarto, helping them harness this authoring framework and tool potential to create visually appealing, easily reproducible, and shareable documents.
• Module 3 - Collaboration: This module shifts the focus to collaboration and publishing. It explores effective collaboration with others, using version control within RStudio, pushing local changes to a remote repository, managing dependencies for R/Quarto projects, and sharing reproducible research with a wider audience.

This lesson has a supplementary repository with the project example used for challenges and exercises.

For an earlier version of this workshop using RMarkdown, please check for the v1.0-RMarkdown release.

Contributing

We welcome all contributions to improve the lesson! Your expertise and perspective are crucial to elevating the quality and effectiveness of the workshop content. Whether sharing domain-specific knowledge, addressing existing issues, suggesting improvements, or teaching the workshop materials, we invite you to contribute. Please refer to the issues page for topics seeking contributions, and feel free to flag any bugs, add questions, or recommend opportunities for improvement on the issues page. Maintainers will do their best to help you if you have any questions, concerns, or experience any difficulties along the way.

We'd like to ask you to familiarize yourself with our Contribution Guide and have a look at the more detailed guidelines on proper formatting, ways to render the lesson locally, and even how to write new episodes.

Please see the current list of issues for ideas for contributing to this repository. For making your contribution, we use the GitHub flow, which is nicely explained in the chapter Contributing to a Project in Pro Git by Scott Chacon. Look for the tag . This indicates that the maintainers will welcome a pull request to fix this issue.

Maintainer(s)

Current maintainers of this lesson are:

• Renata Curty (rcurty)
• Torin White (torwhite)
• Ian Lessing (ilessing)
• Greg Janee (gjanee)
• Julien Brun (brunj7)
• kristi Liu (kristi-sara)

Authors

A list of contributors to the lesson can be found in AUTHORS

Citation

To cite this lesson, please consult with CITATION

Thanks for contributing to The Carpentries Incubator! This repository provides a blank starting point for lessons to be developed here.

A member of the Carpentries Curriculum Team will work with you to get your lesson listed on the Community Developed Lessons page and make sure you have everything you need to begin developing your new lesson.

What to do next

Before you begin developing your new lesson, here are a few things we recommend you do:

• If you're going to be developing lesson material for the first time according to our design principles, consider reading the Carpentries Curriculum Development Handbook
• Consult the Lesson Example website to find out more about working with the lesson template -- specifically https://carpentries.github.io/lesson-example/05-rmarkdown-example/index.html to see rmarkdown example
• Update this README with relevant information about your lesson
  and delete this section

* To set the URL on GitHub, click the gear wheel button next to About on the right of the repository landing page. The lesson URL structure is https://carpentries-incubator.github.io/<repository-slug>: a repository at https://github.com/carpentries-incubator/new-lesson/ will have pages at the lesson URL https://carpentries-incubator.github.io/new-lesson/.

R Markdown vs. Github Markdown

Note the two flavors of markdown are different. Some formatting tips:

• Line Breaks: must have two spaces at the end of the line or manually add a break
  

Lesson-specific formatting

For formatting & consistency's sake, we should :

1. for examples that don't need to be input to the paper example rmd file, DON'T use {: .source} callouts but DO use ``` ``` so the markdown doesn't render. For short partial line chunks can be used.
2. use {: .source} callouts for code we're walking them through to add to the rmd file.
3. for challenge solutions the solutions should be unrendered markdown syntax between ``` ```
4. for tips, use the {: .callout} callout

Examples:

1. R markdown examples
   code: *I can't get the markdown to render correctly this this comment so this is just a screenshot

outputs to:

2. Exercises (i.e. "follow me" not challenges) code:

~~~
## MATERIALS AND METHODS  
### Survey Overview  
### Data Analysis  
~~~
{: .source}

outputs as:

3. Challenges

• Make sure to label challenges CHALLENGE [ep#.challenge#]
• the solution is just SOLUTION code:

> ## CHALLENGE 3.1
> Insert headings throughout the rest of the paper so it is split into 5 sections (Introduction, Materials and Methods, Results and Discussion, Conclusion, and References). Use the search function in R Markdown to find these lines in the document. 
>
>> ## SOLUTION
>> ```
>> ## INTRODUCTION
>> ## MATERIALS AND METHODS
>> ## RESULTS AND DISCUSSION
>> ## CONCLUSION
>> ## REFERENCES
>> ```
>> Why are we using `##`? Because `#` should only be used once in the paper (for the title) and `##` is for the next heading level.
> {: .solution}
{: .challenge}

outputs as:

• heading should say Tip: [short description of tip]

> ## Tip: how to make callouts
> Use `>`s on each line of callout and after callout ends the next line should contain {: .callout}
{: .callout}

Generate regular vanilla Markdown from R-markdown for episodes

When creating episodes in the _episodes_rmd directory you'll want to process them into rgular markdown so they will be further processed by Github and published when pushed to Github. If you have the make utility, which Mac or Linux has by default you can call make lesson-m. But if you do not have make which is the case for most windows users then you can use R and Knitr from the command line. There are two ways to do this for Windows users:

1) Use knitr from the command line/ Rstudio terminal to process an R-markdown file into a regular markdown file: *assumes you are in the root directory *change the file name to match the episode you edited

Rscript -e 'knitr::knit("./_episodes_rmd/01-r-markdown-episode-template.Rmd", output = "./_episodes/01-r-markdown-episode-template.md")'

2) Change your knit button settings Next to the knit button there is a gear for options. Click it and chose output options at the very bottom of the list. Choose the Advanced tab and check keep markdown source file. Requires that you move some files around after: Make sure to 1) move the .md file to the _episodes/ folder and 2) delete the html file output.

*method 1 will work even if all your image links etc. aren't working. Method 2 won't work unless all links are correct - errors out otherwise.

Code for all lessons method 1 cheatsheet:

# episode 2:
Rscript -e 'knitr::knit("./_episodes_rmd/02-basic-rstudio.Rmd", output = "./_episodes/02-basic-rstudio.md")'
# episode 3:
Rscript -e 'knitr::knit("./_episodes_rmd/03-rmarkdown-file.Rmd", output = "./_episodes/03-rmarkdown-file.md")'
# episode 4:
Rscript -e 'knitr::knit("./_episodes_rmd/04-good-project.Rmd", output = "./_episodes/04-good-project.md")'
# episode 5:
Rscript -e 'knitr::knit("./_episodes_rmd/05-setup-versioning.Rmd", output = "./_episodes/05-setup-versioning.md")'
# episode 6:
Rscript -e 'knitr::knit("./_episodes_rmd/07-code-chunks.Rmd", output = "./_episodes/07-code-chunks.md")'

Releases and Roadmap

• 2022-09-23 release version 1.0 - This version compatibile with R-studio "Ghost Orchid" Release 2021.09.02 or thereabouts.
• Fall-Winter 2022 plan to update this workshop for compatibility with Quarto