API Reference

Sequence

class phytest.bio.sequence.Sequence(*args, **kwargs)

assert_contains(pattern: str, *, warning: bool = False)

Asserts that the sequence contains a particular pattern.

Parameters

pattern (str) – The sequence must contain this value.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_count(pattern: str, *, count: Optional[int] = None, min: Optional[int] = None, max: Optional[int] = None, warning: bool = False) → None

Asserts that the count of a pattern in the sequence meets the specified criteria.

Parameters

pattern – (str): the pattern to count in the the sequence.
count (int, optional) – If set, then pattern count must be equal to this value. Defaults to None.
min (int, optional) – If set, then pattern count must be equal to or greater than this value. Defaults to None.
max (int, optional) – If set, then pattern count must be equal to or less than this value. Defaults to None.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_count_Ns(count: Optional[int] = None, *, min: Optional[int] = None, max: Optional[int] = None, warning: bool = False) → None

Asserts that the number of a N’s in the sequence meets the specified criteria.

Parameters

count (int, optional) – If set, then the number of N’s must be equal to this value. Defaults to None.
min (int, optional) – If set, then the number of N’s must be equal to or greater than this value. Defaults to None.
max (int, optional) – If set, then the number of N’s must be equal to or less than this value. Defaults to None.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_count_gaps(count: Optional[int] = None, *, min: Optional[int] = None, max: Optional[int] = None, warning: bool = False) → None

Asserts that the number of a gaps (-) in the sequence meets the specified criteria.

Parameters

count (int, optional) – If set, then the number of gaps (-) must be equal to this value. Defaults to None.
min (int, optional) – If set, then the number of gaps (-) must be equal to or greater than this value. Defaults to None.
max (int, optional) – If set, then the number of gaps (-) must be equal to or less than this value. Defaults to None.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_endswith(pattern: str, *, warning: bool = False)

Asserts that the sequence ends with a particular pattern.

Parameters

pattern (str) – The sequence must end with this value.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_length(length: Optional[int] = None, *, min: Optional[int] = None, max: Optional[int] = None, warning: bool = False) → None

Asserts that that the sequence length meets the specified criteria.

Parameters

length (int, optional) – If set, then sequence length must be equal to this value. Defaults to None.
min (int, optional) – If set, then sequence length must be equal to or greater than this value. Defaults to None.
max (int, optional) – If set, then sequence length must be equal to or less than this value. Defaults to None.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_longest_stretch(pattern: str, *, count: Optional[int] = None, min: Optional[int] = None, max: Optional[int] = None, warning: bool = False)

Asserts that the longest stretch of a pattern in the sequence meets the specified criteria.

e.g. the longest stretch of N’s in ‘ANNNANNA’ is 3.

Parameters

pattern – (str): the pattern to count in the the sequence.
count (int, optional) – If set, then the longest stretch of the pattern must be equal to this value. Defaults to None.
min (int, optional) – If set, then the longest stretch of the pattern must be equal to or greater than this value. Defaults to None.
max (int, optional) – If set, then the longest stretch of the pattern must be equal to or less than this value. Defaults to None.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_longest_stretch_Ns(count: Optional[int] = None, *, min: Optional[int] = None, max: Optional[int] = None, warning: bool = False)

Asserts that the longest stretch of a N’s in the sequence meets the specified criteria.

e.g. the logest stretch of N’s in ‘ANNNANNA’ is 3.

Parameters

count (int, optional) – If set, then the longest stretch of N’s must be equal to this value. Defaults to None.
min (int, optional) – If set, then the longest stretch of N’s must be equal to or greater than this value. Defaults to None.
max (int, optional) – If set, then the longest stretch of N’s must be equal to or less than this value. Defaults to None.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_longest_stretch_gaps(count: Optional[int] = None, *, min: Optional[int] = None, max: Optional[int] = None, warning: bool = False)

Asserts that the longest stretch of a gaps (-) in the sequence meets the specified criteria.

e.g. the logest stretch of gaps (-) in ‘A—A–A’ is 3.

Parameters

count (int, optional) – If set, then the longest stretch of gaps (-) must be equal to this value. Defaults to None.
min (int, optional) – If set, then the longest stretch of gaps (-) must be equal to or greater than this value. Defaults to None.
max (int, optional) – If set, then the longest stretch of gaps (-) must be equal to or less than this value. Defaults to None.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_percent(nucleotide: Union[str, List[str]], *, percent: Optional[float] = None, min: Optional[float] = None, max: Optional[float] = None, warning: bool = False) → None

