Network Structures

This module provides social network structures for modeling transmission patterns, household connections, and social interactions in TBsim simulations.

Network Classes

class tbsim.networks.HouseholdNet(hhs=None, pars=None, **kwargs)[source]

Bases: Network

A household-level contact network for agent-based simulations using Starsim.

This network constructs complete graphs among household members and supports dynamically adding newborns to the simulation and linking them to their household based on the parent-child relationship. It is especially useful in intervention trials where household structure and arm assignment are important.

Parameters:

  • hhs (list of lists or arrays of int, optional) – A list of households, where each household is represented by a list or array of agent UIDs.

  • pars (dict, optional) –

    Dictionary of network parameters. Supports:

    • add_newborns (bool): Whether to dynamically add newborns to households.

  • **kwargs (dict) – Additional keyword arguments passed to the Network base class.

hhs

List of household UID groups.

Type:

list

pars

Dictionary-like container of network parameters.

Type:

sc.objdict

edges

Container for the network’s edges (p1, p2, and beta arrays).

Type:

Starsim EdgeStruct

add_hh(uids):

Add a complete graph among the given UIDs to the network.

init_pre(sim):

Initialize the network prior to simulation start. Adds initial household connections.

step():

During simulation, adds newborns to the network by linking them to their household contacts and assigning household-level attributes (e.g., hhid, trial arm).

__init__(hhs=None, pars=None, **kwargs)[source]
add_hh(uids)[source]

Add a complete graph among the given UIDs to the network.

init_pre(sim)[source]

Initialize the network prior to simulation start. Adds initial household connections.

step()[source]

Adds newborns to the trial population, including hhid, arm, and household contacts.

class tbsim.networks.HouseholdNetRationsTrial(hhs=None, pars=None, **kwargs)[source]

Bases: Network

RATIONS trial network. A household-level contact network for agent-based simulations using Starsim.

This network constructs complete graphs among household members and supports dynamically adding newborns to the simulation and linking them to their household based on the parent-child relationship. It is especially useful in intervention trials where household structure and arm assignment are important (e.g., RATIONS trial).

Parameters:

  • hhs (list of lists or arrays of int, optional) – A list of households, where each household is represented by a list or array of agent UIDs.

  • pars (dict, optional) –

    Dictionary of network parameters. Supports:

    • add_newborns (bool): Whether to dynamically add newborns to households.

  • **kwargs (dict) – Additional keyword arguments passed to the Network base class.

hhs

List of household UID groups.

Type:

list

pars

Dictionary-like container of network parameters.

Type:

sc.objdict

edges

Container for the network’s edges (p1, p2, and beta arrays).

Type:

Starsim EdgeStruct

add_hh(uids):

Add a complete graph among the given UIDs to the network.

init_pre(sim):

Initialize the network prior to simulation start. Adds initial household connections.

step():

During simulation, adds newborns to the network by linking them to their household contacts and assigning household-level attributes (e.g., hhid, trial arm).

__init__(hhs=None, pars=None, **kwargs)[source]
add_hh(uids)[source]
init_pre(sim)[source]

Initialize with the sim, initialize the edges, and validate p1 and p2

step()[source]

Adds newborns to the trial population, including hhid, arm, and household contacts

tbsim.networks.plot_household_structure(households, title='Household Network Structure', figsize=(12, 8))[source]

Plot the structure of household networks showing connections within households.

This function creates a network visualization where: - Nodes represent individual agents - Edges represent household connections (complete graphs within households) - Different colors represent different households - Node size is proportional to household size

Parameters:

  • households (list) – List of lists, where each inner list contains agent UIDs in a household

  • title (str) – Title for the plot

  • figsize (tuple) – Figure size (width, height)

Returns:

The NetworkX graph object for further analysis

Return type:

networkx.Graph

Example

>>> from tbsim.networks import plot_household_structure
>>> households = [[0, 1, 2], [3, 4], [5, 6, 7, 8]]
>>> G = plot_household_structure(households, "My Household Network")

Household Network Implementation

A household-level contact network for agent-based simulations using Starsim.

This network constructs complete graphs among household members and supports dynamically adding newborns to the simulation and linking them to their household based on the parent-child relationship. It is especially useful in intervention trials where household structure and arm assignment are important.

param hhs:

A list of households, where each household is represented by a list or array of agent UIDs.

type hhs:

list of lists or arrays of int, optional

param pars:
Dictionary of network parameters. Supports:

  • add_newborns (bool): Whether to dynamically add newborns to households.

type pars:

dict, optional

param **kwargs:

