KGBN.sensitivity_analysis

The KGBN.sensitivity_analysis module provides three helpers for analyzing PBNs:

• sensitivity_analysis: Morris or Sobol sensitivity analysis against experimental measurements.

• influence_analysis: node-to-node influence analysis from steady-state samples.

• mse_sensitivity_analysis: MSE change after perturbing probabilities in an optimized PBN.

Install optional dependencies with pip install "KGBN[sensitivity]" or pip install "KGBN[all]".

KGBN.sensitivity_analysis.sensitivity_analysis(network, experiments, config=None, top_n=5, verbose=True, Measured_formula: str | None = None, normalize: bool = False)

Perform sensitivity analysis to identify the most influential nodes affecting measurements.

class KGBN.sensitivity_analysis.PBNSensitivityAnalyzer(network, experiments, config=None, verbose=True, Measured_formula: str | None = None, normalize: bool = False)

Bases: object

Performs sensitivity analysis on PBN using existing steady state methods.

Methods

get_top_sensitive_nodes(sensitivity_df[, top_n])	Extract top N sensitive nodes from results
run_analysis()	Run the sensitivity analysis

__init__(network, experiments, config=None, verbose=True, Measured_formula: str | None = None, normalize: bool = False)

run_analysis()

Run the sensitivity analysis

get_top_sensitive_nodes(sensitivity_df, top_n=5)

Extract top N sensitive nodes from results

KGBN.sensitivity_analysis.plot_sensitivity_results(sensitivity_df, top_n=20, save_path=None)

Create visualization of sensitivity analysis results.

KGBN.sensitivity_analysis.influence_analysis(network, output_node: str | int | None = None, config: Dict | None = None, top_n: int = 10, only_inputs: bool = True, verbose: bool = True) → Dict[str, object]

Perform influence analysis on a Probabilistic Boolean Network.

This function calculates the influence of each node on others based on the Shmulevich et al. (2002) definition:

Inf(i -> j) = sum_k p_k^{(j)} * P_X[ f_k^{(j)}(X) != f_k^{(j)}(X^{(i)}) ]

where X is sampled from the steady state distribution.

KGBN.sensitivity_analysis.mse_sensitivity_analysis(network, experiments, config=None, top_n=5, verbose=True, Measured_formula: str | None = None, normalize: bool = False)

Perform MSE sensitivity analysis to identify which nodes have the largest impact on model fitting quality.

This function analyzes how changes in node probabilities affect the Mean Squared Error (MSE) between model predictions and experimental data. It’s useful for understanding which nodes are most critical for maintaining the model’s fit to experimental data.

class KGBN.sensitivity_analysis.MSESensitivityAnalyzer(network, experiments, config=None, verbose=True, Measured_formula: str | None = None, normalize: bool = False)

Bases: object

Performs MSE sensitivity analysis on PBN to identify nodes critical for model fitting.

Methods

get_top_sensitive_nodes(sensitivity_df[, top_n])	Extract top N sensitive nodes from results
run_analysis()	Run the MSE sensitivity analysis

__init__(network, experiments, config=None, verbose=True, Measured_formula: str | None = None, normalize: bool = False)

run_analysis()

Run the MSE sensitivity analysis

get_top_sensitive_nodes(sensitivity_df, top_n=5)

Extract top N sensitive nodes from results

KGBN.sensitivity_analysis.plot_influence_results(influence_df, sensitivity_df, top_n=20, save_path=None)

Create visualization of influence analysis results.

KGBN.sensitivity_analysis.plot_mse_sensitivity_results(sensitivity_df, baseline_mse, top_n=20, save_path=None)

Create visualization of MSE sensitivity analysis results.

Inputs

Sensitivity functions expect a ProbabilisticBN object. Convert a BN to a PBN before analysis:

import KGBN

bn = KGBN.load_network("model.txt", network_type="bn")
pbn_string, nodes_to_optimize = KGBN.BN2PBN(bn, prob=0.8)
pbn = KGBN.load_network(pbn_string, network_type="pbn")

For sensitivity_analysis and mse_sensitivity_analysis, pass either an experiment CSV path or a list of experiment dictionaries. See KGBN.experiment_data for the CSV format.

Functions

sensitivity_analysis

KGBN.sensitivity_analysis.sensitivity_analysis(network, experiments, config=None, top_n=5, verbose=True, Measured_formula: str | None = None, normalize: bool = False)

Perform sensitivity analysis to identify the most influential nodes affecting measurements.

from KGBN.sensitivity_analysis import sensitivity_analysis

results = sensitivity_analysis(
    pbn,
    "experiments.csv",
    config={
        "sensitivity_method": "morris",  # or "sobol"
        "morris_trajectories": 20,
        "sobol_samples": 512,
        "parallel": True,
        "n_workers": -1,
        "steady_state": {
            "method": "tsmc",
            "tsmc_params": {
                "epsilon": 0.01,
                "max_iterations": 1000,
            },
        },
    },
    top_n=10,
)

print(results["sensitivity_df"])
print(results["top_nodes"])

influence_analysis

KGBN.sensitivity_analysis.influence_analysis(network, output_node: str | int | None = None, config: Dict | None = None, top_n: int = 10, only_inputs: bool = True, verbose: bool = True) → Dict[str, object]

Perform influence analysis on a Probabilistic Boolean Network.

This function calculates the influence of each node on others based on the Shmulevich et al. (2002) definition:

Inf(i -> j) = sum_k p_k^{(j)} * P_X[ f_k^{(j)}(X) != f_k^{(j)}(X^{(i)}) ]

where X is sampled from the steady state distribution.

from KGBN.sensitivity_analysis import influence_analysis, plot_influence_results

results = influence_analysis(
    pbn,
    config={
        "method": "tsmc",
        "samples": 10000,
        "burn_in": 2000,
        "thin": 5,
        "epsilon": 0.001,
    },
    top_n=10,
)

plot_influence_results(
    results["influence_df"],
    results["sensitivity_df"],
    top_n=20,
    save_path="influence_analysis.png",
)

mse_sensitivity_analysis

KGBN.sensitivity_analysis.mse_sensitivity_analysis(network, experiments, config=None, top_n=5, verbose=True, Measured_formula: str | None = None, normalize: bool = False)

Perform MSE sensitivity analysis to identify which nodes have the largest impact on model fitting quality.

This function analyzes how changes in node probabilities affect the Mean Squared Error (MSE) between model predictions and experimental data. It’s useful for understanding which nodes are most critical for maintaining the model’s fit to experimental data.

from KGBN.sensitivity_analysis import (
    mse_sensitivity_analysis,
    plot_mse_sensitivity_results,
)

results = mse_sensitivity_analysis(
    optimized_pbn,
    "experiments.csv",
    config={
        "perturbation_magnitude": 0.3,
        "steady_state": {
            "method": "tsmc",
            "tsmc_params": {
                "epsilon": 0.01,
                "max_iterations": 1000,
            },
        },
    },
    top_n=10,
)

plot_mse_sensitivity_results(
    results["sensitivity_df"],
    results["baseline_mse"],
    top_n=20,
    save_path="mse_sensitivity.png",
)

Formula Measurements

If the objective uses a formula instead of direct measured nodes, pass Measured_formula and optionally enable min-max normalization:

results = sensitivity_analysis(
    pbn,
    "experiments.csv",
    Measured_formula="N1 + N2 - N3",
    normalize=True,
)

See Also

• KGBN.parameter_optimizer

• KGBN.experiment_data

• Steady State Calculation Guide