From 089c82a6fd8ff132e69675264fc2be182c6953ec Mon Sep 17 00:00:00 2001 From: "Felix.S" Date: Wed, 16 Jul 2025 16:30:18 +0200 Subject: [PATCH] Shorten README Chapter; add new in-depth page --- .gitignore | 2 +- _quarto.yml | 4 +- in_depth_material/other_dependencies.qmd | 96 ++++++++++ make_readme.qmd | 221 ++++++++--------------- 4 files changed, 180 insertions(+), 143 deletions(-) create mode 100644 in_depth_material/other_dependencies.qmd diff --git a/.gitignore b/.gitignore index 504c572..dbaa102 100644 --- a/.gitignore +++ b/.gitignore @@ -62,5 +62,5 @@ _outline.md # Other files created by the project grateful-refs.bib -#data.csv # we keep this file in the repo +data.csv _data_dictionary.qmd \ No newline at end of file diff --git a/_quarto.yml b/_quarto.yml index b17a242..0e383db 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -51,12 +51,14 @@ website: - choose_license.qmd - make_readme.qmd - archive.qmd - - section: "💡 In-depth material" + - section: "Excursus: In-depth material 💡" contents: - href: in_depth_material/introduction_copyright.qmd text: "Introduction to Copyright and Licensing" - href: in_depth_material/data_dic_generation.qmd text: "Automatic Generation of Data Dictionaries" + - href: in_depth_material/other_dependencies.qmd + text: "Identify additional system dependencies for the README" # End Website diff --git a/in_depth_material/other_dependencies.qmd b/in_depth_material/other_dependencies.qmd new file mode 100644 index 0000000..4e42d3b --- /dev/null +++ b/in_depth_material/other_dependencies.qmd @@ -0,0 +1,96 @@ +--- +title: "Identify additional system dependencies for the README" +engine: knitr +--- + +The specific version of R and the loaded packages is the most crucial information that should go into the README (or that is stored in the `renv` lockfile). Ideally, you list other system dependencies, such as the version of Quarto[^renv-quarto] that you used to render your paper. + +[^renv-quarto]: As of August 2024, a proposal for `renv` to record the version of Quarto +has not been implemented, see [rstudio/renv#1143](https://github.com/rstudio/renv/issues/1143). + +An overview over the system dependencies of R packages can be created +using the function `pak::pkg_sysreqs()`. +In combination with `renv`, we can obtain the system dependencies +of all R packages the current project directly depends on: + +```{.r filename="Console"} +# Find all R package dependencies +deps <- renv::dependencies()$Package |> + unique() |> + pak::pkg_deps(dependencies = NA) |> + getElement("package") + +# Identify their system dependencies +pak::pkg_sysreqs(deps) +``` + +The output may look like the following: + +```txt +── Install scripts ────────────────── Fedora 40 ── +dnf install -y make pandoc git + +── Packages and their system dependencies ──────── +fs – make +knitr – pandoc +remotes – git +rmarkdown – pandoc +sass – make +``` + +We can see that the programs `make`, `pandoc`, +and `git` were identified as system dependencies. +Often, one can obtain their version by running them with the `--version` argument: + +```{.bash filename="Terminal"} +make --version +pandoc --version +git --version +``` + +However, this does not work for all system dependencies. +Specifically, it does not work for libraries -- software that is not supposed to be run on its own. +Identifying their version is beyond the scope of this tutorial. + +We also know that we need Quarto to create the PDF, +so let's find out its version as well: + +```{.bash filename="Terminal"} +quarto --version +``` + +If you installed `apaquarto` or any other Quarto extension, +one can query their versions as follows:[^already-included] + +[^already-included]: Luckily, the extensions are included in the project folder, +so technically their version is already recorded in the project's files. + +```{.bash filename="Terminal"} +quarto list extensions +``` + +Finally, we know that we installed a $\TeX$ distribution to create the PDF, +so let's find out its version by running: + +```{.bash filename="Terminal"} +quarto check +``` + +The output is quite long and it might look slightly different for you, +but the relevant sections are the following: + +```txt +[✓] Checking tools....................OK + TinyTeX: v2024.09 + Chromium: (not installed) + +[✓] Checking LaTeX....................OK + Using: TinyTex + Path: /home/r155953/.TinyTeX/bin/x86_64-linux + Version: 2024 +``` + +Add these dependencies to the section **Computational Requirements / Dependencies** of your README file. + +Of course, all the system dependencies identified until now +may have dependencies on their own. Use your own judgement to decide when not to dig deeper. diff --git a/make_readme.qmd b/make_readme.qmd index 1aeecda..ea80bd4 100644 --- a/make_readme.qmd +++ b/make_readme.qmd @@ -8,167 +8,116 @@ engine: knitr Having settled on a license, it is time to add a final touch. Imagine returning to your project in five years, having forgotten most of the details of what you did exactly. -What would be useful to know in order to quickly understand -what is going on in the project? -This is what needs to be described in the README. -While you could just start writing along, -it is helpful to provide at least the following information in sections on their own. +What would your future self want to know in order to quickly understand +what is going on in the project? -### Name and Description +This is what needs to be described in the `README` file. +It should be the primary entry point into your project, +the place where new users go first to get an orientation. -How is the project called? -What is it about? -Which files does the project folder contain? -How are they organized? +There is no common standard how to structure a README file, +but you should usually provide at least the following information, +structured by sections: -### Involved Data +**Name and Description** -Are any (empirical) data involved (e.g., being analyzed or used as input)? -From which sources can they be obtained? -Are they already included in the project folder? -Where is their data dictionary located? -Which terms, usage restrictions, or licenses apply? -If they are not publicly available, -is an alternative, synthesized version provided? +- [ ] How is the project called? +- [ ] What is it about? +- [ ] Which files does the project folder contain? +- [ ] How are they organized? -### Computational Requirements +**Data** -What software needs to be installed to run the analysis --- in other words, what are its dependencies? -This also includes software that you have used for any manual steps. -For every dependency, describe where it can be obtained from. -If the code has particular hardware requirements -(e.g., in terms of processor or memory), -these should be also noted. -Finally, for steps that take more than a couple of seconds, -the approximate runtime should be indicated. +- [ ] Are any (empirical) data involved (e.g., being analyzed or used as input)? +- [ ] Are they already included in the project folder? If not: From which sources can they be obtained? +- [ ] Where is their data dictionary located? +- [ ] Which terms, usage restrictions, or licenses apply? +- [ ] (optionally) If they are not publicly available, is an alternative, synthesized version provided? -@nte-dependencies provides more information -on determining the dependencies of an R project. +**Computational Requirements / Dependencies** -### Usage +- [ ] What software needs to be installed to run the analysis? -How can one run the project -- is there a master script -or a particular order in which any scripts need to be executed? -Provide detailed instructions for running the full project. +For every dependency (e.g., packages that you load in R), describe where it can be obtained from. +If the code has particular hardware requirements +(e.g., in terms of processor or memory), these should be also noted. +Finally, for steps that take more than a couple of seconds, +indicate the approximate runtime. -### List of Results +For an R project, the most important information for enabling reproducibility are the specific version of R and the loaded packages. Ideally, you also list other system dependencies. The in-depth supplementary material [*Identify additional system dependencies for the README*](/in_depth_material/other_dependencies.qmd) provides more information on determining the dependencies of an R project. +*For the purpose of this tutorial, however, you can skip this step.* -For every result (i.e., number, figure, or table) that is -computed in the project and displayed in the manuscript, -indicate where exactly it is computed. +**How to reproduce the results** -### Citation +- [ ] Provide step-by-step instructions that are necessary to reproduce all reported results. -Is there a recommended way to cite this project? -Is there a published article associated with it -that you would like to have cited? +Is there a master script or a particular order in which any scripts need to be executed? -### License +**Citation** -Under which licenses are the works in this project folder available? +- [ ] Is there a recommended way to cite this project? +- [ ] Is there a published article associated with it that you would like to have cited? -## Create It! +**License** -Create your README now as the file `README.md`. +- [ ] Under which licenses are the works in this project folder available? -::: {#nte-dependencies .callout-note} -### Identifying R Dependencies -R itself and the R packages are already documented as this project uses `renv`. -Therefore you can focus on all other dependencies, -such as the system dependencies of R packages -as well as the version of Quarto.[^renv-quarto] -[^renv-quarto]: As of August 2024, a proposal for `renv` to record the version of Quarto -has not been implemented, see [rstudio/renv#1143](https://github.com/rstudio/renv/issues/1143). +## Identifying R Dependencies -An overview over the system dependencies of R packages can be created -using the function `pak::pkg_sysreqs()`. -In combination with `renv`, we can obtain the system dependencies -of all R packages the current project directly depends on: +If you just write "We used R to analyze the data" in your manuscript or in the *Computational Requirements / Dependencies* section of your README file, this would be too underspecified. To enable someone else to really reproduce your results, you need specific information on ... -```{.r filename="Console"} -# Find all R package dependencies -deps <- renv::dependencies()$Package |> - unique() |> - pak::pkg_deps(dependencies = NA) |> - getElement("package") +- The exact version of R +- All packages and their versions that you loaded in your project +- (optionally) Further system dependencies -# Identify their system dependencies -pak::pkg_sysreqs(deps) -``` +### R & Package Dependencies -The output may look like the following: +R itself and the R packages are already documented as our tutorial project uses `renv`: The information is stored in the `renv.lock` file at the root of the project, which tracks each package’s version and source. In this case, you can simply refer to that in the README file and all is done: -```txt -── Install scripts ────────────────── Fedora 40 ── -dnf install -y make pandoc git - -── Packages and their system dependencies ──────── -fs – make -knitr – pandoc -remotes – git -rmarkdown – pandoc -sass – make -``` +> The R and packages versions used to compute the results are stored in the `renv` environment (see `renv.lock` file). -We can see that the programs `make`, `pandoc`, -and `git` were identified as system dependencies. -Often, one can obtain their version by running them with the `--version` argument: +If you do *not* use `renv`, the easiest solution to get a list of all needed packages is the `sessionInfo()` command. *Call it **after** you loaded all necessary packages!* -```{.bash filename="Terminal"} -make --version -pandoc --version -git --version -``` +It lists all packages including their versions, and you can copy & paste that information into your README file. Here's an example for a project: -However, this does not work for all system dependencies. -Specifically, it does not work for libraries -- software that is not supposed to be run on its own. -Identifying their version is beyond the scope of this tutorial. - -We also know that we need Quarto to create the PDF, -so let's find out its version as well: +```txt +> sessionInfo() +R version 4.4.1 (2024-06-14) +Platform: aarch64-apple-darwin20 +Running under: macOS 15.5 -```{.bash filename="Terminal"} -quarto --version -``` +Matrix products: default +BLAS: /System/Library/Frameworks/Accelerate.framework/Versions/A/Frameworks/vecLib.framework/Versions/A/libBLAS.dylib +LAPACK: /Library/Frameworks/R.framework/Versions/4.4-arm64/Resources/lib/libRlapack.dylib; LAPACK version 3.12.0 -If you installed `apaquarto` or any other Quarto extension, -one can query their versions as follows:[^already-included] +locale: +[1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8 -[^already-included]: Luckily, the extensions are included in the project folder, -so technically their version is already recorded in the project's files. +time zone: Europe/Berlin +tzcode source: internal -```{.bash filename="Terminal"} -quarto list extensions -``` +attached base packages: +[1] parallel stats graphics grDevices utils datasets methods base -Finally, we know that we installed a $\TeX$ distribution to create the PDF, -so let's find out its version by running: +other attached packages: + [1] rio_1.2.2 doRNG_1.8.6 rngtools_1.5.2 + [4] doParallel_1.0.17 iterators_1.0.14 foreach_1.5.2 + [7] fitPCurve_0.0.0.9000 testthat_3.2.3 prettycode_1.1.0 +[10] colorDF_0.1.7 -```{.bash filename="Terminal"} -quarto check +loaded via a namespace (and not attached): + [1] gtable_0.3.6 ggplot2_3.5.2 htmlwidgets_1.6.4 devtools_2.4.5 + [5] remotes_2.5.0 TruncExpFam_1.2.1 vctrs_0.6.5 tools_4.4.1 + [9] generics_0.1.4 tibble_3.2.1 pkgconfig_2.0.3 R.oo_1.26.0 +[13] data.table_1.17.4 RColorBrewer_1.1-3 desc_1.4.3 lifecycle_1.0.4 ``` -The output is quite long and it might look slightly different for you, -but the relevant sections are the following: -```txt -[✓] Checking tools....................OK - TinyTeX: v2024.09 - Chromium: (not installed) - -[✓] Checking LaTeX....................OK - Using: TinyTex - Path: /home/r155953/.TinyTeX/bin/x86_64-linux - Version: 2024 -``` +## ✍️ Practical Exercise: Create your README! -Of course, all the system dependencies identified until now -may have dependencies on their own. -Use your own judgement to decide when not to dig deeper. -::: +Create your README now as the file `README.md`, located at the top level folder. If you feel stuck, you can have a look at the following examples: @@ -187,15 +136,15 @@ The most important file in this project folder is `Manuscript.qmd` which contain - `data_dictionary.html`: a dictionary to the data file, created using `data_dictionary.qmd` -The folder `_extensions` contains the `apaquarto` extension which is used to typeset the PDF accoording to APA guidelines. +The folder `_extensions` contains the `apaquarto` extension which is used to typeset the PDF according to APA guidelines. ``` ::: ::: {#tip-data .callout-tip collapse="true"} -### Involved Data +### Data ```{.md .code-overflow-wrap filename="README.md"} -## Involved Data +## Data The manuscript analyzes the "palmerpenguins" data set available from . The data is stored as "data.csv" and documented in the file "data_dictionary.html". It is made available under CC0 1.0. ``` @@ -233,7 +182,7 @@ All R packages that this project requires are managed using [`renv`](https://cra install.packages("renv") ``` -Next, one can open a new R session in the root folder of this project and run the following, which should install all required R packages at their recorded versions: +Next, one can open a new R session in the root folder of this project and run the following command, which should install all required R packages at their recorded versions: ```r renv::restore() @@ -241,11 +190,11 @@ renv::restore() `````` ::: -::: {#tip-usage .callout-tip collapse="true"} -### Usage +::: {#tip-how-to-reproduce .callout-tip collapse="true"} +### How to reproduce the results `````{.md .code-overflow-wrap filename="README.md"} -## Usage +## How to reproduce the results The manuscript can be rendered to PDF using the following command: @@ -255,17 +204,7 @@ quarto render Manuscript.qmd `````` ::: -::: {#tip-list-of-results .callout-tip collapse="true"} -### List of Results - -```{.md .code-overflow-wrap filename="README.md"} -## List of Results -- In-text numbers in the section "results": Calculated in the chunk "t-test" within "Manuscript.qmd" -- Table 1: Calculated in the chunk "tbl-descriptive-statistics" within "Manuscript.qmd" -- Figure 2: Calculated in the chunk "fig-bill-length-comparison" within "Manuscript.qmd" -``` -::: ::: {#tip-citation .callout-tip collapse="true"} ### Citation @@ -289,6 +228,6 @@ Of course, you would use the same license for the manuscript that you chose in t ```{.md .code-overflow-wrap filename="README.md"} ## License -The manuscript files `Manuscript.qmd`, `Manuscript.tex`, and `Manuscript.pdf` by Josephine Zerna, Christoph Scheffel, and are available under [CC\ BY-SA\ 4.0](https://creativecommons.org/licenses/by-sa/4.0/) or (at your option) under the [AGPLv3](https://www.gnu.org/licenses/agpl-3.0.html) (or later). For further copyright information, see `LICENSE.txt`. +The manuscript files `Manuscript.qmd`, `Manuscript.tex`, and `Manuscript.pdf` by Josephine Zerna, Christoph Scheffel, and are available under [CC\ BY-SA\ 4.0](https://creativecommons.org/licenses/by-sa/4.0/). For further copyright information, see `LICENSE.txt`. ``` :::