Open a job, creating it from its template if needed

Finds the study root from dir, creates the job with add_job when it does not exist, and opens it in the editor. An existing job is opened as it stands, never overwritten.

Usage

open_job(prefix, subject, type, dir = NULL, qualifier = NULL)

Arguments

prefix: Job type: one of the prefixes reported by template_list, or a template's full name as reported in its name column, e.g. "dc.trends"; the dash spelling "dc-trends" is accepted too. A full name carries the qualifier, so qualifier must then be left NULL.
subject: Grouping topic for the job set, e.g. "death" or "cohort". A subject names a statistical endpoint only when the job analyses one. Your choice: there is no list of valid values, and every job of one analysis should share it (see Details). Must match ^[A-Za-z0-9_]+$: . separates the filename's fields, and - separated them in names before 2026-10, so neither may appear here.
type: The analysis type the job's set belongs to, e.g. "hz". Your choice, like subject, and shared the same way. Must match ^[A-Za-z0-9_]+$, for the same reason as subject.
dir: Character. Any directory inside the study. NULL, the default, starts from the working directory, and is an error outside a study.
qualifier: Job type within the prefix, e.g. "trends" for dp. Required only where a prefix carries more than one template; omitting it there is an error naming the choices, never a silent pick. Restricted to [A-Za-z0-9_]+, because . separates the filename's fields.

Value

The path to the job file, invisibly.

Details

The study root is the nearest directory at or above dir holding _study.yml, so this can be called from anywhere inside a study. Naming, prefix and qualifier rules are those of add_job. A job scaffolded before 2026-10, named <subject>-<type>-<prefix>[-<qualifier>].qmd, is found and opened under that name. So is a job scaffolded under a template's name before a rename, such as graphs/dp.trends.<subject>.<type>.qmd for dc.trends, whichever of the two names the call uses. The editor is opened only in an interactive session.

Examples

root <- file.path(tempdir(), "open-job-example")
suppressMessages(hvtiRutilities::study_setup(
  root, study = "Example", study_tracker_id = 1L, renv = FALSE
))
#> Study: /tmp/RtmpcLEZJZ/open-job-example
#> 
#> [x] _study.yml — study: Example
#> [ ] renv.lock — no renv.lock; run renv::init() in the study project
#> [ ] manifest.yaml — no manifest.yaml; register_data() creates it
#> [ ] dataset — no default dataset registered; run register_data()
#> [ ] provenance — no .qmd/.Rmd sources found; 0 sidecars
#> 
#> 0 .R  |  0 .qmd/.Rmd  |  0 .sas  |  0 provenance sidecars
open_job(prefix = "ac", subject = "death", type = "eda", dir = root)
unlink(root, recursive = TRUE)