Command line¶

Installing c4 (pip install -e .) gives you the c4 command. c4 --help lists the commands, and c4 <command> --help shows every option. The full reference at the bottom of this page is generated from that same help text.

In the examples, replace COHORT with a cohort name from the data catalog.

Command	What it does
`dosages`	Dosages for a few variants from a cohort's VCFs, with `patient_id`
`survival`	Cox PH survival test per variant
`prs`	Survival test of a weighted polygenic risk score
`clump`	LD-clump GWAS summary statistics against a VCF or PLINK panel
`finemap avail`, `finemap setup`	Build a per-session LD reference panel from a cohort's genetic data
`finemap loci`	Regions to fine-map, from one or more GWAS
`finemap run`	SuSiE-RSS on each locus, with LD from a `finemap setup` panel
`finemap visualize`	Plot fine-mapped loci: p-values, PIPs and genes
`concordance`	Genotype concordance between samples in two VCF/PLINK files
`vcf-overlap`	Variants shared by two VCFs
`genotype-correlation`	Per-sample Pearson r between two VCFs' dosages
`liftover`	Lift a file of variant positions to another genome build
`split-hla`, `merge-hla`	Switch HLA tables between `A` and `A_1`/`A_2` columns
`hla_concordance`	Per-sample, per-gene concordance between two HLA call files
`convert-p`	Not yet implemented (planned: P-group conversion)

External tools needed on your PATH: bcftools for dosages, survival, prs, concordance, vcf-overlap and genotype-correlation; plink2 (or PLINK 1.9) for clump; plink2 for finemap setup; R with susieR for finemap run (on C4: module load r).

Writing variants

Variants are chr:pos:ref:alt, chr:pos:ref>alt or chr:pos; the chr prefix is optional. Quote anything with >: unquoted, the shell treats it as a redirect and writes to a file named after the ALT allele.

Variants, survival and PRS¶

# Dosages for a few SNPs: one row per sample, plus snps.variants.tsv
c4 dosages --dataset COHORT --variants 6:32659999:A:G --variant-list more.txt -o snps.tsv

# One variant: prints a results table (add --km-plot km.png for a Kaplan-Meier plot)
c4 survival --dataset COHORT --variants '4:1455432:A>T' --survival OS

# Many variants in b37 (lifted to the VCFs' build automatically), saved to files
c4 survival --dataset COHORT --variant-list vars.txt --variant-build b37 --survival PFS \
    -o results.tsv --save-dosages dosages.tsv

# PRS: weights are a headerless 3-column TSV (variant_id, effect_allele, effect)
c4 prs --dataset COHORT --weights prs.tsv --survival OS --quantiles 5 -o prs_OS/

Dosage counts the ALT allele as you wrote it. If the VCF has the alleles the other way round, the dosage is flipped and the variant gets a warning. See Extracting variants for how matching works.
Covariates, endpoints and which VCFs to use come from the cohort's survival: block in the catalog.
--variant-build lifts variants with the catalog's chain files; give --chain-file to use another.
prs writes prs.log, individual_prs.tsv, prs_variants.tsv and plots into its output directory. The weights file must have exactly three columns; anything else is an error naming the line.
How the Cox models are set up (complete cases, PC standardisation, what the HR is per): c4.survival.

Clumping¶

c4 clump results.PHENO.glm.logistic.hybrid panel.chr6.vcf.gz -o out/chr6 \
    --chr 6 --kgp-pops EUR --clump-p1 1e-5 --clump-r2 0.2 --clump-kb 500

GWAS and panel variants are matched on chromosome, position and alleles (REF/ALT swaps allowed), whatever ID scheme each uses.
For a per-chromosome panel, give one chromosome's file; the others are found by substituting into its chr<N>.
--kgp-pops subsets a 1000 Genomes panel to populations or super-populations.
Writes {out}.clumps, {out}.lead.tsv (index variants with their GWAS stats), {out}.dropped.tsv (unmatched variants, with a reason) and {out}.log.
plink2's --memory defaults to half of the SLURM or cgroup job limit, so it isn't killed on shared nodes. If the plink2 build has no --clump, PLINK 1.9 is used.

Fine-mapping¶

c4 finemap avail                                               # genetic data you can build a panel from
c4 finemap setup --dna demo.imputed --panel-name demo --chr 6  # LD panel in $TMPDIR/demo/
c4 finemap loci results.PHENO.glm.linear --build b38 -o loci.tsv
c4 finemap run results.PHENO.glm.linear --loci loci.tsv --panel demo --build b38 --in-sample -o fm/pheno
c4 finemap visualize fm/pheno -o plots/                        # one plot per locus with a credible set

