API reference: c4.genotypes

Dosages for a handful of variants, pulled from per-chromosome VCFs.

from c4.genotypes import get_dosages, write_dosages

dos, info = get_dosages("demo", ["6:32659999:A:G", "4:1455432:A>T"])
write_dosages(dos, info, "my_snps.tsv")

dos has one row per VCF sample, with patient_id when the cohort's id_map links it, and one column per requested variant. Each column counts copies of the ALT allele as you wrote it: if the VCF stores the alleles the other way round, the dosage is flipped (2 - DS). info has one row per variant: the VCF record it matched, and any warning or error.

Variants can be written chr:pos:ref:alt, chr:pos:ref>alt, or chr:pos (any allele at that position). A "chr" prefix is optional. Variants in another genome build are lifted over first.

survival and PRS use the same extraction (extract_dosages).

get_dosages(cohort, variants, build=None, dna='imputed', dosage=True, chain_file=None, keep_dropped=False, catalog=None)

Dosages for a few variants in one of a cohort's genetic data sets.

Parameters:

Name	Type	Description	Default
cohort	str | Cohort	Cohort name (e.g. "demo") or a Cohort from c4.cohort.cohort().	required
variants	list	Variant strings: chr:pos:ref:alt, chr:pos:ref>alt or chr:pos.	required
build	Optional[str]	Genome build of variants. Defaults to the VCFs' build; otherwise they are lifted over with a chain from the catalog.	None
dna	str	Which dna: entry of the cohort to read, e.g. "imputed".	'imputed'
dosage	bool	Use the DS field; otherwise dosage is derived from GT.	True
chain_file	Optional[str | Path]	Liftover chain to use instead of the catalog's.	None
keep_dropped	bool	Keep samples of patients marked drop=1 in the id_map.	False
catalog	str | Path | dict | None	Catalog path or dict, when cohort is a name.	None

Returns:

Type	Description
tuple	(dosages, info). dosages has patient_id (when the cohort has an
tuple	id_map), the VCF sample ID column (<dna>_id) and one column per
tuple	variant. info has one row per variant: variant, vcf_id, status,
tuple	warning, error.

write_dosages(dosages, info, path)

Write dosages to path and the per-variant table next to it. Returns both paths.

extract_dosages(variants, vcfs, vcf_build, build=None, dosage=True, chain_file=None, workdir=None, sample_column='sample_id')

Parse variants, liftover if needed, extract dosages, align alleles.

Parameters:

Name	Type	Description	Default
variants	list	Variant strings (see the module docstring for formats).	required
vcfs	dict	{chromosome: VCF path}, e.g. {"6": ".../chr6.vcf.gz"}. VCFs must be indexed.	required
vcf_build	str	Genome build of the VCFs, e.g. "b38".	required
build	Optional[str]	Genome build of variants. Defaults to vcf_build.	None
dosage	bool	Use the DS field; otherwise dosage is derived from GT.	True
chain_file	Optional[str | Path]	Liftover chain from build to vcf_build. Required when the builds differ.	None
workdir	Optional[str | Path]	Where to write the small per-chromosome region files. Defaults to a temporary directory.	None
sample_column	str	Name of the sample ID column in the result.	'sample_id'

Returns:

Type	Description
tuple	(dosage_df, variant_meta). dosage_df has columns [sample_column] plus
tuple	one per input variant string, with dosage always coded relative to
tuple	the input ALT allele; it is None if no chromosome could be queried
tuple	(e.g. every liftover failed). variant_meta maps each input string to
tuple	{'vcf_id', 'warning', 'error'}.

parse_variant(variant_str)

Parse a variant string into components.

Accepted formats

chr:pos — position only, alleles unknown chr:pos:ref>alt — full specification (arrow-delimited alleles) chr:pos:ref:alt — full specification (colon-delimited alleles)

CHROM is always normalised to 'chrN' format.

variant_info(variant_meta)

One row per variant: matched VCF record, ok/error status, warning and error.