phenosign.core package

phenosign.core.dataset module

class PhenotypeDataset(hpo_data: HpoFeatureData, phenopackets: list[Phenopacket] = <factory>, gpsea_cohort: Cohort | None = None)

Bases: object

High-level dataset wrapper for phenotype-based analysis.

This class integrates HPO feature matrices, phenopacket metadata, and optional GPSEA variant annotations into a unified analysis interface.

describe_conditions() → tuple[DataFrame, DataFrame, DataFrame, DataFrame | None]

Generate summary tables describing key cohort-level conditions.

This method provides an overview of diseases, sex distribution, gene annotations, and variant effects (if a GPSEA cohort is available).

describe_sex() → DataFrame

Summarize sex distribution across individuals.

Returns:

Columns:

sex :
One of female, male, or unknown.
n_individuals :
Count of individuals with this sex.

Return type:

pd.DataFrame

property feature_ids: Index: HPO feature IDs (matrix columns).

get_condition(predicate: Callable[[Phenopacket], bool | None], *, name: str | None = None) → Series

Convert a phenopacket predicate into an individual-level binary condition.

Parameters:

predicate (Callable[[ppkt.Phenopacket], bool | None]) – Function that maps a phenopacket to True, False, or None (unknown).
name (str | None, optional) – Name of the condition to store in cache. Default is None.

Returns:

Index: individual IDs Values: - 1.0 = True - 0.0 = False - NaN = unknown

Return type:

pd.Series

Raises:

TypeError – If predicate returns a non-bool/non-None value.
RuntimeError – If predicate raises an exception for a specific individual.

get_pmids() → Series

Retrieve PubMed IDs associated with a list of individuals.

Returns:: Index: individual IDs Values: list of PMIDs as strings. Empty list if no PMIDs found.
Return type:: pd.Series

get_variant_condition(predicate: Callable[[Patient], bool | None], *, name: str | None = None) → Series

Build a binary condition vector for transcript-aware variant effects.

Parameters:

predicate (Callable[[Patient], bool | None]) – Function that maps a GPSEA Patient to True, False, or None.
name (str | None, optional) – Name of the condition to store in cache. Default is None.

Returns:

Index: individual IDs Values: - 1.0 : True - 0.0 : False - NaN : unknown

Return type:

pd.Series

Raises:

ValueError – If GPSEA cohort is not available.

gpsea_cohort: Cohort | None = None

hpo_data: HpoFeatureData

property individual_ids: Index: Individual IDs (matrix index).

list_diseases() → DataFrame

Summarize observed diseases across individuals.

Returns:

Columns:

disease_id :
Disease identifier (e.g., OMIM or ORPHA ID).
label :
Human-readable disease label.
n_individuals :
Number and percentage of individuals with the disease.

Return type:

pd.DataFrame

list_genes() → DataFrame

List gene symbols annotated in the cohort.

Returns:

Columns:

gene_symbol :
HGNC gene symbol.
n_individuals :
Number and percentage of individuals carrying variants in the gene.

Return type:

pd.DataFrame

phenopackets: list[Phenopacket]

variant_effect_summary() → DataFrame

Summarize GPSEA variant effects by transcript.

Calculates variant effect distributions for each transcript. Returns a transposed matrix where each cell contains both absolute counts and percentages.

Returns:

pd.DataFrame –

Rows:
Variant effect types (e.g., MISSENSE, NONSENSE)

Columns:
Transcript IDs

Values:
Strings formatted as "count (percentage%)"
Example – 15 (75.0%)

Raises:

ValueError – If no GPSEA cohort has been loaded.

phenosign.core.features module

phenosign.core.predicates module

has_disease(disease_id: str) → Callable[[Phenopacket], bool | None]

Generate a predicate to check if a phenopacket matches a specific disease status.

Parameters:

disease_id (str) – The target disease identifier to query (e.g., “OMIM:154700”).

Returns:

A predicate function that takes a Phenopacket and returns:

True : If the disease is explicitly listed as observed.
False : If the disease is explicitly marked as excluded, or not found.
None : (Reserved for missing disease block context, defaults to False here).

Return type:

Callable[[phenopackets.Phenopacket], bool | None]