Asserts that the percentage of a nucleotide in the sequence meets the specified criteria.

Parameters

nucleotide – (Union[str, List[str]]): The nucleotide(s) to count in the the sequence.
percent (float, optional) – If set, then nucleotide percentage must be equal to this value. Defaults to None.
min (float, optional) – If set, then nucleotide percentage must be equal to or greater than this value. Defaults to None.
max (float, optional) – If set, then nucleotide percentage must be equal to or less than this value. Defaults to None.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_percent_GC(percent: Optional[int] = None, *, min: Optional[int] = None, max: Optional[int] = None, warning: bool = False) → None

Asserts that the percent of GC’s (ambiguous nucleotide S) in the sequence meets the specified criteria.

Parameters

percent (float, optional) – If set, then the percentage of GC’s must be equal to this value. Defaults to None.
min (float, optional) – If set, then the percentage of GC’s must be equal to or greater than this value. Defaults to None.
max (float, optional) – If set, then the percentage of GC’s must be equal to or less than this value. Defaults to None.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_percent_N(percent: Optional[int] = None, *, min: Optional[int] = None, max: Optional[int] = None, warning: bool = False) → None

Asserts that the percent of N’s in the sequence meets the specified criteria.

Parameters

percent (float, optional) – If set, then the percentage of N’s must be equal to this value. Defaults to None.
min (float, optional) – If set, then the percentage of N’s must be equal to or greater than this value. Defaults to None.
max (float, optional) – If set, then the percentage of N’s must be equal to or less than this value. Defaults to None.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_percent_gaps(percent: Optional[int] = None, *, min: Optional[int] = None, max: Optional[int] = None, warning: bool = False) → None

Asserts that the percent of gaps (-) in the sequence meets the specified criteria.

Parameters

percent (float, optional) – If set, then the percentage of gaps must be equal to this value. Defaults to None.
min (float, optional) – If set, then the percentage of gaps must be equal to or greater than this value. Defaults to None.
max (float, optional) – If set, then the percentage of gaps must be equal to or less than this value. Defaults to None.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_startswith(pattern: str, *, warning: bool = False)

Asserts that the sequence starts with a particular pattern.

Parameters

pattern (str) – The sequence must start with this value.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_valid_alphabet(alphabet: str = 'ATCGN-', *, warning: bool = False) → None

Asserts that that the sequence only contains particular charaters.

Parameters

alphabet (str) – A string containing legal charaters. Defaults to ‘ATCGN-‘.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

Alignment

class phytest.bio.alignment.Alignment(*args, **kwargs)

assert_length(length: Optional[int] = None, *, min: Optional[int] = None, max: Optional[int] = None, warning: bool = False) → None

Asserts that the alignment length (the number of sequences in the alignment) meets the specified criteria.

Parameters

length (int, optional) – If set, then alignment length must be equal to this value. Defaults to None.
min (int, optional) – If set, then alignment length must be equal to or greater than this value. Defaults to None.
max (int, optional) – If set, then alignment length must be equal to or less than this value. Defaults to None.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_width(width: Optional[int] = None, *, min: Optional[int] = None, max: Optional[int] = None, warning: bool = False) → None

Asserts that the alignment width (the number of bases in the sequences) meets the specified criteria.

Parameters

length (int, optional) – If set, then alignment width must be equal to this value. Defaults to None.
min (int, optional) – If set, then alignment width must be equal to or greater than this value. Defaults to None.
max (int, optional) – If set, then alignment width must be equal to or less than this value. Defaults to None.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

Tree

class phytest.bio.tree.Tree(*args, **kwargs)

assert_branch_lengths(*, min: Optional[float] = None, max: Optional[float] = None, terminal: Optional[bool] = None, warning: bool = False)

Asserts that the all brach lengths meet the specified criteria.

Parameters

min (float, optional) – If set, then each brach length must be equal to or greater than this value. Defaults to None.
max (float, optional) – If set, then each brach length must be equal to or less than this value. Defaults to None.
terminal (bool, optional) – True searches for only terminal nodes, False excludes terminal nodes, and the default, None, searches both terminal and non-terminal nodes, as well as any tree elements lacking the is_terminal method.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_internal_branch_lengths(*, min: Optional[float] = None, max: Optional[float] = None, warning: bool = False)