Additional keyword arguments passed to the Network base class.

type **kwargs:

dict

tbsim.networks.HouseholdNet.hhs

List of household UID groups.

Type:

list

tbsim.networks.HouseholdNet.pars

Dictionary-like container of network parameters.

Type:

sc.objdict

tbsim.networks.HouseholdNet.edges

Container for the network’s edges (p1, p2, and beta arrays).

Type:

Starsim EdgeStruct

add_hh(uids):

Add a complete graph among the given UIDs to the network.

init_pre(sim):

Initialize the network prior to simulation start. Adds initial household connections.

step():

During simulation, adds newborns to the network by linking them to their household contacts and assigning household-level attributes (e.g., hhid, trial arm).

tbsim.networks.HouseholdNet.__delattr__(self, name, /)

Implement delattr(self, name).

tbsim.networks.HouseholdNet.__dir__(self, /)

Default dir() implementation.

tbsim.networks.HouseholdNet.__eq__(self, value, /)

Return self==value.

tbsim.networks.HouseholdNet.__format__(self, format_spec, /)

Default object formatter.

tbsim.networks.HouseholdNet.__ge__(self, value, /)

Return self>=value.

tbsim.networks.HouseholdNet.__getattribute__(self, name, /)

Return getattr(self, name).

tbsim.networks.HouseholdNet.__gt__(self, value, /)

Return self>value.

tbsim.networks.HouseholdNet.__hash__(self, /)

Return hash(self).

tbsim.networks.HouseholdNet.__init_subclass__()

This method is called when a class is subclassed.

The default implementation does nothing. It may be overridden to extend subclasses.

tbsim.networks.HouseholdNet.__le__(self, value, /)

Return self<=value.

tbsim.networks.HouseholdNet.__lt__(self, value, /)

Return self<value.

tbsim.networks.HouseholdNet.__ne__(self, value, /)

Return self!=value.

tbsim.networks.HouseholdNet.__new__(*args, **kwargs)

Create and return a new object. See help(type) for accurate signature.

tbsim.networks.HouseholdNet.__reduce__(self, /)

Helper for pickle.

tbsim.networks.HouseholdNet.__reduce_ex__(self, protocol, /)

Helper for pickle.

tbsim.networks.HouseholdNet.__sizeof__(self, /)

Size of object in memory, in bytes.

tbsim.networks.HouseholdNet.__subclasshook__()

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

RATIONS Trial Network

RATIONS trial network. A household-level contact network for agent-based simulations using Starsim.

This network constructs complete graphs among household members and supports dynamically adding newborns to the simulation and linking them to their household based on the parent-child relationship. It is especially useful in intervention trials where household structure and arm assignment are important (e.g., RATIONS trial).

param hhs:

A list of households, where each household is represented by a list or array of agent UIDs.

type hhs:

list of lists or arrays of int, optional

param pars:
Dictionary of network parameters. Supports:

  • add_newborns (bool): Whether to dynamically add newborns to households.

type pars:

dict, optional

param **kwargs:

Additional keyword arguments passed to the Network base class.

type **kwargs:

dict

tbsim.networks.HouseholdNetRationsTrial.hhs

List of household UID groups.

Type:

list

tbsim.networks.HouseholdNetRationsTrial.pars

Dictionary-like container of network parameters.

Type:

sc.objdict

tbsim.networks.HouseholdNetRationsTrial.edges

Container for the network’s edges (p1, p2, and beta arrays).

Type:

Starsim EdgeStruct

add_hh(uids):

Add a complete graph among the given UIDs to the network.

init_pre(sim):

Initialize the network prior to simulation start. Adds initial household connections.

step():

During simulation, adds newborns to the network by linking them to their household contacts and assigning household-level attributes (e.g., hhid, trial arm).

tbsim.networks.HouseholdNetRationsTrial.__delattr__(self, name, /)

Implement delattr(self, name).

tbsim.networks.HouseholdNetRationsTrial.__dir__(self, /)

Default dir() implementation.

tbsim.networks.HouseholdNetRationsTrial.__eq__(self, value, /)

Return self==value.

tbsim.networks.HouseholdNetRationsTrial.__format__(self, format_spec, /)

Default object formatter.

tbsim.networks.HouseholdNetRationsTrial.__ge__(self, value, /)

Return self>=value.

tbsim.networks.HouseholdNetRationsTrial.__getattribute__(self, name, /)

Return getattr(self, name).

tbsim.networks.HouseholdNetRationsTrial.__gt__(self, value, /)

Return self>value.

