One-call functions#

Each function builds a MaxMPDInstance and calls one of its methods. For several questions about the same trees, build the instance once instead, so the trees are read only once.

forestpd.optimize_maxmpd(trees, budget, costs=None, weights=None, survival=None, *, return_taxa=False, maf=None, missing_branch_length='error', rooted=False)[source]#

Maximize phylogenetic diversity across several phylogenetic trees under a budget.

Equivalent to MaxMPDInstance(trees, costs, weights, survival).optimize(budget). For repeated analyses on the same data (several budgets, or evaluating taxon sets), build the MaxMPDInstance once instead, so the trees are parsed only once.

Parameters:

  • trees (str | os.PathLike | Sequence) – The path of a file holding one Newick tree per line, or a list of Newick strings and/or PhyloZoo SemiDirectedPhyNetwork / DirectedPhyNetwork trees (with the phylozoo extra). Every Newick tree ends with ;. All trees must carry the same taxon set.

  • budget (int) – Total integer budget B (>= 0).

  • costs (Mapping[str, int] | None, optional) – Integer cost per taxon label, at least 1. None means unit costs; missing labels cost 1.

  • weights (Sequence[float] | Mapping[int, float] | None, optional) – Per-tree weight w_j, in the order of the trees (the list, or the file), or keyed by tree index (missing indices weigh 1.0). None means all 1.0.

  • survival (Mapping[str, float] | None, optional) – Probability a(x) in [0, 1) that taxon x survives when not protected; the objective is then the expected PD of the survivors. None means 0 for every taxon.

  • return_taxa (bool, default False) – Also reconstruct an optimal taxon set.

  • maf (MAFComputer | None, optional) – Agreement-forest stage. None (default) uses HeuristicMAF.

  • missing_branch_length (str | float, default "error") – Policy for edges without a branch length: "error", "zero", or a numeric default.

  • rooted (bool, default False) – Use rooted PD (see MaxMPDInstance).

Returns:

The optimal value, optionally an optimal taxon set, and diagnostics, including meta["frontier"]: the optimal value for every budget 0..budget (up to the total cost of all taxa; beyond it the value stays the same). A budget above half the total cost is solved with the complementary tables, which cover only the budgets from it on; the rest of the frontier is then NaN (see MaxMPDResult).

Return type:

MaxMPDResult

Raises:

ForestPDInputError – If any input is malformed, the trees do not share one taxon set, or the MAF stage does not return an agreement forest.

Warns:

ForestPDWarning – If the trees look rooted but rooted is False (see MaxMPDInstance).

Examples

>>> import forestpd as fpd
>>> r = fpd.optimize_maxmpd(["(A,B,(C,D));", "(A,C,(B,D));"], budget=2,
...                         return_taxa=True, missing_branch_length=1.0)
>>> r.value
6.0
>>> r.taxa in ({"A", "D"}, {"B", "C"})
True
forestpd.optimize_many_maxmpd(trees, budgets, costs=None, weights=None, survival=None, *, return_taxa=False, maf=None, missing_branch_length='error', rooted=False)[source]#

optimize_maxmpd() for several budgets at once, from a single solve.

Equivalent to MaxMPDInstance(trees, costs, weights, survival).optimize_many(budgets). For repeated analyses on the same data, build the MaxMPDInstance once instead.

Parameters:
Returns:

One result per budget, in the given order.

Return type:

list[MaxMPDResult]

Raises:

ForestPDInputError – If any input is malformed, the trees do not share one taxon set, or the MAF stage does not return an agreement forest.

Warns:

ForestPDWarning – If the trees look rooted but rooted is False (see MaxMPDInstance).

Examples

>>> import forestpd as fpd
>>> results = fpd.optimize_many_maxmpd(["(A:1,B:1,(C:1,D:1):2);", "(A:1,C:1,(B:1,D:1):2);"],
...                                    [1, 2, 3])
>>> [r.value for r in results]
[0.0, 8.0, 10.0]
forestpd.evaluate_maxmpd(trees, taxa, weights=None, survival=None, *, missing_branch_length='error', rooted=False)[source]#

The objective value of protecting a given taxon set.

Equivalent to MaxMPDInstance(trees, weights=weights, survival=survival).evaluate_pd(taxa). For repeated analyses on the same data (several taxon sets), build the MaxMPDInstance once instead.

Parameters:
Returns:

The weighted sum of phylogenetic diversities over all trees (its expected value over the surviving taxa, with survival probabilities).

Return type:

float

Raises:

ForestPDInputError – If any input is malformed, a label is unknown, or the trees do not share one taxon set.

Warns:

ForestPDWarning – If the trees look rooted but rooted is False (see MaxMPDInstance).

Examples

>>> import forestpd as fpd
>>> fpd.evaluate_maxmpd(["(A:1,B:1,(C:1,D:1):2);", "(A:1,C:1,(B:1,D:1):2);"], {"A", "B"})
6.0