Basic Quarto Reproducible Project File/Folder Structure for the EPR Reports

Creating files and folders for the basic Quarto project having the structure shown in Details and corresponding to reproducible report in EPR. The main .qmd ("quarto markdown") file, wd.subdir.name.qmd, is editable (so do the additional files as well) and used for rendering. The latter can be done directly within the RStudio IDE (by activating the Render button and selecting the desired output format like .html,.pdf or .docx). Alternatively, the rendering can be also performed in the terminal or R console. The .pdf format requires one of the \(\LaTeX\) distributions: {tinytex} (R package), \(\TeX\) Live or \(Mik\TeX\). The complete, above-described, R-environmental setup is also available at Posit Cloud.

Usage

create_qmdReport_proj(
  title = "Project Report",
  path_to_wd = ".",
  wd.subdir.name = "Project_Report",
  citation.style = NULL,
  Rproj.init = TRUE,
  git.init = FALSE
)

Arguments

title: Character string, corresponding to title of the report like the default one: title = "Project Report". It appears on the title page in all formats: .pdf, .html and .docx.
path_to_wd: Character string, setting up the path for working directory, i.e. the parent one, where the project with wd.subdir.name will be stored (see also Details). Alternatively, the file.path can be used to set the path. Default: path_to_wd = ".", referring to actual directory.
wd.subdir.name: Character string, pointing to subdirectory (name, see also path_to_wd), under which the entire report project is stored. This actually corresponds to main project directory. Default: wd.subdir.name = "Project_Report".
citation.style: Character string, referring to citation style used for References and citations in the main .qmd document, which inherits the name from wd.subdir.name. This file is automatically created under the subdirectory. The argument must be added in the form of https url, like citation.style = "https://www.zotero.org/styles/american-chemical-society". All available citation styles can be found at Zotero Citation Style Language Repository. Default: citation.style = NULL, actually corresponding to Chicago Manual of Style (Author-Date).
Rproj.init: Logical, whether to initiate the newly created repository/directory as R-project when working in RStudio. Therefore, default: Rproj.init = TRUE, which triggers the creation of .Rproj file, with the name inherited from wd.subdir.name. If the RStudio is not the preferred IDE of your choice, set Rproj.init = FALSE.
git.init: Logical, if git.init = TRUE, the whole repository/directory becomes (initiated by the use_git) version-controlled, using the git system. PLEASE, FOLLOW THE R CONSOLE PROMPT and select whether to commit your changes immediately or later. Default: git.init = FALSE. This is meant to be an option either for novice users or for those who do not want track changes within the repository by the git. Instead, they prefer cloud storage services like nexcloud/owncloud/ Open Science Framework...etc., supporting version (history of changes) control.

Value

File-folder structure ("tree") for the basic Quarto reproducible report in R, which may be used for data processing and analysis in Electron Paramagnetic Resonance (EPR).

Details

In order to support reproducible research workflow (see References) in EPR from scratch, a central data hub (repository/directory) with a well-defined structure must be available. The one, presented below, is created using the essential dir.create and file.create file-folder R-management functions. For several files (like wd.subdir.name.qmd, header.tex, title.tex, styles.scss and _quarto.yml) customized templates (stored under /extdata/_extensions) are used. Remaining wd.subdir.name.bib and README.Rmd files are generated "ab initio". The wd.subdir.name is everywhere replaced by the actual character string defined by the argument of the same name. Therefore, if we take the default string like "Project_Report", file/directory names turn into Project_Report/Project_Report.ext (.ext \(\equiv\) .qmd, .bib,...etc). Prior to rendering, you may provide information about the author like name:, email:, orcid: and affiliations name: and url:, directly within the main .qmd file. The .bib file is already pre-populated by one example, actually corresponding to {eprscope} package citation. The .bib reference/citation database/file can be extended and organized by the online service called CiteDrive, which can be also used as a web clipper for your references/citations, please refer to the available browser extensions.

