API Reference

Below is a concise reference for DiNetxify classes and functions, based on the current package implementation.

Class `DiseaseNetworkData`

class DiseaseNetworkData(
    study_design: str = "cohort",
    phecode_level: int = 1,
    min_required_icd_codes: int = 1,
    date_fmt: str = "%Y-%m-%d",
    phecode_version: str = "1.2",
)

Create a data container for phenotype data, medical records, phecode mappings, and downstream pair-construction results.

Parameters:

study_design (str): One of "cohort", "matched cohort", "exposed-only cohort", or "nested case-control".
phecode_level (int): Phecode granularity, either 1 or 2.
min_required_icd_codes (int): Minimum mapped ICD count required before a phecode is counted as present.
date_fmt (str): Default date format used for phenotype data and, unless overridden, medical-record data.
phecode_version (str): One of "1.2" or "1.3a". Version "1.2" is the recommended general-purpose option.

Instance Methods

`phenotype_data`

phenotype_data(
    self,
    phenotype_data_path: str,
    column_names: dict,
    covariates: list,
    is_single_sex: bool = False,
    force: bool = False,
) -> None

Load phenotype data into the object.

Parameters:

phenotype_data_path (str): Path to a CSV or TSV phenotype file.
column_names (dict): Mapping from DiNetxify-required field names to dataset columns. Every End date must be strictly later than its Index date.
covariates (list): Additional phenotype variables to load. High-cardinality values are classified as continuous only when the source dtype is numeric; text values remain categorical.
is_single_sex (bool): Set to True if the cohort contains only one sex.
force (bool): Overwrite existing phenotype and medical-record data if True.

Returns:

None

`Table1`

Table1(
    self,
    continuous_stat_mode: str = "auto",
) -> pd.DataFrame

Generate a Table 1 style summary of the phenotype data.

Parameters:

continuous_stat_mode (str): One of "auto", "normal", or "nonnormal".

Returns:

pd.DataFrame

`merge_medical_records`

merge_medical_records(
    self,
    medical_records_data_path: str,
    diagnosis_code: str,
    column_names: dict,
    date_fmt: str = None,
    chunksize: int = 1000000,
    diagnosis_code_exclusion: list = [],
) -> None

Load and merge one medical-record file into the object.

Parameters:

medical_records_data_path (str): Path to a CSV or TSV diagnosis file.
diagnosis_code (str): One of "ICD-9-CM", "ICD-9-WHO", "ICD-10-CM", or "ICD-10-WHO".
column_names (dict): Mapping for "Participant ID", "Diagnosis code", and "Date of diagnosis".
date_fmt (str | None): Date format for this file. If None, use the object’s date_fmt.
chunksize (int): Number of rows processed per chunk.
diagnosis_code_exclusion (list): Diagnosis codes to exclude before Phecode mapping. Input and exclusion codes are normalized before matching. Rows missing participant ID, diagnosis code, or diagnosis date, and records after the participant’s End date, are excluded before counts are formed.

Returns:

None

`get_attribute`

get_attribute(
    self,
    attr_name: str,
) -> Any

Access selected internal metadata from the object.

Supported attribute names:

warning_phenotype
phenotype_statistics
phenotype_info
warning_medical_records
medical_records_statistics
medical_records_info
module_dir
significant_phecodes

Returns:

Requested value (Any)

`concat`

concat(
    cls,
    first_data: "DiseaseNetworkData",
    second_data: "DiseaseNetworkData",
    duplicates: str = "raise",
) -> "DiseaseNetworkData"

Class method reserved for concatenating two DiseaseNetworkData objects.

Current status:

Present in the API, but currently raises NotImplementedError.

`modify_phecode_level`

modify_phecode_level(
    self,
    phecode_level: int,
) -> None

Switch between phecode level 1 and 2. This cannot be done after trajectory data have already been generated.

Returns:

None

`disease_pair`

