source commit: 598f0dd

CODE_OF_CONDUCT.md

@@ -0,0 +1,15 @@
+---
+title: "Contributor Code of Conduct"
+---
+
+As contributors and maintainers of this project,
+we pledge to follow the [The Carpentries Code of Conduct][coc].
+
+Instances of abusive, harassing, or otherwise unacceptable behavior
+may be reported by following our [reporting guidelines][coc-reporting].
+
+
+[coc-reporting]: https://docs.carpentries.org/topic_folders/policies/incident-reporting.html
+[coc]: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html
+
+We also adhere to the [Epiverse-TRACE Code of Conduct](https://github.com/epiverse-trace/.github/blob/main/CODE_OF_CONDUCT.md).

LICENSE.md

@@ -0,0 +1,74 @@
+---
+title: "Licenses"
+---
+
+## Instructional Material
+
+The tutorials in this repository are developed by Epiverse-TRACE, based on the [lesson template from the Carpentries](https://github.com/carpentries/workbench-template-rmd) (template under CC BY license).
+
+All Epiverse-TRACE
+instructional material is made available under the [Creative Commons
+Attribution license][cc-by-human]. The following is a human-readable summary of
+(and not a substitute for) the [full legal text of the CC BY 4.0
+license][cc-by-legal].
+
+You are free:
+
+- to **Share**---copy and redistribute the material in any medium or format
+- to **Adapt**---remix, transform, and build upon the material
+
+for any purpose, even commercially.
+
+The licensor cannot revoke these freedoms as long as you follow the license
+terms.
+
+Under the following terms:
+
+- **Attribution**---You must give appropriate credit (mentioning that your work
+  is derived from work that is Copyright (c) Epiverse-TRACE, where
+  practical, linking to <https://epiverse-trace.github.io/>), provide a [link to the
+  license][cc-by-human], and indicate if changes were made. You may do so in
+  any reasonable manner, but not in any way that suggests the licensor endorses
+  you or your use.
+
+- **No additional restrictions**---You may not apply legal terms or
+  technological measures that legally restrict others from doing anything the
+  license permits.  With the understanding that:
+
+Notices:
+
+* You do not have to comply with the license for elements of the material in
+  the public domain or where your use is permitted by an applicable exception
+  or limitation.
+* No warranties are given. The license may not give you all of the permissions
+  necessary for your intended use. For example, other rights such as publicity,
+  privacy, or moral rights may limit how you use the material.
+
+## Software
+
+Except where otherwise noted, the example programs and other software provided
+by Epiverse-TRACE are made available under the [OSI][osi]-approved [MIT
+license][mit-license].
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+[cc-by-human]: https://creativecommons.org/licenses/by/4.0/
+[cc-by-legal]: https://creativecommons.org/licenses/by/4.0/legalcode
+[mit-license]: https://opensource.org/licenses/mit-license.html
+[osi]: https://opensource.org

appendix.md

@@ -0,0 +1,185 @@
+---
+title: 'Appendix'
+teaching: 10
+exercises: 2
+---
+
+:::::::::::::::::::::::::::::::::::::: questions 
+
+- Where can I add my functions?
+- How do I need to document my functions?
+- How can I read the documentation of my functions?
+- How can I write a manuscript with my project outputs?
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: objectives
+
+- Write your functions documentation following the `{rcompendium}` template.
+- Load your functions and update its documentation using `{devtools}`.
+- Create a website for the project using `{usethis}`.
+- Create a manuscript template with `{rrtools}`.
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+## What about my functions?
+
+### How do I write my functions documentation?
+
+We must __write__ our custom functions as _Modular functions_ and save them in the `R/` folder. 
+You can __write__ the documentation of your functions following a [standard documentation method](https://r-pkgs.org/man.html). The `{rcompendium}` template already contains a `fun-demo.R` for this. 
+
+![](fig/fun-demo.png)
+
+:::callout
+
+Remember that _documented functions_ can facilitate further efforts to reuse them and create a specific R package!
+
+:::
+
+
+### How do I load my functions?
+
+To __load__ your project functions, as written in `line 20` of the `make.R` file, run:
+
+```r
+devtools::load_all(here::here())
+```
+
+### How do I read my functions documentation?
+
+Is there an easier way to read the documentation of my _modular functions_? 
+
+Remember that after you write the documentation of new functions on the `R/` folder, you must update your function and project documentation files, which are in _different_ files and folders. To do this run:
+
+```r
+devtools::document()
+```
+
+This last step will update the following:
+
+- `man/` folder, which stores the project documentation, and 
+- the `NAMESPACE`, that registers the functions that your project exports for your data analysis to run.
+
+Lastly, you can ask with `?function` in the `Console` and read the documentation for your functions, as any other function from the packages you installed. Try to run this:
+
+```r
+?print_msg
+```
+
+
+## Create a project website
+
+An alternative way to navigate all the files generated by the `{rcompendium}` template is with a website. 
+
+We can create a website using [GitHub pages](https://pages.github.com/). To make this possible run:
+
+```r
+usethis::use_pkgdown_github_pages()
+```
+
+This function implements the GitHub setup needed to automatically publish your site to GitHub pages using the [`{pkgdown}` package](https://pkgdown.r-lib.org/).
+
+This output is possible in two steps: 
+
+- First, it prepares to _publish_ the pkgdown site from a new `gh-pages` branch. 
+- Then, it configures a [GitHub Action](https://github.com/features/actions) to automatically _build_ the site and _deploy_ it via GitHub Pages.
+
+Lastly, the `pkgdown` site's URL is added to the `pkgdown` configuration file, to the URL field of `DESCRIPTION`, and to the GitHub repo.
+
+Commit and Push your changes.
+
+:::callout
+
+Remember that when using _GitHub Actions_, next to the `SHA/hash` will be the _status icon_ of the actions. 
+
+- Yellow ball for "Job running", 
+- Red cross for "Failed Run", and 
+- Green check for "job done!".
+
+:::
+
+Please wait for it to get green and inspect the Reference tab on the navigation bar.
+
+Now, let's compare the `fun-demo.R` file, the `?print_msg` output, and the website format:
+
+![](fig/fun-demo-web.png)
+
+:::callout
+
+A `pkgdown` website format can facilitate the navigation through: 
+
+- Community files and 
+- Function documentation.
+
+:::
+
+:::instructor
+
+If required, you can add vignettes for an `{rcompendium}` using: 
+
+```r
+rcompendium::add_vignette(filename = "vignette-01")
+```
+
+Vignettes look more suitable for package documentation than a project. But knowing that we have that alternative with the `{rcompendium}` template is helpful.
+
+:::
+
+## How do I write a manuscript for my project?
+
+You can use handy functions from another research compendium package called `{rrtools}`.
+
+To get a template of files required to fill a manuscript run:
+
+```r
+rrtools::use_analysis(location = "inst", data_in_git = FALSE)
+```
+
+This function will create a folder `inst/` with a new set of folders for data and figures. You can avoid using them and only use the `.qmd` as a template for your manuscript.
+
+![](fig/rrtools-paper.png)
+
+The `.qmd` files get formatted from several template files like references using `.bib` and citation style using `.csl`.
+
+![](fig/rrtools-templates.png)
+
+Using `rrtools::use_analysis()` with those arguments will not modify your `{rcompendium}` configuration. Other functions can change it. 
+
+:::instructor
+
+This manuscript will not be visible on a website unless moved to the `vignette/` folder. We have yet to test that behaviour.
+
+:::
+
+## Reproducible research features
+
+We also relate Reproducibility with the practice of _describing_ and _documenting_ the research process so that another researcher can re-run the software on the same data input to get the same data outputs.
+
+Features related to this are:
+
+- __Documentation strings__ in one or two lines using active verbs to describe how inputs turn into outputs ([Irving et al. 2021](https://merely-useful.tech/py-rse/documentation.html)). The documentation of functions, like the `fun-demo.R` template file, follows this good practice.
+
+- __Manuscripts__ using [literate programming](https://books.ropensci.org/targets/literate-programming.html) with tools like [Rmarkdown](https://rstudio.github.io/cheatsheets/html/rmarkdown.html) or [Quarto](https://quarto.org/). The template provided by `{rrtools}` facilitates files to start with this practice.
+
+
+:::callout
+
+Remember that if you have all your changes as commits with git, you can _revert_ any modification with the button __`Revert`__, located between the `Stage` and `Ignore` buttons.
+
+![](fig/git-revert.png)
+
+:::
+
+::::::::::::::::::::::::::::::::::::: keypoints 
+
+- Write your functions documentation following the `R/fun-demo.R` template.
+- Run your project functions with `devtools::load_all()`.
+- Update your functions documentation with `devtools::document()`.
+- Read your functions documentation with the `?function` notation in the R console.
+- Create a website for the project with `usethis::use_pkgdown_github_pages()`.
+- Use a manuscript template with `rrtools::use_analysis(location = "inst", data_in_git = FALSE)`.
+- _Documentation strings_ and _Manuscripts_ using _literate programming_ are features related to Reproducible research.
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+

beforestart.md

@@ -0,0 +1,60 @@
+---
+title: 'Before we start'
+teaching: 10
+exercises: 0
+---
+
+:::::::::::::::::::::::::::::::::::::: questions 
+
+- Where can I meet other workshop participants?
+- Where can I fill in my questions about the workshop topic?
+- Where can I find the Code of Conduct?
+- How can I report unacceptable behaviour?
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: objectives
+
+- Share our communication forum.
+- Share our Code of Conduct.
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+## Roll call
+
+:::checklist
+
+Hello!
+
+Before we start, tell us something about you on our _communication forum_ called [GitHub Discussions](https://github.com/epiverse-trace/research-compendium/discussions/1).
+
+<!-- You can fill in your questions on the topic under the [Q&A category](https://github.com/epiverse-trace/research-compendium/discussions/categories/q-a). -->
+
+:::
+
+## Welcome
+
+:::checklist
+
+A reminder of our [Code of conduct](https://github.com/epiverse-trace/.github/blob/main/CODE_OF_CONDUCT.md):
+
+- If you experience or witness unacceptable behaviour or have any other concerns, please report by completing this short form:  <https://forms.gle/guKqVXPk6K43jPn59>
+
+- To report an issue involving one of the organisers, please use the LSHTM’s [Report and Support tool](https://reportandsupport.lshtm.ac.uk/), where your concern will be triaged by a member of LSHTM’s Equity and Diversity Team.
+
+:::
+
+## Contributors
+
+This material has contributions from:
+
+- [James Azam, PhD](https://www.lshtm.ac.uk/aboutus/people/azam.james), RSE at Epiverse.
+- [Carmen Tamayo-Cuartero, PhD](https://www.lshtm.ac.uk/aboutus/people/tamayo-cuartero.carmen), RF at Epiverse.
+
+::::::::::::::::::::::::::::::::::::: keypoints 
+
+- Use the `GitHub Discussions` as our communication forum for the workshop.
+- Use the Code of Conduct to report unacceptable behaviour.
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+