path_to_wd
|
|
|—– wd.subdir.name
|
|
|—– wd.subdir.name.qmd..."dynamic" document, main file for the entire
| data processing and analysis workflow
|
|
|—– header.tex...file to set up the .qmd (.tex)
| ==> .pdf conversion, usually containing additional \(LaTeX\)
| packages and visual setup for the .pdf output
|
|
|—– title.tex...file for setting up the title and authors
| in the .pdf output
|
|
|—– styles.scss...style sheet to set up visual style
| of the .html output format
|
|
|—– wd.subdir.name.bib...bibliographic file database of all
| reference-list entries related to the project report
|
|
|—– README.Rmd...general documentation for the entire project/repository
|
|
|—– _quarto.yml...setup for the main wd.subdir.name.qmd file,
| providing different format outputs (.html,.pdf,.docx)
|
|
|—– Input_Data
| |
| |
| |—– EPR_RAW
| | |
| | |
| | |—–...folder dedicated for all raw files from EPR spectrometer,
| | like .dsc/.DSC/.par, .DTA, .YGF
| |
| |
| |—– EPR_ASCII
| | |
| | |
| | |—–...folder dedicated to all additional text files from EPR spectrometer,
| | like .txt, .csv, .asc
| |
| |
| |—– EasySpin_Simulations
| | |
| | |
| | |—–...folder dedicated for output files from the EasySpin(-MATLAB),
| | like .mat or .txt corresponding to EPR simulated spectral data
|
|
|—– _output
|
|
|—– Figures
|
|
|—– Tables
|
|
|—–...+ .html,.pdf,.docx formats and supporting files
of the report, these are created by rendering the main
wd.subdir.name.qmd file (they are not present after
the project is created)

Rendering of the wd.subdir.name.qmd into different formats (.html,.pdf, .docx) is provided by the open-source scientific and technical publishing system (based on pandoc), called Quarto (Allaire JJ et al. (2024) in the References). The main .qmd file represents a "dynamic" document, combining text, code (besides R, also other programming languages like Python, Julia or Observable can be used as well) and outputs (usually, figures and/or tables). Upon rendering, they are nicely combined into shareable above-listed report formats stored under the _output. Among them, the .html output possesses a distinctive position, because it preserves the structure of interactive EPR spectra or tables (see e.g. plot_EPR_Specs3D_interact or readEPR_params_tabs). File-Folder structure, presented above, is flexible and customizable to meet the user's needs, right after its creation by the actual function. For such purpose, please consult the Quarto documentation as well.

References

Alston JM, Rick JA (2021). “A Beginner's Guide to Conducting Reproducible Research”, Bull. Ecol. Soc. Am., 102(2), e01801–14, https://doi.org/10.1002/bes2.1801.

Gandrud C (2020). Reproducible Research with R and RStudio, 3rd edition, Chapman and Hall/CRC. ISBN 978-0-429-03185-4, https://doi.org/10.1201/9780429031854.

National Academies of Sciences, Engineering, and Medicine, Policy and Global Affairs, Committee on Science, Engineering, Medicine, and Public Policy, Board on Research Data and Information, Division on Engineering and Physical Sciences, Committee on Applied and Theoretical Statistics, Board on Mathematical Sciences and Analytics, Division on Earth and Life Studies, Nuclear and Radiation Studies Board, Division of Behavioral and Social Sciences and Education, Committee on National Statistics, Board on Behavioral, Cognitive, and Sensory Sciences, Committee on Reproducibility and Replicability in Science (2019). “Reproducibility and Replicability in Science: Understanding Reproducibility and Replicability”, https://www.ncbi.nlm.nih.gov/books/NBK547546/, National Academies Press (US).

Allaire JJ, Teague C, Scheidegger C, Xie Y, Dervieux C (2024). Quarto. https://doi.org/10.5281/zenodo.5960048, v1.5, https://github.com/quarto-dev/quarto-cli.

Examples

if (FALSE) { # \dontrun{
## creating reproducible report structure
## with the default parameters
create_qmdReport_proj()
#
## creating report with the specified citation style (ACS)
## and with versioning controlled by the `git` within
## the RStudio (Rproj.init = TRUE)
create_qmdReport_proj(
  citation.style =
    "https://www.zotero.org/styles/american-chemical-society",
  git.init = TRUE
)
} # }