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.

Bioconductor already has MultiAssayExperiment for lining up data that is already loaded. biocohort sits one step earlier, before anything is loaded: the manifest, the file paths, the sample sheet, and the record of every manual fix.

Installation

From CRAN:

install.packages("biocohort")

The development version, from GitHub:

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

or from r-universe:

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.

Contributing

See CONTRIBUTING.md for the development workflow.

License

MIT. See LICENSE.