disease_pair(
    self,
    phewas_result: pd.DataFrame,
    min_interval_days: int = 0,
    max_interval_days: float = np.inf,
    force: bool = False,
    n_process: int = 1,
    **kwargs,
) -> None

Construct temporal and non-temporal disease pairs from significant PheWAS phecodes among exposed participants after an exposure or outcome cases before an outcome.

Parameters:

phewas_result (pd.DataFrame): Result table from phewas().
min_interval_days (int | float): Minimum gap required for a temporal D1 -> D2 relationship.
max_interval_days (int | float): Maximum gap allowed before a pair is treated as non-temporal.
force (bool): Overwrite existing trajectory data if True.
n_process (int): Must be 1. Parallel pair construction is disabled because it did not preserve the serial interval-classification behavior.
**kwargs: Optional column-name overrides:
- phecode_col (default 'phecode')
- significance_col (default 'phewas_p_significance')

Returns:

None

`medical_records_to_dataframe`

medical_records_to_dataframe(
    self,
    phecode_list: list,
    medical_history: bool = False,
) -> pd.DataFrame

Export selected phecodes from the stored medical records into a participant-level DataFrame.

Parameters:

phecode_list (list): Phecodes to extract.
medical_history (bool): If True, add <phecode>_history indicators.

Returns:

pd.DataFrame

`save`

save(
    self,
    file: str,
) -> None

Save the object as a gzip-compressed pickle file. The .pkl.gz suffix is appended automatically if needed.

`load`

load(
    self,
    file: str,
    force: bool = False,
) -> None

Load the object from a gzip-compressed pickle file.

`save_npz`

save_npz(
    self,
    file: str,
) -> None

Save the object as a compressed NumPy archive. The output file is written as .npz.

`load_npz`

load_npz(
    self,
    file: str,
    force: bool = False,
) -> None

Load the object from a compressed NumPy archive.

Analysis Functions

For p-value correction arguments throughout the analysis API, DiNetxify accepts 'none' or any method supported by statsmodels.stats.multitest.multipletests.

Function: `disease_network_pipeline`

disease_network_pipeline(
    data: DiseaseNetworkData,
    n_process: int,
    n_threshold_phewas: int,
    n_threshold_comorbidity: int,
    output_dir: str,
    project_prefix: str,
    keep_positive_associations: bool = False,
    save_intermediate_data: bool = False,
    system_inc: list = None,
    system_exl: list = None,
    phecode_inc: list = None,
    phecode_exl: list = None,
    pipeline_mode: str = "v1",
    method: str = "RPCN",
    covariates: list = None,
    matching_var_dict: dict = {"sex": "exact"},
    matching_n: int = 2,
    min_interval_days: int = 0,
    max_interval_days: float = np.inf,
    enforce_temporal_order: bool = False,
    correction: str = "bonferroni",
    cutoff=0.05,
    phewas_penalizer: float = 0.0,
    **kwargs,
) -> tuple

Run the main workflow:

PheWAS -> disease_pair -> comorbidity_strength -> binomial/comorbidity_network -> disease_trajectory

The loaded analysis group determines the workflow. Exposure data retain the original after-exposure analysis. Outcome cohorts use time-varying Cox PheWAS, and Outcome-only nested case-control data use conditional logistic PheWAS within Match ID sets. Downstream stages use the analysis-positive group. The selected pipeline_mode and its stage order are written to the pipeline log and stored in DataFrame.attrs on every returned result table. enforce_temporal_order controls both the binomial temporal filter and the trajectory interval rule; passing the old duplicate enforce_time_interval keyword to the pipeline raises ValueError.

Returns:

A 5-tuple in this order:
- phewas_result
- com_strength_result
- com_network_result
- binomial_result
- trajectory_result

Method-specific kwargs:

For method="RPCN":
- auto_penalty (bool, default True)
- alpha (float, required if auto_penalty=False)
- alpha_range (tuple, default (1, 15))
- scaling_factor (float, default 1)
For method="PCN_PCA":
- n_PC (int, default 5)
- explained_variance (float)

