people
people
Defines the People class and functions associated with making people
Classes
| Name | Description |
|---|---|
| People | A class to perform all the operations on the people |
| Person | A simple class to hold all attributes of a person |
People
people.People(self, n_agents, age_data=None, extra_states=None, mock=False)A class to perform all the operations on the people This class is usually created automatically by the sim. The only required input argument is the population size, but typically the full parameters dictionary will get passed instead since it will be needed before the People object is initialized.
Note that this class handles the mechanics of updating the actual people, as well as the additional housekeeping methods (saving, loading, exporting, etc.).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| pars | dict | the sim parameters, e.g. sim.pars – alternatively, if a number, interpreted as n_agents | required |
| age_data | dataframe |
a dataframe of years and population sizes, if available | None |
| extra_states | list | non-default states to initialize | None |
| mock | bool | if True, initialize the People object with a mock Sim object (for debugging only) | False |
Examples: ppl = ss.People(2000)
Attributes
| Name | Description |
|---|---|
| dead | Dead boolean |
| male | Male boolean |
| n_agents | Alias for len(people) |
Methods
| Name | Description |
|---|---|
| add_module | Add a Module to the People instance |
| disp | Full object information |
| filter | Store indices to allow for easy filtering of the People object. |
| get_age_dist | Return an age distribution based on provided data |
| grow | Increase the number of agents |
| init_mock | Initialize with a mock simulation (for debugging purposes only) |
| init_vals | Populate states with initial values, the final step of initialization |
| link_sim | Initialization |
| person | Get all the properties for a single person. |
| plot | Plot all the properties of the People object |
| plot_ages | Plot the age pyramid for males and females. |
| remove_dead | Remove dead agents |
| request_death | External-facing function to request an agent die at the current timestep |
| scale_flows | Return the scaled versions of the flows – replacement for len(inds) |
| step_die | Carry out any deaths that took place this timestep |
| to_df | Export to dataframe |
| update_post | Final updates at the very end of the timestep |
add_module
people.People.add_module(module, force=False)Add a Module to the People instance
This method is used to add a module to the People. It will register any module states with this people instance for dynamic resizing, and expose the states contained in the module to the user via People.states.<module_name>.<state_name>
The entries created below make it possible to do sim.people.hiv.susceptible or sim.people.states['hiv.susceptible'] and have both of them work
disp
people.People.disp()Full object information
filter
people.People.filter(criteria=None, uids=None, split=False)Store indices to allow for easy filtering of the People object.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| criteria | bool array | a boolean array for the filtering critria | None |
| uids | array | alternatively, explicitly filter by these indices | None |
| split | bool | if True, return separate People objects matching both True and False | False |
Returns
| Name | Type | Description |
|---|---|---|
| A filtered People object, which works just like a normal People object | ||
| except only operates on a subset of indices. |
get_age_dist
people.People.get_age_dist(age_data)Return an age distribution based on provided data
The data should be provided in the form of either an Nx2 array, a pandas series with age as the index and counts/probability as the value, or a pandas DataFrame with “age” and “value” as columns. Each of these should look like e.g.:
age value
0 220.548
1 206.188
2 195.792
3 187.442The ages will be interpreted as lower bin edges. An upper bin edge will automatically be added based on the final age plus the difference of the last two bins. To explicitly control the width of the upper age bin, add an extra entry to the age_data with a value of 0 and an age value corresponding to the desired upper age bound.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| age_data | An array/series/dataframe with an index corresponding to age values, and a value corresponding to histogram counts or relative proportions. A distribution will be estimated based on the histogram. The histogram will be assumed to correspond to probability densitiy if the sum of the histogram values is equal to 1, otherwise it will be assumed to correspond to counts. | required |
Note: age_data can also be provided as a string (interpreted as a filename).
If no value is provided, uniform ages from 0-60 are created (to match the global mean age of ~30 years).
Returns
| Name | Type | Description |
|---|---|---|
An ss.Dist instance that returns an age for newly created agents |
grow
people.People.grow(n=None, new_slots=None)Increase the number of agents
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| n | Integer number of agents to add | None |
|
| new_slots | Optionally specify the slots to assign for the new agents. Otherwise, it will default to the new UIDs | None |
init_mock
people.People.init_mock()Initialize with a mock simulation (for debugging purposes only)
init_vals
people.People.init_vals()Populate states with initial values, the final step of initialization
link_sim
people.People.link_sim(sim, init=False)Initialization
person
people.People.person(ind)Get all the properties for a single person.
Example:
sim = ss.Sim(diseases='sir', networks='random', n_agents=100).run()
print(sim.people.person(5)) # The 5th agent in the simulationplot
people.People.plot(
key=None,
alive=True,
bins=50,
hist_kw=None,
max_plots=20,
figsize=(16, 12),
**kwargs,
)Plot all the properties of the People object
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| key | str / list | the state(s) to plot | None |
| alive | bool | if false, use all agents in the simulation instead of active (alive) ones | True |
| bins | int | the number of bins to use in plt.hist() |
50 |
| hist_kw | dict | passed to plt.hist() |
None |
| max_plots | int | the maximum number of plots to create | 20 |
| figsize | tuple | passed to plt.figure(); by default large since the plots are crowded |
(16, 12) |
| **kwargs | dict | passed to sc.getrowscols(), including fig_kw |
{} |
plot_ages
people.People.plot_ages(bins=None, absolute=False, fig_kw=None)Plot the age pyramid for males and females.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| bins | list / int | optional list or int for binning age groups (default: 5-year bins up to max age) | None |
| absolute | bool | whether to show absolute numbers or percentage of the population | False |
| fig_kw | dict | passed to plt.subplots() |
None |
Example:
sim = ss.demo(plot=False)
sim.people.plot_age()remove_dead
people.People.remove_dead()Remove dead agents
request_death
people.People.request_death(uids)External-facing function to request an agent die at the current timestep
In general, users should not directly interact with People.ti_dead to minimize interactions between modules (e.g., if a module requesting a future death, overwrites death due to a different module taking place at the current timestep).
Modules that have a future time of death (e.g., due to disease duration) should keep track of that internally. When the module is ready to cause the agent to die, it should call this method, and can update its own results for the cause of death. This way, if multiple modules request death on the same day, they can each record a death due to their own cause.
The actual deaths are resolved after modules have all run, but before analyzers. That way, regardless of whether removing dead agents is enabled or not, analyzers will be able to see and record outcomes for agents that died this timestep.
WARNING - this function allows multiple modules to each independently carry out and record state changes associated with death. It is therefore important that they can guarantee that after requesting death, the death is guaranteed to occur.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| uids | Agent IDs to request deaths for | required |
Returns
| Name | Type | Description |
|---|---|---|
| UIDs of agents that have been scheduled to die on this timestep |
scale_flows
people.People.scale_flows(inds)Return the scaled versions of the flows – replacement for len(inds) followed by scale factor multiplication
step_die
people.People.step_die()Carry out any deaths that took place this timestep
to_df
people.People.to_df()Export to dataframe
update_post
people.People.update_post()Final updates at the very end of the timestep
Person
people.Person()A simple class to hold all attributes of a person
Example:
sim = ss.Sim(diseases='sir', networks='random', n_agents=100).run()
print(sim.people.person(5)) # The 5th agent in the simulationMethods
| Name | Description |
|---|---|
| to_df | Convert to a dataframe |
to_df
people.Person.to_df()Convert to a dataframe