Asserts that the internal brach lengths meet the specified criteria.

Parameters

min (float, optional) – If set, then each internal brach length must be equal to or greater than this value. Defaults to None.
max (float, optional) – If set, then each internal brach length must be equal to or less than this value. Defaults to None.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_is_bifurcating(*, warning: bool = False)

Asserts that the tree is bifurcating.

The root may have 3 descendents and still be considered part of a bifurcating tree, because it has no ancestor.

Parameters: warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_is_monophyletic(tips: List[Bio.Phylo.BaseTree.Clade], *, warning: bool = False)

Asserts that the specified tips form a monophyletic group.

Parameters

tips (List[Clade]) – List of terminal nodes (tips).
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_is_rooted(*, warning: bool = False)

Asserts that the tree is rooted.

Parameters: warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_no_negatives(*, terminal: Optional[bool] = None, warning: bool = False)

Asserts that there are no negative branches.

Parameters

terminal (bool, optional) – True searches for only terminal nodes, False excludes terminal nodes, and the default, None, searches both terminal and non-terminal nodes, as well as any tree elements lacking the is_terminal method.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_number_of_tips(tips: Optional[int] = None, *, min: Optional[int] = None, max: Optional[int] = None, warning: bool = False)

Asserts that the number of tips meets the specified criteria.

Parameters

tips (int, optional) – If set, then number of tips must be equal to this value. Defaults to None.
min (int, optional) – If set, then number of tips must be equal to or greater than this value. Defaults to None.
max (int, optional) – If set, then number of tips must be equal to or less than this value. Defaults to None.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_root_to_tip(*, regression: Optional[treetime.treetime.TreeTime] = None, min_r_squared: Optional[float] = None, min_rate: Optional[float] = None, max_rate: Optional[float] = None, min_root_date: Optional[float] = None, max_root_date: Optional[float] = None, valid_confidence: Optional[bool] = None, extra: Optional[List] = None, warning: bool = False, **kwargs)

Checks inferred values from a root-to-tip regression.

Parameters

regression (TreeTime, optional) – The root-to-tip regression for this tree. If None, then this regression is calculated using the root_to_tip_regression method.
min_r_squared (float, optional) – If set, then R^2 must be equal or greater than this value. Defaults to None.
min_rate (float, optional) – If set, then the clock rate must be equal or greater than this value. Defaults to None.
max_rate (float, optional) – If set, then the clock rate must be equal or less than this value. Defaults to None.
min_root_date (float, optional) – If set, then the interpolated root date must be equal or greater than this value. Defaults to None.
max_root_date (float, optional) – If set, then the interpolated root date must be equal or less than this value. Defaults to None.
valid_confidence (bool, optional) – Checks that the valid_confidence value in the regression is equal to this boolean value. Defaults to None which does not perform a check.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.
extra (List) – The pytest-html extra fixture for adding in root-to-tip regression plot.
**kwargs – Keyword arguments for the root_to_tip_regression method.

assert_terminal_branch_lengths(*, min: Optional[float] = None, max: Optional[float] = None, warning: bool = False)

Asserts that the terminal brach lengths meet the specified criteria.

Parameters

min (float, optional) – If set, then each terminal brach length must be equal to or greater than this value. Defaults to None.
max (float, optional) – If set, then each terminal brach length must be equal to or less than this value. Defaults to None.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_tip_names(names: List[str], warning=False)

Asserts that the tree tip names match the supplied names.

Parameters

names (List[str]) – The names to match.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_tip_regex(patterns: Union[List[str], str], *, warning: bool = False)

Asserts that all the tips match at least one of a list of regular expression patterns.

Parameters

patterns (Union[List[str], str]) – The regex pattern(s) to match to. If a string, then every tip must match that pattern. If a list then each tip must match at least one pattern in the list.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_total_branch_length(length: Optional[float] = None, *, min: Optional[float] = None, max: Optional[float] = None, warning: bool = False)

Asserts that the total brach length meets the specified criteria.

Parameters

length (float, optional) – If set, then total brach length must be equal to this value. Defaults to None.
min (float, optional) – If set, then total brach length must be equal to or greater than this value. Defaults to None.
max (float, optional) – If set, then total brach length must be equal to or less than this value. Defaults to None.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_unique_tips(*, warning: bool = False)