Function: `phewas`

phewas(
    data: DiseaseNetworkData,
    covariates: list = None,
    proportion_threshold: float = None,
    n_threshold: int = None,
    n_process: int = 1,
    correction: str = "bonferroni",
    cutoff: float = 0.05,
    system_inc: list = None,
    system_exl: list = None,
    phecode_inc: list = None,
    phecode_exl: list = None,
    log_file: str = None,
    lifelines_disable: bool = False,
    penalizer: float = 0.0,
    multiprocessing_start_method: str = None,
    method: str = "bfgs",
    maxiter: int = 300,
) -> pd.DataFrame

Run a phecode-wide association scan.

Notes:

n_threshold and proportion_threshold are mutually exclusive.
A proportional threshold is converted separately for each tested Phecode from the disease-eligible exposed group after history, sex, matched-set, and valid-follow-up restrictions. An absolute n_threshold is unchanged.
The same positive-follow-up population is used for thresholding, displayed summaries, and model fitting; sex-specific Phecodes are restricted to the applicable sex.
For after-exposure cohort and matched cohort data, PheWAS fits Cox models.
For exposed-only cohort, significance is based on the case-count threshold rather than a model-based p-value.
For before-outcome cohort data loaded with Outcome, phewas() runs the time-varying Cox PheWAS with statsmodels by default and lifelines fallback when lifelines_disable=False.
For nested case-control data, phewas() codes incident phecodes between Index date and the matched case diagnosis End date, then fits conditional logistic regression within Match ID sets. Its coefficient is a conditional log odds ratio.
multiprocessing_start_method ("fork", "spawn", or "forkserver"): optional override for multiprocessing. On POSIX systems the default prefers forkserver when it is safe to use.
method: optimizer passed to Statsmodels Cox fitting for after-exposure Cox models and before-outcome cohort time-varying Cox models. Supported values are "newton", "bfgs", "lbfgs", "nm", "cg", "ncg", "powell", and "basinhopping".
maxiter: maximum number of Statsmodels Cox optimizer iterations. The default is 300.
The PheWAS optimizer method is separate from disease_network_pipeline(method=...), which selects "RPCN", "PCN_PCA", or "CN". The Cox optimizer settings do not change nested case-control conditional logistic regression.

Function: `phewas_before_outcome_nested_case_control`

phewas_before_outcome_nested_case_control(
    data: DiseaseNetworkData,
    covariates: list = None,
    proportion_threshold: float = None,
    n_threshold: int = None,
    n_process: int = 1,
    correction: str = "bonferroni",
    cutoff: float = 0.05,
    system_inc: list = None,
    system_exl: list = None,
    phecode_inc: list = None,
    phecode_exl: list = None,
    log_file: str = None,
    multiprocessing_start_method: str = None,
) -> pd.DataFrame

Run the dedicated Outcome-only nested case-control PheWAS. Incident phecodes between Index date and the matched case diagnosis End date are compared by conditional logistic regression within Match ID sets. The common public phewas() function dispatches here automatically for this study design.

Function: `disease_network_before_outcome_pipeline`

Run the explicit before-outcome workflow for either a cohort or nested case-control DiseaseNetworkData object. Its five returned DataFrames and outcome-prefixed output files match the before-outcome branch of disease_network_pipeline().

Function: `phewas_multipletests`

phewas_multipletests(
    df: pd.DataFrame,
    correction: str = "bonferroni",
    cutoff: float = 0.05,
) -> pd.DataFrame

Apply multiple-testing correction to the PheWAS result table.

Function: `comorbidity_strength`

comorbidity_strength(
    data: DiseaseNetworkData,
    proportion_threshold: float = None,
    n_threshold: int = None,
    n_process: int = 1,
    log_file: str = None,
    correction_phi: str = "bonferroni",
    cutoff_phi: float = 0.05,
    correction_RR: str = "bonferroni",
    cutoff_RR: float = 0.05,
) -> pd.DataFrame

