Core

The miscore.core module provides the framework of MISCore. A disease or anything else that needs be simulated should be implemented as a Process. A Universe holds one or more processes, while a Model is defined by a set of universes.

miscore.core.MAX_AGE: float = 100.0

Maximum age an individual can reach. If individuals are still alive, their simulation stops after this period in years (i.e. the moment they turn 100). This variable is not used in the core, but can be used in processes and ensures that the maximum age is managed centrally.

class miscore.Process

Anything that should be simulated, should be implemented as a subclass of Process. Only processes are able to log events and durations, respond to events, edit the events queue and define properties of individuals. One or more processes can be combined in a Universe.

name: str = None

The name of the process.

event_tags: List[str] = []

All event tags that can be logged by this process.

duration_tags: List[str] = []

All duration tags that can be logged by this process.

event_individual_tags: List[str] = []

All individual event tags that can be logged by this process.

snapshot_tags: List[str] = []

All snapshot tags that can be logged by this process.

callbacks: Dict[str, Callable[[Individual], None]] = {}

This dictionary maps event messages to functions or methods.

random_number_generators: List[str] = []

For each name in this list, a random number generator is created, which can be accessed during the simulation via miscore.Individual.random.

classmethod from_data(module, allow_unused_values=False, key=None, **kwargs)

Construct the Process by passing the module in which the required data is defined.

Parameters:

• module – The module in which the required data is defined.

• allow_unused_values (bool) – Whether or not to allow the module to contain values not required by the Process.

• key (str | None) – Key to retrieve the correct set in nested dictionaries.

• kwargs – Any arguments that are not defined in the module or arguments that should be overridden.

Returns:

An instance of the Process.

properties(rng, n, properties)

This method enables the process to define properties for each individual (e.g. birth date). During the simulation, these properties can be accesses using the properties() method of the current Individual object. All created properties will be included in the output of a simulation run. Override this method if the Process should generate properties.

Parameters:

• rng (Generator) – The random number generator that should be used to generate any random values.

• n (int) – The number of individuals to create properties for.

• properties (Dict[str, ndarray]) – The properties generated by other processes so far.

Return type:

Dict[str, ndarray]

Returns:

Properties for ‘n’ individuals in a dictionary. The key of each dictionary entry should be the ‘tag’ of the property. Each value should be an iterable of size ‘n’ in the first dimension.

properties_tmp(rng, n, properties, properties_tmp)

This method enables the process to define temporary properties for each individual. This is especially useful to generate and store the random numbers that are needed during the simulation These temporary properties can be accesses using the properties_tmp() method of the current Individual object. Note that the temporary properties will be overwritten many times during the simulation. Thus, these values will not be included in the simulation output. Override this method if the Process should generate temporary properties.

Parameters:

• rng (Generator) – The random number generator that should be used to generate any random values.

• n (int) – The number of individuals to create properties for.

• properties (Dict[str, ndarray]) – The properties of the ‘n’ individuals.

• properties_tmp (Dict[str, ndarray]) – The temporary properties generated by other processes so far.

Return type:

Dict[str, ndarray]

Returns:

Temporary properties for ‘n’ individuals in a dictionary. The key of each dictionary entry should be the ‘tag’ of the property. Each value should be an iterable of size ‘n’ in the first dimension.

class miscore.Universe(name, processes)

A universe holds one or more processes. One or more universe can be used to define a Model.

Parameters:

• name (str) – The name of the universe.

• processes (Sequence[Process]) – The processes the universe should hold.

Raises:

• AssertionError – At least one of the processes in the universe should include the ‘__start__’ message in its callbacks.

• AssertionError – Universes should not contain multiple Processes of the same type.

class miscore.Model(universes)

A model holds one or more universes. These universes can be simulated by calling the run() method.

Parameters:

universes (Sequence[Universe]) – A list of universes.

Raises:

ValueError – The names of the universes should be unique.

property random_number_generators: List[str]

Returns all random number generators used by the processes in the model.

