tlo.population module

Types for representing a properties of a population of individuals.

class IndividualProperties(population_dataframe: DataFrame, person_id: int, read_only: bool = True)

Bases: object

Memoized view of population dataframe row that is optionally read-only.

This class should not be instantiated directly but instead the Population.individual_properties() context manager method used to create instances for a given population.

synchronize_updates_to_dataframe() → None: Synchronize values for any updated properties to population dataframe.

finalize() → None: Synchronize updates to population dataframe and prevent further access.

class Population(properties: Dict[str, Property], initial_size: int, append_size: int | None = None)

Bases: object

A complete population of individuals.

Useful properties of a population:

props: A Pandas DataFrame with the properties of all individuals as columns.

Create a new population.

This will create the required the population dataframe and initialise individual’s properties as dataframe columns with ‘empty’ values. The simulation will then call disease modules to fill in suitable starting values.

Parameters:

properties – Dictionary defining properties (columns) to initialise population dataframe with, keyed by property name and with values Property instances defining the property type.
initial_size – The initial population size.
append_size – How many rows to append when growing the population dataframe (optional).

initial_size

props

new_row

new_rows

next_person_id

do_birth()

Create a new person within the population.

TODO: This will over-allocate capacity in the population dataframe for efficiency.

Returns:: id of the new person

make_test_property(name, type_)

Create a new property for test purposes.

When testing a particular method in isolation, it’s helpful to be able to define the properties it reads that would normally be provided by other methods. That is what this is for. It adds an extra column into the property DataFrame for this population, set up with the appropriate type.

This should only be used in tests, not in your actual module code!

Parameters:

name – the name of the property to add
type – a member of the Types enumeration giving the type of the property

individual_properties(person_id: int, read_only: bool = True) → Generator[IndividualProperties, None, None]

Context manager for a memoized view of a row of the population dataframe.

The view returned represents the properties of an individual with properties accessible by indexing using string column names, and lazily read-on demand from the population dataframe.

Optionally the view returned may allow updating properties as well as reading. In this case on exit from the with block in which the context is entered, any updates to the individual properties will be written back to the population dataframe.

Once the with block in which the context is entered has been exited the view returned will raise an error on any subsequent attempts at reading or writing properties.

Parameters:

person_id – Row index of the dataframe row to extract.
read_only – Whether view is read-only or allows updating properties. If True IndividualProperties.synchronize_updates_to_dataframe() method needs to be called for any updates to be written back to population dataframe.

Returns:

Object allowing memoized access to an individual’s properties.