Estimate disease-pair strength in the analysis-positive group using phi correlation and relative risk.

Notes:

Requires disease pairs to have already been built with DiseaseNetworkData.disease_pair().
n_threshold and proportion_threshold are mutually exclusive.
A proportional threshold is calculated separately for each disease pair from its eligible exposed sub-cohort after history and sex restrictions. An absolute n_threshold is unchanged.
Phi is reported without clipping at -1 or 1. Its test statistic uses max(C_i, C_j) and a two-sided Student’s t test; RR uses the pair-specific sub-cohort size.

Function: `comorbidity_strength_multipletests`

comorbidity_strength_multipletests(
    df: pd.DataFrame,
    correction_phi: str = "bonferroni",
    cutoff_phi: float = 0.05,
    correction_RR: str = "bonferroni",
    cutoff_RR: float = 0.05,
) -> pd.DataFrame

Apply multiple-testing correction to phi_p and RR_p.

Function: `binomial_test`

binomial_test(
    data: DiseaseNetworkData,
    comorbidity_strength_result: pd.DataFrame,
    comorbidity_network_result: pd.DataFrame = None,
    n_process: int = 1,
    log_file: str = None,
    correction: str = "bonferroni",
    cutoff: float = 0.05,
    enforce_temporal_order: bool = False,
    **kwargs,
) -> pd.DataFrame

Test whether one temporal direction is more common than the reverse direction for disease pairs that are significant in comorbidity strength.

Parameters of interest:

comorbidity_network_result: Optional filter table. If supplied, only disease pairs retained by the network result are tested.
enforce_temporal_order: If True, exclude non-temporal D1-D2 pairs when forming the binomial test counts.

Notes:

Multiprocessing is currently disabled for this function.
**kwargs can be used to override relevant input-column names.

Function: `binomial_multipletests`

binomial_multipletests(
    df: pd.DataFrame,
    correction: str = "bonferroni",
    cutoff: float = 0.05,
) -> pd.DataFrame

Apply multiple-testing correction to binomial_p.

Function: `comorbidity_network`

comorbidity_network(
    data: DiseaseNetworkData,
    comorbidity_strength_result: pd.DataFrame,
    binomial_test_result: pd.DataFrame = None,
    method: str = "RPCN",
    covariates: list = None,
    n_process: int = 1,
    log_file: str = None,
    correction: str = "bonferroni",
    cutoff: float = 0.05,
    **kwargs,
) -> pd.DataFrame

Fit pairwise non-temporal comorbidity models.

Supported methods:

'CN': correlation network
'RPCN': regularized partial correlation network
'PCN_PCA': partial correlation network with principal components

Supported kwargs:

Column-name overrides for the input result tables:
- phecode_d1_col
- phecode_d2_col
- significance_phi_col
- significance_RR_col
- significance_binomial_col
Method-specific options:
- alpha, auto_penalty, alpha_range, scaling_factor
- n_PC, explained_variance
With automatic RPCN, scaling_factor multiplies candidate disease-covariate penalties. Selection uses the unscaled search-grid key, while the result reports the effective scaled alpha. With fixed RPCN, the supplied alpha is used directly.
enforce_time_interval (bool, default True)
multiprocessing_start_method ("fork", "spawn", or "forkserver"): optional override for Step 4 multiprocessing. On POSIX systems the default prefers forkserver when it is safe to use.

Function: `comorbidity_multipletests`

comorbidity_multipletests(
    df: pd.DataFrame,
    correction: str = "bonferroni",
    cutoff: float = 0.05,
) -> pd.DataFrame

Apply multiple-testing correction to comorbidity_p.

Function: `disease_trajectory`

