Individual

This module contains the Individual class.

class miscore.Individual(properties, universes, random_number_generators, event_tags, event_ages, event_years, duration_tags, duration_ages, duration_years, event_individual_tags, individual_block_size, snapshot_tags, snapshot_ages, snapshot_years, snapshot_functions, n_stratum_hops, preserve_stratum, log_events_individual, verify_tags)

An Individual object is created for each run. This object is passed to any Process method call during the simulation. This enables all processes to add (add_to_queue(), add_to_queue_age() and add_to_queue_year()), move (move_in_queue()) and remove (remove_from_queue()) events from the queue. Furthermore, events and durations can be logged using log_event() and log_duration(), respectively. Logging events at the individual level is possible using log_event_individual().

age: float = None

The current age of the individual currently being simulated.

memory: dict = None

The memory is a dictionary that can be used to store any information regarding the current individual in the current universe. It is cleared at the beginning of each life (i.e. individual/universe).

random: Dict[str, Random] = None

This dictionary holds all the random number generators created based on the names listed in random_number_generators of each Process.

property year: float

The current year.

properties(tag)

This method provides access to the properties of the current individual.

Parameters:

tag (str) – The name of the property.

Returns:

The ‘tag’ property of the current individual.

properties_tmp(tag)

This method provides access to the temporary properties of the current individual.

Parameters:

tag (str) – The name of the property.

Returns:

The ‘tag’ temporary property of the current individual.

hop_stratum(stratum)

This method allows a process to change the stratum of the individual being simulated. Events and durations will be written towards this stratum from this age forward. A maximum of 256 changes of stratum can be recorded per individual.

Parameters:

stratum (int) – The integer index of the stratum to switch to

log_event(tag)

Log an event at the current time.

Parameters:

tag (str) – The name of the event. The event will only be logged if this tag is in the list of tags passed as ‘event_tags’ to run().

Raises:

Exception – The simulation stops if a user-supplied tag doesn’t correspond with the list of event tags from the processes or supplied by the user in run().

log_duration(tag, start_age, end_age)

Log a duration.

Parameters:

• tag (str) – The name of the duration. The duration will only be logged if this tag is in the list of tags passed as ‘duration_tags’ to run().

• start_age (float) – The start age of the duration.

• end_age (float) – The end age of the duration.

Raises:

Exception – The simulation stops if a user-supplied tag doesn’t correspond with the list of duration tags from the processes or specified by the user in run().

log_duration_start(tag, start_age=None)

Start logging a duration.

The duration can be ended using log_duration_end(). At the end of the simulation, all durations that are still ongoing are ended at the termination age.

Parameters:

• tag (str) – The name of the duration.

• start_age (float | None) – The start age of the duration. If None, the current simulation age is used.

Raises:

AssertionError – If the duration with tag was started before.

log_duration_end(tag, end_age=None)

End logging an ongoing duration.

Parameters:

• tag (str) – The name of the duration.

• end_age (float | None) – The end age of the duration. If None, the current simulation age is used.

Raises:

AssertionError – If the duration with tag was not started before calling log_duration_end.

log_event_individual(tag, age=-1.0, element=0)

Log an event at the individual level.

Each entry requires 17B of computer memory. Thus, taking some overhead into account, about 60 million entries should fit in each GiB of available RAM.

Parameters:

• tag (str) – The tag of the event. The event will only be logged if this tag is in the list of tags passed as ‘individual_tags’ to the run() method.

• age (float) – The age at which the event should be logged. The current age is used by default.

• element (int) – To distinguish between events belonging to different elements of an individual (e.g. different lesions), an integer identifying this element (e.g. lesion) can be passed as ‘element’.

Raises:

Exception – The simulation stops if a user-supplied tag doesn’t correspond with the list of individual tags from the processes or specified by the user in run().

add_to_queue(delta, message, priority=0, terminate=False, **kwargs)

Add an event to the queue at a time relative to the current time.

Parameters:

• delta (float) – The time in years after which this event should be triggered, relative to the current time.

• message (str) – The message of the event.

• priority (int) – The priority of the event, where higher priority values are taken from the queue first. Default is 0.

• terminate (bool) – Whether or not the simulation should be terminated when this event is due.

• kwargs – Any other data passed to this function is stored and will be returned when the event is due.

Return type:

int

Returns:

The unique id of the added event.

add_to_queue_age(age, message, priority=0, terminate=False, **kwargs)

Add an event to the queue at a specific age.

Parameters:

• age (float) – The age at which this event should be triggered.

• message (str) – The message of the event.

• priority (int) – The priority of the event, where higher priority values are taken from the queue first. Default is 0.

• terminate (bool) – Whether or not the simulation should be terminated when this event is due.

• kwargs – Any other data passed to this function is stored and will be returned when the event is due.

Return type:

int

Returns:

The unique id of the added event.

add_to_queue_year(year, message, priority=0, terminate=False, **kwargs)

Add an event to the queue at a specific date.

Parameters:

• year (float) – The date at which this event should be triggered.

• message (str) – The message of the event.

• priority (int) – The priority of the event, where higher priority values are taken from the queue first. Default is 0.

• terminate (bool) – Whether or not the simulation should be terminated when this event is due.

• kwargs – Any other data passed to this function is stored and will be returned when the event is due.

Return type:

int

Returns:

The unique id of the added event.

remove_from_queue(idx)

Remove an event from the queue.

Parameters:

idx (int) – The unique id of the event.

remove_from_queue_message(message)

Remove all events from the queue with a particular message.

Parameters:

message (str) – The message of events to be removed.

move_in_queue(idx, delta)

Move an event that is on the queue to a different age. In fact, this will delete the original event and create a new event.

Parameters:

• idx (int) – The unique id of the event to move.

• delta (float) – The time in years with which to move this event, relative to the age the event is currently scheduled at.

Return type:

int

Returns:

The unique id of the updated event.

move_in_queue_age(idx, age)

Move an event that is on the queue to a different age. In fact, this will delete the original event and create a new event.

Parameters:

• idx (int) – The unique id of the event to move.

• age (float) – The age at which the event should take place.

Return type:

int

Returns:

The unique id of the updated event.

move_in_queue_year(idx, year)

Move an event that is on the queue to a different date. In fact, this will delete the original event and create a new event.

Parameters:

• idx (int) – The unique id of the event to move.

• year (float) – The date at which the event should take place.

Return type:

int

Returns:

The unique id of the updated event.