From 64cb7f390ab84b68cc8b919295e94f041519b049 Mon Sep 17 00:00:00 2001 From: Matthew Carroll <28577806+MJC598@users.noreply.github.com> Date: Fri, 12 Dec 2025 11:40:33 -0500 Subject: [PATCH 1/5] Updating the README and _quarto doc for new information --- .Rbuildignore | 3 --- README.md | 36 ++++++++++++++++++++++++++++++++---- _quarto.yml | 4 +++- 3 files changed, 35 insertions(+), 8 deletions(-) delete mode 100644 .Rbuildignore diff --git a/.Rbuildignore b/.Rbuildignore deleted file mode 100644 index 4862ac6..0000000 --- a/.Rbuildignore +++ /dev/null @@ -1,3 +0,0 @@ -^renv$ -^renv\.lock$ -^\.github$ diff --git a/README.md b/README.md index edb425d..7c53a08 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,38 @@ A template repository for R analysis projects. ## Structure -Data Folder - Stores all data. Should generally contain data used within the project. Ensure if it is too big that it does not get checked into VC itself but instead a reference to the data is copied. +This template contains a basic analysis R project folder structure. It assumes we make use of [Quarto notebooks](https://quarto.org/) and the [renv](https://rstudio.github.io/renv/) virtual environment tool. We also make use of our custom linter and format restrictions based on our lab style guide rules. -Notebooks - Where the analysis happens. Should be written in an Rmd format and knit together into a readable format. +**Note:** While based on tidyverse, we do not subscribe to all the ideas and provide different checks. A major example of this is we utilize 4 space indentation rather than 2 space. -Output - The resulting visualizations from the analysis that we want to output from the repository. +### Folders -R - Where general R functions live. NOTE: No scripts go here, any scripting should be within the notebooks themselves alongside documentation. This is exclusively for R functions! +- `data/` - General folder for all data. Ensure if it is too big that it does not get checked into VC itself but instead a reference to the data is copied. +- `data/processed/` - Folder used to store data that is processed by the repository. This is not necessarily output data we want to report but intermediate data that we keep to save compute time. +- `data/raw/` - Folder used to store data that has been untouched by the repository. It is a location for database routing, CSVs, etc. that are pulled from outside sources. Specifically, we do not store any data we have manipulated in this folder. +- `notebooks/` - This folder contains all the Quarto notebooks and is where the analysis happens. Note, these are just `.qmd` files and not rendered results nor partially-rendered files. +- `R/` - Folder used to house all R functions and scripts used across the analysis notebooks. These scripts are not meant to stand alone and should not be run outside of the analysis notebooks. If these are run outside the analysis notebooks, the function should be moved into a package structure or the script should be converted into a notebook. +- `renv/` - A folder created and maintained by `renv`. Do not change by hand. +- `output/` - The folder to store all results from analysis. Specifically, we want to store any generated images or data necessary for a report out. This is also where the rendering should produce the final notebooks. + +### Files + +- `_quarto.yml` - A yaml file that governs the entire project for quarto rendering. Specifically, this file tells the quarto command how to execute and provides basic formatting/metadata requirements for all notebooks to conform to. +- `.gitignore` - A standard git file to ensure certain elements of the repository are not checked into version control. +- `.lintr` - The linter file used to ensure we are linting for Syndemics specific style guide standards. It is used with the [`lintr` library](https://lintr.r-lib.org/index.html). +- `.Rprofile` - A file created and maintained by `renv`. Do not change by hand. **Note:** This file sources the `utils.R` file for the helper function `ensure_packages`. This is a replacement for the `library()` and `require()` function calls. +- `air.toml` - A TOML file to ensure we are providing the correct formatting to the repository. It works with the [Air formatter](https://posit-dev.github.io/air/). +- `LICENSE.md` - The GNU Affero GPL. This is our lab wide standard open source License. +- `PROJECT_NAME.Rproj` - The default file for RStudio projects. We recommend changing this name after creating your template. +- `README.md` - This file! The basic outline of the project and explanation of the use cases. +- `renv.lock` - A file created and maintained by `renv`. Do not change by hand. + +## How to Use + +1. Click the green button in the top right of this repository that says "Use this template" and "Create a new repository". +2. Choose your name and settings for the new repository. +3. Clone the new repository and rename the `PROJECT_NAME.Rproj` file. +4. Run `renv::restore()` to get all libraries from `renv` installed. + 1. (Optional) If you want to reset the default `renv` installs run `renv::snapshot()` instead to store your libraries into the `renv`. +5. Update the README to contain details about your project. +6. Develop and enjoy. diff --git a/_quarto.yml b/_quarto.yml index 0a499c6..f3795b9 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -2,11 +2,13 @@ project: output-dir: output number-sections: true +bibliography: references.bib +execute: + freeze: auto format: html: default pdf: - documentclass: report margin-left: 20mm margin-top: 30mm margin-right: 20mm From 8a1064ccb3ea3ca6bb761c866225f8f831de9c81 Mon Sep 17 00:00:00 2001 From: Matthew Carroll <28577806+MJC598@users.noreply.github.com> Date: Fri, 12 Dec 2025 11:43:56 -0500 Subject: [PATCH 2/5] Adding github templates --- .github/ISSUE_TEMPLATE/bug_report.md | 34 +++++++++++++++++++ .github/ISSUE_TEMPLATE/feature_request.md | 20 +++++++++++ .../pull_request_template.md | 17 ++++++++++ 3 files changed, 71 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE/pull_request_template.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..55fd8bf --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,34 @@ +--- +name: Bug report +about: Create a report to help us improve +title: '' +labels: '' +assignees: '' + +--- + +**Describe the bug** +A clear and concise description of what the bug is. + +**To Reproduce** +Steps to reproduce the behavior: + +1. Go to '...' +2. Click on '....' +3. Scroll down to '....' +4. See error + +**Expected behavior** +A clear and concise description of what you expected to happen. + +**Screenshots** +If applicable, add screenshots to help explain your problem. + +**Desktop (please complete the following information):** + +- OS: [e.g. iOS] +- Browser [e.g. chrome, safari] +- Version [e.g. 22] + +**Additional context** +Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..bbcbbe7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,20 @@ +--- +name: Feature request +about: Suggest an idea for this project +title: '' +labels: '' +assignees: '' + +--- + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Additional context** +Add any other context or screenshots about the feature request here. diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md new file mode 100644 index 0000000..0bba7bb --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md @@ -0,0 +1,17 @@ +--- +name: Pull Request +about: Prepare to Merge Code to Main +title: '' +labels: '' +assignees: '' + +--- +## What does this PR do? + +## What Wrike task is this associated with? + +## Checklist before merging + +- [ ] If its a core feature, I have added through test. +- [ ] Do we need to implement analytics? +- [ ] Will this be part of a product update? If yes, please write one phrase about this update From 8b5a513bfbe5a875b53372b1ea8ead672e5a4aad Mon Sep 17 00:00:00 2001 From: Matthew Carroll <28577806+MJC598@users.noreply.github.com> Date: Fri, 12 Dec 2025 12:02:49 -0500 Subject: [PATCH 3/5] comment from respond PR about PR templates --- .github/PULL_REQUEST_TEMPLATE/pull_request_template.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md index 0bba7bb..f7af544 100644 --- a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md +++ b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md @@ -1,6 +1,6 @@ --- -name: Pull Request -about: Prepare to Merge Code to Main +name: Pull Request to Default +about: Submit code to be merged into the default branch title: '' labels: '' assignees: '' @@ -12,6 +12,5 @@ assignees: '' ## Checklist before merging -- [ ] If its a core feature, I have added through test. -- [ ] Do we need to implement analytics? -- [ ] Will this be part of a product update? If yes, please write one phrase about this update +- [ ] If adding a core feature, I've added related tests. +- [ ] This is part of a [product update](https://www.chameleon.io/blog/product-updates), and I've added an explanation of what is different to the changelog. From 5aa7f134f19a3c0a95161aadb80c79e1f7b47a8a Mon Sep 17 00:00:00 2001 From: Matthew Carroll <28577806+MJC598@users.noreply.github.com> Date: Fri, 12 Dec 2025 13:16:59 -0500 Subject: [PATCH 4/5] Update README.md Co-authored-by: Dimitri Baptiste <55843498+ddbaptiste@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7c53a08..7645e2b 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ This template contains a basic analysis R project folder structure. It assumes w ### Folders -- `data/` - General folder for all data. Ensure if it is too big that it does not get checked into VC itself but instead a reference to the data is copied. +- `data/` - General folder for all data. Ensure if it is [too big](https://docs.github.com/en/repositories/working-with-files/managing-large-files/about-large-files-on-github#file-size-limits) that it does not get checked into version control itself but instead a reference to the data is copied. - `data/processed/` - Folder used to store data that is processed by the repository. This is not necessarily output data we want to report but intermediate data that we keep to save compute time. - `data/raw/` - Folder used to store data that has been untouched by the repository. It is a location for database routing, CSVs, etc. that are pulled from outside sources. Specifically, we do not store any data we have manipulated in this folder. - `notebooks/` - This folder contains all the Quarto notebooks and is where the analysis happens. Note, these are just `.qmd` files and not rendered results nor partially-rendered files. From 8ad5ffbb74371cb399b425254d75b019d4d2f3d3 Mon Sep 17 00:00:00 2001 From: Matthew Carroll <28577806+MJC598@users.noreply.github.com> Date: Fri, 12 Dec 2025 13:18:57 -0500 Subject: [PATCH 5/5] addressing PR comments --- README.md | 2 +- _quarto.yml | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7645e2b..204c693 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ A template repository for R analysis projects. This template contains a basic analysis R project folder structure. It assumes we make use of [Quarto notebooks](https://quarto.org/) and the [renv](https://rstudio.github.io/renv/) virtual environment tool. We also make use of our custom linter and format restrictions based on our lab style guide rules. -**Note:** While based on tidyverse, we do not subscribe to all the ideas and provide different checks. A major example of this is we utilize 4 space indentation rather than 2 space. +**Note:** While based on tidyverse, we do not subscribe to all the ideas and provide different checks. Check the [lab style guide](https://github.com/SyndemicsLab/styleguide/blob/main/Rguide.md) for more information. ### Folders diff --git a/_quarto.yml b/_quarto.yml index f3795b9..79034fb 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -3,6 +3,7 @@ project: number-sections: true bibliography: references.bib +link-citations: true execute: freeze: auto