disease_trajectory(
    data: DiseaseNetworkData,
    comorbidity_strength_result: pd.DataFrame,
    binomial_test_result: pd.DataFrame,
    method: str = "RPCN",
    matching_var_dict: dict = {"sex": "exact"},
    matching_n: int = 2,
    max_n_cases: int = np.inf,
    global_sampling: bool = False,
    covariates: list = None,
    n_process: int = 1,
    log_file: str = None,
    correction: str = "bonferroni",
    cutoff: float = 0.05,
    **kwargs,
) -> pd.DataFrame

Fit temporal disease-trajectory models using nested case-control sampling.

Parameters of interest:

matching_var_dict (dict): Matching criteria for trajectory sampling. Use 'exact' for categorical variables; use a positive numeric tolerance for continuous variables.
matching_n (int): Maximum number of matched controls per case.
max_n_cases (int | np.inf): Optional cap on the number of D2 cases.
global_sampling (bool): If True, sample once per unique D2 and fit separate D1 models within that sampled set.
Significant pairs in binomial_test_result must occur in the significant comorbidity-strength results. Pair matching is unordered, and an uncoupled pair raises ValueError before fitting.

Supported kwargs:

Column-name overrides for the input result tables:
- phecode_d1_col
- phecode_d2_col
- significance_phi_col
- significance_RR_col
- significance_binomial_col
Method-specific options:
- alpha, auto_penalty, alpha_range, scaling_factor
- n_PC, explained_variance
With automatic RPCN, scaling_factor multiplies candidate disease-covariate penalties. Selection uses the unscaled search-grid key, while the result reports the effective scaled alpha.
enforce_time_interval (bool, default True)
multiprocessing_start_method ("fork", "spawn", or "forkserver"): optional override for trajectory multiprocessing. On POSIX systems the default prefers forkserver when it is safe to use.

Function: `trajectory_multipletests`

trajectory_multipletests(
    df: pd.DataFrame,
    correction: str = "bonferroni",
    cutoff: float = 0.05,
) -> pd.DataFrame

Apply multiple-testing correction to trajectory_p.

Class `Plot`

Import with:

from DiNetxify.visualization import Plot

class Plot(
    phewas_result: pd.DataFrame,
    comorbidity_result: pd.DataFrame | None = None,
    trajectory_result: pd.DataFrame | None = None,
    exposure_name: str | None = None,
    exposure_location: Tuple[float] | None = None,
    exposure_size: float | None = None,
    outcome_name: str | None = None,
    outcome_location: Tuple[float] | None = None,
    outcome_size: float | None = None,
    phecode_col: str = "phecode",
    disease_col: str = "disease",
    system_col: str = "system",
    phewas_number_col: str = "N_cases_exposed",
    phewas_coef_col: str = "phewas_coef",
    phewas_se_col: str = "phewas_se",
    source_col: str = "phecode_d1",
    target_col: str = "phecode_d2",
    disease_pair_col: str = "name_disease_pair",
    comorbidity_beta_col: str = "comorbidity_beta",
    trajectory_beta_col: str = "trajectory_beta",
    phewas_significance_col: str = "phewas_p_significance",
    comorbidity_significance_col: str = "comorbidity_p_significance",
    trajectory_significance_col: str = "trajectory_p_significance",
    **kwargs,
)

Create a visualization object from PheWAS results, with optional comorbidity-network and trajectory result tables.

Required inputs:

phewas_result (pd.DataFrame)

Optional network inputs:

comorbidity_result (pd.DataFrame | None): Required for comorbidity_network_plot(), three_dimension_plot(), and trajectory_plot().
trajectory_result (pd.DataFrame | None): Required for three_dimension_plot() and trajectory_plot().

Optional display inputs:

exposure_name: Name of the exposure node. Set to None for exposed-only analyses.
exposure_location: 3D location of the exposure node.
exposure_size: Marker size for the exposure node.
outcome_name: Name of the terminal outcome node for before-outcome analyses. Do not specify it together with exposure_name.
outcome_location: 3D location of the outcome node.
outcome_size: Marker size for the outcome node.

Optional kwargs:

SYSTEM: Ordered list of disease systems to use in the legend and color mapping.
COLOR: Colors corresponding to SYSTEM.