Asserts that all the tip names are unique.

Parameters: warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

copy(): Makes a deep copy of this tree.

plot_root_to_tip(filename: Union[str, pathlib.Path], *, format: Optional[str] = None, regression: Optional[treetime.treetime.TreeTime] = None, add_internal: bool = False, label: bool = True, ax=None, **kwargs)

Plots a root-to-tip regression.

Parameters

filename (str, Path) – The path to save the plot as an image.
regression (TreeTime, optional) – The root-to-tip regression for this tree. If None, then this regression is calculated using the root_to_tip_regression method.
add_internal (bool) – Whether or not to plot the internal node positions. Default: False.
label (bool) – Whether or not to label the points. Default: True.
ax (matplotlib axes) – Uses matplotlib axes if provided. Default: None.
**kwargs – Keyword arguments for the root_to_tip_regression method.

root_to_tip_regression(*, dates: Optional[Dict] = None, alignment: Optional[Bio.Align.MultipleSeqAlignment] = None, sequence_length: Optional[int] = None, clock_filter: float = 3.0, gtr: Union[treetime.gtr.GTR, str] = 'JC69', root_method: str = 'least-squares', allow_negative_rate: bool = False, keep_root: bool = False, covariation: bool = False)

Performs a root-to-tip regression to determine how clock-like a tree is.

Parameters

dates (Dict, optional) – The tip dates as a dictionary with the tip name as the key and the date as the value. If not set, then it parses the tip dates to generate this dictionary using the parse_tip_dates method.
alignment (MultipleSeqAlignment, optional) – The alignment associated with this tree. Defaults to None.
sequence_length (int, optional) – The sequence length of the alignment. Defaults to None.
clock_filter (float, optional) – The number of interquartile ranges from regression beyond which to ignore. This provides a way to ignore tips that don’t follow a loose clock. Defaults to 3.0.
gtr (GTR, str, optional) – The molecular evolution model. Defaults to ‘JC69’.
allow_negative_rate (bool, optional) – Whether or not a negative clock rate is allowed. For trees with little temporal signal, it can be set to True to achieve essentially mid-point rooting. Defaults to False.
keep_root (bool, optional) – Keeps the current root of the tree. If False, then a new optimal root is sought. Defaults to False.
root_method (str, optional) – The method used to reroot the tree if keep_root is False. Valid choices are: ‘min_dev’, ‘least-squares’, and ‘oldest’. Defaults to ‘least-squares’.
covariation (bool, optional) – Accounts for covariation when estimating rates or rerooting. Defaults to False.

Data

class phytest.bio.data.Data(*args, **kwargs)

assert_columns(allowed_columns: List[str], *, exact: bool = False, warning: bool = False) → None

Asserts that the specified column(s) are in the DataFrame.

Parameters

allowed_columns (List[str], required) – The list of allowed columns.
exact (bool) – If True, the list of allowed columns must be exactly the same as the list of columns in the DataFrame.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_contains(column: str, value: str, *, warning: bool = False) → None

Asserts that specified column contains the specified value.

Parameters

column (str, required) – The column to check.
value (str, required) – the value to look for.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_match(column: str, pattern: str, *, warning: bool = False) → None

Asserts that all values of the specified column match the specified pattern.

Parameters

column (str, required) – The column to check.
pattern (str, required) – The pattern to match.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_range(column: str, *, min: Optional[Union[int, float]] = None, max: Optional[Union[int, float]] = None, warning: bool = False) → None

Asserts that all values of the specified column are in the specified range.

Parameters

column (str, required) – The column to check.
min (Union[int, float]) – The minimum value of the range.
max (Union[int, float]) – The maximum value of the range.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.

assert_values(column: str, values: list, *, allow_nan: bool = False, exact: bool = False, warning: bool = False) → None

Asserts that all values of the specified column are in the specified list of allowed values.

Parameters

column (str, required) – The column to check.
values (list, required) – The list of allowed values.
allow_nan (bool) – If True, allow NaN values.
exact (bool) – If True, the list of allowed values must be exactly the same as the list of values in the DataFrame.
warning (bool) – If True, raise a warning instead of an exception. Defaults to False. This flag can be set by running this method with the prefix warn_ instead of assert_.