Library for the Development and Use of Phylogenetic Network Methods
Axis 1 -- what you observed: GeneTrees, Alignment, BiallelicMarkers. The input knows its own type, which is half of the dispatch key.
Raised when a data container is malformed or cannot be loaded.
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.
The set of allele / sequence labels present in the data.
Explicit species -> allele mapping, or ``None`` if unset.
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``.
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). |
Set the explicit species -> allele mapping (``None`` to clear it).
Return an explicit mapping, falling back to identity.
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.
The set of gene-copy (allele) labels across all trees.
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.
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``.
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. |
DataError: If *trees* is empty or contains a reticulate network.Set the explicit species -> allele mapping, keeping it in step with ``species_gene_mapping``.
Species -> allele mapping, resolved through the naming rule. Defers to the inherited resolution chain: an explicit mapping, then the naming rule, then identity.
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. |
DataError: If the file cannot be read or holds no trees.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. |
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...
The set of sequence labels across all loci.
Number of loci.
Total aligned site count summed across loci.
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``. |
DataError: If no loci are supplied.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__`. |
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.
The set of taxon labels in the marker matrix.
Number of marker sites.
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. |
DataError: If *alignment* is not an ``MSA``.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. |