Instance Methods

`interactive_website`

interactive_website(
    self,
    path: str,
) -> None

Generate a self-contained, multi-page interactive visualization website. The PheWAS section is always included. A comorbidity-network section is added when comorbidity_result is available, and disease-trajectory and 3D network sections are added when both comorbidity_result and trajectory_result are available. The generated website supports both exposure_name and outcome_name endpoint displays.

path: Output directory for the website. Open the generated index.html in a modern browser; no web server or internet connection is required.

Example:

result_plot.interactive_website(
    path="results/interactive_website"
)

`three_dimension_plot`

three_dimension_plot(
    self,
    path: str,
    max_radius: float = 180.0,
    min_radius: float = 35.0,
    line_color: str = "black",
    line_width: float = 1.0,
    size_reduction: float = 0.5,
    cluster_reduction_ratio: float = 1,
    layer_distance: float = 40.0,
    layout_width: float = 900.0,
    layout_height: float = 900.0,
    font_style: str = "Times New Roman",
    font_size: float = 15.0,
) -> None

Generate an interactive 3D HTML disease-network plot. Requires both comorbidity_result and trajectory_result.

`comorbidity_network_plot`

comorbidity_network_plot(
    self,
    path: str,
    max_radius: float = 180.0,
    min_radius: float = 35.0,
    size_reduction: float = 0.5,
    cluster_reduction_ratio: float = 1,
    line_width: float = 1.0,
    line_color: str = "black",
    layer_distance: float = 40.0,
    font_style: str = "Times New Roman",
) -> None

Generate an interactive 2D HTML comorbidity-network plot. Requires comorbidity_result.

`trajectory_plot`

trajectory_plot(
    self,
    path: str,
    dpi: float = 500,
) -> None

Generate trajectory plots as PNG files, one cluster per image. Requires both comorbidity_result and trajectory_result.

`phewas_plot`

phewas_plot(
    self,
    path: str,
    system_font_size: float = 17,
    disease_font_size: float = 10,
    HR_max: float = 2,
    incident_number_max: int = None,
    exposed_only_cohort: bool = False,
    dpi: float = 200,
) -> None

Generate a circular PheWAS plot as a static image.

API Reference

Class DiseaseNetworkData

Instance Methods

phenotype_data

Table1

merge_medical_records

get_attribute

concat

modify_phecode_level

disease_pair

medical_records_to_dataframe

save

load

save_npz

load_npz

Analysis Functions

Function: disease_network_pipeline

Function: phewas

Function: phewas_before_outcome_nested_case_control

Function: disease_network_before_outcome_pipeline

Function: phewas_multipletests

Function: comorbidity_strength

Function: comorbidity_strength_multipletests

Function: binomial_test

Function: binomial_multipletests

Function: comorbidity_network

Function: comorbidity_multipletests

Function: disease_trajectory

Function: trajectory_multipletests

Class Plot

Instance Methods

interactive_website

three_dimension_plot

comorbidity_network_plot

trajectory_plot

phewas_plot

Class `DiseaseNetworkData`

`phenotype_data`

`Table1`

`merge_medical_records`

`get_attribute`

`concat`

`modify_phecode_level`

`disease_pair`

`medical_records_to_dataframe`

`save`

`load`

`save_npz`

`load_npz`

Function: `disease_network_pipeline`

Function: `phewas`

Function: `phewas_before_outcome_nested_case_control`

Function: `disease_network_before_outcome_pipeline`

Function: `phewas_multipletests`

Function: `comorbidity_strength`

Function: `comorbidity_strength_multipletests`

Function: `binomial_test`

Function: `binomial_multipletests`

Function: `comorbidity_network`

Function: `comorbidity_multipletests`

Function: `disease_trajectory`

Function: `trajectory_multipletests`

Class `Plot`

`interactive_website`

`three_dimension_plot`

`comorbidity_network_plot`

`trajectory_plot`

`phewas_plot`