Skip to main content

multiHGtest

Testing for differences in survival using multiple hypergeometric P-values

PyPI version License: MIT

Overview

The multiHGtest package provides nonparametric methods for comparing survival between two populations with sensitivity to rare and localized departures from the null hypothesis of equal hazards. Unlike standard tests (e.g., log-rank), these methods are designed to detect non-proportional hazard differences that occur at only a few time points.

The approach works by:

  1. Computing exact hypergeometric P-values at each time interval, testing whether the observed number of events in one group deviates from what is expected under equal hazard rates.
  2. Combining these per-interval P-values using higher criticism or Fisher's combination test to obtain an overall test statistic.

This package implements the methods described in:

Kipnis, A., Galili, B., and Yakhini, Z. (2026). "Higher criticism for rare and weak non-proportional hazard deviations in survival analysis." Biometrika, 113(1).

Installation

From PyPI:

pip install multiHGtest

From source:

git clone https://github.com/alonkipnis/multiHGtest_package.git
cd multiHGtest_package
pip install -e .

Requirements

Quick Start

From survival table data (at-risk counts and events)

import numpy as np
from multiHGtest import hchg_test, fisher_hg_test, hg_test_dashboard

# Survival data: at-risk counts and events at each time interval
Nt1 = np.array([100, 95, 90, 85])  # Group 1 at-risk counts
Nt2 = np.array([100, 92, 88, 82])  # Group 2 at-risk counts
Ot1 = np.array([5, 5, 5, 3])       # Group 1 events
Ot2 = np.array([8, 4, 6, 3])       # Group 2 events

# Higher Criticism test
hc_stat = hchg_test(Nt1, Nt2, Ot1, Ot2, alternative='two-sided')
print(f"HC statistic: {hc_stat:.4f}")

# Fisher combination test
fisher_stat, fisher_pval = fisher_hg_test(Nt1, Nt2, Ot1, Ot2)
print(f"Fisher statistic: {fisher_stat:.4f}, p-value: {fisher_pval:.4f}")

# Full dashboard with all statistics
df, stats = hg_test_dashboard(Nt1, Nt2, Ot1, Ot2)
print(df)
print(stats)

From time-to-event data

If your data is in the standard time-to-event format (e.g., from clinical trials), you can convert it first:

import pandas as pd
from multiHGtest import from_time_to_event_to_survival_table, hchg_test

# Time-to-event data with columns: time, event (1=event, 0=censored), group
data = pd.DataFrame({
    'time':  [1, 2, 3, 4, 5, 1, 2, 3, 4, 5],
    'event': [1, 1, 0, 1, 0, 1, 0, 1, 1, 0],
    'group': [1, 1, 1, 1, 1, 2, 2, 2, 2, 2]
})

# Convert to survival table format
result = from_time_to_event_to_survival_table(data)

# Run the HCHG test
hc = hchg_test(
    result['at_risk_1'], result['at_risk_2'],
    result['observed_1'], result['observed_2'],
    alternative='two-sided'
)
print(f"HC statistic: {hc:.4f}")

API Reference

hchg_test(Nt1, Nt2, Ot1, Ot2, alternative='two-sided', **kwargs)

Higher Criticism test of hypergeometric P-values. Returns the HC test statistic.

Parameter Description
Nt1, Nt2 At-risk counts per time interval for groups 1 and 2
Ot1, Ot2 Event counts per time interval for groups 1 and 2
alternative 'greater', 'less', or 'two-sided' (default)
gamma HC threshold parameter (default: 0.4)
randomize Use randomized P-values (default: False)

fisher_hg_test(Nt1, Nt2, Ot1, Ot2, **kwargs)

Fisher combination test of hypergeometric P-values. Returns (statistic, p_value).

hg_test_dashboard(Nt1, Nt2, Ot1, Ot2, **kwargs)

Comprehensive dashboard returning a DataFrame with per-interval results and a dictionary with HC, Fisher, and MinP statistics.

hypergeom_test(k, M, n, N, alternative='greater', randomize=False)

Exact hypergeometric test for comparing proportions. Supports 'greater', 'less', and 'two-sided' alternatives.

from_time_to_event_to_survival_table(data, time_col, event_col, group_col)

Convert time-to-event (survival) data into the at-risk/event count format required by the test functions.

Legacy aliases

For backward compatibility: HCHGtest, FisherHGtest, testHG_dashboard.

Running Tests

pip install -e ".[dev]"
pytest

Citation

If you use this package in your research, please cite:

@article{kipnis2026higher,
  title={Higher criticism for rare and weak non-proportional hazard deviations in survival analysis},
  author={Kipnis, Alon and Galili, Ben and Yakhini, Zohar},
  journal={Biometrika},
  volume={113},
  number={1},
  year={2026}
}

License

MIT License. See LICENSE for details.

Metadata

Release files for multiHGtest 0.0.6

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

Source distribution (sdist)

Source distribution for multiHGtest 0.0.6
File Size Uploaded Provenance Actions
multihgtest-0.0.6.tar.gz 15.5 kB Without provenance Details for multihgtest-0.0.6.tar.gz

Built distribution (wheel)

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

Total release size: 23.9 kB

Release files / multihgtest-0.0.6.tar.gz

Download URL multihgtest-0.0.6.tar.gz
Size 15.5 kB
Tags Source
SHA-256 checksum
How to use checksums
e49d25118bc90ba8778b642fee2202652943a2a8d2a802e9f81083e42cfdc0f4
BLAKE2b-256 checksum
How to use checksums
90482da735b587b0641d105997d76a67e52a491c1c653ef241b382a45a38cedd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.6

Release files / multihgtest-0.0.6-py3-none-any.whl

Download URL multihgtest-0.0.6-py3-none-any.whl
Size 8.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2cffb0c14a36e22f397b5ac2346e3c1a75bba560428335232fbaeab5bc541742
BLAKE2b-256 checksum
How to use checksums
7b4f3fc3142b7249bc864b658bc353c7f08cb155260412a7051ef3dc1baaf18a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.6

Security for multiHGtest 0.0.6

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.

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