Visualization

DiNetxify.visualization.Plot turns the result tables produced by DiNetxify into publication-ready static figures and interactive network views. The class combines three complementary outputs:

  • PheWAS results

  • Comorbidity network results

  • Disease trajectory results

The visualization module assumes all provided result tables use consistent phecode identifiers. During initialization, Plot always validates the PheWAS table, optionally validates the comorbidity and trajectory tables, verifies that diseases in provided network tables also appear in the PheWAS table, and keeps only significant positive associations for the comorbidity and trajectory networks.

Initialize a Plot object

Import the plotting class from the visualization module:

from DiNetxify.visualization import Plot

PheWAS only

result_plot = Plot(
    phewas_result=phewas_result
)

PheWAS plus comorbidity network

result_plot = Plot(
    phewas_result=phewas_result,
    comorbidity_result=comorbidity_result
)

Standard or matched cohort

result_plot = Plot(
    phewas_result=phewas_result,
    comorbidity_result=comorbidity_result,
    trajectory_result=trajectory_result,
    exposure_name="Smoking",
    exposure_location=(0, 0, 0),
    exposure_size=15
)

Exposed-only cohort

For an exposed-only cohort, set the exposure-related arguments to None:

result_plot = Plot(
    phewas_result=phewas_result,
    comorbidity_result=comorbidity_result,
    trajectory_result=trajectory_result,
    exposure_name=None,
    exposure_location=None,
    exposure_size=None
)

Default result columns

If you use the output generated by the DiNetxify analysis module without renaming columns, the defaults should work directly:

  • phecode_col='phecode'

  • disease_col='disease'

  • system_col='system'

  • phewas_number_col='N_cases_exposed'

  • phewas_coef_col='phewas_coef'

  • phewas_se_col='phewas_se'

  • source_col='phecode_d1'

  • target_col='phecode_d2'

  • disease_pair_col='name_disease_pair'

  • comorbidity_beta_col='comorbidity_beta'

  • trajectory_beta_col='trajectory_beta'

  • phewas_significance_col='phewas_p_significance'

  • comorbidity_significance_col='comorbidity_p_significance'

  • trajectory_significance_col='trajectory_p_significance'

If your tables use different column names, pass the alternatives when creating Plot.

Only phewas_result is always required. Add comorbidity_result for Plot.comorbidity_network_plot(), and add both comorbidity_result and trajectory_result for Plot.three_dimension_plot() and Plot.trajectory_plot().

When an outcome-style PheWAS table does not contain the default N_cases_exposed column, Plot automatically uses N_cases_outcome_group. Nested conditional-logistic results also switch the PheWAS effect legend from hazard ratio to odds ratio through model_type.

Optional system colors

You can also customize the order and colors of phecode systems with SYSTEM and COLOR:

result_plot = Plot(
    phewas_result=phewas_result,
    comorbidity_result=comorbidity_result,
    trajectory_result=trajectory_result,
    SYSTEM=["circulatory system", "neurological", "others"],
    COLOR=["#94B447", "#8C564B", "#4ECDC4"]
)

PheWAS plot

Plot.phewas_plot() creates a circular summary plot of significant PheWAS results.

  • In cohort and matched-cohort Cox analyses, the color scale represents hazard ratios.

  • In nested case-control analyses, the color scale represents conditional odds ratios when the PheWAS result includes model_type.

  • In exposed-only cohorts, the color scale represents incident counts.

Example:

result_plot.phewas_plot(
    path="results/phewas_plot.png",
    exposed_only_cohort=False
)

Main parameters:

  • path: Output file path. Any format supported by Matplotlib can be used, such as .png, .svg, or .jpg.

  • exposed_only_cohort: Set to True for exposed-only analyses and False for standard or matched cohorts.

  • system_font_size: Font size for disease-system labels. Default: 17.

  • disease_font_size: Font size for disease labels. Default: 10.

  • HR_max: Upper bound of the exponentiated-effect color scale (hazard ratio or conditional odds ratio). Default: 2.

  • incident_number_max: Upper bound of the incident-count color scale for exposed-only cohorts. None uses the maximum observed count. Default: None.

  • dpi: Output resolution. Default: 200.