Returns:

All random number generators.

property event_tags: List[str]

Returns all unique event tags that can possible be logged by the processes in the model.

Returns:

All possible event tags in the model.

property duration_tags: List[str]

Returns all unique duration tags that can possible be logged by the processes in the model.

Returns:

All possible duration tags in the model.

property event_individual_tags: List[str]

Returns all unique individual event tags that can possible be logged by the processes in the model.

Returns:

All possible individual event tags in the model.

property snapshot_tags: List[str]

Returns all unique snapshots tags that can possible be logged by the processes in the model.

Returns:

All possible snapshots tags in the model.

run(n, cores=None, seed=None, seeds_properties=None, seeds_properties_tmp=None, seeds_random=None, event_tags=None, event_ages=None, event_years=None, duration_tags=None, duration_ages=None, duration_years=None, event_individual_tags=None, individual_block_size=10000, snapshot_tags=None, snapshot_functions=None, snapshot_ages=None, snapshot_years=None, properties=None, return_properties=False, n_stratum_hops=None, preserve_stratum=None, stratum_names=None, block_size=2000, log_events_individual=False, verbose=False, verify_tags=True)

Runs the model and returns the result.

Parameters:

• n (SupportsInt) – The number of individuals to simulate.

• cores (int | Literal['all'] | None) – The number of CPU processes to create to run the simulation on. If None (the default), no new processes are created. If ‘all’, a process is created for each detected CPU.

• seed (int | None) – If required seeds are missing in ‘seeds_properties’, ‘seeds_properties_tmp’ or ‘seeds_random’, these seeds will be drawn using a random number generator seeded with ‘seed’.

• seeds_properties (Dict[str, int] | None) – The seeds to use for the properties() method of each Process in the model. If no seed is provided for a Process that implemented the properties() method, a random seed is drawn. All used seeds are stored in the returned Result.

• seeds_properties_tmp (Dict[str, int] | None) – The seeds to use for the properties_tmp() method of each Process in the model. If no seed is provided for a Process that implemented the properties_tmp() method, a random seed is drawn. All used seeds are stored in the returned Result.

• seeds_random (Dict[str, int] | None) – The seeds to use for the random number generators accessible during the simulation. If no seed is provided for a random number generator, a random seed is drawn. All used seeds are stored in the returned Result.

• event_tags (Collection[str] | None) – The tags of the events that should be logged. If None (the default), all events are logged.

• event_ages (Collection[SupportsFloat] | None) – The lower bounds of the age groups that should be used in the event log. E.g. [40, 60] would group the events in the following three groups: [0, 40), [40, 60), [60, inf). By default, all events are logged in a single age group [0, inf).

• event_years (Collection[SupportsFloat] | None) – The lower bounds of the year groups that should be used in the event log. E.g. [1990, 2000] would group the events in the following three groups: [0, 1990), [1990, 2000), [2000, inf). By default, all events are logged in a single year group [0, inf).

• duration_tags (Collection[str] | None) – The tags of the durations that should be logged. If None (the default), all durations are logged.

• duration_ages (Collection[SupportsFloat] | None) – The lower bounds of the age groups that should be used in the duration log. E.g. [40, 60] would group the durations in the following three groups: [0, 40), [40, 60), [60, inf). By default, all durations are logged in a single age group [0, inf).

• duration_years (Collection[SupportsFloat] | None) – The lower bounds of the year groups that should be used in the duration log. E.g. [1990, 2000] would group the durations in the following three groups: [0, 1990), [1990, 2000), [2000, inf). By default, all durations are logged in a single year group [0, inf).

• event_individual_tags (Collection[str] | None) – The tags of the individual events that should be logged. If None (the default), all individual events are logged.

• individual_block_size (SupportsInt) – For the individual event log, blocks of memory are pre-allocated to store the logged events in. If a block is full, another block of memory is created. This arguments determines the size of each such block. By default, blocks that can hold 10000 entries are created.

