phenosign.ontology package

phenosign.ontology.hierarchy module

class HPOHierarchyEngine(hpo_file: IO[Any] | str | None = None, release: str | None = None)

Bases: object

Perform hierarchy-aware operations on HPO feature matrices.

This class supports: - Propagation of observed and excluded HPO terms through the ontology hierarchy. - Construction of pairwise relationship masks for downstream analyses. - Canonicalization of HPO term IDs and merging of duplicate columns.

Input matrices are expected to use:

1 = observed 0 = excluded NaN = unknown

Invalid HPO terms are removed during preprocessing.

build_relationship_mask(terms: Sequence[str]) → DataFrame

Build a pairwise relationship mask for HPO terms.

Related terms (ancestor, descendant, or self) are marked with NaN, while unrelated terms are marked with 0. This mask can be used to exclude ontology-related term pairs in correlation or synergy analyses.

Parameters:

terms (Sequence[str]) – Canonical HPO term IDs (typically obtained after propagation). The input order is preserved.

Returns:

Square matrix indexed by HPO term IDs, where NaN indicates related terms (ancestor, descendant, or self) and 0 indicates unrelated terms.

Return type:

pd.DataFrame

get_id_mapping() → dict[str, str]

Return cached mapping from original to canonical HPO term IDs.

get_labels() → dict[str, str]

Return cached HPO term labels.

property hpo: MinimalOntology

Direct access to underlying HPO ontology (read-only).

propagate(matrix: DataFrame) → DataFrame

Propagate HPO observations and exclusions through the ontology hierarchy.

Observed terms (1) are propagated to ancestor terms, and excluded terms (0) are propagated to descendant terms. Conflicts (1 vs 0) are logged as warnings but the original value is preserved.

Parameters:

matrix (pd.DataFrame) – HPO status matrix with individuals as rows and HPO terms as columns. Values should be 1 (observed), 0 (excluded), or NaN (unknown).

Returns:

Matrix with propagated values and canonicalized HPO term IDs.

Return type:

pd.DataFrame