diff --git a/docs/collaborating/peer-code-review.md b/docs/collaborating/peer-code-review.md index 3253fb61..02a0f4bb 100644 --- a/docs/collaborating/peer-code-review.md +++ b/docs/collaborating/peer-code-review.md @@ -7,7 +7,7 @@ Once you're comfortable in using [merge/pull requests](merge-pull-requests.md) t Remember that code review is a **discussion and critique** of a person's work. The code author will naturally feel that they own the code, and the reviewer needs to respect this. -For further advice and suggestions on how to conduct peer code review, please see the [Performing peer code review](../references.md#performing-peer-code-review) references. +For further advice and suggestions on how to conduct peer code review, please see the [Performing peer code review](../resources.md#performing-peer-code-review) resources. !!! tip diff --git a/docs/community/meetings/2023-08-15.md b/docs/community/meetings/2023-08-15.md index 18c74cbd..22c459bb 100644 --- a/docs/community/meetings/2023-08-15.md +++ b/docs/community/meetings/2023-08-15.md @@ -128,7 +128,7 @@ This journal issue was followed by an [invited paper session](https://github.com - [Mastering Shiny](https://mastering-shiny.org/): an online book that teaches how to create web applications with R and Shiny. -- [CoMo Consortium App](https://comomodel.net/): the COVID-19 International Modelling Consortium (CoMo) has developed web application for an age-structured, compartmental SEIRS model. +- [CoMo Consortium App](https://comomodel.net/): the COVID-19 International Modelling Consortium (CoMo) has developed a web application for an age-structured, compartmental SEIRS model. ### Continuous integration examples for R diff --git a/docs/references.md b/docs/resources.md similarity index 53% rename from docs/references.md rename to docs/resources.md index 949bf44d..78f10c5b 100644 --- a/docs/references.md +++ b/docs/resources.md @@ -1,13 +1,34 @@ -# References +# Useful resources ## Education and commentary articles - [A Beginner's Guide to Conducting Reproducible Research](https://doi.org/10.1002/bes2.1801) describes key requirements for producing reproducible research outputs. +- [Why code rusts](http://www.tdda.info/why-code-rusts) collects together some of reasons the behaviour of code changes over time. + - [Point of View: How open science helps researchers succeed](https://doi.org/10.7554/eLife.16800) presents evidence that open research practices bring significant benefits to researchers. +- The Journal of Statistics and Data Science Education published a [special issue: Teaching Reproducibility](https://www.tandfonline.com/toc/ujse21/30/3?nav=tocList) in November 2022. + Also see the presentations from an [invited paper session](https://github.com/ttimbers/jsm2023-teaching-reproducibility-and-responsible-workflow): + + - **Collaborative writing workflows:** building blocks towards reproducibility + + - **Opinionated practices for teaching reproducibility:** motivation, guided instruction, and practice + + - **From teaching to practice:** Insights from the Toronto Reproducibility Conferences + + - **Teaching reproducibility and responsible workflow:** an editor's perspective + +## How to structure your project? + - [A Quick Guide to Organizing Computational Biology Projects](https://doi.org/10.1371/journal.pcbi.1000424) suggests an approach for structuring a computational research repository. +- The [TIER Protocol 4.0](https://www.projecttier.org/tier-protocol/protocol-4-0/#%3A~%3Atext%3DFlexibility%20and%20Adaptability%20of%20the%20TIER%20Protocol) provides a template for organising the contents and reproduction documentation for projects that involve working with statistical data: + + > Documentation that meets the specifications of the TIER Protocol contains all the data, scripts, and supporting information necessary to enable you, your instructor, or an interested third party to reproduce all the computations necessary to generate the results you present in the report you write about your project. + +- [A simple kit to use computational notebooks for more openness, reproducibility, and productivity in research](https://doi.org/10.1371/journal.pcbi.1010356) provides some good recommendations for organising a project repository and setting up a reproducible workflow using computational notebooks. + ## Using Git and other software tools - NDP Software have created [an interactive Git cheat-sheet](https://ndpsoftware.com/git-cheatsheet.html) that shows how git commands interact with the local and upstream repositories, and provides brief documentation for many common examples. @@ -21,6 +42,12 @@ It presents an example of analysing publicly available ChIP-seq data with Python. The repository for the article is also [publicly available](https://github.com/jdblischak/git-for-science). +## Examples of making models publicly available + +- [CoMo Consortium App](https://comomodel.net/): the COVID-19 International Modelling Consortium (CoMo) has developed a [Shiny](https://shiny.posit.co/) web application for an age-structured, compartmental SEIRS model. + +- [Mastering Shiny](https://mastering-shiny.org/): an online book that teaches how to create web applications with R and Shiny. + ## Performing peer code review - [The Art of Giving and Receiving Code Reviews (Gracefully)](https://www.alexandra-hill.com/2018/06/25/the-art-of-giving-and-receiving-code-reviews/) @@ -31,11 +58,24 @@ - [The 5 Golden Rules of Code Review](https://www.semasoftware.com/blog/the-5-golden-rules-of-code-reviews) -## Computational research practices +## Continuous Integration (CI) examples -- [A simple kit to use computational notebooks for more openness, reproducibility, and productivity in research](https://doi.org/10.1371/journal.pcbi.1010356) provides some good recommendations for organising a project repository and setting up a reproducible workflow using computational notebooks. +- [GitHub Actions for Python](https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python): the GitHub Actions documentation includes examples of building and testing Python projects. -- [Why code rusts](http://www.tdda.info/why-code-rusts) collects together some of reasons the behaviour of code changes over time. +- [Building reproducible analytical pipelines with R](https://raps-with-r.dev/ci_cd.html): this article shows how to use GitHub Actions to run R code when you push new commits to a GitHub repository. + +- [GitHub Actions for the R language](https://github.com/r-lib/actions): this repository provides a variety of GitHub actions for R projects, such as installing specific versions of R and R packages. + +- See the [GitHub actions](https://github.com/robmoss/git-is-my-lab-book/tree/master/.github/workflows) for **Git is my lab book**. + The [build action](https://github.com/robmoss/git-is-my-lab-book/blob/master/.github/workflows/build.yml) does the following: + + 1. Check out the repository with [`actions/checkout`](https://github.com/actions/checkout); + + 2. Install Python with [`actions/setup-python`](https://github.com/actions/setup-python); + + 3. Install [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) and other required tools, as listed in [`requirements.txt`](https://github.com/robmoss/git-is-my-lab-book/blob/master/requirements.txt); and + + 4. Build the HTML version of this book with [`mkdocs`](https://www.mkdocs.org/). ## High-performance computing platforms diff --git a/mkdocs.yml b/mkdocs.yml index 3095a8c9..929f0c9d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -134,4 +134,4 @@ nav: - "19 February 2024": "community/meetings/2024-02-19.md" - "How to contribute": "how-to-contribute.md" - "Contributors": "contributors.md" - - "References": "references.md" + - "Useful resources": "resources.md"