This glossary defines the terms used across biocohort’s documentation
and code.
Core entities
| Subject |
One organism in a study. Each subject has a unique
subject_id and metadata such as species, genotype, or
cohort. A row in subject_tbl. |
| Species |
The species of a subject, for example “rat”, “mouse”, or “human”.
Species are free-form values, not a fixed list, and are stored lower
case. Required in subject metadata. |
| Cohort |
A group of subjects analyzed together. It combines subject-level
metadata, sample-to-assay mappings, and optional study context. The main
data container in biocohort. |
| Study |
Project-level metadata: study ID, title, hypotheses, aims, assay
types, and genome build versions. Optional context for a cohort. |
Sample and assay concepts
| Sample |
A biospecimen (tissue or cells) collected from a subject for an
assay. Samples have a unique ID, for example a tumor or normal
sample. |
| Assay |
A molecular technique applied to a sample. Assays are free-form
values, not a fixed list, for example wgs,
wes, atac, bulk_rna,
scrna. A new assay is just a new label in the
assay column. |
Role (role) |
The part a sample plays within its assay, for example
"tumor" or "normal". A design with no
tumor/normal split can leave role as NA. |
| Tumor sample |
A sample from tumor tissue or neoplastic cells: a
sample_map row with role = "tumor". |
| Normal sample |
A sample from non-neoplastic tissue or a control: a
sample_map row with role = "normal". A
baseline for somatic mutation calling. |
Sample ID (sample_id) |
A unique ID for one sample, separate from the subject ID. Tells
apart samples from the same subject. |
Pair (pair_id) |
A tumor and normal pairing of two samples of the same assay, for one
subject. Derived on demand from sample_map with
sample_pairs(). The pair_id is
paste0(tumor_sample_id, "__", normal_sample_id). Pairing
works for any assay and is not stored in sample_map
itself. |
Data tables
| subject_tbl |
Subject-level metadata, one row per subject. |
subject_id, species, sex,
strain, genotype, cohort,
timepoint, notes
|
| sample_map |
The long-format map of subjects to samples, one row per sample. A
new assay is a new row, never a new column. |
subject_id, assay, sample_id,
role
|
| completeness_tbl |
Sample counts per assay, one row per subject_id and
assay pair. |
subject_id, assay,
n_samples
|
Registry and analysis
| Analysis registry |
A named set of AnalysisSpec objects that document the
analyses run on a cohort. Each spec has a unique name and describes its
input, method, and output. Stored in cohort@registry. |
| AnalysisSpec |
An S7 object that documents one analysis: its name, description,
input and output type, version, and any other configuration. Used to
track how a result was produced. |
| Analysis artifact |
An output of an analysis: a table, a plot, a model, or any other
object. Stored in cohort@analyses under the analysis name,
and read back later. |
Data organization
| Manifest |
A CSV, or other tabular file, with the metadata and sample IDs for a
study. validate_manifest() and read_manifest()
turn it into subject_tbl and sample_map. |
| Manifest CSV |
A long-format, comma-separated file, one row per sample. Required
columns: subject_id, assay,
sample_id. Optional: role, plus any
subject-level metadata (species, sex, genotype, cohort), which must stay
constant within a subject. |
Genotype and phenotype
| Genotype |
The genetic background of a subject, for example “WT” (wild-type),
“KO” (knockout), or “HET” (heterozygous). Optional. |
| Sex |
The biological sex of a subject: “M” or “F”. Optional. |
| Strain |
The inbred strain or breed of a subject, for example “Fischer 344”
or “B6”. Optional. |
|
Cohort (column) |
A treatment group or condition, for example “Control” or
“Treatment_A”. A subject-level column, distinct from a
Cohort object. |
| Timepoint |
A study visit, age, or collection date, for example “Day 0” or “Week
12”. Optional. |
Object structure
| S7 class |
R’s formal object system (the S7 package). It gives typed, immutable
properties and method dispatch. Study,
Subject, and Cohort are all S7 classes. |
| Property |
A named field on an S7 object, read with @, for example
cohort@subject_tbl or study@title. Set once,
at construction. |
| Subject object |
One subject’s metadata as an S7 object. Built on demand from a
cohort with subject(cohort, id), or directly with
subject_new(). A cohort stores subjects as rows of
subject_tbl, not as objects. |
| Cohort object |
The main data container: subjects, sample mappings, optional study
context, file paths, analyses, and a registry of analysis specs. |
File and path references
| Paths |
A named list in cohort@paths that maps a name, for
example "wes_vcf_dir", to a file path or URL. Used to point
at analysis inputs and outputs. |
Further reading
See Naming conventions for the
standard names for columns, objects, and files.