• snapshot_tags (Collection[str] | None) – The tags of the snapshots that should be included in the result. If None (the default), all snapshots are logged.

• snapshot_functions (Collection[Callable[[Individual], set | dict | None]] | None) – The functions to take the snapshots with.

• snapshot_ages (Collection[SupportsFloat] | None) – The ages at which snapshots should be taken.

• snapshot_years (Collection[SupportsFloat] | None) – The calendar years at which snapshots should be taken.

• properties (Dict[str, ndarray] | None) – A dictionary with individuals properties. Each property returned by the properties() method of a Process is ignored if its name exists in this dictionary.

• return_properties (Collection[str] | bool) – By default, no properties are included in the returned Result. If a collection of strings is passed, a property is only included if its name is in this collection. Set this argument to True to return all generated properties.

• n_stratum_hops (int | None) – Int to denote the number of strata that should be preallocated to allow for dynamic stratification. Only supply if using dynamic stratification in your model.

• preserve_stratum (Literal['dynamic', 'final'] | None) – Whether the stratification from the first universe should be preserved to study stratum-specific changes in outcomes by universe. For example, to evaluate the outcomes of would-be screenees in a non-screening universe. Defaults to None. Options are “final” to preserve the final stratum or “dynamic” to also preserve the stratum hops.

• stratum_names (Sequence[str] | None) – Names of strata to replace the integer numbering used by default. Order of names should follow the integer sequence of the matching strata, starting from stratum 0.

• block_size (int) – During a simulation, the population is split up in ‘blocks’. For each block and each process, a seed is generated and passed to the properties_tmp() method of each process to use for the generation of temporary properties. The number of individuals in each block is equal to ‘block_size’. If this variable is set to a too high value, memory issues may arise. However, low values may decrease performance. By default, this variable is set to 2000.

• log_events_individual (bool) – When set to True, log_event() will call log_event_individual() after logging the event. If no ‘event_individual_tags’ are passed, these will be set equal to event_tags().

• verbose (bool) – Whether or not to print progress during the simulation. Set to False by default.

• verify_tags (bool) – Boolean flag indicating whether an error should be raised when the process attempts to log an event, duration, event_individual or snapshot tag that is not listed in respective list of tags supplied by the user and the processes. Defaults to True.

Return type:

Result

Returns:

The output of the simulation.

Raises:

• ValueError – ‘n’ should be positive.

• Exception – The simulation stops if a logged event, duration, event_individual or snapshot tag doesn’t correspond with the list of tags gathered from the processes or supplied by the user.

class miscore.Result(n, block_size, version, released, seeds_properties, seeds_properties_tmp, seeds_random, properties, events, durations, events_individual, snapshots_ages, snapshots_years)

Simulation result containing all properties and logged events, durations and snapshots.

Parameters:

• n (int) – The number of individuals simulated.

• block_size (int) – The used block_size.

• version (str) – The version of MISCore used to obtain the result.

• released (bool) – Boolean indicating whether or not this version of MISCore was released.

• seeds_properties (Dict[str, int]) – The seeds used for the properties() method of each Process.

• seeds_properties_tmp (Dict[str, int]) – The seeds used for the properties_tmp() method of each Process.

• seeds_random (Dict[str, int]) – The seeds used for the random number generators accessible during the simulation.

• properties (DataFrame) – The properties of the simulated individuals.

• events (DataFrame) – The logged events.

• durations (DataFrame) – The logged durations.

• events_individual (DataFrame) – The logged individual events.

• snapshots_ages (DataFrame) – The age snapshots taken during the simulation.

• snapshots_years (DataFrame) – The year snapshots taken during the simulation.

save(path)

Save the result to a file.

Use load_result() to load the result from the file.

Parameters:

path (str) – The path to the file.

miscore.load_result(path)

Load a Result from a file.

Use Result.save() to save a result to a file.

Parameters:

path (str) – The path to the file.

Raises:

ValueError – ‘path’ does not contain a Result object.

Return type:

Result

Returns:

The loaded Result object.