Skip to contents

Build a cohort from a study YAML file

Source: R/study_yaml.R
read_study_yaml.Rd

Reads a study, its manifest, its file paths, and its registered analyses from one YAML file, and returns a ready-to-use Cohort. This turns the handful of calls a study's setup script usually makes (study_new(), read_manifest(), cohort_new(), one analysis_spec_new() per analysis) into one function call and one file to edit.

Usage

read_study_yaml(path, strict = TRUE)

Arguments

path

Path to the study YAML file.

strict

Logical. When TRUE (default), an unknown top-level key is an error. Set FALSE to read a study: block out of a larger configuration file that has other keys of its own.

Value

A Cohort built from the file.

Details

The file has these top-level keys, all optional except manifest:

  • study: fields for study_new() (study_id, title, description, hypotheses, aims, assays, genome_builds, tags).

  • manifest: path to the manifest file, read with read_manifest(). Required. For several files, a list of entries, each with a path and an optional assay that fills the assay column of a file that has none. The files are stacked as read_manifest() stacks them.

  • sample_cols: extra sample-level columns, passed to validate_manifest().

  • species: fills a species column when the manifest has none.

  • paths: a map of root name to path, stored as cohort@paths.

  • corrections: path to a corrections file, applied to the manifest with apply_corrections() before it is validated.

  • analyses: a list of analysis_spec_new() field sets, one per registered analysis.

  • logs: a map with up to three keys, qc, derive, and corrections, each the path of a CSV file that write_study_yaml() wrote. They fill qc_log(), derive_log(), and corrections_log().

Every path (manifest, an entry of paths, corrections, an entry of logs) is resolved relative to the YAML file's own directory unless it is already absolute.

The audit of a corrections file is kept in the cohort, after the audit read from logs, so corrections_log() shows both.

See also

write_study_yaml(), read_manifest(), cohort_new()

Examples

dir <- tempfile()
dir.create(dir)
writeLines(
  c(
    "subject_id,species,assay,sample_id,role",
    "R1,rat,wes,T1,tumor",
    "R1,rat,wes,N1,normal"
  ),
  file.path(dir, "manifest.csv")
)
writeLines(
  c(
    "study:",
    "  study_id: PILOT",
    "  title: Example pilot",
    "manifest: manifest.csv"
  ),
  file.path(dir, "study.yaml")
)

cohort <- read_study_yaml(file.path(dir, "study.yaml"))
cohort
#> 
#> ── Cohort: Example pilot 
#> • 1 subject (1 rat)
#> • 2 samples (2 wes)