BasePeople#

class BasePeople(pars)[source]#

Bases: FlexPretty

A class to handle all the boilerplate for people – note that as with the BaseSim vs Sim classes, everything interesting happens in the People class, whereas this class exists to handle the less interesting implementation details.

Attributes

`abnormal`	Boolean array of everyone with abnormal cells.
`alive_inds`	Indices of everyone alive
`alive_level0`	Indices of everyone alive who is a level 0 agent
`alive_level0_inds`	Indices of everyone alive who is a level 0 agent
`dt_age`	Return ages rounded to the nearest whole timestep
`f_inds`	Indices of everyone female
`infected`	Boolean array of everyone infected.
`int_age`	Return ages as an integer
`is_active`	Boolean array of everyone sexually active i.e. past debut.
`is_female`	Boolean array of everyone female
`is_female_adult`	Boolean array of everyone eligible for screening
`is_female_alive`	Boolean array of everyone female and alive
`is_male`	Boolean array of everyone male
`is_male_alive`	Boolean array of everyone male and alive
`is_virgin`	Boolean array of everyone not yet sexually active i.e. pre debut.
`latent`	Boolean array of everyone with latent infection.
`m_inds`	Indices of everyone male
`n_alive`	Number of people alive
`n_alive_level0`	Number of people alive
`precin`	Boolean array of females with HPV whose disease severity level does not meet the threshold for detectable cell changes
`round_age`	Rounds age up to the next highest integer

Methods

initialize()[source]#: Initialize underlying storage and map arrays

set_pars(pars=None)[source]#: Re-link the parameters stored in the people object to the sim containing it, and perform some basic validation.

validate(sim_pars=None, verbose=False)[source]#

Perform validation on the People object.

Parameters:

sim_pars (dict) – dictionary of parameters from the sim to ensure they match the current People object
verbose (bool) – detail to print

lock()[source]#: Lock the people object to prevent keys from being added

unlock()[source]#: Unlock the people object to allow keys to be added

filter_inds(inds)[source]#

Store indices to allow for easy filtering of the People object.

Parameters:: inds (array) – filter by these indices
Returns:: A filtered People object, which works just like a normal People object except only operates on a subset of indices.

filter(criteria)[source]#

Store indices to allow for easy filtering of the People object.

Parameters:: criteria (array) – a boolean array for the filtering critria
Returns:: A filtered People object, which works just like a normal People object except only operates on a subset of indices.

unfilter()[source]#

Set main simulation attributes to be views of the underlying data

This method should be called whenever the number of agents required changes (regardless of whether or not the underlying arrays have been resized)

__add__(people2)[source]#: Combine two people arrays

addtoself(people2)[source]#: Combine two people arrays, avoiding dcp

get(key)[source]#: Convenience method – key can be string or list of strings

property is_female#: Boolean array of everyone female

property is_female_alive#: Boolean array of everyone female and alive

property is_male#: Boolean array of everyone male

property is_male_alive#: Boolean array of everyone male and alive

property f_inds#: Indices of everyone female

property m_inds#: Indices of everyone male

property int_age#: Return ages as an integer

property round_age#: Rounds age up to the next highest integer

property dt_age#: Return ages rounded to the nearest whole timestep

property is_active#: Boolean array of everyone sexually active i.e. past debut

property is_female_adult#: Boolean array of everyone eligible for screening

property is_virgin#: Boolean array of everyone not yet sexually active i.e. pre debut

property alive_inds#: Indices of everyone alive

property alive_level0#: Indices of everyone alive who is a level 0 agent

property alive_level0_inds#: Indices of everyone alive who is a level 0 agent

property n_alive#: Number of people alive

property n_alive_level0#: Number of people alive

property infected#: Boolean array of everyone infected. Union of infectious and inactive. Includes people with cancer, people with latent infections, and people with active infections

property abnormal#: Boolean array of everyone with abnormal cells. Union of episomal, transformed, and cancerous

