Site stratification

Site stratification#

A Stratification splits sites into categories so the Parser counts a separate spectrum per stratum, for instance neutral versus selected sites.

`Stratification`	Abstract class for Stratifying the SFS by determining a site's type based on its properties.
`SNPStratification`	Abstract class for stratifications that can only handle SNPs.
`BaseContextStratification`	Stratify the SFS by the base context of the mutation.
`BaseTransitionStratification`	Stratify the SFS by the base transition of the mutation, i.e., `A>T`.
`TransitionTransversionStratification`	Stratify the SFS by whether we have a transition or transversion.
`AncestralBaseStratification`	Stratify the SFS by the base context of the mutation: the reference base.
`DegeneracyStratification`	Stratify SFS by degeneracy.
`SynonymyStratification`	Stratify SFS by synonymy (neutral or selected).
`VEPStratification`	Stratify SFS by synonymy (neutral or selected) based on annotation provided by VEP.
`SnpEffStratification`	Stratify SFS by synonymy (neutral or selected) based on annotation provided by SnpEff.
`GenomePositionDependentStratification`	Base class for stratifications that derive the type from a site's genomic position.
`ContigStratification`	Stratify SFS by contig.
`ChunkedStratification`	Stratify SFS by creating `n` contiguous chunks of roughly equal size.
`RandomStratification`	Stratify the SFS randomly into a fixed number of bins.

Stratification#

class Stratification[source]#

Bases: ABC

Abstract class for Stratifying the SFS by determining a site’s type based on its properties.

Methods:

`__init__`	Create instance.
`get_type`	Get type of given Variant.
`get_types`	Get all possible types.

__init__()[source]#: Create instance.

parser: Parser | None#: Parser instance

n_valid: int#: The number of sites that didn’t have a type.

abstractmethod get_type(variant: Site)[source]#

Get type of given Variant. Only the types given by get_types() are valid, or None if no type could be determined.

Parameters:: variant (Site) – The site
Return type:: Optional[str]
Returns:: Type of the variant

abstractmethod get_types()[source]#

Get all possible types.

Return type:: List[str]
Returns:: List of types

SNPStratification#

class SNPStratification[source]#

Bases: Stratification, ABC

Abstract class for stratifications that can only handle SNPs. We need to issue a warning in this case.

Methods:

`__init__`	Create instance.
`get_type`	Get type of given Variant.
`get_types`	Get all possible types.

__init__()#: Create instance.

abstractmethod get_type(variant: Site)#

Get type of given Variant. Only the types given by get_types() are valid, or None if no type could be determined.

Parameters:: variant (Site) – The site
Return type:: Optional[str]
Returns:: Type of the variant

abstractmethod get_types()#

Get all possible types.

Return type:: List[str]
Returns:: List of types

parser: Parser | None#: Parser instance

n_valid: int#: The number of sites that didn’t have a type.

BaseContextStratification#

class BaseContextStratification(fasta: str, n_flanking: int = 1, aliases: Dict[str, List[str]] = {}, cache: bool = True)[source]#

Bases: Stratification, FASTAHandler

Stratify the SFS by the base context of the mutation. The number of flanking bases can be configured. Note that we attempt to take the ancestral allele as the middle base. If skip_non_polarized is set to False, we use the reference allele as the middle base.

Methods:

`__init__`	Create instance.
`get_type`	Get the base context for a given mutation
`get_types`	Create all possible base contexts.
`download_file`	Download a file from a URL.
`download_if_url`	Download the file if it is a URL.
`get_aliases`	Get all aliases for the given contig alias including the primary alias.
`get_contig`	Get the contig from the FASTA file.
`get_contig_names`	Get the names of the contigs in the FASTA file.
`get_filename`	Return the file extension of a URL.
`hash`	Return a truncated SHA1 hash of a string.
`is_url`	Check if the given path is a URL.
`load_fasta`	Load a FASTA file into a dictionary.
`unzip_if_zipped`	If the given file is gzipped, unzip it and return the path to the unzipped file.

__init__(fasta: str, n_flanking: int = 1, aliases: Dict[str, List[str]] = {}, cache: bool = True)[source]#

Create instance. Note that we require a fasta file to be specified for base context to be able to be inferred

Parameters:

fasta (str) – The fasta file path, possibly gzipped or a URL
n_flanking (int) – The number of flanking bases
aliases (Dict[str, List[str]]) – Dictionary of aliases for the contigs in the input, e.g. {'chr1': ['1']}. This is used to match the contig names in the input with the contig names in the FASTA file and GFF file.
cache (bool) – Whether to cache files that are downloaded from URLs

n_flanking: int#: The number of flanking bases

contig: SeqRecord | None#: The current contig

get_type(variant: Site)[source]#

Get the base context for a given mutation