See Fine-mapping for how each step works, the output files, and how to check the results.

Genotype QC¶

# Concordance between every sample pair across two files, plus within each file
c4 concordance array.vcf.gz exome.vcf.gz concordance.tsv --within

# Only specific pairs (file-1 ID, file-2 ID per line)
c4 concordance array.vcf.gz exome.vcf.gz concordance.tsv --between-pairs pairs.tsv

# Shared variants (CHROM POS), e.g. to subset both files first
c4 vcf-overlap array.vcf.gz imputed.vcf.gz overlap.tsv --remove-dup

# Per-sample correlation of dosages (DS) between two VCFs
c4 genotype-correlation vcf1.vcf.gz vcf2.vcf.gz corr.tsv --dosage --samples map.tsv

Concordance output: each between-file pair gets two rows. - all_exclHomRef: sites where the file-2 sample is homozygous reference are left out. - all_inclHomRef: all sites.

P2, P1 and P0 are the share of sites matching on 2, 1 or 0 alleles. Within-file pairs get one row, all. Variants are matched on chromosome, position and alleles; multi-allelic records are left out. On millions of variants it can be slow, so subset to shared positions first.

Correlation matches variants on CHROM, POS, REF and ALT. Without --dosage, genotypes are counted as non-reference alleles, so haploid calls work. --verbose writes the sums needed to combine results across chromosomes.

Liftover of a variant file¶

c4 liftover hg19ToHg38.over.chain variants.bed variants_hg38.bed
c4 liftover hg19ToHg38.over.chain variants.txt variants_hg38.bed --chrom-col 0 --start-col 1

.bed input is 0-based, as BED is. For other files give --chrom-col and --start-col; positions are 1-based (as in VCFs) unless --zero-based.
Output is a 3-column BED file in input order. Rows that can't be lifted go to <output>.unmapped with the reason: not in the new build, mapping to several places, or a region that doesn't lift as one piece.
Uses pyliftover, like the variant liftover above. No R needed.

HLA¶

c4 split-hla calls.csv calls_split.tsv --genes A,B --columns ID --digits 4
c4 merge-hla calls_split.tsv calls.tsv
c4 hla_concordance wes.csv imputed.csv --file1_id seqID --file2_id genotype_id -o hla_concordance.tsv

See HLA calls for these commands and the Python HLA tools.

Full reference¶

Generated from c4 <command> --help.

c4¶

C4 toolkit for various commands.

Usage:

