diff --git a/_quarto.yml b/_quarto.yml index 4ead6ab..c7f872f 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -48,12 +48,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 # Begin Format 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 18b4e4b..254deab 100644 --- a/make-readme.qmd +++ b/make-readme.qmd @@ -8,85 +8,73 @@ 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** + +- [ ] 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? + +**Computational Requirements / Dependencies** -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. +- [ ] What software needs to be installed to run the analysis? + +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. +(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. +indicate the approximate runtime. -@nte-dependencies provides more information -on determining the dependencies of an R project. +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.* -### Usage +**How to reproduce the results** -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. +- [ ] Provide step-by-step instructions that are necessary to reproduce all reported results. -### List of Results +Is there a master script or a particular order in which any scripts need to be executed? -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. +**Citation** -### Citation +- [ ] 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 recommended way to cite this project? -Is there a published article associated with it -that you would like to have cited? +**License** -### License +- [ ] Under which licenses are the works in this project folder available? -Under which licenses are the works in this project folder available? -## Create It! -Create your README now as the file `README.md`. +## Identifying R Dependencies -::: {#nte-dependencies .callout-note} -### Identifying R Dependencies +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 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] +- The exact version of R +- All packages and their versions that you loaded in your project +- (optionally) Further system dependencies -[^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). +### R & Package 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: +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: ```{.r filename="R Console"} # Find all R package dependencies @@ -95,80 +83,46 @@ deps <- renv::dependencies()$Package |> pak::pkg_deps(dependencies = NA) |> getElement("package") -# Identify their system dependencies -pak::pkg_sysreqs(deps) -``` +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!* -The output may look like the following: +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: ```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 -``` +> sessionInfo() +R version 4.4.1 (2024-06-14) +Platform: aarch64-apple-darwin20 +Running under: macOS 15.5 -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: +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 -```{.bash filename="Terminal"} -make --version -pandoc --version -git --version -``` +locale: +[1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8 -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. +time zone: Europe/Berlin +tzcode source: internal -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 -``` +attached base packages: +[1] parallel stats graphics grDevices utils datasets methods base -If you installed `apaquarto` or any other Quarto extension, -one can query their versions as follows:[^already-included] +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 -[^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 +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 ``` -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 -``` +## ✍️ Practical Exercise: Create your README! -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 -``` - -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: @@ -191,10 +145,10 @@ The folder `_extensions` contains the `apaquarto` extension which is used to typ ::: ::: {#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. ``` @@ -232,7 +186,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() @@ -240,11 +194,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: @@ -254,17 +208,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 @@ -288,7 +232,7 @@ 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`. ``` :::