How-to Scripts

Tutorial and example scripts demonstrating specific features and workflows.

scripts.howto.comprehensive_analyzer_plots_example.build_tbsim(sim_pars=None)

Build a TB simulation with dwell time analyzer

scripts.howto.comprehensive_analyzer_plots_example.demonstrate_all_analyzer_plots()

Demonstrate all available plotting methods in the DwtAnalyzer class

scripts.howto.comprehensive_analyzer_plots_example.demonstrate_post_processor()

Demonstrate the DwtPostProcessor for multiple simulation results

Example of enhanced DwtAnalyzer docstrings with embedded images.

This shows how to use the generated images in actual docstrings for the TB simulation analyzer class.

class scripts.howto.example_enhanced_docstrings.DwtAnalyzer

Bases: object

Dwell Time Analyzer for TB Simulation.

This class provides comprehensive tools for analyzing and visualizing dwell time data from tuberculosis simulation runs.

The analyzer tracks how long agents spend in each TB state and provides multiple visualization types including Sankey diagrams, network graphs, histograms, and interactive charts.

sankey_agents(subtitle='')

Creates a Sankey diagram showing agent flow between TB states.

This method visualizes the movement of agents between different tuberculosis states throughout the simulation.

The Sankey diagram above shows: - Nodes: TB states (Susceptible, Latent, Active, Treatment, etc.) - Flows: Agent transitions between states - Width: Proportional to the number of agents - Colors: Different state categories

Mathematical Model:

For each transition (state_i → state_j): - Flow width = N_ij / max(N) * max_width - Node width = Σ(N_ij) / max(Σ(N)) * max_node_width

Parameters:

subtitle (str) – Additional subtitle for the plot

Returns:

Displays interactive Plotly Sankey diagram

Return type:

None

Example

>>> analyzer = DwtAnalyzer(scenario_name="example")
>>> analyzer.sankey_agents(subtitle="TB State Transitions")
# Opens interactive Sankey diagram in browser

histogram_with_kde(subtitle='')

Creates histograms with kernel density estimation for dwell time distributions.

This method shows how long agents spend in each TB state, providing insights into the timing patterns of disease progression.

The plot above demonstrates: - Histogram bars: Frequency distribution of dwell times - KDE curve: Smooth probability density estimation - Multi-panel layout: One subplot per TB state - Automatic scaling: Optimized bin sizes and ranges

Mathematical Model:

For each state i and dwell time t: - Histogram: H_i(bin) = count(dwell_times ∈ bin) - KDE: f_i(t) = (1/nh) * Σ K((t-t_j)/h) - Bandwidth: h = 1.06 * σ * n^(-1/5) (Silverman’s rule)

Parameters:

subtitle (str) – Additional subtitle for the plot

Returns:

Displays matplotlib figure with subplots

Return type:

None

Example

>>> plotter = DwtPlotter(file_path='data.csv')
>>> plotter.histogram_with_kde(subtitle="Dwell Time Analysis")
# Displays multi-panel histogram with KDE

graph_state_transitions_curved(states=None, subtitle='', colormap='Paired')

Creates a curved network graph showing state transitions with statistics.

This method generates a directed graph visualization where nodes represent TB states and edges show transitions with statistical annotations.

The network above illustrates: - Nodes: TB states (circles with state names) - Edges: State transitions (curved arrows) - Edge thickness: Proportional to transition frequency - Edge labels: Mean dwell time, mode, and agent count - Color coding: Different states and transition types

Mathematical Model:

For each transition (state_i → state_j): - Edge weight = N_ij / max(N) * max_thickness - Mean dwell time = μ_ij = Σ(t_k) / N_ij - Mode dwell time = most frequent value in transition

Parameters:

• states (list, optional) – Specific states to include

• subtitle (str) – Additional subtitle for the plot

• colormap (str) – Matplotlib colormap name

Returns:

Displays matplotlib network visualization

Return type:

None

Example

