Cohort Objects for Subjects and Samples in Omics Studies

Keeps the subjects, samples, and analysis outputs of a study in one validated object. It starts from a sample manifest with one row per sample, which is read, checked, and split into a subject table and a sample map. Species and assay are plain values in those tables rather than fixed types, so the same object serves any organism and any omics assay. From that object the package writes the sample sheet a pipeline expects, pairs tumor and normal samples on demand, and records where each analysis writes its output so the files can be loaded back in by subject or by pair. Manual corrections are kept in an audit trail. Results can also be translated across genome builds or species, with liftover for coordinates and ortholog mapping for genes.

biocohort

biocohort keeps the subjects, samples, and analysis outputs of a study in one validated object. Species and assays are values in the data, not columns or classes, so the same functions work for any organism and any omics assay.

See the repository root README for the motivation behind this package.

Installation

pak::pak("samuelbharti/biocohort/pkg-r")

r-universe works too:

install.packages("biocohort", repos = "https://samuelbharti.r-universe.dev")

Quick start

A manifest is one long-format table, one row per sample. Four columns carry the shape of the study: subject_id, assay, sample_id, role. Every other column is metadata.

subject_id,species,genotype,assay,sample_id,role
R1,rat,WT,wes,T1,tumor
R1,rat,WT,wes,N1,normal
R2,rat,KO,wes,T2,tumor
R2,rat,KO,wes,N2,normal

library(biocohort)

parsed <- read_manifest("manifest.csv")
cohort <- cohort_new(parsed$subject_tbl, parsed$sample_map)
cohort
#> ── Cohort
#> • 2 subjects (2 rat)
#> • 4 samples (4 wes)

subjects(cohort)
samples(cohort, assay = "wes")
completeness(cohort, wide = TRUE)

Some studies keep one row per subject, with one id column per assay. manifest_from_wide() turns that into the long form first:

id_cols <- data.frame(
  column = c("wes_tumor_id", "wes_normal_id"),
  assay = c("wes", "wes"),
  role = c("tumor", "normal")
)
long <- manifest_from_wide(wide_table, id_cols)

What it does

• Read a manifest. read_manifest() reads CSV, TSV, or Excel, always as text, so an id like 007 keeps its leading zero. validate_manifest() checks it and splits subject-level columns from sample-level ones.
• Hold a cohort. cohort_new() builds a Cohort: one table of subjects, one long table of samples, an optional Study, and a registry of analyses.
• Read it back. subjects(), samples(), completeness(), and sample_pairs() return plain tibbles. cohort_filter() keeps a subset and stays valid.
• Flag or drop for QC. cohort_qc() flags or drops subjects or samples with a required reason. qc_log() reads the audit trail, which survives later cohort_filter() calls.
• Group and contrast. cohort_groups() groups subjects by one or more columns. cohort_contrasts() enumerates every pairwise contrast between those groups.
• Derive a column from cutoffs. cohort_derive() bins an existing numeric column at named cutoffs, so a cutoff is a value passed in, not code. derive_log() reads its provenance.
• Write files for other tools. sample_sheet() writes the sample list a pipeline expects. as_coldata() and join_metadata() carry cohort metadata into a SummarizedExperiment, a Seurat object, or a data frame.
• Track analysis outputs. analysis_spec_new() and load_analysis() resolve a path template per subject or pair, read the files, and record which ones were found.
• Keep a record of manual fixes. apply_corrections() applies a table of documented overrides to a manifest and keeps an audit trail, instead of a value changing quietly inside a script.
• Translate across species. translate() moves a feature table across genome builds or species, through a liftover or an ortholog backend.
• Keep a study in one file. read_study_yaml() builds a cohort from a YAML file that names the study, the manifest, the paths, and the registered analyses.

Documentation

The package website includes:

• Get started: a manifest, a cohort, and a sample sheet, end to end.
• Glossary: key terms and definitions.
• Naming conventions: standard column, object, and file names.

To build the site locally, run from the repository root:

pkgdown::build_site("pkg-r")

Contributing

See CONTRIBUTING.md for the development workflow.

License

MIT