Parameters:: variant (Site) – The site
Return type:: str
Returns:: Base context of the mutation

get_types()[source]#

Create all possible base contexts.

Return type:: List[str]
Returns:: List of contexts

classmethod download_file(url: str, cache: bool = True, desc: str = 'Downloading file')#

Download a file from a URL.

Parameters:

cache (bool) – Whether to cache the file.
url (str) – The URL to download the file from.
desc (str) – Description for the progress bar

Return type:

str

Returns:

The path to the downloaded file.

download_if_url(path: str)#

Download the file if it is a URL.

Parameters:: path (str) – The path to the file.
Return type:: str
Returns:: The path to the downloaded file or the original path.

get_aliases(contig: str)#

Get all aliases for the given contig alias including the primary alias.

Parameters:: contig (str) – The contig.
Return type:: List[str]
Returns:: The aliases.

get_contig(aliases, rewind: bool = True, notify: bool = True)#

Get the contig from the FASTA file. The contig is looked up in the header index and read by seeking to it, so the sites may visit the contigs in any order at the same cost.

Note that pyfaidx would be more efficient here, but there were problems when running it in parallel.

Parameters:

aliases – The contig aliases.
rewind (bool) – Unused, the lookup does not depend on the position of a cursor.
notify (bool) – Unused, the lookup does not depend on the position of a cursor.

Return type:

SeqRecord

Returns:

The contig.

Raises:

LookupError – Where the FASTA carries none of the aliases.

get_contig_names()#

Get the names of the contigs in the FASTA file.

Return type:: List[str]
Returns:: The contig names.

static get_filename(url: str)#

Return the file extension of a URL.

Parameters:: url (str) – The URL to get the file extension from.
Returns:: The file extension.

static hash(s: str)#

Return a truncated SHA1 hash of a string.

Parameters:: s (str) – The string to hash.
Return type:: str
Returns:: The SHA1 hash.

static is_url(path: str)#

Check if the given path is a URL.

Parameters:: path (str) – The path to check.
Return type:: bool
Returns:: True if the path is a URL, False otherwise.

load_fasta(file: str)#

Load a FASTA file into a dictionary.

Parameters:: file (str) – The path to The FASTA file path, possibly gzipped or a URL
Return type:: FastaIterator
Returns:: Iterator over the sequences.

static unzip_if_zipped(file: str)#

If the given file is gzipped, unzip it and return the path to the unzipped file. If the file is not gzipped, return the path to the original file.

Parameters:: file (str) – The path to the file.
Returns:: The path to the unzipped file, or the original file if it was not gzipped.

parser: 'Parser' | None#: Parser instance

n_valid: int#: The number of sites that didn’t have a type.

fasta: str#: The path to the FASTA file.

cache: bool#: Whether to cache files that are downloaded from URLs

aliases#: The contig mappings

BaseTransitionStratification#

class BaseTransitionStratification[source]#

Bases: SNPStratification

Stratify the SFS by the base transition of the mutation, i.e., A>T.

Warning

This stratification only works for SNPs. You thus need to update the number of mono-allelic sites manually.

Methods:

`get_type`	Get the base transition for the given variant.
`get_types`	Get all possible base transitions.
`__init__`	Create instance.

get_type(variant: Site)[source]#

Get the base transition for the given variant.

Parameters:: variant (Site) – The site
Return type:: str
Returns:: Base transition
Raises:: NoTypeException – if not type could be determined

get_types()[source]#

Get all possible base transitions.

Return type:: List[str]
Returns:: List of contexts

__init__()#: Create instance.

parser: Parser | None#: Parser instance

n_valid: int#: The number of sites that didn’t have a type.

TransitionTransversionStratification#

class TransitionTransversionStratification[source]#

Bases: BaseTransitionStratification

Stratify the SFS by whether we have a transition or transversion.

Warning

This stratification only works for SNPs. You thus need to update the number of mono-allelic sites manually.

Methods:

`get_type`	Get the mutation type (transition or transversion) for a given mutation.
`get_types`	All possible mutation types (transition and transversion).
`__init__`	Create instance.

get_type(variant: Site)[source]#

Get the mutation type (transition or transversion) for a given mutation.

Parameters:: variant (Site) – The site
Return type:: str
Returns:: Mutation type

get_types()[source]#

All possible mutation types (transition and transversion).

Return type:: List[str]
Returns:: List of mutation types

__init__()#: Create instance.

parser: Parser | None#: Parser instance

n_valid: int#: The number of sites that didn’t have a type.

AncestralBaseStratification#

class AncestralBaseStratification[source]#

Bases: Stratification

Stratify the SFS by the base context of the mutation: the reference base. If skip_non_polarized is set to False, we use the reference allele as ancestral base. By default, we use the AA tag to determine the ancestral allele.

