Input validation

Check a species tree and an OrthoXML file against each other before analysing them with pyHam.

Most problems users hit when loading data come from a species tree that doesn’t match the OrthoXML file: species named differently, levels missing from the tree, or a group nesting that contradicts the tree. validate_input() checks for all of these in one go and returns a ValidationReport listing every problem found, instead of failing at the first one.

The checks run in four stages:

1. Species tree: can it be read, does every node have a name, are the names unique?

2. OrthoXML: duplicate species or gene ids, references to undefined genes, genes used twice.

3. Tree vs. OrthoXML: is every OrthoXML species a leaf of the tree, and is every level the OrthoXML claims for its HOGs (TaxRange/taxid) a node of the tree?

4. Trial build: if nothing above is an error, every family is built exactly as pyham.Ham would, but a family that fails is recorded and skipped instead of stopping the whole parse.

The same checks are available from the command line:

pyham-validate species_tree.nwk hogs.orthoxml

pyham.validation.validate_input(tree_file, hog_file, tree_format=None, use_internal_name=False, phyloxml_leaf_name_tag='taxonomy_scientific_name', phyloxml_internal_name_tag='taxonomy_scientific_name', orthoXML_as_string=False, trial_build=True)

Check a species tree and an OrthoXML file for problems that would stop pyHam, or make it silently build something different from what the files say.

Takes the same arguments as pyham.Ham, so the check reflects what Ham would do with them. Unlike Ham, it doesn’t stop at the first problem: it reports everything it finds.

Args:

tree_file (str): path to the species tree file, or a newick string.

hog_file (str): path to the OrthoXML file (may be gzipped), or its content if orthoXML_as_string is True.

tree_format (str, optional): ‘newick’, ‘newick_string’ or ‘phyloxml’. Defaults to guessing from the file extension.

use_internal_name (bool, optional): as for pyham.Ham. Defaults to False.

phyloxml_leaf_name_tag, phyloxml_internal_name_tag (str, optional): as for pyham.Ham.

orthoXML_as_string (bool, optional): hog_file is the OrthoXML content. Defaults to False.

trial_build (bool, optional): also build every family, as Ham would, and report the ones that fail. This takes about as long as loading the data with Ham. Defaults to True.

Returns:

ValidationReport: print it for a readable summary, or inspect its issues.

class pyham.validation.ValidationReport

Result of validate_input().

Print it for a human-readable report, or inspect issues (or errors, warnings, notes) programmatically.

Attributes:

inputs (dict): short description of each input that was checked.

issues (list of ValidationIssue): everything found, in the order it was found.

stats (dict): counts gathered along the way (species, genes, families, …).

trial_build (str): outcome of the trial build, or why it was skipped. None if not applicable.

format(max_items=10)

Render the report as text, showing at most max_items affected entities per issue.

property ok

True if no errors were found (warnings and notes are allowed).

raise_for_errors()

Raise InputValidationError if the report contains any error.

class pyham.validation.ValidationIssue(severity: str, code: str, summary: str, items: List[str] = <factory>, hint: str | None = None, data: dict = <factory>)

One problem, or noteworthy fact, found in the inputs.

Attributes:

severity (str): 'error' (pyHam will fail, or silently build something wrong), 'warning' (pyHam works, but probably not as intended) or 'note' (worth knowing).

code (str): stable identifier of the kind of issue, e.g. 'species-not-in-tree'.

summary (str): one-sentence description.

items (list of str): every affected entity, one description each. The printed report shows only the first few; this list is always complete.

hint (str): suggested fix, when one can be inferred from the data.

data (dict): machine-readable details, specific to each code.

class pyham.validation.InputValidationError(report, footer=None)

Raised when the inputs given to pyHam contain errors. The full ValidationReport is available as the report attribute.

Subclasses KeyError because that is what pyHam raised for these problems before.