--- title: "Getting Started with SCIproj" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Getting Started with SCIproj} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` ## What is a research compendium? A **research compendium** is a self-contained collection of data, code, and documentation that accompanies a research project. By structuring a project as an R package, you gain: - a standard, well-understood directory layout, - built-in dependency management via `DESCRIPTION`, - documentation infrastructure (`roxygen2`, vignettes), - testing infrastructure (`testthat`), - easy sharing and installation via GitHub. SCIproj automates the creation of such a compendium, adding opinionated defaults for reproducible workflows (`targets`), dependency snapshots (`renv`), and FAIR-compliant metadata (`CITATION.cff`). ## Getting started Install SCIproj from GitHub: ```{r install, eval = FALSE} # install.packages("remotes") remotes::install_github("saskiaotto/SCIproj") ``` Create a new project with a single call: ```{r basic, eval = FALSE} library(SCIproj) create_proj("~/projects/my_analysis") ``` This creates a fully scaffolded research compendium with `renv` and `targets` enabled by default. ### Customizing the call ```{r custom, eval = FALSE} create_proj("~/projects/baltic_cod", add_license = "MIT", license_holder = "Jane Doe", orcid = "0000-0001-2345-6789", use_docker = TRUE, use_git = TRUE ) ``` Directory names with underscores or hyphens are fine --- the R package name in `DESCRIPTION` is automatically sanitized (e.g., `baltic_cod` becomes `baltic.cod`). ## IDE support SCIproj works with RStudio, Positron, VSCode, and terminal R sessions. By default, `create_proj()` sets your working directory to the new project (`setwd_to_proj = TRUE`) so you can start working immediately. Three parameters control post-creation behavior: - `setwd_to_proj` (default `TRUE`): whether the current session's working directory is switched to the new project. Set to `FALSE` for batch workflows where you create multiple projects in sequence and want to stay in your current directory. - `use_rproj` (default `TRUE`): whether an `.Rproj` file is created. Set to `FALSE` for projects used exclusively in Positron, VSCode, or similar IDEs that don't rely on `.Rproj` files. - `open_proj` (default `FALSE`): if `TRUE`, opens the new project in a fresh RStudio or Positron session. In that case, the current session keeps its original working directory. ## Project structure After creation, the project directory looks like this: ``` your-project/ ├── DESCRIPTION # Project metadata, dependencies, and author info (with ORCID). ├── README.Rmd # Top-level project description. ├── your-project.Rproj # RStudio project file (if use_rproj = TRUE, default). ├── CITATION.cff # Machine-readable citation metadata for FAIR compliance. ├── CONTRIBUTING.md # Contribution guidelines. ├── LICENSE.md # Full license text (here: MIT). ├── NAMESPACE # Auto-generated by roxygen2 (do not edit by hand). │ ├── data-raw/ # Raw data files and pre-processing scripts. │ ├── clean_data.R # Script template for data cleaning. │ ├── DATA_SOURCES.md # Data provenance: source, license, DOI, download date. │ └── ... │ ├── data/ # Cleaned datasets stored as .rda files. │ ├── R/ # Custom R functions and dataset documentation. │ ├── function_ex.R # Template for custom functions. │ ├── data.R # Template for dataset documentation. │ └── ... │ ├── analyses/ # R scripts or R Markdown/Quarto documents for analyses. │ ├── figures/ # Generated plots. │ └── ... │ ├── docs/ # Publication-ready documents (article, report, presentation). ├── trash/ # Temporary files that can be safely deleted. │ ├── _targets.R # Pipeline definition for reproducible workflow. ├── renv/ # renv library and settings. ├── renv.lock # Lockfile for reproducible package versions. └── Dockerfile # Container definition for full reproducibility. ``` | Directory / File | Purpose | |---------------------|------------------------------------------------------| | `R/` | Reusable R functions (documented with `roxygen2`) | | `data/` | Cleaned, analysis-ready datasets (`.rda` format) | | `data-raw/` | Raw data files and the script that cleans them | | `analyses/` | Analysis scripts, R Markdown reports, figures | | `docs/` | Manuscripts, presentations, supplementary material | | `trash/` | Temporary files not under version control | | `_targets.R` | Pipeline definition for `targets` | | `CITATION.cff` | Machine-readable citation metadata | | `CONTRIBUTING.md` | Guidelines for collaborators | ## FAIR compliance SCIproj encourages **FAIR** (Findable, Accessible, Interoperable, Reusable) research practices through several built-in features: ### CITATION.cff A [Citation File Format](https://citation-file-format.github.io/) file is created automatically. It includes the project title, author name, version, release date, and optionally a license and ORCID iD. Services like GitHub and Zenodo can parse this file to generate proper citations. ```{r citation, eval = FALSE} create_proj("my_project", license_holder = "Jane Doe", orcid = "0000-0001-2345-6789", add_license = "MIT" ) ``` ### DATA_SOURCES.md When `data_raw = TRUE` (the default), a `DATA_SOURCES.md` template is placed in `data-raw/`. Use it to document the provenance of every dataset: source, URL, DOI, license, download date, and file names. ### ORCID Pass your [ORCID iD](https://orcid.org/) via the `orcid` parameter to embed it in `CITATION.cff`, making your authorship unambiguously machine-readable. ## Workflow with targets By default (`use_targets = TRUE`), SCIproj adds a `_targets.R` pipeline template. The [targets](https://docs.ropensci.org/targets/) package provides: - **Automatic dependency tracking** --- only outdated targets are re-run. - **Caching** --- results are stored in the `_targets/` data store. - **Visualization** --- `tar_visnetwork()` shows the pipeline as a graph. A typical workflow: ```{r targets, eval = FALSE} # 1. Define targets in _targets.R # 2. Inspect the pipeline targets::tar_manifest() targets::tar_visnetwork() # 3. Run the pipeline targets::tar_make() # 4. Read a result targets::tar_read(my_result) ``` Edit `_targets.R` to define your data-loading, analysis, and reporting steps. Each step is a target that depends on upstream targets and R functions in `R/`. ## Dependency management with renv By default (`use_renv = TRUE`), SCIproj initializes [renv](https://rstudio.github.io/renv/) with the `"explicit"` snapshot type. This means renv discovers dependencies from `DESCRIPTION` rather than scanning all R files, which is the recommended approach for package-based compendia. Key commands: ```{r renv, eval = FALSE} renv::status() # check if lockfile is in sync renv::snapshot() # update the lockfile after adding packages renv::restore() # reinstall packages from the lockfile ``` The `renv.lock` file should be committed to version control so collaborators can reproduce your exact package versions. ## Optional features ### Docker Set `use_docker = TRUE` to add a `Dockerfile` and `.dockerignore`. The Dockerfile provides a template for building a container that reproduces your computational environment, independent of the host system. ### GitHub and CI Set `create_github_repo = TRUE` to create a GitHub repository (requires a configured `GITHUB_PAT`). Add `ci = "gh-actions"` to include a GitHub Actions workflow for automated R CMD check on push. ```{r github, eval = FALSE} create_proj("my_project", use_git = TRUE, create_github_repo = TRUE, ci = "gh-actions" ) ``` ### Licenses Choose from `"MIT"`, `"GPL"`, `"AGPL"`, `"LGPL"`, `"Apache"`, `"CCBY"`, or`"CC0"` via the `add_license` parameter. The selected license is applied to `DESCRIPTION` and recorded in `CITATION.cff`. ### testthat Set `testthat = TRUE` to add testing infrastructure (`tests/testthat.R` and `tests/testthat/`). Writing tests for your analysis functions helps catch regressions early. ### Makefile Set `makefile = TRUE` to add a `makefile.R` script as an alternative to `targets` for orchestrating your workflow. ## Typical development cycle 1. **Create the project** ```r SCIproj::create_proj("~/projects/my_study", add_license = "MIT", license_holder = "Your Name") ``` 2. **Start working in the project.** Your working directory is already set to the new project (`setwd_to_proj = TRUE` by default), so you can continue immediately. For a dedicated project session, either open the `.Rproj` file manually (RStudio) or the project folder as a workspace (Positron/VSCode) — or pass `open_proj = TRUE` to `create_proj()` to open a new IDE session automatically. 3. **Add raw data** to `data-raw/` and document it in `DATA_SOURCES.md`. 4. **Write cleaning code** in `data-raw/clean_data.R`; save cleaned data to `data/` with `usethis::use_data()`. 5. **Write analysis functions** in `R/` and document them with `roxygen2`. 6. **Define the pipeline** in `_targets.R` to connect data, functions, and reports. 7. **Run `targets::tar_make()`** to execute the pipeline. 8. **Write reports** in `analyses/` using R Markdown or Quarto, reading results with `targets::tar_read()`. 9. **Snapshot dependencies** with `renv::snapshot()` before sharing. 10. **Push to GitHub** and let CI run `R CMD check` automatically.