Any subclass of AncestralAlleleAnnotation can be used to annotate the ancestral allele.

Methods:

`get_type`	Get the type which is the reference allele.
`get_types`	The possible base types.
`__init__`	Create instance.

get_type(variant: Site)[source]#

Get the type which is the reference allele.

Parameters:: variant (Site) – The site
Return type:: str
Returns:: reference allele

get_types()[source]#

The possible base types.

Return type:: List[str]
Returns:: List of contexts

__init__()#: Create instance.

parser: Parser | None#: Parser instance

n_valid: int#: The number of sites that didn’t have a type.

DegeneracyStratification#

class DegeneracyStratification(custom_callback: Callable[[cyvcf2.Variant], str] = None)[source]#

Bases: Stratification

Stratify SFS by degeneracy. We only consider sides which 4-fold degenerate (neutral) or 0-fold degenerate (selected) which facilitates counting.

DegeneracyAnnotation can be used to annotate the degeneracy of a site.

Methods:

`__init__`	Initialize the stratification.
`get_type`	Get the degeneracy.
`get_types`	Get all possible degeneracy type (`neutral` and `selected`).

__init__(custom_callback: Callable[[cyvcf2.Variant], str] = None)[source]#

Initialize the stratification.

Parameters:: custom_callback (Callable[[cyvcf2.Variant], str]) – Custom callback to determine the type of mutation

get_degeneracy#: Custom callback to determine the degeneracy of mutation

get_type(variant: Site)[source]#

Get the degeneracy.

Parameters:: variant (Site) – The site
Return type:: Literal['neutral', 'selected']
Returns:: Type of the mutation
Raises:: NoTypeException – If the mutation is not synonymous or non-synonymous

get_types()[source]#

Get all possible degeneracy type (neutral and selected).

Return type:: List[str]
Returns:: List of contexts

parser: Parser | None#: Parser instance

n_valid: int#: The number of sites that didn’t have a type.

SynonymyStratification#

class SynonymyStratification[source]#

Bases: SNPStratification

Stratify SFS by synonymy (neutral or selected).

SynonymyAnnotation can be used to annotate the synonymy of a site.

Warning

This stratification only works for SNPs. You thus need to update the number of mono-allelic sites manually.

Methods:

`get_types`	Get all possible synonymy types (`neutral` and `selected`).
`get_type`	Get the synonymy using the custom synonymy annotation.
`__init__`	Create instance.

get_types()[source]#

Get all possible synonymy types (neutral and selected).

Return type:: List[str]
Returns:: List of contexts

get_type(variant: Site)[source]#

Get the synonymy using the custom synonymy annotation.

Parameters:: variant (Site) – The site
Return type:: Literal['neutral', 'selected']
Returns:: Type of the mutation, either neutral or selected

__init__()#: Create instance.

parser: Parser | None#: Parser instance

n_valid: int#: The number of sites that didn’t have a type.

VEPStratification#

class VEPStratification[source]#

Bases: SynonymyStratification

Stratify SFS by synonymy (neutral or selected) based on annotation provided by VEP.

Warning

This stratification only works for SNPs. You thus need to update the number of mono-allelic sites manually.

Methods:

`get_types`	Get all possible synonymy types (`neutral` and `selected`).
`get_type`	Get the synonymy of a site.
`__init__`	Create instance.

info_tag: str = 'CSQ'#: The tag used by VEP to annotate the synonymy

get_types()[source]#

Get all possible synonymy types (neutral and selected).

Return type:: List[str]
Returns:: List of contexts

get_type(variant: Site)[source]#

Get the synonymy of a site.

Parameters:: variant (Site) – The site
Return type:: Literal['neutral', 'selected']
Returns:: Type of the mutation, either neutral or selected

__init__()#: Create instance.

parser: Parser | None#: Parser instance

n_valid: int#: The number of sites that didn’t have a type.

SnpEffStratification#

class SnpEffStratification[source]#

Bases: VEPStratification

Stratify SFS by synonymy (neutral or selected) based on annotation provided by SnpEff.

Warning

This stratification only works for SNPs. You thus need to update the number of mono-allelic sites manually.

Methods:

`__init__`	Create instance.
`get_type`	Get the synonymy of a site.
`get_types`	Get all possible synonymy types (`neutral` and `selected`).

info_tag: str = 'ANN'#: The tag used by SnpEff to annotate the synonymy

__init__()#: Create instance.

get_type(variant: Site)#

Get the synonymy of a site.

Parameters:: variant (Site) – The site
Return type:: Literal['neutral', 'selected']
Returns:: Type of the mutation, either neutral or selected

get_types()#

Get all possible synonymy types (neutral and selected).

Return type:: List[str]
Returns:: List of contexts

parser: Parser | None#: Parser instance

n_valid: int#: The number of sites that didn’t have a type.

