PhyNetPy Documentation

Library for the Development and Use of Phylogenetic Network Methods

data Module v1.0.0

Axis 1 -- what you observed: GeneTrees, Alignment, BiallelicMarkers. The input knows its own type, which is half of the dispatch key.

Author:
Mark Kessler
Source:
data.py

Exceptions

exception DataError(Exception)

Raised when a data container is malformed or cannot be loaded.

Data

class Data(ABC)

Base class for every input type on the data axis. Subclasses declare *what kind of observation* the user has: :class:`~phynetpy.data.GeneTrees` (gene-tree estimates), :class:`~phynetpy.data.Alignment` (per-locus sequences), or :class:`~phynetpy.data.BiallelicMarkers` (SNPs). A criterion declares which of these it is defined on via ``Criterion.accepts_data``, and the registry keys engines on the concrete class. Every data type carries the species-to-allele mapping alongside the observations, because the mapping describes *the sample*, not the biology or the objective: which gene copies were sequenced from which species is a property of the data set. This is why neither verb takes a separate ``mapping`` argument.

Properties

taxa -> set property abstract

The set of allele / sequence labels present in the data.

mapping -> Optional[Dict[str, List[str]]] property

Explicit species -> allele mapping, or ``None`` if unset.

has_branch_lengths -> bool property

Whether the data carries usable branch lengths. Only meaningful for :class:`~phynetpy.data.GeneTrees`; sequence and marker data have no branch lengths of their own, so the base implementation reports ``False``. Consulted by the registry when a criterion's ``use_branch_lengths`` policy is ``True``.

Constructor

__init__(mapping: Optional[Dict[str, List[str]]] = None) -> None

Initialise the shared mapping slot.

Parameter Type Description
mapping Species -> list of allele / gene-copy labels. ``None`` defers to :meth:`resolved_mapping`, which falls back to an identity mapping (each label is its own species).

Methods

mapping(value: Optional[Dict[str, List[str]]]) -> None

Set the explicit species -> allele mapping (``None`` to clear it).

resolved_mapping -> Dict[str, List[str]]

Return an explicit mapping, falling back to identity.

Returns: dict[str, list[str]]: Species -> allele labels. When no mapping was supplied, every label is treated as its own species, which is the right default for single-copy (one allele per species) data.

GeneTrees

class GeneTrees(Data, _GeneTreeCollection)

Gene-tree estimates: the data axis type for gene trees. Accepted by the MDC, likelihood, pseudo-likelihood, and Bayesian criteria -- gene trees are the only data type all four are defined on. Because this subclasses :class:`phynetpy.GeneTrees.GeneTrees`, every inherited utility (``build_majority_rule_consensus_tree``, ``most_frequent_gene_tree``, ``cluster_support``, ``rf_distance``, ``astral``, ``mp_allop_map``, ...) is available, and the object can be handed straight to the numerical engines, which expect that type. Attributes: trees: Set of gene trees, each a :class:`~phynetpy.Network.Network`. taxa_names: Union of all gene-copy (allele) labels.

Properties

taxa -> set property

The set of gene-copy (allele) labels across all trees.

mapping -> Optional[Dict[str, List[str]]] property

Explicit species -> allele mapping, or ``None`` if unset. Kept in step with the inherited ``species_gene_mapping`` so the numerical engines and the two verbs read the same value.

has_branch_lengths -> bool property

Whether these gene trees carry observed branch lengths. ``False`` means the trees are topologies only. Set at construction (from the source file's text, or from the trees' edges) rather than inferred later, because ``phynetpy.IO`` back-fills missing lengths with ``1``.

Constructor

__init__(trees: Optional[List[Network]] = None, mapping: Optional[Dict[str, List[str]]] = None, naming_rule: Optional[Callable[..., Any]] = None, has_branch_lengths: Optional[bool] = None) -> None

Wrap a set of gene trees as a data-axis object.

Parameter Type Description
trees The gene trees. Each should be a rooted binary :class:`~phynetpy.Network.Network` with no reticulations.
mapping Species -> list of allele labels. Omit for single-copy data, where each label is its own species.
naming_rule ``f : str -> str`` deriving a species key from an allele label; an alternative to an explicit *mapping* (e.g. :func:`phynetpy.GeneTrees.phynetpy_naming`).
has_branch_lengths Override the branch-length flag. ``None`` infers it from the trees' edges.
Raises: DataError: If *trees* is empty or contains a reticulate network.

Methods

mapping(value: Optional[Dict[str, List[str]]]) -> None

Set the explicit species -> allele mapping, keeping it in step with ``species_gene_mapping``.

resolved_mapping -> Dict[str, List[str]]

Species -> allele mapping, resolved through the naming rule. Defers to the inherited resolution chain: an explicit mapping, then the naming rule, then identity.

from_file(path: Union[str, os.PathLike], mapping: Optional[Dict[str, List[str]]] = None, naming_rule: Optional[Callable[..., Any]] = None, format: Optional[str] = None) -> 'GeneTrees' @classmethod

Load gene trees from a NEXUS or Newick file.

