S7 Cohort class

An S7 class that keeps the subjects and samples of a study in one object. A Cohort holds a subject table, a long-format sample map, an optional Study, file paths, analysis tables, and a registry of analysis specs.

Usage

Cohort(
  study = NULL,
  subject_tbl = tibble::tibble(subject_id = character(), species = character()),
  sample_map = tibble::tibble(subject_id = character(), assay = character(), sample_id =
    character(), role = character()),
  paths = list(),
  analyses = list(),
  registry = list(),
  cache = list(),
  qc = tibble::tibble(scope = character(), id = character(), action = character(), reason
    = character(), previous_status = character(), timestamp = as.POSIXct(character())),
  derived = tibble::tibble(name = character(), from = character(), level = character(),
    cutoffs = list(), n_derived = integer(), n_na = integer(), timestamp =
    as.POSIXct(character()))
)

Arguments

study

A Study object with project-level context, or NULL.

subject_tbl

A data frame with one row per subject. Required columns: subject_id and species, both character. Common optional columns: sex, strain, genotype, cohort, timepoint, notes. Checked by validate_cohort(). Defaults to an empty table with the two required columns.

sample_map

A long-format data frame with one row per sample. Required columns: subject_id, assay, sample_id, role, all character. A new assay is a new row, never a new column. Checked by validate_cohort(). Defaults to an empty table with the four required columns.

paths

Named list of file paths to data files or result folders. Defaults to an empty list.

analyses

Named list of analysis tables or other data objects. Defaults to an empty list.

registry

Named list of AnalysisSpec objects. Names match spec@name. Defaults to an empty list.

cache

Named list used to memoize loaded analysis data. Cleared by cohort_filter() on every structural change, since it holds state that can always be recomputed. Defaults to an empty list.

qc

A tibble recording every cohort_qc() call (columns scope, id, action, reason, previous_status, timestamp). Unlike cache, this is a durable record and is not cleared by cohort_filter(). Defaults to an empty table.

derived

A tibble recording every cohort_derive() call (columns name, from, level, cutoffs, n_derived, n_na, timestamp). Durable in the same way as qc. Defaults to an empty table.

Value

A Cohort object with the given properties.

Details

Use cohort_new() to build a Cohort. It checks the input types, converts both tables to tibbles, and runs validate_cohort(). Construction itself also checks subject_tbl and sample_map with the same rules, so building a Cohort any other way still enforces the required columns.

Subjects live only in subject_tbl. Use subject() to read one row as a Subject object.

Access properties with the @ operator:

cohort@study         # Study object or NULL
cohort@subject_tbl   # Subject metadata table
cohort@sample_map    # Sample mapping table
cohort@paths         # File paths
cohort@analyses      # Stored analysis results
cohort@registry      # Named list of AnalysisSpec objects
cohort@cache         # Memoization cache
cohort@qc            # QC audit log
cohort@derived       # Derived-column provenance

See also

cohort_new() for object construction, subject() for reading one subject, validate_cohort() for validation details, validate_manifest() for manifest preparation, read_manifest_csv() for loading manifest from file, analysis_register() for registering analyses

Examples

# An empty cohort has the required columns and nothing else.
empty <- Cohort()
empty@subject_tbl
#> # A tibble: 0 × 2
#> # ℹ 2 variables: subject_id <chr>, species <chr>
empty@sample_map
#> # A tibble: 0 × 4
#> # ℹ 4 variables: subject_id <chr>, assay <chr>, sample_id <chr>, role <chr>

# The raw constructor runs the same checks as cohort_new().
cohort <- Cohort(
  subject_tbl = data.frame(subject_id = "R1", species = "rat"),
  sample_map = data.frame(
    subject_id = "R1", assay = "wes", sample_id = "T1", role = "tumor"
  )
)
cohort
#> 
#> ── Cohort 
#> • 1 subject (1 rat)
#> • 1 sample (1 wes)