diff --git a/README.md b/README.md index e73663b..d5f0f1b 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,18 @@ -# (UNDER CONSTRUCTION) Quarto-TIER project for scientific article +# (UNDER DEVELOPMENT) Quarto-TIER project for scientific article [![](https://zenodo.org/badge/DOI/10.5281/zenodo.10443127.svg)](https://doi.org/10.5281/zenodo.10443127) +See the template deployment at: + This repository is a template for you who want to develop an project article in [Quarto book](https://quarto.org/docs/books/) and [TIER protocol 4.0](https://www.projecttier.org/tier-protocol/protocol-4-0/) structure. The Quarto book is a tool for reproducible research and scientific writing. It is based on markdown and R language (Python, Julia and Observable), and integrated on RStudio. The TIER protocol 4.0 is a structure for organizing the project files and scripts. +## What you need to know for using this template? + +- If you've read this far, you most likely have some knowledge of RStudio and Git/GitHub (you should have installed it, created an account, and know how to clone repositories). +- Quarto is a relatively recent solution (2021) and you may not have some knowledge about it. If don't, you can check the [Quarto documentation](https://quarto.org/docs/). It is a tool that will possibly replace RMarkdown. If you are familiar with RMarkdown, you will have no problem with Quarto. +- Regardless of your field of study or scientific methodology, I strongly advise you to read [TIER Protocol 4.0 documentation](https://www.projecttier.org/tier-protocol/protocol-4-0/) if you haven't already. After all, everything you need to organize and document your folder and file structure is there. It's an effortless and intuitive read that will save you hours of thought. +- Docker??? + ## Why Quarto book project and not manuscript project? There is a Quarto specific framework for dealing with scientific articles, [Quarto manuscript](https://quarto.org/docs/manuscripts/), and another for books, [Quarto book](https://quarto.org/docs/books/). Both share the same background, and they similar in many aspects, but the Quarto book project is more flexible, allows us to create a more complex structure, greater variability of layouts, and can be adapted to the TIER protocol structure. The Quarto manuscript is still recent and lacks some functionality to make it more interesting. @@ -40,16 +49,41 @@ The structure of the folders and files is as follows: - **all others files**: are the configuration files for the project, from the `.gitignore`, `renv` to the `.Rprofile` file. -Clone this repository to your local PC and change the structure of the \_quarto.yml file as you wish. Maybe ligth and dark [themes](https://quarto.org/docs/output-formats/html-themes.html). -See the template deployment at: +Given that this template was created using Windows 11 Pro (23H2), R 4.4.0, RStudio 2024.04.2 (Build 764) and Quarto 1.5.45, the best way for replicate this repository locally, modify the narrative, and then publish the article as a dynamic document is: -The R environment is already configured by the [renv package](https://rstudio.github.io/renv/articles/renv.html). So, make sure you have renv installed and run renv::restore() to recover the versions used in this project. +1. **Use this template**: -Consider changing your article cover (img/cover.png). +- Click on the green button `Use this template` at the right top of the repository and then `Create a new repository`. Name your repository. If you want to make it public you can publish your article while it is still in development. If private, use the repository for backup and commits and leave it public when publishing the research. -Consider changing the [PDF format](https://quarto.org/docs/output-formats/pdf-basics.html) of your article. +2. **Clone the repository to your local PC**: -How cite this template: +- Get the repository URL by clicking on the green button `Code` and copy the URL. You can use the terminal to clone the repository. Open the terminal in the folder where you want to clone the repository and type `git clone URL`. Replace `URL` with the repository URL. -[![](https://zenodo.org/badge/DOI/10.5281/zenodo.10443127.svg)](https://doi.org/10.5281/zenodo.10443127) +- You can use the RStudio interface to clone the repository. Go to `File > New Project > Version Control > Git` and paste the repository URL. + +3. **Restore the Enviroment Control**: + +- The R environment is already configured by the [renv package](https://rstudio.github.io/renv/articles/renv.html). So, make sure you have `renv` installed and run `renv::restore()`to recover the versions used in this project. + +4. **Edit READMEs**: + +- Modify the READMEs files to correspond with the findings of your investigation. The description found in this repository's READMEs can serve as a guide, but you will undoubtedly need to modify it to fit the needs of your project, folder structure, files, etc. You might want to remove the README file from the `adm` folder. Just make sure to read everything first because you may find something useful for your situation. Of course you can do this during the research or at the end. + +5. **Edit the Quarto configuration**: + +- The Quarto configuration file is the `_quarto.yml` file. This file is located in the root of the `project` folder. You can change the structure of the `_quarto.yml`file with moderation. In this file there are some comments `(#)` that can guide you in the changes. For example, perhaps you want to change the [themes](https://quarto.org/docs/output-formats/html-themes.html) to one that is available. + +- Naturally, you can keep an eye on these modifications as the study progresses and determine which configurations are most suitable for you or require. For example: consider changing your article cover (adm/cover.png) or Consider changing the [PDF format](https://quarto.org/docs/output-formats/pdf-basics.html). + +6. **Edit the narrative**: + +- The narrative is divided into `.qmd` files, each representing a section of the article's narrative in the `project` folder. Insert your narrative inside these files on RStudio/Quarto. Use your creativity to compile what you consider important in the main text of the article and leave intermediate analysis to other scripts. From an operational point of view, your best friend will be the [Quarto documentation](https://quarto.org/docs/guide/). Of course, assuming you know what you are doing in R for your statistical analyses. + +- Commits are your friends. Use them to document the changes you make to the narrative. This will help you keep track of the changes you make and, if necessary, go back to a previous version. Don't forget to push and pull the changes to/from the remote repository. + +7. **Publish the article**: + +- When you are ready to publish the article, you can render the document in RStudio. The `docs` folder will be updated with the new version of the article. You can then push the changes to the remote repository and the article will be available on GitHub Pages. You can activate GitHub Pages in the repository settings, in the `Pages` tab, and select the `main` (or `master`) branch and the `docs` folder. + +- This stage should, in my opinion, be carried out continuously throughout the project. From the outset, make the repository public. Then, when you commit and make changes, test to ensure that the renderings, or compilations, are proceeding as expected. This way, you will have a more reliable and less stressful publication process. diff --git a/project/_quarto.yml b/project/_quarto.yml index b8af2e5..cbf5cb2 100644 --- a/project/_quarto.yml +++ b/project/_quarto.yml @@ -1,8 +1,10 @@ project: - type: book - output-dir: ../docs + type: book + # if change this key, maybe you have a problem with the structure output + output-dir: ../docs + # not change this key if you want to deploy in GitHub Pages execute: - #echo: false + # echo: false warning: false #filters: #- webr @@ -14,7 +16,7 @@ book: date: last-modified date-format: long doi: 10.5281/zenodo.10443128 - cover-image: img/cover.png + cover-image: adm/cover.png downloads: pdf reader-mode: true sidebar: @@ -50,6 +52,7 @@ format: #css: style.css #code-link: true theme: + # See more theme options at: https://quarto.org/docs/output-formats/html-themes.html light: flatly dark: darkly number-sections: true diff --git a/renv.lock b/renv.lock index dc81059..fdbb91f 100644 --- a/renv.lock +++ b/renv.lock @@ -243,6 +243,16 @@ ], "Hash": "5e3c5dc0b071b21fa128676560dbe94d" }, + "renv": { + "Package": "renv", + "Version": "1.0.7", + "Source": "Repository", + "Repository": "RSPM", + "Requirements": [ + "utils" + ], + "Hash": "397b7b2a265bc5a7a06852524dabae20" + }, "rlang": { "Package": "rlang", "Version": "1.1.4", diff --git a/renv/activate.R b/renv/activate.R index 08f2632..7409d8d 100644 --- a/renv/activate.R +++ b/renv/activate.R @@ -2,13 +2,11 @@ local({ # the requested version of renv - version <- "1.0.3" + version <- "1.0.7" attr(version, "sha") <- NULL # the project directory - project <- Sys.getenv("RENV_PROJECT") - if (!nzchar(project)) - project <- getwd() + project <- getwd() # use start-up diagnostics if enabled diagnostics <- Sys.getenv("RENV_STARTUP_DIAGNOSTICS", unset = "FALSE") @@ -33,14 +31,6 @@ local({ if (!is.null(override)) return(override) - # if we're being run in a context where R_LIBS is already set, - # don't load -- presumably we're being run as a sub-process and - # the parent process has already set up library paths for us - rcmd <- Sys.getenv("R_CMD", unset = NA) - rlibs <- Sys.getenv("R_LIBS", unset = NA) - if (!is.na(rlibs) && !is.na(rcmd)) - return(FALSE) - # next, check environment variables # TODO: prefer using the configuration one in the future envvars <- c( @@ -60,22 +50,9 @@ local({ }) - # bail if we're not enabled - if (!enabled) { - - # if we're not enabled, we might still need to manually load - # the user profile here - profile <- Sys.getenv("R_PROFILE_USER", unset = "~/.Rprofile") - if (file.exists(profile)) { - cfg <- Sys.getenv("RENV_CONFIG_USER_PROFILE", unset = "TRUE") - if (tolower(cfg) %in% c("true", "t", "1")) - sys.source(profile, envir = globalenv()) - } - + if (!enabled) return(FALSE) - } - # avoid recursion if (identical(getOption("renv.autoloader.running"), TRUE)) { warning("ignoring recursive attempt to run renv autoloader") @@ -131,21 +108,6 @@ local({ } - heredoc <- function(text, leave = 0) { - - # remove leading, trailing whitespace - trimmed <- gsub("^\\s*\\n|\\n\\s*$", "", text) - - # split into lines - lines <- strsplit(trimmed, "\n", fixed = TRUE)[[1L]] - - # compute common indent - indent <- regexpr("[^[:space:]]", lines) - common <- min(setdiff(indent, -1L)) - leave - paste(substring(lines, common), collapse = "\n") - - } - startswith <- function(string, prefix) { substring(string, 1, nchar(prefix)) == prefix } @@ -648,9 +610,6 @@ local({ # if the user has requested an automatic prefix, generate it auto <- Sys.getenv("RENV_PATHS_PREFIX_AUTO", unset = NA) - if (is.na(auto) && getRversion() >= "4.4.0") - auto <- "TRUE" - if (auto %in% c("TRUE", "True", "true", "1")) return(renv_bootstrap_platform_prefix_auto()) @@ -842,23 +801,24 @@ local({ # the loaded version of renv doesn't match the requested version; # give the user instructions on how to proceed - dev <- identical(description[["RemoteType"]], "github") - remote <- if (dev) + remote <- if (!is.null(description[["RemoteSha"]])) { paste("rstudio/renv", description[["RemoteSha"]], sep = "@") - else + } else { paste("renv", description[["Version"]], sep = "@") + } # display both loaded version + sha if available friendly <- renv_bootstrap_version_friendly( version = description[["Version"]], - sha = if (dev) description[["RemoteSha"]] + sha = description[["RemoteSha"]] ) - fmt <- heredoc(" - renv %1$s was loaded from project library, but this project is configured to use renv %2$s. - - Use `renv::record(\"%3$s\")` to record renv %1$s in the lockfile. - - Use `renv::restore(packages = \"renv\")` to install renv %2$s into the project library. - ") + fmt <- paste( + "renv %1$s was loaded from project library, but this project is configured to use renv %2$s.", + "- Use `renv::record(\"%3$s\")` to record renv %1$s in the lockfile.", + "- Use `renv::restore(packages = \"renv\")` to install renv %2$s into the project library.", + sep = "\n" + ) catf(fmt, friendly, renv_bootstrap_version_friendly(version), remote) FALSE @@ -1081,7 +1041,7 @@ local({ # if jsonlite is loaded, use that instead if ("jsonlite" %in% loadedNamespaces()) { - json <- tryCatch(renv_json_read_jsonlite(file, text), error = identity) + json <- catch(renv_json_read_jsonlite(file, text)) if (!inherits(json, "error")) return(json) @@ -1090,7 +1050,7 @@ local({ } # otherwise, fall back to the default JSON reader - json <- tryCatch(renv_json_read_default(file, text), error = identity) + json <- catch(renv_json_read_default(file, text)) if (!inherits(json, "error")) return(json) @@ -1103,14 +1063,14 @@ local({ } renv_json_read_jsonlite <- function(file = NULL, text = NULL) { - text <- paste(text %||% readLines(file, warn = FALSE), collapse = "\n") + text <- paste(text %||% read(file), collapse = "\n") jsonlite::fromJSON(txt = text, simplifyVector = FALSE) } renv_json_read_default <- function(file = NULL, text = NULL) { # find strings in the JSON - text <- paste(text %||% readLines(file, warn = FALSE), collapse = "\n") + text <- paste(text %||% read(file), collapse = "\n") pattern <- '["](?:(?:\\\\.)|(?:[^"\\\\]))*?["]' locs <- gregexpr(pattern, text, perl = TRUE)[[1]] @@ -1158,14 +1118,14 @@ local({ map <- as.list(map) # remap strings in object - remapped <- renv_json_read_remap(json, map) + remapped <- renv_json_remap(json, map) # evaluate eval(remapped, envir = baseenv()) } - renv_json_read_remap <- function(json, map) { + renv_json_remap <- function(json, map) { # fix names if (!is.null(names(json))) { @@ -1192,7 +1152,7 @@ local({ # recurse if (is.recursive(json)) { for (i in seq_along(json)) { - json[i] <- list(renv_json_read_remap(json[[i]], map)) + json[i] <- list(renv_json_remap(json[[i]], map)) } }