Parameter Type Description
path Path to the file.
mapping Species -> list of allele labels.
naming_rule ``f : str -> str`` deriving species from labels.
format ``"nexus"`` or ``"newick"``. ``None`` infers from the file extension, defaulting to NEXUS.
Returns: GeneTrees: The loaded collection, with ``has_branch_lengths`` determined from the file's text.
Raises: DataError: If the file cannot be read or holds no trees.
from_newick(strings: Union[str, Sequence[str]], mapping: Optional[Dict[str, List[str]]] = None, naming_rule: Optional[Callable[..., Any]] = None) -> 'GeneTrees' @classmethod

Build from one or more Newick strings.

Parameter Type Description
strings A single Newick string, or a sequence of them. A single string containing several ``;``-terminated trees is split.
mapping Species -> list of allele labels.
naming_rule ``f : str -> str`` deriving species from labels.
Returns: GeneTrees: The parsed collection.
__repr__ -> str

Alignment

class Alignment(Data)

Multilocus nucleotide sequence alignments. One :class:`Alignment` holds *all* loci for the analysis; each locus is a separate alignment over the same allele labels. Accepted by the Bayesian criterion, which co-estimates the species network and the gene trees (Wen & Nakhleh 2018). PhyNetPy will not estimate gene trees from an alignment, so the MDC and pseudo-likelihood criteria reject this type outright: those are defined over gene-tree topologies. Summarise the alignment externally and pass :class:`~phynetpy.data.GeneTrees` instead. The nucleotide substitution model lives here rather than on the model axis, because it describes how *these sequences* were generated, while the model axis describes how the gene copies are related. Attributes: loci: Per-locus alignments as ``{label: sequen...

Properties

taxa -> set property

The set of sequence labels across all loci.

n_loci -> int property

Number of loci.

n_sites -> int property

Total aligned site count summed across loci.

Constructor

__init__(loci: Union[MSA, Sequence[Any]], mapping: Optional[Dict[str, List[str]]] = None, substitution_model: Optional[Any] = None) -> None

Wrap per-locus alignments as a data-axis object.

Parameter Type Description
loci A single :class:`~phynetpy.MSA.MSA`, or a sequence of per-locus alignments (each an ``MSA`` or a ``{label: sequence}`` dict).
mapping Species -> list of allele labels, where the allele labels are the alignment row names.
substitution_model A :class:`~phynetpy.infer.SubstitutionModel` (``JC69``, ``HKY85``, ``GTR``). ``None`` selects ``JC69``.
Raises: DataError: If no loci are supplied.

Methods

from_file(path: Union[str, os.PathLike, Sequence[Union[str, os.PathLike]]], mapping: Optional[Dict[str, List[str]]] = None, format: Optional[str] = None, substitution_model: Optional[Any] = None) -> 'Alignment' @classmethod

Load one locus per file.

Parameter Type Description
path A single path, or a sequence of paths (one per locus).
mapping Species -> list of allele labels.
format ``"nexus"``, ``"fasta"``, or ``"vcf"``. ``None`` infers from each file's extension.
substitution_model See :meth:`__init__`.
Returns: Alignment: The loaded alignments, one locus per file.
__repr__ -> str

BiallelicMarkers

class BiallelicMarkers(Data)

Unlinked biallelic markers (SNPs). Sites are encoded as per-taxon counts of the "red" allele, so a row of a diploid data set reads ``0``/``1``/``2``. Accepted by the likelihood and Bayesian criteria (Bryant et al. 2012; Zhu et al. 2018). ``samples`` -- how many gene copies were sequenced per taxon -- belongs here rather than on the model axis: it describes the sampling effort, not the biology. The mutation rates ``u``/``v`` and the coalescent rate live on :class:`~phynetpy.models.MSC` instead, since those *are* the generative process. Attributes: alignment: The underlying :class:`~phynetpy.MSA.MSA`. samples: Taxon label -> number of sampled gene copies.

Properties

taxa -> set property

The set of taxon labels in the marker matrix.

n_sites -> int property

Number of marker sites.

Constructor

__init__(alignment: MSA, mapping: Optional[Dict[str, List[str]]] = None, samples: Optional[Dict[str, int]] = None) -> None

Wrap a biallelic marker matrix as a data-axis object.

Parameter Type Description
alignment The marker matrix, as an :class:`~phynetpy.MSA.MSA` whose sequences hold per-site red-allele counts.
mapping Species -> list of taxon labels. Usually the identity for marker data, where each row is its own taxon.
samples Taxon label -> sampled gene-copy count. ``None`` assumes one sampled copy per taxon.
Raises: DataError: If *alignment* is not an ``MSA``.

Methods

from_file(path: Union[str, os.PathLike], mapping: Optional[Dict[str, List[str]]] = None, samples: Optional[Dict[str, int]] = None, format: Optional[str] = None) -> 'BiallelicMarkers' @classmethod

Load markers from a NEXUS or VCF file.

Parameter Type Description
path Path to the file.
mapping Species -> list of taxon labels.
samples Taxon label -> sampled gene-copy count.
format ``"nexus"`` or ``"vcf"``. ``None`` infers from the extension.
Returns: BiallelicMarkers: The loaded marker matrix.
__repr__ -> str

Navigation

Modules

This Page