has_exon_and_variant_effect(transcript_id: str, exon: int, variant_effect: VariantEffect) → Callable[[Patient], bool | None]

Generate a predicate to identify variants spanning both a specific exon and variant effect.

Useful for granular genotype-phenotype analysis, such as isolating variants localized within hotspot domains (e.g., FBN1 exons 24-32).

Parameters:

transcript_id (str) – The target transcript identifier (e.g., “NM_000138.5”).
exon (int) – The specific exon number expected to be affected (1-based index).
variant_effect (VariantEffect) – The expected GPSEA VariantEffect consequence.

Returns:

A predicate function that takes a GPSEA Patient and returns:

True : If a variant disrupts the designated exon AND exhibits the specified effect.
False : If the transcript is tracked but no variant satisfies both criteria simultaneously.
None : If the transcript model itself is not annotated within the patient’s variants.

Return type:

Callable[[gpsea.model.Patient], bool | None]

has_gene(symbol: str) → Callable[[Phenopacket], bool | None]

Generate a predicate to detect the presence of causative variants in a target gene.

Inspects both the gene_descriptor block and the gene_context within the genomic interpretations of a phenopacket.

Parameters:

symbol (str) – The HGNC gene symbol to search for (e.g., “FBN1”, “NOTCH1”).

Returns:

A predicate function that takes a Phenopacket and returns:

True : If a diagnostic variant is found mapped to the target gene symbol.
False : If genomic interpretations exist, but none implicate the target gene.
None : If the phenopacket contains no genomic interpretations/diagnostic data.

Return type:

Callable[[phenopackets.Phenopacket], bool | None]

has_sex(sex: str) → Callable[[Phenopacket], bool | None]

Generate a predicate to verify if a phenopacket matches the designated biological sex.

Parameters:

sex (str) – The biological sex to filter by. Must be either ‘female’ or ‘male’ (case-insensitive).

Returns:

A predicate function that takes a Phenopacket and returns:

True : If the individual’s sex matches the specified criterion.
False : If the individual’s sex is explicitly different.
None : If the subject context or sex info is entirely missing/unknown.

Return type:

Callable[[phenopackets.Phenopacket], bool | None]

Raises:

ValueError – If the input sex string is not ‘female’ or ‘male’.

has_variant_effect(transcript_id: str, variant_effect: VariantEffect) → Callable[[Patient], bool | None]

Generate a predicate to filter GPSEA Patients by a specific molecular variant effect.

Evaluates transcript annotations mapped to the specified transcript model identifier.

Parameters:

transcript_id (str) – The target transcript identifier (e.g., “NM_000138.5”, “ENST00000316673”).
variant_effect (VariantEffect) – The target GPSEA VariantEffect enum or object to evaluate (e.g., MISSENSE_VARIANT).

Returns:

A predicate function that takes a GPSEA Patient and returns:

True : If the patient carries a variant with the exact effect on the transcript.
False : If annotations for the transcript exist, but the specified effect is absent.
None : If no annotations for the given transcript id are detected in this patient.

Return type:

Callable[[gpsea.model.Patient], bool | None]

phenosign.core.builder module

class PhenotypeDatasetBuilder(phenopackets: list[Phenopacket], *, hpo_file: IO[Any] | str | None = None, hpo_release: str | None = None)

Bases: object

Builder class to create an analysis-ready PhenotypeDataset from phenopackets.

build(missing_threshold: float = 1.0, build_gpsea_cohort: bool = True) → PhenotypeDataset

Parse phenopackets and assemble a PhenotypeDataset

Parameters:

missing_threshold (float, default=1.0) – Threshold for filtering out individuals with too many missing HPO terms. 1.0 (default): no filtering, keep all individuals regardless of missingness.
build_gpsea_cohort (bool, default=True) – If True, build a GPSEA cohort from phenopackets for variant-based conditions. Requires GPSEA to be installed.

Returns:

Analysis-ready dataset containing: - hpo_data : HpoFeatureData instance with HPO matrix, labels, and relationship mask - phenopackets : raw phenopackets for reference - gpsea_cohort : optional GPSEA cohort if build_gpsea_cohort=True

Return type:

PhenotypeDataset

Raises:

ValueError – If no HPO terms are found in the phenopackets, or none remain after filtering.