analyzers
analyzers
Common analyzers for STI analyses
Classes
| Name | Description |
|---|---|
| DebutAge | Analyze the proportion of agents who have sexually debuted by age. |
| NetworkDegree | Analyze lifetime partner count distributions in a StructuredSexual network. |
| RelationshipDurations | Analyze relationship durations in a StructuredSexual network. |
| TimeBetweenRelationships | Analyzes the time between relationships in a structuredsexual network. |
| art_coverage | Track ART coverage (number and proportion) by sex and age bin. |
| coinfection_stats | Generates stats for the coinfection of two diseases. |
| partner_age_diff | Analyze age differences between sexual partners. |
| result_grouper | Base analyzer providing conditional probability utilities for grouped results. |
| sw_stats | Track new infections and transmissions among sex workers and their clients. |
DebutAge
analyzers.DebutAge(bins=None, cohort_starts=None, *args, **kwargs)Analyze the proportion of agents who have sexually debuted by age.
Tracks the share of agents who are sexually active (past their debut age) at each single-year age bin, disaggregated by sex and birth cohort. Useful for validating debut age distributions against survey data such as DHS.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| bins | array | Age bins to evaluate, e.g. np.arange(12, 31). Defaults to ages 12-30. |
None |
| cohort_starts | array | Birth-year cohort start years. Defaults to all cohorts that fit within the simulation timespan. | None |
Methods
| Name | Description |
|---|---|
| plot | Plot the proportion of active agents by cohort and debut age |
plot
analyzers.DebutAge.plot()Plot the proportion of active agents by cohort and debut age
NetworkDegree
analyzers.NetworkDegree(
year=None,
bins=None,
relationship_types=None,
*args,
**kwargs,
)Analyze lifetime partner count distributions in a StructuredSexual network.
At a specified year, records the number of lifetime partners per agent, disaggregated by sex and relationship type (stable, casual, one-time, sex work). Results are binned into a histogram for plotting and comparison with survey data.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| year | float | Calendar year at which to record partner counts. Defaults to the last year of the simulation. | None |
| bins | array | Bin edges for the partner count histogram. Defaults to [0, 1, ..., 20, 100]. |
None |
| relationship_types | list | Relationship types to track, e.g. ['stable', 'casual']. Use 'partners' for combined stable + casual counts. |
None |
Methods
| Name | Description |
|---|---|
| init_pre | Initialize the analyzer |
| init_results | Add results for n_rships, separated for males and females |
| plot | Plot histograms and stats by sex and relationship type |
| step | record lifetime_partners for the user-specified year |
init_pre
analyzers.NetworkDegree.init_pre(sim, **kwargs)Initialize the analyzer
init_results
analyzers.NetworkDegree.init_results()Add results for n_rships, separated for males and females Optionally disaggregate for risk level / age?
plot
analyzers.NetworkDegree.plot()Plot histograms and stats by sex and relationship type
step
analyzers.NetworkDegree.step()record lifetime_partners for the user-specified year
RelationshipDurations
analyzers.RelationshipDurations(*args, **kwargs)Analyze relationship durations in a StructuredSexual network.
Records the mean and median duration of all relationships (stable, casual, etc.) at each timestep, disaggregated by sex. Durations are extracted from the network’s relationship_durs tracking dict.
Methods
| Name | Description |
|---|---|
| get_relationship_durations | Returns the durations of all relationships, separated by sex. |
get_relationship_durations
analyzers.RelationshipDurations.get_relationship_durations()Returns the durations of all relationships, separated by sex.
If include_current is False, return the duration of only relationships that have ended
Returns
| Name | Type | Description |
|---|---|---|
| female_durations | list of durations of relationships | |
| male_durations | list of durations of relationships |
TimeBetweenRelationships
analyzers.TimeBetweenRelationships(relationship_type='stable', *args, **kwargs)Analyzes the time between relationships in a structuredsexual network. Each timestep, for each debuted agent, check if they are in a relationship of the provided type. If not, increment the counter Otherwise, reset the counter to 0 and append the counter to the list of times between relationships for that agent.
Methods
| Name | Description |
|---|---|
| step | For each debuted agent, check if they are in a relationship. |
step
analyzers.TimeBetweenRelationships.step()For each debuted agent, check if they are in a relationship. If they are not, increment the time since last relationship by 1. If they are and time since last relationship is greater than 0, append the time to the list of times between relationships.
art_coverage
analyzers.art_coverage(age_bins=None, *args, **kwargs)Track ART coverage (number and proportion) by sex and age bin.
Results are stored as time series per stratum, accessible via: analyzer.results[‘n_art_f_15_25’] # Women 15-25 on ART (count) analyzer.results[‘p_art_m_25_35’] # Men 25-35 on ART (proportion of infected)
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| age_bins | list | age bin edges, e.g. [15, 25, 35, 45, 65]. Default: [15, 25, 35, 45, 65]. Bins are half-open intervals: [lo, hi), i.e. lo <= age < hi. | None |
Methods
| Name | Description |
|---|---|
| plot | Plot ART coverage over time. |
plot
analyzers.art_coverage.plot(by_age=True)Plot ART coverage over time.
Creates a 2-panel figure: aggregate coverage (left) and by age/sex (right). If by_age=False, only plots aggregate.
Example::
sim.run()
sim.analyzers.art_coverage.plot()coinfection_stats
analyzers.coinfection_stats(
disease1,
disease2,
disease1_infected_state_name='infected',
disease2_infected_state_name='infected',
age_limits=None,
denom=None,
*args,
**kwargs,
)Generates stats for the coinfection of two diseases. This is useful for looking at the coinfection of HIV and syphilis, for example.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| disease1 | str | ss.Disease |
name of the first disease | required |
| disease2 | str | ss.Disease |
name of the second disease | required |
| disease1_infected_state_name | str | name of the infected state for disease1 (default: ‘infected’) | 'infected' |
| disease2_infected_state_name | str | name of the infected state for disease2 (default: ‘infected’) | 'infected' |
| age_limits | list | list of two integers that define the age limits for the denominator. | None |
| denom | function |
function that returns a boolean array of the denominator, usually the relevant population. default: lambda self: (self.sim.people.age >= 15) & (self.sim.people.age < 50) | None |
| *args, **kwargs | optional, passed to ss.Analyzer constructor | required |
partner_age_diff
analyzers.partner_age_diff(
year=2000,
age_bins=['teens', 'young', 'adult'],
network='structuredsexual',
*args,
**kwargs,
)Analyze age differences between sexual partners.
Records the mean, median, and standard deviation of male-female age differences (male age minus female age) at each timestep. At a specified year, stores full age-difference distributions disaggregated by female age group for detailed plotting.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| year | float | Calendar year at which to store detailed age-difference distributions. Defaults to 2000. | 2000 |
| age_bins | list | Female age group names matching the network’s f_age_group_bins keys. Defaults to ['teens', 'young', 'adult']. |
['teens', 'young', 'adult'] |
| network | str | Name of the network to analyze. Defaults to 'structuredsexual'. |
'structuredsexual' |
Methods
| Name | Description |
|---|---|
| init_results | Initialize the results for the age differences. |
| plot | Plot histograms of the age differences between partners. |
| step | Record the age differences between partners in the specified year. |
init_results
analyzers.partner_age_diff.init_results()Initialize the results for the age differences.
plot
analyzers.partner_age_diff.plot()Plot histograms of the age differences between partners.
step
analyzers.partner_age_diff.step()Record the age differences between partners in the specified year.
result_grouper
analyzers.result_grouper()Base analyzer providing conditional probability utilities for grouped results.
Provides a cond_prob static method that computes the proportion of a numerator group within a denominator group. Intended as a base class for analyzers that compute stratified prevalence or infection statistics.
sw_stats
analyzers.sw_stats(diseases=None, *args, **kwargs)Track new infections and transmissions among sex workers and their clients.
At each timestep, records the number and share of new infections and transmissions attributable to female sex workers (FSW), clients, and non-sex-worker populations, disaggregated by disease.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| diseases | list | List of disease names (str) to track, e.g. ['hiv', 'syphilis']. |
None |