GenomePositionDependentStratification#

class GenomePositionDependentStratification[source]#

Bases: Stratification, ABC

Base class for stratifications that derive the type from a site’s genomic position.

Methods:

`__init__`	Create instance.
`get_type`	Get type of given Variant.
`get_types`	Get all possible types.

__init__()#: Create instance.

abstractmethod get_type(variant: Site)#

Get type of given Variant. Only the types given by get_types() are valid, or None if no type could be determined.

Parameters:: variant (Site) – The site
Return type:: Optional[str]
Returns:: Type of the variant

abstractmethod get_types()#

Get all possible types.

Return type:: List[str]
Returns:: List of types

parser: Parser | None#: Parser instance

n_valid: int#: The number of sites that didn’t have a type.

ContigStratification#

class ContigStratification(contigs: List[str] = None)[source]#

Bases: GenomePositionDependentStratification

Stratify SFS by contig.

Methods:

`__init__`	Initialize the stratification.
`get_type`	Get the contig.
`get_types`	Get all possible contig type.

__init__(contigs: List[str] = None)[source]#

Initialize the stratification.

Parameters:: contigs (List[str]) – List of contigs to stratify by. Defaults to all contigs in the input.

contigs: List[str]#: List of contigs

get_type(variant: Site)[source]#

Get the contig.

Parameters:: variant (Site) – The site
Return type:: str
Returns:: The contig name

get_types()[source]#

Get all possible contig type.

Return type:: List[str]
Returns:: List of contexts

parser: Parser | None#: Parser instance

n_valid: int#: The number of sites that didn’t have a type.

ChunkedStratification#

class ChunkedStratification(n_chunks: int)[source]#

Bases: GenomePositionDependentStratification

Stratify SFS by creating n contiguous chunks of roughly equal size.

Note

Since the total number of sites is not known in advance, we cannot create contiguous chunks of exactly equal size.

Warning

Chunk boundaries are sized from the raw input record count (parser.n_sites), but a site is assigned to a chunk only once it has survived filtration and down-projection. When any filtration or projection drops sites, all included sites fall within the first n_included / n_sites fraction of the record range, so they concentrate in the leading chunks and the trailing chunks come out under-filled or empty. The included count is not known at setup without an extra pass over the data, so the chunks cannot be pre-balanced; a warning is logged at setup when the parser carries filtrations.

The first pass assigns sites by counting them and records the genomic position at which each chunk begins. Any further pass over the same input (the TargetSiteCounter sampling pass, which visits a different number of sites) is assigned by position instead, so a sampled site lands in the same chunk as the variants surrounding it.

Methods:

`__init__`	Initialize the stratification.
`get_types`	Get all possible window types.
`get_type`	Get the type.

__init__(n_chunks: int)[source]#

Initialize the stratification.

Parameters:: n_chunks (int) – Number of sites per window

n_chunks: int#: Number of chunks

chunk_sizes: List[int] | None#: List of chunk sizes

counter: int#: Number of sites seen so far

get_types()[source]#

Get all possible window types.

Return type:: List[str]
Returns:: List of contexts

get_type(variant: Site)[source]#

Get the type.

Parameters:: variant (Site) – The site
Return type:: str
Returns:: The type

parser: Parser | None#: Parser instance

n_valid: int#: The number of sites that didn’t have a type.

RandomStratification#

class RandomStratification(n_bins: int, seed: int | None = 0)[source]#

Bases: Stratification

Stratify the SFS randomly into a fixed number of bins. Can be used to analyze expected sampling variance between different stratifications.

Methods:

`__init__`	Initialize random stratification.
`get_type`	Assign the variant to a random bin.
`get_types`	Get all possible bin labels.

__init__(n_bins: int, seed: int | None = 0)[source]#

Initialize random stratification.

Parameters:

n_bins (int) – Number of bins to randomly assign sites to.
seed (Optional[int]) – Random seed, for reproducible bin assignment.

num_bins: int#: Number of bins

seed: int | None#: Random seed for reproducibility

rng#: Random generator instance

get_type(variant: Site)[source]#

Assign the variant to a random bin.

Parameters:: variant (Site) – The site
Return type:: str
Returns:: Randomly chosen bin label

get_types()[source]#

Get all possible bin labels.

Return type:: List[str]
Returns:: List of bin labels

parser: Parser | None#: Parser instance

n_valid: int#: The number of sites that didn’t have a type.

Site stratification

Contents

Site stratification#

Stratification#

SNPStratification#

BaseContextStratification#

BaseTransitionStratification#

TransitionTransversionStratification#

AncestralBaseStratification#

DegeneracyStratification#

SynonymyStratification#

VEPStratification#

SnpEffStratification#

GenomePositionDependentStratification#

ContigStratification#

ChunkedStratification#

RandomStratification#