c4 [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--install-completion`	boolean	Install completion for the current shell.	None
`--show-completion`	boolean	Show completion for the current shell, to copy it or customize the installation.	None
`--help`	boolean	Show this message and exit.	`False`

Subcommands

clump: LD-clump GWAS summary statistics using a VCF or PLINK genotype panel.
concordance: Calculate genotype concordance between two variant call files.
convert-p: [Not yet implemented] Convert HLA alleles to P-group designations.
dosages: Extract dosages for a few variants from a cohort's VCFs.
finemap: Fine-mapping: LD reference panels built from the data catalog.
genotype-correlation: Compute per-sample Pearson r and r² between dosage vectors across two VCFs.
hla_concordance: Compare HLA typing between two files.
liftover: Lift variant positions in a file to another genome build.
merge-hla: Merge separate allele columns back into HLA genotype columns.
prs: Test a weighted polygenic risk score (PRS) for survival association.
split-hla: Split HLA genotype columns into separate allele columns.
survival: Run Cox PH survival analysis for one or more variants.
vcf-overlap: Find overlapping variants between two VCF files.

clump¶

LD-clump GWAS summary statistics using a VCF or PLINK genotype panel.

GWAS and panel variants are harmonized to CHROM:POS:REF:ALT before clumping (matching on the unordered allele pair, so REF/ALT swaps still match). Variants that can't be matched are reported with a reason.

Per-chromosome panels: pass any one chromosome's file (e.g. ALL.chr3.phased.vcf.gz) and the files for the other GWAS chromosomes are found by substituting into the 'chrN' token.

Writes {out}.clumps (plink2 report), {out}.lead.tsv (index variants with their GWAS stats), {out}.dropped.tsv (unmatched GWAS variants) and {out}.log.

Examples:

c4 clump results.PHENO.glm.logistic.hybrid 1kg_EUR -o clumped/pheno

c4 clump results.assoc 1kg.chr6.vcf.gz -o out/chr6 --chr 6 --kgp-pops EUR,YRI \
    --clump-p1 1e-5 --clump-r2 0.2 --clump-kb 500

Usage:

c4 clump [OPTIONS] GWAS GENO

Options:

Name	Type	Description	Default
`--out`, `-o`	path	Output prefix	_required
`--chr`	text	Only clump GWAS variants on this chromosome (e.g. 6, chr6, X)	None
`--kgp-pops`	text	Comma-separated 1000 Genomes populations and/or super-populations to subset a KGP panel to (e.g. EUR,AMR,YRI). Can't be combined with --keep.	None
`--keep`	path	Sample ID file to subset the panel to (plink2 --keep format: IID, or FID IID)	None
`--clump-p1`	float	Significance threshold for index variants	`5e-08`
`--clump-p2`	float	Significance threshold for clumped variants	`0.01`
`--clump-r2`	float	LD r² threshold for clumping	`0.1`
`--clump-kb`	float	Clumping window in kb	`250`
`--chrom-col`	text	GWAS chromosome column (default: auto-detect)	None
`--pos-col`	text	GWAS position column (default: auto-detect)	None
`--ref-col`	text	GWAS REF allele column (default: auto-detect)	None
`--alt-col`	text	GWAS ALT allele column (default: auto-detect)	None
`--p-col`	text	GWAS p-value column (default: auto-detect)	None
`--threads`	integer	plink2 --threads	None
`--memory`	integer	plink2 --memory (MiB). Default: half of the SLURM/cgroup job memory limit, if one is found	None
`--plink2`	text	Path to the plink2 executable	`plink2`
`--plink1`	text	Path to PLINK1.9, used for clumping only if the plink2 build has no --clump	`plink`
`--verbose`, `-v`	boolean	Also print each plink command as it runs	`False`
`--help`	boolean	Show this message and exit.	`False`

concordance¶

Calculate genotype concordance between two variant call files.

Example: c4 concordance file1.vcf file2.bed output.tsv --within c4 concordance file1.vcf file2.bed output.tsv --samples1 samples1.txt --samples2 samples2.txt

Computes pairwise concordance between samples in two files. Optionally computes within-file concordance with --within flag.

Each between-file pair gets two rows: all_exclHomRef (sites where the file-2 sample is homozygous reference left out) and all_inclHomRef (all sites). Within-file pairs get one row, labelled "all".

Usage:

c4 concordance [OPTIONS] FILE1 FILE2 OUTPUT

Options:

Name	Type	Description	Default
`--within`, `-w`	boolean	Also compute within-file concordance	`False`
`--samples1`, `-s1`	path	File with sample IDs to use from file1 (one per line)	None
`--samples2`, `-s2`	path	File with sample IDs to use from file2 (one per line)	None
`--between-pairs`, `-b`	path	File containing sample ID pairs to compare between files (tab-separated: file1_ID file2_ID per line).	None
`--help`	boolean	Show this message and exit.	`False`

convert-p¶

[Not yet implemented] Convert HLA alleles to P-group designations.

Planned usage: c4 convert-p input.csv output.csv --genes DRB1 --genes DQB1 --drop

Will read columns like DRB1_1, DRB1_2, DQB1_1, DQB1_2 and add DRB1_1_P, DRB1_2_P, DQB1_1_P, DQB1_2_P. See convert_p_impl in c4/cli.py for the implementation plan.

Usage:

c4 convert-p [OPTIONS] INPUT_FILE OUTPUT_FILE

Options:

Name	Type	Description	Default
`--genes`, `-g`	text	List of gene names (assumes {gene}_1, {gene}_2 columns)	_required
`--sep`, `-s`	text	File separator (default: comma)	`,`
`--drop`	boolean	Remove original allele columns after conversion	`False`
`--p-nom-file`	path	Custom P-group nomenclature file	None
`--help`	boolean	Show this message and exit.	`False`

dosages¶

Extract dosages for a few variants from a cohort's VCFs.

Each column counts copies of the ALT allele as you wrote it; if the VCF has the alleles the other way round, the dosage is flipped. Samples are linked to patient_id through the cohort's id_map.

Examples:

c4 dosages --dataset COHORT --variants 6:32659999:A:G -o hla_snp.tsv

c4 dosages --dataset COHORT --variant-list snps.txt --variant-build b37 -o snps.tsv

Usage:

c4 dosages [OPTIONS]

Options:

Name	Type	Description	Default
`--dataset`, `-d`	text	Cohort name, as listed in the data catalog (c4/catalog.yaml)	_required
`--output`, `-o`	path	Output TSV: one row per sample, one column per variant. How each variant matched goes to NAME.variants.tsv next to it.	_required
`--variants`, `-v`	text	Variant(s) as chr:pos:ref:alt, 'chr:pos:ref>alt' (quote it) or chr:pos. Repeat the flag for several.	None
`--variant-list`	path	File with one variant per line	None
`--variant-build`	text	Genome build of the variants (e.g. b37). Default: the VCFs' build.	None
`--dna`	text	Which genetic data set of the cohort to read (a dna: entry in the catalog)	`imputed`
`--dosage` / `--no-dosage`	boolean	Use the DS dosage field (default) vs GT-derived dosage	`True`
`--chain-file`	path	Liftover chain to use instead of the catalog's	None
`--keep-dropped`	boolean	Keep samples of patients marked drop=1 in the cohort's id_map	`False`
`--help`	boolean	Show this message and exit.	`False`

finemap¶

Fine-mapping: LD reference panels built from the data catalog.

Usage:

c4 finemap [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

Subcommands

avail: List the genetic data sets that can be used as a panel (pass the name as
loci: Define the loci to fine-map from one or more GWAS.
run: Fine-map loci with SuSiE-RSS, using GWAS z-scores and LD from a panel
setup: Build an LD reference panel from a cohort's genetic data in the catalog.
visualize: Plot fine-mapped loci: -log10(p), PIP and genes, one figure per locus.

avail¶

List the genetic data sets that can be used as a panel (pass the name as --dna to c4 finemap setup), and the panels already set up in --dir.

Usage:

c4 finemap avail [OPTIONS]

Options:

Name	Type	Description	Default
`--dir`	path	Where panels are written (default: $TMPDIR)	None
`--help`	boolean	Show this message and exit.	`False`

loci¶

Define the loci to fine-map from one or more GWAS.

Every variant with p < --p gets a window of ±--window; overlapping windows are merged, pooling all traits, so a locus doesn't depend on which trait found it. All variants in a locus are fine-mapped later, whatever their p-value. With --build, windows touching the extended MHC become one MHC locus.

Locus IDs are coordinates (6:31500000-32500000), so they stay the same between runs. Each row also has the lead variant across traits, the number of significant variants, each trait's minimum p, and is_mhc / exceeds_max_width flags. Edit the file, or write your own, to fine-map other regions.

Examples:

c4 finemap loci results.PHENO.glm.logistic.hybrid --build b38 -o loci.tsv

c4 finemap loci te1.tsv te2.tsv --trait TE1 --trait TE2 --build b38 --p 1e-6 --window 1mb -o loci.tsv

Usage:

c4 finemap loci [OPTIONS] GWAS...

Options:

Name	Type	Description	Default
`--out`, `-o`	path	Output TSV of loci	_required
`--build`	text	Genome build of the GWAS positions (b37 or b38), used to merge the MHC into one locus	None
`--p`	float	A locus is built around every variant with p below this	`5e-08`
`--window`	text	Window on each side of a significant variant (e.g. 500kb, 1mb, 250000)	`500kb`
`--max-width`	text	Flag loci wider than this (they are not split)	`3mb`
`--skip-mhc`	boolean	Leave the MHC locus out of the output	`False`
`--trait`	text	Trait name for each GWAS file, in order (repeat the option). Default: from the file name	None
`--trait-col`	text	Column holding the trait, for files with several traits	None
`--chrom-col`	text	GWAS chromosome column (default: auto-detect)	None
`--pos-col`	text	GWAS position column (default: auto-detect)	None
`--p-col`	text	GWAS p-value column (default: auto-detect)	None
`--verbose`, `-v`	boolean	More progress output	`False`
`--help`	boolean	Show this message and exit.	`False`

run¶

Fine-map loci with SuSiE-RSS, using GWAS z-scores and LD from a panel built with c4 finemap setup.

For each locus, every GWAS variant in it (whatever its p-value) is matched to the panel on position and alleles, z is oriented to the panel ALT allele, LD is computed from the panel dosages, and susie_rss is run in R. estimate_s_rss and kriging_rss check that the z-scores fit the LD (allele flips, panel mismatch).

Writes {out}.cs.tsv (one row per credible set, with purity, the lead variant by PIP and by p, and the minimum p), {out}.cs_members.tsv (full GWAS row for every member), {out}.pip.tsv (every variant), {out}.summary.tsv (one row per locus: status, counts, drop reasons, s), {out}.dropped.tsv and {out}.run.json.

If the GWAS was run on the panel's own genotypes (e.g. a GWAS of the demo cohort, with a panel built from demo.imputed), say so with --in-sample: SuSiE then estimates the residual variance, --drop-ambiguous is refused, and loci whose N differs from the panel's sample count, or with kriging flags, get a note in summary.tsv.

Needs R with susieR (on C4: module load r).

Examples:

c4 finemap run results.PHENO.glm.logistic.hybrid --loci loci.tsv --panel kgp_eur --build b38 -o fm/pheno

c4 finemap run demo_gwas.glm.linear --loci loci.tsv --panel demo --build b38 \
    --in-sample --locus 6:31500000-32500000 -o fm/one_locus

Usage:

c4 finemap run [OPTIONS] GWAS

Options:

Name	Type	Description	Default
`--loci`	path	Loci to fine-map: the output of `c4 finemap loci`, or any TSV with chrom, start, end	_required
`--panel`	text	LD panel name, as given to `c4 finemap setup --panel-name`	_required
`--build`	text	Genome build of the GWAS (b37 or b38); must match the panel	_required
`--out`, `-o`	path	Output prefix	_required
`--dir`	path	Where the panel is (default: $TMPDIR)	None
`--locus`	text	Only this locus_id (repeat the option for several)	None
`--n`	float	GWAS sample size. Default: the median OBS_CT/N of each locus's variants	None
`--L`	integer	SuSiE L: maximum number of causal signals per locus	`10`
`--coverage`	float	Credible set coverage	`0.95`
`--min-abs-corr`	float	Purity: credible sets whose minimum	r
`--in-sample`	boolean	The GWAS was run on the panel's own genotypes (not allowed for a reference panel such as kgp)	`False`
`--estimate-residual-variance` / `--fixed-residual-variance`	boolean	Let SuSiE estimate the residual variance. Default: yes with --in-sample, no otherwise	None
`--drop-ambiguous`	boolean	Leave out strand-ambiguous SNPs (A/T, C/G); not allowed with in-sample LD. They are always flagged	`False`
`--max-variants`	integer	Skip loci with more variants than this	`20000`
`--chrom-col`	text	GWAS chromosome column (default: auto-detect)	None
`--pos-col`	text	GWAS position column (default: auto-detect)	None
`--ref-col`	text	GWAS REF allele column (default: auto-detect)	None
`--alt-col`	text	GWAS ALT allele column (default: auto-detect)	None
`--p-col`	text	GWAS p-value column (default: auto-detect)	None
`--z-col`	text	z-score column (default: Z_STAT, Z or T_STAT, else BETA/SE or log(OR)/SE)	None
`--beta-col`	text	Effect size column, used with --se-col	None
`--se-col`	text	Standard error column	None
`--n-col`	text	Per-variant sample size column (default: OBS_CT, N, ...)	None
`--ea-col`	text	Effect allele column (default: A1, EFFECT_ALLELE or ALLELE1, else ALT)	None
`--rscript`	text	Path to Rscript (with susieR installed)	`Rscript`
`--verbose`, `-v`	boolean	Also print each Rscript command, and tracebacks for failed loci	`False`
`--help`	boolean	Show this message and exit.	`False`

setup¶

Build an LD reference panel from a cohort's genetic data in the catalog.

Writes one plink2 fileset per chromosome to

//chr.pgen (variant IDs CHROM:POS:REF:ALT, dosages kept), plus samples.keep and settings.json. defaults to $TMPDIR, so the panel lasts as long as the session or job.

Samples: the id_map's IDs for that data set, minus patients marked drop=1, narrowed by --pops and --keep if given. For 1000 Genomes (kgp.b38, kgp.b37) that is the 2,504 unrelated phase 3 samples.

Running again with the same --panel-name adds chromosomes. If the panel was built with different settings, or a chromosome is already there, you are asked before it is overwritten (--force skips the question).

Examples:

c4 finemap avail

c4 finemap setup --dna demo.imputed --panel-name demo --chr 6 --maf 0.001

c4 finemap setup --dna kgp.b38 --panel-name kgp_eur --pops EUR --chr 6

c4 finemap setup --dna demo.imputed --panel-name demo_eur --keep eur.txt --dir /scratch/me

Usage:

c4 finemap setup [OPTIONS]

Options:

Name	Type	Description	Default
`--dna`	text	Genetic data set, as . (e.g. demo.imputed). See `c4 finemap avail`.	_required
`--panel-name`	text	Name of the panel; files go to //	_required
`--dir`	path	Where to write the panel (default: $TMPDIR)	None
`--chr`	text	Chromosome(s) to build, e.g. 6 or 6,7 (default: 1-22)	None
`--keep`	path	Only these samples (plink --keep format: IID, or FID IID), within the id_map samples not marked drop=1	None
`--pops`	text	Comma-separated populations and/or super-populations to keep (e.g. EUR or GBR,CEU), from the pheno pop/super_pop columns of a reference panel such as kgp	None
`--maf`	float	plink2 --maf: minimum minor allele frequency	None
`--mac`	integer	plink2 --mac: minimum minor allele count	None
`--geno`	float	plink2 --geno: maximum per-variant missingness	None
`--hwe`	float	plink2 --hwe: HWE p-value threshold	None
`--plink-args`	text	Any other plink2 arguments, quoted, e.g. "--snps-only just-acgt"	None
`--dosage` / `--hardcalls`	boolean	Import FORMAT/DS dosages (default: if the VCF has DS)	None
`--force`, `-f`	boolean	Overwrite an existing panel or chromosome without asking	`False`
`--threads`	integer	plink2 --threads	None
`--memory`	integer	plink2 --memory (MiB). Default: half of the SLURM/cgroup job memory limit, if one is found	None
`--plink2`	text	Path to the plink2 executable	`plink2`
`--verbose`, `-v`	boolean	Also print each plink2 command as it runs	`False`
`--help`	boolean	Show this message and exit.	`False`

visualize¶

Plot fine-mapped loci: -log10(p), PIP and genes, one figure per locus.

Points are coloured by r² with the nearest credible-set lead (LocusZoom colours; --color-by top uses the top-PIP variant instead). Credible-set members get one marker shape per set, leads are purple diamonds, and kriging-flagged variants have a black ring. The title line gives the number of variants, N, credible sets, s and the LD source.

Uses only the run's outputs, so the LD panel doesn't need to exist any more. LD colours need a run made with this version of c4 (older runs plot in grey).

Examples:

c4 finemap visualize fm/pheno -o plots/

c4 finemap visualize fm/pheno -o plots/ --locus 6:31500000-32500000 --format pdf

Usage:

c4 finemap visualize [OPTIONS] PREFIX

Options:

Name	Type	Description	Default
`--out`, `-o`	path	Directory for the plots (one file per locus)	_required
`--locus`	text	Only this locus_id (repeat the option for several)	None
`--all`	boolean	Also plot loci without a credible set	`False`
`--full-locus`	boolean	Show the whole locus window (default: just the span of its variants, plus a margin)	`False`
`--format`	text	png, pdf or svg	`png`
`--color-by`	text	cs: r² with the nearest credible-set lead; top: r² with the top-PIP variant	`cs`
`--genes` / `--no-genes`	boolean	Draw the gene track	`True`
`--gtf`	path	GTF for the gene track (default: the catalog's GTF for the run's build)	None
`--all-biotypes`	boolean	Show every gene, not only protein-coding ones	`False`
`--verbose`, `-v`	boolean	More progress output	`False`
`--help`	boolean	Show this message and exit.	`False`

genotype-correlation¶

Compute per-sample Pearson r and r² between dosage vectors across two VCFs.

Matches samples by ID (or by mapping file) and computes correlation across all overlapping variants (matched on CHROM, POS, REF, ALT).

Examples:

c4 genotype-correlation vcf1.vcf.gz vcf2.vcf.gz output.tsv

c4 genotype-correlation vcf1.vcf.gz vcf2.vcf.gz output.tsv --dosage

c4 genotype-correlation vcf1.vcf.gz vcf2.vcf.gz output.tsv \
    --samples samples.txt --positions positions.txt --verbose

Usage:

c4 genotype-correlation [OPTIONS] VCF1 VCF2 OUTPUT

Options:

Name	Type	Description	Default
`--dosage`	boolean	Use DS field if present in VCF; falls back to GT if absent.	`False`
`--samples`, `-s`	path	Optional sample file. Single column: sample IDs to use from both VCFs. Two columns (tab-separated): VCF1 ID -> VCF2 ID mapping.	None
`--positions`, `-p`	path	Optional positions file (two columns: CHROM POS, no header) to subset variants.	None
`--verbose`, `-v`	boolean	Output Pearson sufficient statistics per sample pair (N, SUM_X, SUM_Y, SUM_X2, SUM_Y2, SUM_XY) to allow genome-wide aggregation across chromosomes.	`False`
`--keep-tmp`	boolean	Do not delete temporary files after completion (useful for debugging).	`False`
`--help`	boolean	Show this message and exit.	`False`

hla_concordance¶

Compare HLA typing between two files.

Files can have one genotype column per gene (A*01:01/02:01) or two allele columns (A_1, A_2). Prints a per-gene summary; per-sample scores go to --output, or stdout.

Example: c4 hla_concordance wes.csv imputed.csv \ --file1_id sample_id --file2_id sample_id \ --output concordance.tsv

Usage:

c4 hla_concordance [OPTIONS] FILE1 FILE2

Options:

Name	Type	Description	Default
`--output`, `-o`	path	Output file for per-sample results (.csv, .tsv or .txt). Default: print to stdout.	None
`--genes`, `-g`	text	Genes to compare, separated by commas (no spaces). Default: every canonical HLA gene in both files.	None
`--file1_id`	text	ID column name in file 1	_required
`--file2_id`	text	ID column name in file 2	_required
`--digits`, `-d`	integer	Compare at this resolution, e.g. 4 for 2-field	None
`--help`	boolean	Show this message and exit.	`False`

liftover¶

Lift variant positions in a file to another genome build.

Uses pyliftover; no R needed. A .bed file's first three columns are used (0-based, as BED is). For other files give --chrom-col and --start-col; positions are taken as 1-based unless --zero-based. Output is a 3-column BED file in the input's order. Rows that can't be lifted (not in the new build, mapping to several places, or a region that splits) are written to OUTPUT.unmapped with the reason.

Examples: c4 liftover hg19ToHg38.over.chain variants.bed variants_hg38.bed c4 liftover hg19ToHg38.over.chain variants.txt variants_hg38.bed --chrom-col 0 --start-col 1

Usage:

c4 liftover [OPTIONS] CHAIN_FILE INPUT_FILE OUTPUT_BED

Options:

Name	Type	Description	Default
`--chrom-col`	integer	0-indexed chromosome column (required unless the input is .bed)	None
`--start-col`	integer	0-indexed position column (required unless the input is .bed)	None
`--end-col`	integer	0-indexed end column, for regions. Default: each row is the single base at --start-col.	None
`--zero-based`	boolean	Table positions are 0-based (BED-style). Default: 1-based, as in VCFs. .bed input is always 0-based.	`False`
`--help`	boolean	Show this message and exit.	`False`

merge-hla¶

Merge separate allele columns back into HLA genotype columns.

Example: c4 merge-hla input.csv output.csv --genes A B C DRB1 --sep ","

Converts columns like "DRB1_1" and "DRB1_2" back into "DRB1" with "01:01/02:02"

Usage:

c4 merge-hla [OPTIONS] INPUT_FILE [OUTPUT_FILE]

Options:

Name	Type	Description	Default
`--genes`, `-g`	text	Gene to include. Must separate by commas (no spaces).	None
`--digits`, `-d`	integer	Resolution in digits (e.g., 4 for 2-field)	None
`--columns`, `-c`	text	Non-gene columns to include. Will ONLY include these + gene columns in output. Must be separated by commas (no spaces).	None
`--format`, `-f`	text	The output text format. Options are: standard (A01:02/03:04), standard2 (A01:02/A*03:04), standard_no_gene (01:02/03:04).	`standard`
`--help`	boolean	Show this message and exit.	`False`

prs¶

Test a weighted polygenic risk score (PRS) for survival association.

The weights file is a headerless 3-column TSV: variant_id (chr:bp:ref:alt or chr:bp:ref>alt), effect_allele, and effect (additive beta). The PRS is the weighted sum of effect-allele dosages, standardised to report HR per SD.

Examples:

c4 prs --dataset COHORT --weights prs.tsv --survival OS

c4 prs --dataset COHORT --weights prs.tsv --survival OS \
    --weight-build b37 --gt-build b38 --chain-file hg19ToHg38.chain \
    --quantiles 5 --output-dir prs_OS/

Usage:

c4 prs [OPTIONS]

Options:

Name	Type	Description	Default
`--dataset`, `-d`	text	Cohort name; it needs a survival: block in the data catalog (c4/catalog.yaml)	_required
`--weights`, `-w`	path	Headerless 3-column TSV: variant_id, effect_allele, effect	_required
`--weight-build`	text	Genome build of the weight variants (b37 or b38)	`b38`
`--gt-build`	text	Genome build of the genotype VCF (b37 or b38). Defaults to the dataset's build.	None
`--chain-file`	path	Liftover chain file (required when weight-build != gt-build)	None
`--survival`	text	Survival endpoint (e.g. OS, PFS)	_required
`--keep-ambiguous` / `--drop-ambiguous`	boolean	Keep palindromic (A/T, C/G) SNPs (default: drop them)	`False`
`--quantiles`	integer	If >1, also report HR of top vs bottom PRS quantile (e.g. 5)	`0`
`--output-dir`, `-o`	path	Output directory (created if needed). Writes individual PRS, a log, a PRS histogram, per-variant table, and (with --quantiles) a KM plot.	_required
`--dosage` / `--no-dosage`	boolean	Use DS dosage field (default) vs GT-derived dosage	`True`
`--tmpdir`	path	Directory for intermediate files (default: $TMPDIR)	None
`--verbose` / `--no-verbose`	boolean	Show per-variant matching detail	`False`
`--save-dosages`	boolean	Also write the weight variants' dosages to prs_dosages.tsv in the output directory (ALT-coded as in the weights file), plus prs_dosages.variants.tsv.	`False`
`--help`	boolean	Show this message and exit.	`False`

split-hla¶

Split HLA genotype columns into separate allele columns.

Example: c4 split-hla input.csv output.csv --genes A B C DRB1 --sep ","

Converts columns like "DRB1" with "01:01/02:02" into: - DRB1_1: "01:01" - DRB1_2: "02:02"

Usage:

c4 split-hla [OPTIONS] INPUT_FILE [OUTPUT_FILE]

Options:

Name	Type	Description	Default
`--genes`, `-g`	text	Gene to include. Must separate by commas (no spaces).	None
`--digits`, `-d`	integer	Resolution in digits (e.g., 4 for 2-field)	None
`--columns`, `-c`	text	Non-gene columns to include. Will ONLY include these + gene columns in output. Must be separated by commas (no spaces).	None
`--format`, `-f`	text	The output text format. Options are: standard (A01:02/03:04), standard2 (A01:02/A*03:04), standard_no_gene (01:02/03:04).	`standard`
`--help`	boolean	Show this message and exit.	`False`

survival¶

Run Cox PH survival analysis for one or more variants.

IMPORTANT: quote any 'ref>alt' variant on the command line — an unquoted '>' is redirection to your shell, and it will silently send this command's output to a file named after the ALT allele instead of running the analysis (e.g. --variants 2:8599331:T>C with no quotes creates/overwrites a file called "C"). Either quote it (--variants '2:8599331:T>C') or use the colon-delimited form, which needs no quoting (--variants 2:8599331:T:C).

Examples:

c4 survival --dataset COHORT --variants '4:1455432:A>T' --survival OS

c4 survival --dataset COHORT --variant-list vars.txt --survival OS --output results.tsv

c4 survival --dataset COHORT --variants '4:1455432:A>T' --survival OS --km-plot km.png

c4 survival --dataset COHORT --variants '4:1455432:A>T' --survival OS --km-plot km.png --km-plot-carrier

Usage:

c4 survival [OPTIONS]

Options:

Name	Type	Description	Default
`--dataset`, `-d`	text	Cohort name; it needs a survival: block in the data catalog (c4/catalog.yaml)	_required
`--variants`, `-v`	text	Variant(s) in 'chr:pos:ref>alt' format. ALWAYS quote the value — unquoted '>' is redirection to your shell and will silently dump output to a file named after the ALT allele instead of running the command. Repeat the flag for multiple: --variants '4:1234:A>G' --variants '6:5678:C>T'. Alternatively use the colon-delimited form (chr:pos:ref:alt), which needs no quoting, e.g. --variants 4:1234:A:G	None
`--variant-list`	path	File with one variant per line (implies TSV output)	None
`--variant-build`	text	Genome build of the input variants (e.g. b37, b38)	`b38`
`--survival`	text	Survival endpoint (e.g. OS, PFS)	_required
`--output`, `-o`	path	Output TSV path (required when using --variant-list)	None
`--dosage` / `--no-dosage`	boolean	Use DS dosage field (default) vs GT-derived dosage	`True`
`--tmpdir`	path	Directory for intermediate files (default: $TMPDIR)	None
`--verbose` / `--no-verbose`	boolean	Show full table (VCF ID, N, events); default shows variant, HR, p, MAF, notes only	`False`
`--km-plot`	path	Write a Kaplan-Meier plot (PNG) for this variant. Only valid when exactly one variant is given.	None
`--km-plot-carrier`	boolean	With --km-plot, plot just two curves — carrier (>=1 copy) vs non-carrier — instead of one curve per genotype. Useful for rare alleles where the homozygous-alt group is empty or tiny.	`False`
`--save-dosages`	path	Also write the variants' dosages to this TSV (one row per sample, one column per variant), plus NAME.variants.tsv with how each variant matched.	None
`--help`	boolean	Show this message and exit.	`False`

vcf-overlap¶

Find overlapping variants between two VCF files.

Both VCF files must be indexed (.csi or .tbi). Files are automatically ordered by size (smaller loaded into memory, larger streamed).

Example: c4 vcf-overlap array.vcf.gz imputed.vcf.gz overlap.tsv c4 vcf-overlap array.vcf.gz imputed.vcf.gz overlap.tsv --no-allele c4 vcf-overlap array.vcf.gz imputed.vcf.gz overlap.tsv --remove-dup

Usage:

c4 vcf-overlap [OPTIONS] VCF1 VCF2 OUTPUT

Options:

Name	Type	Description	Default
`--on-allele`, `-a` / `--no-allele`, `-A`	boolean	Match on REF/ALT in addition to position	`True`
`--remove-dup`, `-d`	boolean	Remove duplicate positions	`False`
`--help`	boolean	Show this message and exit.	`False`