>>> analyzer.graph_state_transitions_curved(
...     subtitle="State Transition Network",
...     colormap='viridis'
... )
# Displays network graph with curved edges

reinfections_percents_bars_interactive(target_states, scenario='')

Creates an interactive bar chart showing reinfection percentages.

This method visualizes the percentage of the population that experienced different numbers of reinfections, important for TB epidemiology.

The interactive chart above provides: - Bar heights: Percentage of population with each reinfection count - Hover information: Exact percentages and counts - Color coding: Different reinfection numbers - Interactive features: Zoom, pan, and export capabilities

Mathematical Model:

For each reinfection count k: - Count agents: N_k = count(agents with max_infection = k) - Calculate percentage: P_k = N_k / total_agents * 100 - Create bar: height = P_k, x = k

Parameters:

• target_states (list) – States that count as infections

• scenario (str) – Scenario name for plot title

Returns:

Displays interactive Plotly bar chart

Return type:

None

Example

>>> plotter.reinfections_percents_bars_interactive(
...     target_states=[0.0, 1.0],  # Active TB states
...     scenario="Population Reinfection Analysis"
... )
# Opens interactive reinfection analysis in browser

barchar_all_state_transitions_interactive(dwell_time_bins=None, filter_states=None)

Creates an interactive bar chart of all state transitions grouped by dwell time.

This method provides detailed analysis of state transitions with customizable dwell time categories and state filtering.

The interactive chart above shows: - Horizontal bars: Each representing a state transition - Dwell time categories: Grouped by time ranges (0-30d, 30-90d, etc.) - Bar heights: Number of agents making each transition - Interactive features: Hover details, zoom, and filtering

Mathematical Model:

For each transition (state_i → state_j) and dwell time bin [t_min, t_max): - Filter transitions: T where dwell_time ∈ [t_min, t_max) - Count agents: N_ij(bin) = count(T) - Create bar: height = N_ij(bin), label = “state_i → state_j (bin_range)”

Parameters:

• dwell_time_bins (list, optional) – Bin edges for categorizing dwell times

• filter_states (list, optional) – States to include in analysis

Returns:

Displays interactive Plotly bar chart

Return type:

None

Example

>>> plotter.barchar_all_state_transitions_interactive(
...     dwell_time_bins=[0, 30, 90, 180, 365, float('inf')],
...     filter_states=['Latent', 'Active', 'Treatment']
... )
# Opens interactive bar chart in browser

scripts.howto.example_enhanced_docstrings.example_usage()

Example of how to use the DwtAnalyzer with visual documentation.

This function demonstrates the workflow for analyzing TB simulation data and generating visualizations with embedded documentation.

The workflow involves: 1. Creating a simulation with the analyzer 2. Running the simulation to collect data 3. Generating various visualizations 4. Using the plots in documentation

Each visualization type provides different insights into the simulation dynamics and can be used for different analytical purposes.

Generate example images for DwtAnalyzer docstrings.

This script creates sample visualizations that will be used in the documentation to illustrate what each plotting method produces.

scripts.howto.generate_doc_images.create_sankey_example()

Create a Sankey diagram example for documentation.

scripts.howto.generate_doc_images.create_histogram_kde_example()

Create a histogram with KDE example for documentation.

scripts.howto.generate_doc_images.create_network_graph_example()

Create a network graph example for documentation.

scripts.howto.generate_doc_images.create_reinfection_analysis_example()

Create a reinfection analysis example for documentation.

scripts.howto.generate_doc_images.create_interactive_bar_example()

Create an interactive bar chart example for documentation.

scripts.howto.generate_doc_images.main()

Generate all example images for documentation.

scripts.howto.quick_analyzer_plots_example.build_tbsim(sim_pars=None)

Build a TB simulation with dwell time analyzer

scripts.howto.quick_analyzer_plots_example.demonstrate_essential_plots()

Demonstrate the most essential plotting methods from the DwtAnalyzer class

scripts.howto.quick_analyzer_plots_example.demonstrate_plotter_usage()

Show how to use the DwtPlotter with existing data files