property latent#: Boolean array of everyone with latent infection. By definition, these people have inactive infection and no cancer.

property precin#: Boolean array of females with HPV whose disease severity level does not meet the threshold for detectable cell changes

true(key)[source]#: Return indices matching the condition

true_by_genotype(key, genotype)[source]#: Return indices matching genotype-condition

false_by_genotype(key, genotype)[source]#: Return indices not matching genotype-condition

false(key)[source]#: Return indices not matching the condition

defined(key)[source]#: Return indices of people who are not-nan

undefined(key)[source]#: Return indices of people who are nan

count(key, weighted=True)[source]#: Count the number of people for a given key

count_any(key, weighted=True)[source]#: Count the number of people for a given key for a 2D array if any value matches

count_by_genotype(key, genotype, weighted=True)[source]#: Count the number of people for a given key

keys()[source]#: Returns keys for all non-derived properties of the people object

person_keys()[source]#: Returns keys specific to a person (e.g., their age)

state_keys()[source]#: Returns keys for different states of a person (e.g., symptomatic)

imm_keys()[source]#: Returns keys for different states of a person (e.g., symptomatic)

date_keys()[source]#: Returns keys for different event dates (e.g., date a person became symptomatic)

dur_keys()[source]#: Returns keys for different durations (e.g., the duration from exposed to infectious)

layer_keys()[source]#: Get the available contact keys – try contacts first, then acts

indices()[source]#: The indices of each people array

to_df()[source]#: Convert to a Pandas dataframe

to_arr()[source]#: Return as numpy array

person(ind)[source]#: Method to create person from the people

to_list()[source]#: Return all people as a list

from_list(people)[source]#: Convert a list of people back into a People object

to_graph()[source]#

Convert all people to a networkx MultiDiGraph, including all properties of the people (nodes) and contacts (edges).

Example:

import hpvsim as hpv
import networkx as nx
sim = hpv.Sim(n_agents=50, pop_type='hybrid', contacts=dict(h=3, s=10, w=10, c=5)).run()
G = sim.people.to_graph()
nodes = G.nodes(data=True)
edges = G.edges(keys=True)
node_colors = [n['age'] for i,n in nodes]
layer_map = dict(h='#37b', s='#e11', w='#4a4', c='#a49')
edge_colors = [layer_map[G[i][j][k]['layer']] for i,j,k in edges]
edge_weights = [G[i][j][k]['beta']*5 for i,j,k in edges]
nx.draw(G, node_color=node_colors, edge_color=edge_colors, width=edge_weights, alpha=0.5)

save(filename=None, force=False, **kwargs)[source]#

Save to disk as a gzipped pickle.

Note: by default this function raises an exception if trying to save a run or partially run People object, since the changes that happen during a run are usually irreversible.

Parameters:

filename (str or None) – the name or path of the file to save to; if None, uses stored
force (bool) – whether to allow saving even of a run or partially-run People object
kwargs – passed to sc.makefilepath()

Returns:

the validated absolute path to the saved file

Return type:

filename (str)

Example:

sim = hpv.Sim()
sim.initialize()
sim.people.save() # Saves to a .ppl file

static load(filename, *args, **kwargs)[source]#

Load from disk from a gzipped pickle.

Parameters:

filename (str) – the name or path of the file to load from
args (list) – passed to hpv.load()
kwargs (dict) – passed to hpv.load()

Returns:

the loaded people object

Return type:

people (People)

Example:

people = hpv.people.load('my-people.ppl')

init_contacts(reset=False)[source]#: Initialize the contacts dataframe with the correct columns and data types

add_contacts(contacts, lkey=None, beta=None)[source]#: Add new contacts to the array. See also contacts.add_layer().

make_edgelist(contacts)[source]#: Parse a list of people with a list of contacts per person and turn it into an edge list.

static remove_duplicates(df)[source]#: Sort the dataframe and remove duplicates – note, not extensively tested