tbsim.networks.HouseholdNetRationsTrial.__hash__(self, /)

Return hash(self).

tbsim.networks.HouseholdNetRationsTrial.__init_subclass__()

This method is called when a class is subclassed.

The default implementation does nothing. It may be overridden to extend subclasses.

tbsim.networks.HouseholdNetRationsTrial.__le__(self, value, /)

Return self<=value.

tbsim.networks.HouseholdNetRationsTrial.__lt__(self, value, /)

Return self<value.

tbsim.networks.HouseholdNetRationsTrial.__ne__(self, value, /)

Return self!=value.

tbsim.networks.HouseholdNetRationsTrial.__new__(*args, **kwargs)

Create and return a new object. See help(type) for accurate signature.

tbsim.networks.HouseholdNetRationsTrial.__reduce__(self, /)

Helper for pickle.

tbsim.networks.HouseholdNetRationsTrial.__reduce_ex__(self, protocol, /)

Helper for pickle.

tbsim.networks.HouseholdNetRationsTrial.__sizeof__(self, /)

Size of object in memory, in bytes.

tbsim.networks.HouseholdNetRationsTrial.__subclasshook__()

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

Network Visualization

class tbsim.networks.HouseholdNet(hhs=None, pars=None, **kwargs)[source]

Bases: Network

A household-level contact network for agent-based simulations using Starsim.

This network constructs complete graphs among household members and supports dynamically adding newborns to the simulation and linking them to their household based on the parent-child relationship. It is especially useful in intervention trials where household structure and arm assignment are important.

Parameters:

  • hhs (list of lists or arrays of int, optional) – A list of households, where each household is represented by a list or array of agent UIDs.

  • pars (dict, optional) –

    Dictionary of network parameters. Supports:

    • add_newborns (bool): Whether to dynamically add newborns to households.

  • **kwargs (dict) – Additional keyword arguments passed to the Network base class.

hhs

List of household UID groups.

Type:

list

pars

Dictionary-like container of network parameters.

Type:

sc.objdict

edges

Container for the network’s edges (p1, p2, and beta arrays).

Type:

Starsim EdgeStruct

add_hh(uids):

Add a complete graph among the given UIDs to the network.

init_pre(sim):

Initialize the network prior to simulation start. Adds initial household connections.

step():

During simulation, adds newborns to the network by linking them to their household contacts and assigning household-level attributes (e.g., hhid, trial arm).

__init__(hhs=None, pars=None, **kwargs)[source]
add_hh(uids)[source]

Add a complete graph among the given UIDs to the network.

init_pre(sim)[source]

Initialize the network prior to simulation start. Adds initial household connections.

step()[source]

Adds newborns to the trial population, including hhid, arm, and household contacts.

class tbsim.networks.HouseholdNetRationsTrial(hhs=None, pars=None, **kwargs)[source]

Bases: Network

RATIONS trial network. A household-level contact network for agent-based simulations using Starsim.

This network constructs complete graphs among household members and supports dynamically adding newborns to the simulation and linking them to their household based on the parent-child relationship. It is especially useful in intervention trials where household structure and arm assignment are important (e.g., RATIONS trial).

Parameters:

  • hhs (list of lists or arrays of int, optional) – A list of households, where each household is represented by a list or array of agent UIDs.

  • pars (dict, optional) –

    Dictionary of network parameters. Supports:

    • add_newborns (bool): Whether to dynamically add newborns to households.

  • **kwargs (dict) – Additional keyword arguments passed to the Network base class.

hhs

List of household UID groups.

Type:

list

pars

Dictionary-like container of network parameters.

Type:

sc.objdict

edges

Container for the network’s edges (p1, p2, and beta arrays).

Type:

Starsim EdgeStruct

add_hh(uids):

Add a complete graph among the given UIDs to the network.

init_pre(sim):

Initialize the network prior to simulation start. Adds initial household connections.

step():

During simulation, adds newborns to the network by linking them to their household contacts and assigning household-level attributes (e.g., hhid, trial arm).

__init__(hhs=None, pars=None, **kwargs)[source]
add_hh(uids)[source]
init_pre(sim)[source]

Initialize with the sim, initialize the edges, and validate p1 and p2

step()[source]

Adds newborns to the trial population, including hhid, arm, and household contacts

tbsim.networks.plot_household_structure(households, title='Household Network Structure', figsize=(12, 8))[source]

Plot the structure of household networks showing connections within households.

This function creates a network visualization where: - Nodes represent individual agents - Edges represent household connections (complete graphs within households) - Different colors represent different households - Node size is proportional to household size

