API reference: c4.cohort

Per-cohort data access, driven by the data catalog (catalog.yaml).

from c4.cohort import cohort

demo = cohort("demo")                       # prints what's available
pheno = demo.load("pheno")                  # DataFrame with patient_id first
df = demo.load("pheno", "pcs", "hla.hlahd") # several tables, merged on patient_id
hla = demo.load("hla.hibag.raw", panel="african")
vcf = demo.path("dna.imputed", chrom=6)     # genetic data: a path, not a DataFrame
demo.describe("OS_mo")                      # data dictionary lookup
demo.check()                                # report missing files / ID problems

Every loaded table gets a patient_id column, looked up through the cohort's id_map from whatever ID type the table uses (exome, array, imputed). Merging is therefore always a join on patient_id.

Cohort

entry(name)

Look up a catalog entry by dotted name, following default: links.

path(name, **params)

Path to a data file, e.g. demo.path("dna.imputed", chrom=6).

paths(name)

Every path a templated entry can take, keyed by parameter value, e.g. demo.paths("dna.imputed") -> {1: .../chr1.dose.vcf.gz, ...}.

id_map()

The cohort's patient_id / exome_id / array_id / imputed_id table.

dropped_patients()

patient_ids marked drop=1 in the id_map (empty if there is no drop column).

sample_id_type(dna)

ID type of the sample names in a dna: entry: its id: {type: ...} if set, otherwise the entry's key (dna.imputed -> imputed_id).

samples(dna, keep_dropped=False)

Sample names of a dna: entry's patients, as they appear in its files, leaving out patients marked drop=1 unless keep_dropped. Use it to subset a VCF, e.g. bcftools view -S.

load(*names, how='left', qc_note=True, keep_dropped=False, verbose=True, **params)

Load one or more tables. Several names are merged on patient_id.

Parameters:

Name	Type	Description	Default
names	str	Catalog names, e.g. "pheno", "pcs", "hla.hlahd", "hla.hibag.raw". A name with a default: (like "pheno") loads its default entry.	()
how	str	Join type when merging, starting from the first table ("left" keeps every row of the first table).	'left'
qc_note	bool	Add the id_map's qc_note column, when the cohort has one.	True
keep_dropped	bool	Keep patients marked drop=1 in the id_map (they are removed by default), and add the id_map's drop column.	False
verbose	bool	Print a merge report and notes about unlinked or dropped rows.	True
params	object	Template values, e.g. panel="african". Each is applied to the tables whose path uses it.	{}

Raises if a table being merged has more than one row per patient.

describe(*columns, table='pheno')

Print data dictionary definitions for columns of table.

check(verbose=True)

Check every catalog entry: files exist, tables have their ID column, and the id_map links cleanly. Returns a list of problems (empty if none).

cohort(name, catalog=None, show=True)

Open a cohort by name or alias (case-insensitive).

Parameters:

Name	Type	Description	Default
name	str	Cohort name or alias, e.g. "demo" or "DEMO".	required
catalog	str | Path | dict | None	Catalog path or already-loaded catalog dict. Defaults to $C4_CATALOG, then the catalog.yaml shipped with the package.	None
show	bool	Print the table of available data.	True

list_cohorts(catalog=None, kind=None)

Cohort names in the catalog, optionally only those of one kind: (cohort or reference).

resource_path(name, catalog=None)

Path to a shared reference file listed under resources: in the catalog.

load_catalog(path=None)

Read the catalog from path, $C4_CATALOG, or the packaged catalog.yaml.

$C4_DATA_ROOT overrides the catalog's root. A relative root in the file is taken relative to the catalog file itself.