Comorbidity network plot

Plot.comorbidity_network_plot() creates an interactive HTML view of the comorbidity network. Diseases are grouped into communities, colored by disease system, and connected by significant network edges. If the Plot object was initialized with both comorbidity_result and trajectory_result, trajectory-only edges are included when assigning modules so module labels stay consistent with trajectory_plot() and three_dimension_plot(). If only comorbidity_result was provided, modules are based on comorbidity edges only.

Example:

result_plot.comorbidity_network_plot(
    path="results/comorbidity_network.html"
)

Main parameters:

  • path: Output HTML file path.

  • max_radius: Maximum radial distance for node placement. Default: 180.0.

  • min_radius: Minimum radial distance for node placement. Default: 35.0.

  • size_reduction: Scales node sizes. Default: 0.5.

  • cluster_reduction_ratio: Controls spacing between module sectors. Default: 1.

  • line_width: Width of comorbidity edges. Default: 1.0.

  • line_color: Color of comorbidity edges. Default: 'black'.

  • layer_distance: Distance between concentric layers. Default: 40.0.

  • font_style: Font family used in the figure. Default: 'Times New Roman'.

Disease trajectory plot

Plot.trajectory_plot() generates one static .png figure per disease module, showing directed disease trajectories within that module.

For before-outcome analysis, initialize Plot with outcome_name rather than exposure_name. The outcome node is then placed at the bottom of the 3D and trajectory plots without modifying the result tables.

Example:

result_plot.trajectory_plot(
    path="results/trajectory_plots"
)

Notes:

  • path must be an existing directory.

  • The function writes one file per module using names such as cluster_0.png.

  • dpi controls output resolution and defaults to 500.

Three-dimensional plot

Plot.three_dimension_plot() builds an interactive 3D HTML visualization that combines the comorbidity network and disease trajectories in a single view. If exposure_name is provided, the exposure node is placed at the center and the trajectory layers are arranged relative to it.

Example:

result_plot.three_dimension_plot(
    path="results/three_dimension_network.html"
)

Main parameters:

  • path: Output HTML file path.

  • max_radius: Maximum radial distance for node placement. Default: 180.0.

  • min_radius: Minimum radial distance for node placement. Default: 35.0.

  • line_color: Color of trajectory edges. Default: 'black'.

  • line_width: Width of trajectory edges. Default: 1.0.

  • size_reduction: Scales node sizes. Default: 0.5.

  • cluster_reduction_ratio: Controls spacing between module sectors. Default: 1.

  • layer_distance: Vertical spacing between trajectory layers. Default: 40.0.

  • layout_width: Figure width in pixels. Default: 900.0.

  • layout_height: Figure height in pixels. Default: 900.0.

  • font_style: Font family used in the figure. Default: 'Times New Roman'.

  • font_size: Base font size. Default: 15.0.

The exported HTML supports rotation, zooming, and node-based trajectory highlighting.

Interactive visualization website

Plot.interactive_website() generates a self-contained, multi-page website from the result tables available in the Plot object. The website combines interactive result exploration with downloadable figures and cleaned data payloads.

Example:

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

The generated sections depend on the supplied results:

  • phewas_result: PheWAS scatter plot and, when effect estimates are available, forest plot.

  • phewas_result and comorbidity_result: PheWAS and comorbidity-network sections.

  • phewas_result, comorbidity_result, and trajectory_result: PheWAS, comorbidity network, disease trajectories, and 3D network sections.

The PheWAS pages support disease-system filtering and condition selection. The network pages add module and system filters, search, labels, tooltips, zoom, and figure export. The website also saves cleaned result payloads and an automatically positioned data/comorbidity.gexf file when a comorbidity result is supplied.

For after-exposure analyses, exposure_name is displayed as the starting endpoint of the interactive disease trajectories. For before-outcome analyses, set outcome_name instead; it is displayed as the terminal endpoint. The 3D page retains the corresponding exposure or outcome configuration from the Plot object.

Open the generated index.html in a modern browser. All required website assets are written to path, so no web server or internet connection is required. If trajectory_result is supplied without comorbidity_result, the website contains only the PheWAS section because trajectory modules cannot be constructed without the comorbidity network.