Parameters:

  • households (list) – List of lists, where each inner list contains agent UIDs in a household

  • title (str) – Title for the plot

  • figsize (tuple) – Figure size (width, height)

Returns:

The NetworkX graph object for further analysis

Return type:

networkx.Graph

Example

>>> from tbsim.networks import plot_household_structure
>>> households = [[0, 1, 2], [3, 4], [5, 6, 7, 8]]
>>> G = plot_household_structure(households, "My Household Network")

Model Overview

The Networks module provides comprehensive social network modeling for tuberculosis transmission with the following key features:

Network Types

  • Household Networks: Family and household-based transmission modeling

  • RATIONS Trial Networks: Specialized networks for nutritional intervention studies

  • Social Networks: Community and social contact modeling

  • Transmission Networks: Disease-specific contact patterns

Network Structure

  • Dynamic network generation and management

  • Household assignment and management

  • Contact pattern modeling

  • Transmission probability calculations

Integration Capabilities

  • TB disease model integration

  • Comorbidity consideration

  • Intervention targeting

  • Population dynamics support

Key Features

Household Network Management

  • Automatic household generation

  • Household size distribution modeling

  • Dynamic household membership

  • Contact pattern generation

Transmission Modeling

  • Contact-based transmission probabilities

  • Household clustering effects

  • Social mixing patterns

  • Age and risk factor consideration

Network Visualization

  • Household structure plotting

  • Contact network visualization

  • Transmission pattern analysis

  • Network statistics reporting

Dynamic Network Updates

  • Birth and death handling

  • Household formation and dissolution

  • Contact pattern evolution

  • Intervention effects on networks

Usage Examples

Basic household network:

from tbsim.networks import HouseholdNet
import starsim as ss

sim = ss.Sim(networks=HouseholdNet())
sim.run()

RATIONS trial network:

from tbsim.networks import HouseholdNetRationsTrial

# Create RATIONS trial specific network
rations_network = HouseholdNetRationsTrial(pars={
    'household_size_mean': 4.5,
    'household_size_std': 1.2,
    'contact_probability': 0.3
})

sim = ss.Sim(networks=rations_network)
sim.run()

Custom network parameters:

from tbsim.networks import HouseholdNet

# Customize network parameters
households = HouseholdNet(pars={
    'household_size_mean': 3.8,
    'household_size_std': 1.5,
    'contact_probability': 0.25,
    'max_household_size': 8
})

sim = ss.Sim(networks=households)
sim.run()

Network visualization:

from tbsim.networks import plot_household_structure

# Plot household structure
plot_household_structure(
    households=households.households,
    title="Household Network Structure",
    figsize=(15, 10)
)

Accessing network data:

# Get household information
household_list = households.households
household_sizes = [len(hh) for hh in household_list]

# Get contact patterns
contact_matrix = households.contact_matrix
transmission_rates = households.transmission_rates

# Get network statistics
total_households = len(household_list)
avg_household_size = np.mean(household_sizes)
max_household_size = max(household_sizes)

Network Analysis

Household Statistics

  • Household size distribution

  • Household composition analysis

  • Contact pattern statistics

  • Transmission rate calculations

Network Properties

  • Clustering coefficients

  • Average path lengths

  • Degree distributions

  • Community structure analysis

Transmission Dynamics

  • Contact-based transmission modeling

  • Household clustering effects

  • Social mixing patterns

  • Intervention impact assessment

Integration with Disease Models

TB Transmission Integration

  • Network-based transmission modeling

  • Household clustering effects

  • Contact pattern consideration

  • Transmission probability calculations

Comorbidity Effects

  • HIV status consideration in contacts

  • Nutritional status effects on transmission

  • Age-specific contact patterns

  • Risk factor integration

Intervention Targeting

  • Household-based intervention delivery

  • Contact tracing integration

  • Community intervention programs

  • Network-based effectiveness assessment

Mathematical Framework

Network Generation

  • Household size distribution modeling

  • Contact probability calculations

  • Transmission rate determination

  • Dynamic network updates

Transmission Modeling

  • Contact-based transmission: P(transmission) = f(contact, risk_factors)

  • Household effects: P(household) = f(household_size, contact_density)

  • Social mixing: P(social) = f(age, risk_group, intervention_status)

Network Evolution

  • Birth and death processes

  • Household formation and dissolution

  • Contact pattern evolution

  • Intervention effects on networks

For detailed information about specific methods and parameters, see the individual class documentation above. All methods include comprehensive mathematical models and implementation details in their docstrings.