phenosign.analysis package

phenosign.analysis.correlation_type module

phenosign.analysis.hpo_correlation_analyzer module

class CorrelationResult(correlation_results: DataFrame, coef_matrix: DataFrame, pval_matrix: DataFrame, label_mapping: dict[str, str])

Bases: object

A class to store, manage, and visualize HPO pairwise correlation results.

filter_weak_correlations(corr_threshold: float = 0.1, adj_pval_threshold: float = 0.05) → tuple[DataFrame, DataFrame]

Filter the correlation and p-value matrices by effect size and significance.

Parameters:

  • corr_threshold (float, default=0.1) – Minimum correlation coefficient to retain.

  • adj_pval_threshold (float, default=0.05) – Maximum adjusted p-value to retain.

Returns:

Filtered correlation matrix and filtered p-value matrix.

Return type:

tuple[pd.DataFrame, pd.DataFrame]

plot_correlation_heatmap_with_significance(corr_threshold: float = 0.1, adj_pval_threshold: float = 0.05, title_name: str | None = None) → Figure

Plot an interactive correlation heatmap with statistical filtering.

property results_table: DataFrame

Get a safe copy of the correlation results table.

save_correlation_heatmap(output_file: str = 'correlation_heatmap.html') → None

Save a correlation heatmap as an HTML file.

Parameters:

output_file (str) – Output HTML file path.

save_correlation_results(corr_threshold: float = 0.1, adj_pval_threshold: float = 0.05, output_file: str = 'correlation_results.csv') → None

Save correlation results to a CSV or Excel file.

Parameters:

  • corr_threshold (float, default=0.0) – Minimum correlation coefficient to retain.

  • adj_pval_threshold (float, default=0.05) – Maximum adjusted p-value to retain.

  • output_file (str, default="correlation_results.csv") – Output file path. Supported formats are .csv.

Raises:

ValueError – If correlation results have not been computed or if thresholds are invalid.

class HPOCorrelationAnalyzer(dataset: PhenotypeDataset, min_individuals_for_correlation_test: int = 20)

Bases: object

Analyze pairwise correlations between HPO terms using the Phi coefficient and Fisher’s exact test.

compute_correlation_matrix(n_jobs: int = -1, include_pmids: bool = True) → DataFrame

Compute pairwise correlations between HPO terms.

Parameters:

  • correlation_type (str | CorrelationType, default="spearman") – Correlation metric to compute. Supported values: - “spearman” - “phi”

  • n_jobs (int, default=-1) – Number of parallel jobs. -1 uses all available CPUs.

  • include_pmids (bool, default=True) – If True, aggregate PMIDs from contributing individuals.

Returns:

An object encapsulating the long-format correlationnstatistics, symmetric

score/p-value matrices, and helper plotting methods.

Return type:

CorrelationResult

phenosign.analysis.synergy_analyzer module

class SynergyAnalyzer(dataset: PhenotypeDataset, min_individuals_for_synergy_calculation: int = 30, random_state: int = 42)

Bases: object

Analyze pairwise synergy between HPO terms with respect to a target.

This class computes pairwise feature synergy using mutual information and permutation testing. Targets can be retrieved from pre-built target matrices or generated from metadata.

compute_synergy_matrix(condition: Series, n_jobs=-1, include_pmids: bool = True, n_perms: int = 5000) → DataFrame

Compute pairwise synergy scores for all valid HPO term pairs.

Parameters:

  • condition (pd.Series) – Boolean condition to filter the dataset.

  • n_jobs (int, default=-1) – Number of parallel jobs. -1 uses all available CPUs.

  • include_pmids (bool, default=True) – If True, aggregate PMIDs from contributing individuals and include them in the result table.

  • n_perms (int, default=5000) – Number of Monte Carlo target-label permutations performed for each phenotype pair when exhaustive enumeration is not used. The resulting empirical p-value has a minimum attainable value of 1 / (n_perms + 1). Larger values provide finer p-value resolution and lower Monte Carlo uncertainty at greater computational cost.

Returns:

An object encapsulating the long-format synergy statistics, symmetric score/p-value matrices, and helper plotting methods.

Return type:

SynergyResult

evaluate_pair_synergy(i: int, j: int, n_perms: int = 5000, include_pmids: bool = True) → tuple[int, int, float, float, dict[str, Any]]

Compute synergy and a permutation-based p-value for one feature pair.

Parameters:

  • i (int) – Index of the first feature.

  • j (int) – Index of the second feature.

  • n_perms (int, default=5000) – Number of permutations used to estimate p-values.

  • include_pmids (bool, default=True) – If True, aggregate PMIDs from contributing individuals.

Returns:

Feature indices, corrected synergy, p-value, and count summary.

Return type:

tuple[int, int, float, float, dict]

class SynergyResult(synergy_results: DataFrame, synergy_matrix: DataFrame, pvalue_matrix: DataFrame, label_mapping: dict, condition_name: str)

Bases: object

Data class to hold synergy analysis results for pairs of HPO terms with respect to a target.

filter_weak_synergy(synergy_threshold: float = 0.01, adj_pval_threshold: float = 0.05) → tuple[DataFrame, DataFrame]

Filter the synergy and p-value matrices by effect size and significance.

plot_synergy_heatmap(synergy_threshold: float = 0.01, adj_pval_threshold: float = 0.05) → Figure

Plot an interactive heatmap of pairwise synergy values.

property results_table: DataFrame

Get a safe copy of the synergy results table.

save_synergy_heatmap(output_file: str = 'synergy_heatmap.html') → None

Save a synergy heatmap as an HTML file.

Parameters:

output_file (str) – Output HTML file path.

save_synergy_results(synergy_threshold: float = 0.01, adj_pval_threshold: float = 0.05, output_file: str = 'synergy_results.csv') → None

Save synergy results to a CSV or Excel file.

Parameters:

  • synergy_threshold (float, default=0.01) – Minimum synergy value to retain.

  • adj_pval_threshold (float, default=0.3) – Maximum adjusted p-value to retain.

  • output_file (str, default="synergy_results.csv") – Output file path. Supported formats are .csv.