freyja covariants-assign

Assign the read-level clusters in a COVARIANTS file (from freyja covariants) to the lineages they cannot be told apart from. Each cluster is matched against the barcodes over the span its reads cover, and labelled with the MRCA of the matching lineages (using the same MRCA logic as demix –depthcutoff).

freyja covariants-assign [OPTIONS] COVARIANTS

Options

--barcodes <barcodes>

Path to custom barcode file

--groups <groups>

lineage groups yaml (name/members entries, as in plot_config.yml); if given, also report abundances per group

--assign_by <assign_by>

with –groups, assign a cluster to the group of the MRCA of its lineages, or to the group holding most of its lineages

Default:

majority

Options:

mrca | majority

--max_missing <max_missing>

allow up to this many of a lineage’s mutations in the cluster’s span to be absent from the cluster

Default:

1

--max_extra <max_extra>

allow up to this many of a cluster’s mutations to be absent from the lineage barcode

Default:

0

--unassigned <unassigned>

clusters matching no lineage: count them as Other, or drop them and renormalise over the assigned clusters

Default:

other

Options:

other | drop

--demix_output

also write a freyja demix style output file

Default:

False

--meta <meta>

custom lineage to variant metadata file

--ref <ref>

Reference file in fasta format, for the genome length (default for SARS-CoV-2: data/NC_045512_Hu-1.fasta)

--output <output>

Output file prefix

Default:

covariants_assigned

--confirmedonly

exclude unconfirmed lineages

Default:

False

--lineageyml <lineageyml>

lineage hierarchy file in a yaml format

--relaxedmrca

clusters are assigned robust mrca to handle outliers

Default:

False

--relaxedthresh <relaxedthresh>

associated threshold for robust mrca function

Default:

0.9

--pathogen <pathogen>

Pathogen of interest. Not used if using –barcodes option.

Default:

SARS-CoV-2

Options:

SARS-CoV-2 | MPX | H5Nx | H5Nx-cattle | H1N1 | FLU-B-VIC | H3N2 | MEASLESgenome | RSVa | RSVb | DENV1 | DENV2 | DENV3 | DENV4 | MTB

Arguments

COVARIANTS

Required argument

---

Example Usage:

freyja covariants reports clusters of mutations that co-occur on the same read pair. freyja covariants-assign takes that output and assigns each cluster to the lineages it cannot be told apart from. Each cluster is compared against the lineage barcodes over the span its reads cover, and is labelled with the most recent common ancestor (MRCA) of all matching lineages, using the same MRCA logic as freyja demix --depthcutoff.

freyja covariants sample.bam 21563 25384 --output sample_covariants.tsv
freyja covariants-assign sample_covariants.tsv --output sample

The matching rules can be relaxed with --max_missing (the number of a lineage’s mutations within the cluster’s span that may be absent from the cluster) and --max_extra (the number of a cluster’s mutations that may be absent from the lineage barcode). Clusters that match no lineage are counted as Other by default; use --unassigned drop to drop them and renormalise the abundances over the assigned clusters.

With --output sample, the following files are written:

• sample_clusters.tsv: the input clusters with their assigned class and matching lineages.

• sample_abundances.tsv: summed cluster frequency for each assigned class.

• sample_collapsed_lineages.yml: the lineages behind each assigned class.

• sample_demix.tsv: a freyja demix style output, written when --demix_output is given.

• sample_group_abundances.tsv: abundances per lineage group, written when a lineage groups yaml is given via --groups (same name/members format as plot_config.yml). --assign_by selects whether a cluster is placed in the group of its MRCA (mrca) or in the group holding most of its lineages (majority).