Skip to main content

pyHam: A Tool to Analyze Hierarchical Orthologous Groups (HOGs)

Motivation

pyHam is a library to facilitate the analysis of hierarchical orthologous groups. It also contains a few tools to run standard type of analysis.

Currently, Ham is limited to analyze HOGs that are stored in an orthoXML file. More information on the schema of orthoxml and some examples are available at http://orthoxml.org.

For extended documentation we refer to the docs folder that contain information on common use cases and API documentation of the library.

How to cite pyHam

If you use pyHam in your work, please consider citing:

Clément-Marie Train, Miguel Pignatelli, Adrian Altenhoff, Christophe Dessimoz; iHam and pyHam: visualizing and processing hierarchical orthologous groups, Bioinformatics, bty994, https://doi.org/10.1093/bioinformatics/bty994

Installation

pyHam requires Python 3.10 or newer. Its dependencies (ete4, lxml, requests, tqdm and scipy) are installed automatically by pip:

python -m pip install --upgrade pip
pip install pyham

To work on pyHam itself, install it in editable mode from a checkout of the git repository:

python -m pip install -e ".[dev]"
pytest

Quick start

import pyham

ham = pyham.Ham("simpleEx.phyloxml", "simpleEx.orthoxml",
                tree_format="phyloxml", use_internal_name=True)

# look up a gene family (HOG) and export it as a gene tree
hog = ham.get_hog_by_id("HOG:0355161")
print(hog.to_ete_tree().write())

# compare a species with one of its ancestors
human = ham.get_extant_genome_by_name("Homo sapiens")
primates = ham.get_ancestral_genome_by_name("Primates")
vmap = ham.compare_genomes_vertically(human, primates)
print(len(vmap.get_retained()), len(vmap.get_duplicated()),
      len(vmap.get_lost()), len(vmap.get_gained()))

Example

The example folder contains a few ready-to-use scripts that show the main pyHam features. Run them from inside that folder:

cd example
python run_hog_queries.py
python run_treeProfile.py
python run_iHam.py

Getting started

We create a small introductory blog post about HOGs and pyHam at http://lab.dessimoz.org/blog/2017/06/29/pyham. We highly recommend you to read it before starting using pyHam.

We also create an ipython notebook to help you with basic uses of pyHam API and embedded tools at http://zoo.cs.ucl.ac.uk/tutorials/tutorial_pyHam_get_started.html.

Table of compatibility

Support for pyHam by various HOG inference resources.

Resource

Species tree format

OrthoXML

SUPPORT

OMA browser

PhyloXML and Newick

All HOGs , or one HOG at a time

YES

OMA standalone

PhyloXML and Newick

All HOGs

YES

FastOMA

Newick

All HOGs

YES

Ensembl

Newick

one HOG at a time

YES

HieranoidDB

Newick

one HOG at a time

YES

Common input problems

Most errors when loading data come from a species tree that doesn’t match the OrthoXML file. To check your inputs before analysing them, run:

pyham-validate species_tree.nwk hogs.orthoxml

or, from Python, print(pyham.validate_input(tree_file, hog_file, ...)), which takes the same arguments as pyham.Ham. It reports every problem it finds at once, each with the affected species, levels or families and, where it can tell, how to fix it. The most common problems are:

  • Use the species tree the HOGs were inferred with. pyHam maps each HOG onto the species tree, so the tree must contain every species in the OrthoXML file under the same name, and its topology must agree with how the HOGs are nested. With OMA standalone and FastOMA, use the species tree written alongside the HOGs.

  • use_internal_name=True needs unique internal node names. Some newick trees label internal nodes with numbers (e.g. support values) instead of taxon names. pyHam then reports that the internal names are not unique. Pass use_internal_name=False and pyHam will build names from the child species instead.

  • PhyloXML trees need a name field on every node. Choose the field with phyloxml_leaf_name_tag and phyloxml_internal_name_tag. If the tree has no <taxonomy> elements, use clade_name, or pass use_internal_name=False.

  • Taxonomic conflicts. If a HOG’s taxonomic range (TaxRange or taxid) disagrees with the species tree, pyHam raises TaxonomicConflictError listing every conflicting family it found. Pass fail_fast=True to stop at the first one.

  • Singletons. Genes that belong to no HOG can be looked up with get_gene_by_id, but HOG-based tools such as tree profiles and iHam don’t apply to them.

Documentation

The full documentation of pyHam, including the API reference, is available at https://pyham-dessimozlab.readthedocs.io.

Metadata

Release files for pyham 2.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyham 2.0.1
File Size Uploaded Provenance Actions
pyham-2.0.1.tar.gz 1.4 MB With provenance Details for pyham-2.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyham 2.0.1
File Interpreter ABI Platform Actions
pyham-2.0.1-py3-none-any.whl Python 3 none any Details for pyham-2.0.1-py3-none-any.whl

Total release size: 1.5 MB

Release files / pyham-2.0.1.tar.gz

Download URL pyham-2.0.1.tar.gz
Size 1.4 MB
Tags Source
SHA-256 checksum
How to use checksums
591158271416c51332eb0565bda8beac8b30fd5c6db704e1719102d27beba685
BLAKE2b-256 checksum
How to use checksums
8503ddca6c694d3a1e5b48c1e4210f7831e6112e582ade86e4dbece47a5845aa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / pyham-2.0.1-py3-none-any.whl

Download URL pyham-2.0.1-py3-none-any.whl
Size 65.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e813595865399e2f50342e56070f3b03ccbc329dcacab0c2f6854e95c5a79685
BLAKE2b-256 checksum
How to use checksums
8d14a92f455306c2bd5ac0a682bfcb15097594bb7200a63afd037243ee30e2d5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for pyham 2.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pyham-2.0.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.0.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page