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().

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 standard or matched cohorts, the color scale represents hazard ratios.

  • 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 hazard-ratio color scale for standard or matched cohorts. 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 comorbidity edges.

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.

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.