Source code for hpvsim.defaults

Set the defaults across each of the different files.

import numpy as np
import sciris as sc
import pylab as pl
from .settings import options as hpo # To set options

# Specify all externally visible functions this file defines -- other things are available as e.g. hpv.defaults.default_int
__all__ = ['datadir', 'default_float', 'default_int', 'get_default_plots']

# Define paths
datadir = sc.path(sc.thisdir(__file__)) / 'data'

#%% Specify what data types to use

result_float = np.float64 # Always use float64 for results, for simplicity
if hpo.precision == 32:
    default_float = np.float32
    default_int   = np.int32
elif hpo.precision == 64: # pragma: no cover
    default_float = np.float64
    default_int   = np.int64
    raise NotImplementedError(f'Precision must be either 32 bit or 64 bit, not {hpo.precision}')

#%% Define all properties of people

class State(sc.prettyobj):
    def __init__(self, name, dtype, fill_value=0, shape=None, label=None, color=None,
            name: name of the result as used in the model (e.g. cin1)
            dtype: datatype
            fill_value: default value for this state upon model initialization
            shape: If not none, set to match a string in `pars` containing the dimensionality e.g., `n_genotypes`)
            label: text used to construct labels for the result for displaying on plots and other outputs
            color: color (used for plotting stocks)
            totalprefix: the prefix used for differentiating by-genotype results from total results. Set to None if the result only appears as a total
        ''' = name
        self.dtype = dtype
        self.fill_value = fill_value
        self.shape = shape
        self.label = label or name
        self.color = color
        self.totalprefix = totalprefix or ('total_' if shape else '')
    def ndim(self):
        return len(sc.tolist(self.shape))+1 # None -> 1, 'n_genotypes' -> 2, etc.

    def new(self, pars, n):
        shape = sc.tolist(self.shape) # e.g. convert 'n_genotypes' to ['n_genotypes']
        shape = [pars[s] for s in shape] # e.g. convert ['n_genotypes'] to [2]
        shape.append(n) # We always want to have shape n
        return np.full(shape, dtype=self.dtype, fill_value=self.fill_value)

class PeopleMeta(sc.prettyobj):
    ''' For storing all the keys relating to a person and people '''

    # (attribute, nrows, dtype, default value)
    # If the default value is None, then the array will not be initialized - this is faster and can
    # be used for variables where the People object explicitly supplies the values e.g. age

    def __init__(self):

        # Set the properties of a person
        self.person = [
            State('uid',            default_int),           # Int
            State('cluster',        default_int,    0),     # Int
            State('scale',          default_float,  1.0), # Float
            State('level0',         bool,  True), # "Normal" people
            State('level1',         bool,  False), # "High-resolution" people: e.g. cancer agents
            State('age',            default_float,  np.nan), # Float
            State('sex',            default_float,  np.nan), # Float
            State('debut',          default_float,  np.nan), # Float
            State('ever_partnered', bool,  False), # Whether this person has ever been partnered
            State('rel_sev',        default_float, 1.0), # Individual relative risk for rate severe disease growth
            State('rel_sus',        default_float, 1.0), # Individual relative risk for acquiring infection (does not vary by genotype)
            State('rel_trans',      default_float, 1.0), # Individual relative risk for transmitting infection (does not vary by genotype)
            State('rel_imm',        default_float, 1.0), # Individual relative level of immunity acquired from infection clearance/vaccination
            State('doses',          default_int,    0),  # Number of doses of the prophylactic vaccine given per person
            State('txvx_doses',     default_int,    0),  # Number of doses of the therapeutic vaccine given per person
            State('vaccine_source', default_int,    -1), # Index of the prophylactic vaccine that individual received
            State('screens',        default_int,    0),  # Number of screens given per person
            State('cin_treatments', default_int,    0),  # Number of CIN treatments given per person
            State('cancer_treatments', default_int,    0),  # Number of cancer treatments given per person
            State('art_adherence',  default_float, 0, label='adherence on ART', color='#aaa8ff'),
            State('n_infections',   default_int,    0, 'n_genotypes')

        ###### The following section consists of all the boolean states

        # The following three groupings are all mutually exclusive and collectively exhaustive.
        self.alive_states = [
            # States related to whether or not the person is alive or dead
            State('alive',          bool,   True,   label='Population'),    # Save this as a state so we can record population sizes
            State('dead_cancer',    bool,   False,  label='Cumulative cancer deaths'),   # Dead from cancer
            State('dead_other',     bool,   False,  label='Cumulative deaths from other causes'),   # Dead from all other causes
            State('emigrated',      bool,   False,  label='Emigrated'),  # Emigrated

        self.viral_states = [
            # States related to whether virus is present
            State('susceptible',    bool, True,     'n_genotypes', label='Number susceptible', color='#4d771e'),               # Allowable cell states: normal
            State('infectious',     bool, False,    'n_genotypes', label='Number infectious',  color='#c78f65'),               # Allowable cell states: normal, cin
            State('inactive',       bool, False,    'n_genotypes', label='Number with inactive infection', color='#9e1149'),   # Allowable cell states: normal, cancer in at least one genotype

        self.cell_states = [
            # States related to the cellular changes present in the cervix.
            State('normal',         bool, True, 'n_genotypes', label='Number with no cellular changes', color='#9e1149'), # Allowable viral states: susceptible, infectious, and inactive
            State('cin',            bool, False, 'n_genotypes', label='Number with detectable dysplasia', color='#9e1149'), # Allowable viral states: infectious
            State('cancerous',      bool, False, 'n_genotypes', label='Number with cancer', color='#5f5cd2'),      # Allowable viral states: inactive

        self.derived_states = [
            # From the viral states, cell states, and severity markers, we derive the following additional states:
            State('infected',   bool, False, 'n_genotypes', label='Number infected', color='#c78f65'), # Union of infectious and inactive. Includes people with cancer, people with latent infections, and people with active infections
            State('abnormal',   bool, False, 'n_genotypes', label='Number with abnormal cells', color='#9e1149'),  # Union of CIN and cancerous. Allowable viral states: infectious, inactive
            State('latent',     bool, False, 'n_genotypes', label='Number with latent infection', color='#5f5cd2'), # Intersection of normal and inactive.
            State('precin',     bool, False, 'n_genotypes', label='Number with precin', color='#9e1149'), # Intersection of normal and infectious

        # Additional intervention states
        self.intv_states = [
            State('detected_cancer',    bool,   False, label='Number with detected cancer'), # Whether the person's cancer has been detected
            State('screened',           bool,   False, label='Number screened'), # Whether the person has been screened (how does this change over time?)
            State('cin_treated',        bool,   False, label='Number treated for precancerous lesions'), # Whether the person has been treated for CINs
            State('cancer_treated',     bool,   False, label='Number treated for cancer'), # Whether the person has been treated for cancer
            State('vaccinated',         bool,   False, label='Number vaccinated'), # Whether the person has received the prophylactic vaccine
            State('tx_vaccinated',      bool,   False, label='Number given therapeutic vaccine'), # Whether the person has received the therapeutic vaccine

        # Any other stock states - add a placeholder here to be populated later
        self.other_stock_states = []

        # Immune states, by genotype/vaccine
        self.imm_states = [
            State('sus_imm',        default_float,  0,'n_imm_sources'),  # Float, by genotype
            State('sev_imm',        default_float,  0, 'n_imm_sources'),  # Float, by genotype
            State('peak_imm',       default_float,  0,'n_imm_sources'),  # Float, peak level of immunity
            State('nab_imm',        default_float,  0,'n_imm_sources'),  # Float, current immunity level
            State('t_imm_event',    default_int,    0,'n_imm_sources'),  # Int, time since immunity event
            State('cell_imm',       default_float,  0,'n_imm_sources'),

        # Relationship states
        self.rship_states = [
            State('rship_start_dates', default_float, np.nan, shape='n_partner_types'),
            State('rship_end_dates', default_float, np.nan, shape='n_partner_types'),
            State('n_rships', default_int, 0, shape='n_partner_types'),
            State('partners', default_float, np.nan, shape='n_partner_types'),  # Int by relationship type
            State('current_partners', default_float, 0, 'n_partner_types'),  # Int by relationship type

        # Duration of different states: these are floats per person -- used in
        self.durs = [
            State('dur_infection',      default_float, np.nan, shape='n_genotypes'), # Length of time that a person has any HPV present. Defined for males and females. For females, dur_infection = dur_episomal + dur_transformed. For males, it's taken from a separate distribution
            State('dur_precin',         default_float, np.nan, shape='n_genotypes'), # Length of time that a person has HPV prior to precancerous changes
            State('dur_cin',            default_float, np.nan, shape='n_genotypes'), # Length of time that a person has precancerous changes
            State('dur_cancer',         default_float, np.nan, shape='n_genotypes'), # Duration of cancer

    # Collection of mutually exclusive + collectively exhaustive states
    def mece_states(self):
        return self.alive_states + self.viral_states + self.cell_states

    # Collection of states that we store as stock results
    def stock_states(self):
        return self.viral_states + self.cell_states + self.derived_states + self.intv_states + self.other_stock_states

    # Collection of states for which we store associated dates
    def date_states(self):
        return [state for state in self.alive_states + self.stock_states if not state.fill_value]

    # Set dates
    def dates(self):
        ''' Dates are stored for all states except susceptible, and alive, and normal (which are True by default) '''
        dates = [State(f'date_{}', default_float, np.nan, shape=state.shape) for state in self.date_states]
        dates += [
            State('date_clearance', default_float, np.nan, shape='n_genotypes'),
            State('date_exposed', default_float, np.nan, shape='n_genotypes'),
            State('date_reactivated', default_float, np.nan, shape='n_genotypes'),
            State('date_latent', default_float, np.nan, shape='n_genotypes'),
        return dates

    # All states
    def all_states(self):
        return self.person + self.alive_states + self.viral_states + self.cell_states + self.derived_states + self.intv_states + self.other_stock_states + self.imm_states + self.rship_states + self.durs

    # States to set - same as above but does not include derived states
    def states_to_set(self):
        return self.person + self.alive_states + self.viral_states + self.cell_states + self.intv_states + self.other_stock_states + self.imm_states + self.rship_states + self.durs + self.dates

    def stock_keys(self):
        return [ for state in self.stock_states]

    def stock_names(self):
        return [state.label for state in self.stock_states]

    def stock_colors(self):
        return [state.color for state in self.stock_states]

    def genotype_stock_keys(self):
        return [ for state in self.stock_states if state.shape=='n_genotypes']

    def other_stock_keys(self):
        return [ for state in self.other_stock_states]

    def intv_stock_keys(self):
        return [ for state in self.intv_states]

    def validate(self):
        Check that states are valid

        This check should be performed when PeopleMeta is consumed (i.e., typically in the People() constructor)
        so that any run-time modifications to the states by the end user get accounted for in validation

        Presently, the only validation check is that the state names are unique, but in principle other
        aspects of the states could be checked too

        :return: None if states are valid
        :raises: ValueError if states are not valid

        # Validate
        state_types = ['person', 'mece_states', 'imm_states', 'intv_states', 'dates', 'durs', 'all_states']
        for state_type in state_types:
            states = getattr(self, state_type)
            n_states        = len(states)
            n_unique_states = len(set(states))
            if n_states != n_unique_states: # pragma: no cover
                errormsg = f'In {state_type}, only {n_unique_states} of {n_states} state names are unique'
                raise ValueError(errormsg)


#%% Default result settings

# Flows
# All are stored (1) by genotype and (2) as the total across genotypes
class Flow():
    def __init__(self, name, label=None, color=None, by_genotype=True): = name
        self.label = label or name
        self.color = color
        self.by_genotype = by_genotype

flows = [
    Flow('infections',              color='#c78f65',    label='Infections'),
    Flow('dysplasias',              color='#c1ad71',    label='Dysplasias'),
    Flow('precins',                 color='#c1ad71',    label='Pre-CINs'),
    Flow('cins',                    color='#b86113',    label='CINs'),
    Flow('cancers',                 color='#5f5cd2',    label='Cancers'),
    Flow('detected_cancers',        color='#5f5cd2',    label='Cancer detections', by_genotype=False),
    Flow('cancer_deaths',           color='#000000',    label='Cancer deaths', by_genotype=False),
    Flow('detected_cancer_deaths',  color='#000000',    label='Detected cancer deaths', by_genotype=False),
    Flow('reinfections',            color='#732e26',    label='Reinfections'),
    Flow('reactivations',           color='#732e26',    label='Reactivations'),
flow_keys           = [ for flow in flows]
genotype_flow_keys  = [ for flow in flows if flow.by_genotype]

# Incidence. Strong overlap with stocks, but with slightly different naming conventions
# All are stored (1) by genotype and (2) as the total across genotypes
inci_keys   = ['hpv',       'dysplasia',      'cancer']
inci_names  = ['HPV',       'Dysplasia',      'Cancer']
inci_colors = ['#c78f65',   '#c1ad71',  '#5f5cd2']

# Demographics
dem_keys    = ['births',    'other_deaths', 'migration']
dem_names   = ['births',    'other deaths', 'migration']
dem_colors  = ['#fcba03',   '#000000',      '#000000']

# Results by sex
by_sex_keys    = ['infections_by_sex',    'other_deaths_by_sex']
by_sex_names   = ['infections by sex',    'deaths from other causes by sex']
by_sex_colors  = ['#000000',              '#000000']

# Results for storing type distribution by dysplasia
type_dist_keys   = ['precin', 'cin', 'cancerous']
type_dist_names  = ['Pre-CIN', 'CIN2+', 'Cancer']

#%% Default initial prevalence

default_init_prev = {
    'age_brackets'  : np.array([  12,   17,   24,   34,  44,   64,    80, 150]),
    'm'             : np.array([ 0.0, 0.25, 0.6, 0.25, 0.05, 0.01, 0.0005, 0]),
    'f'             : np.array([ 0.0, 0.35, 0.7, 0.25, 0.05, 0.01, 0.0005, 0]),

#%% Default plotting settings

# Define the 'overview plots', i.e. the most useful set of plots to explore different aspects of a simulation
overview_plots = [

class plot_args():
    ''' Mini class for defining default plot specifications '''
    def __init__(self, keys, name=None, plot_type=None, year=None):
        self.keys = sc.tolist(keys) = name
        self.plot_type = plot_type
        self.year = year

[docs] def get_default_plots(which='default', kind='sim', sim=None): ''' Specify which quantities to plot; used in Args: which (str): either 'default' or 'overview' ''' which = str(which).lower() # To make comparisons easier # Check that kind makes sense sim_kind = 'sim' scens_kind = 'scens' kindmap = { None: sim_kind, 'sim': sim_kind, 'default': sim_kind, 'msim': scens_kind, 'scen': scens_kind, 'scens': scens_kind, } if kind not in kindmap.keys(): errormsg = f'Expecting "sim" or "scens", not "{kind}"' raise ValueError(errormsg) else: is_sim = kindmap[kind] == sim_kind # Default plots -- different for sims and scenarios if which in ['none', 'default', 'epi']: if is_sim: plots = sc.objdict({ 'HPV prevalence by age': ['precin_prevalence_by_age'], # 'HPV prevalence': ['hpv_prevalence_by_genotype'], 'Cancers by age': 'cancers_by_age', 'Cancer incidence (per 100,000 women)': ['cancer_incidence', 'asr_cancer_incidence'], 'HPV type distribution': 'type_dist', }) else: # pragma: no cover plots = sc.odict({ 'HPV incidence': [ 'hpv_prevalence', ], 'Cancers per 100,000 women': [ 'cancer_incidence', ], }) # Demographic plots elif which in ['demographic', 'demographics', 'dem', 'demography']: if is_sim: plots = sc.odict({ 'Birth and death rates': [ 'cdr', 'cbr', ], 'Population size': [ 'n_alive', 'n_alive_by_sex', ], }) # Show an overview elif which == 'overview': # pragma: no cover plots = sc.dcp(overview_plots) # Plot absolutely everything elif which == 'all': # pragma: no cover plots = sim.result_keys('all') # Show an overview elif 'overview' in which: # pragma: no cover plots = sc.dcp(overview_plots) else: # pragma: no cover errormsg = f'The choice which="{which}" is not supported' raise ValueError(errormsg) return plots