Wraps wflow_start to create a standard workflowr
project, then extends it with a themed colour scheme, structured Rmd analysis
pipeline, utility scripts, and a Quarto report template.
Usage
reflow_init(
directory,
name = NULL,
author = "Author Name",
email = NULL,
affiliation = NULL,
orcid = NULL,
website = NULL,
scheme = c("brand", "spectral", "spatial", "omics", "clinical", "methods",
"simulation", "evidence", "platform", "basic", "code", "special", "other"),
depth = c("standard", "minimal", "extended"),
seed = as.integer(format(Sys.Date(), "%Y%m%d")),
github_url = NULL,
existing = FALSE,
overwrite = FALSE,
git = TRUE,
change_wd = rlang::is_interactive(),
user.name = NULL,
user.email = NULL,
open = rlang::is_interactive()
)Arguments
- directory
Character. Path where the project will be created. The existing parent is canonicalized; a linked project root is refused.
- name
Character. Project name (used in titles and navbar). If
NULL, derived from the directory basename.Character. Full name of the primary author.
Character. Author's email address (optional).
- affiliation
Character. Author's institutional affiliation (optional).
- orcid
Character. Author's ORCID iD (optional, format: "0000-0000-0000-0000").
- website
Character. URL to author's or project website (optional).
- scheme
Character. CTTIR v5 family whose colours, icon and fonts style the site: one of
"brand"(default),"spectral","spatial","omics","clinical","methods","simulation","evidence"or"platform". The earlier names"basic","code","special"and"other"remain accepted as aliases of brand, methods, evidence and platform. Seereflow_schemes.- depth
Character. Rmd pipeline depth. One of
"minimal","standard","extended". Defaults to"standard".- seed
Integer. Random seed for workflowr reproducibility. Defaults to
as.integer(format(Sys.Date(), "%Y%m%d")).- github_url
Character. GitHub repository URL (optional). Adds a GitHub link to the navbar.
- existing
Logical. Is the
directoryan existing project or folder? Missing workflowr files are added and present ones left alone. DefaultFALSE. Files that reflowR writes are replaced only withoverwrite = TRUE. Files already in the folder are not committed (seegit).- overwrite
Logical. Replace files that reflowR writes if they already exist in
directory:README.md,_workflowr.yml,analysis/_site.yml,analysis/index.Rmd,analysis/about.Rmdand the theme, icon, script, pipeline and report files. DefaultFALSE: the function then stops before writing anything and lists the files. Other workflowr files are never replaced. Re-theming at a differentdepthleaves the pipeline files of the earlier depth that the new one does not write inanalysis/; remove them yourself if they are no longer needed.- git
Logical. Initialize a git repository (or use the one in an existing folder) and commit the files that this call writes? Other files in
directory, and changes to them, are not committed. If the repository already has staged changes, no commit is made and a warning says so. DefaultTRUE.- change_wd
Logical. Change working directory to the new project? Default
TRUEin interactive sessions.- user.name
Character. Git user name (optional). Passed to
workflowr::wflow_start().- user.email
Character. Git user email (optional). Passed to
workflowr::wflow_start().- open
Logical. Open the project in RStudio after creation? Default
TRUEin interactive sessions.
Details
The function generates both phases in a private staging directory on the destination filesystem before publishing any project files:
Phase 1 – workflowr base: Calls workflowr::wflow_start()
with git = FALSE to create the standard workflowr scaffold without
committing yet.
Phase 2 – reflowR theming: Replaces _site.yml,
index.Rmd, about.Rmd, _workflowr.yml and
README.md with themed versions; adds the
analysis pipeline Rmd files, CSS/SCSS, icon, setup script, utility script,
Quarto report template, and additional subdirectories. If git = TRUE,
initializes git and commits the files written by both phases.
If any of the files that Phase 2 writes already exists in directory
before the call, for example the README or _site.yml of an existing
workflowr project or the files of an earlier call, the function stops before
writing anything and lists them. These preflight refusals leave the project
unchanged. Set overwrite = TRUE to replace them with the
reflowR versions. It also stops before writing anything if one of these
files, or the folder it goes in, is read-only. Managed file and directory
links are refused. Unrelated data and existing workflowr files outside the
themed replacement set are not copied or replaced.
A generation error leaves the project unchanged. Publication backs up old
files, preserves their observed permission modes, and restores them if a
rename fails. If recovery itself fails, a reflow_init_recovery_error names
the retained backup directory in recovery_path; inspect it before retrying.
This is synchronous recovery, not a crash-atomic transaction or protection
against concurrent writers. ACLs and ownership are not copied.
Git operations occur only after successful file publication. Existing staged
changes prevent a commit. A failed add/commit restores the previous index
and leaves the generated project available for manual commit. Linked Git
metadata requires git = FALSE. The operation needs a writable existing
ancestor for its temporary staging directory.
See also
wflow_start for the underlying project creation,
wflow_build to render Rmd files,
wflow_publish to commit + build + commit,
reflow_schemes and reflow_presets for available options.
Examples
# A clinical project with the three-step pipeline, in a temporary folder
project <- file.path(tempdir(), "my_project")
reflow_init(
directory = project,
author = "Your Name",
email = "you@example.com",
scheme = "clinical",
depth = "minimal",
git = FALSE,
change_wd = FALSE,
open = FALSE
)
#>
#> ── Creating reflowR project: "my_project" ──────────────────────────────────────
#> ℹ Scheme: "clinical" | Depth: "minimal"
#>
#> ── Phase 1: workflowr scaffold ──
#>
#> ── Phase 2: reflowR theming ──
#>
#> → Creating directory structure...
#> → Generating themed _site.yml...
#> → Generating theme CSS/SCSS...
#> → Adding scheme icon...
#> → Configuring workflowr seed...
#> → Generating R scripts...
#> → Generating code library...
#> → Generating 3 analysis Rmd files...
#> → Generating index and about pages...
#> → Generating Quarto report template...
#> → Generating README...
#>
#> ── Done! ──
#>
#> ✔ Project created at /tmp/Rtmp5ObUUD/my_project
#> ℹ Scheme: "Clinical science" | Pipeline: "Minimal (3 steps)"
#>
#> ℹ Next steps:
#> 1. Open my_project.Rproj in RStudio
#> 2. Place your data in data/raw/
#> 3. Render and publish with the commands below
#> workflowr::wflow_build(project = "/tmp/Rtmp5ObUUD/my_project")
#> workflowr::wflow_publish("/tmp/Rtmp5ObUUD/my_project/analysis/*.Rmd", message = "Build", project = "/tmp/Rtmp5ObUUD/my_project")
list.files(file.path(project, "analysis"))
#> [1] "01_read_data.Rmd" "02_eda.Rmd" "03_report.Rmd" "_site.yml"
#> [5] "about.Rmd" "index.Rmd" "license.Rmd" "theme.css"
# In a real project, continue with the standard workflowr commands, e.g.
# workflowr::wflow_build(project = project)
# workflowr::wflow_publish(file.path(project, "analysis", "*.Rmd"),
# project = project)
unlink(project, recursive = TRUE)