arrays
arrays
Define array-handling classes, including agent states
Classes
| Name | Description |
|---|---|
| Arr | Store a state of the agents (e.g. age, infection status, etc.) as an array. |
| BaseArr | An object that acts exactly like a NumPy array, except stores the values in self.values. |
| BoolArr | Subclass of Arr with defaults for booleans |
| BoolState | A boolean array being used as a state. |
| FloatArr | Subclass of ss.Arr with defaults for floats and ints. |
| IndexArr | A special class of Arr used for UIDs and RNG IDs; not to be used as an integer array (for that, use FloatArr) |
| IntArr | Subclass of Arr with defaults for ints. |
| uids | Class to specify that integers should be interpreted as UIDs. |
Arr
arrays.Arr(
self,
name=None,
dtype=None,
default=None,
nan=None,
label=None,
raw=None,
skip_init=False,
people=None,
mock=None,
)Store a state of the agents (e.g. age, infection status, etc.) as an array.
In practice, Arr objects can be used interchangeably with NumPy arrays. They have two main data interfaces: Arr.raw contains the “raw”, underlying NumPy array of the data. Arr.values contains the “active” values, which usually corresponds to agents who are alive.
By default, operations are performed on active agents only (specified by Arr.auids, which is a pointer to sim.people.auids). For example, sim.people.age.mean() will only use the ages of active agents. Thus, sim.people.age.mean() is equal to sim.people.age.values.mean(), not sim.people.age.raw.mean().
If indexing by an int or slice, Arr.values is used. If indexing by an ss.uids object, Arr.raw is used. Arr objects can’t be directly indexed by a list or array of ints, as this would be ambiguous about whether values or raw is intended. For example, if there are 1000 people in a simulation and 100 of them have died, sim.people.age[999] will return an IndexError (since sim.people.age[899] is the last active agent), whereas sim.people.age[ss.uids(999)] is valid.
Note on terminology: the term “states” is often used to refer to all ss.Arr objects, (e.g. in module.define_states(), whether or not they are BoolStates.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| name | str | The name for the state (also used as the dictionary key, so should not have spaces etc.) | None |
| dtype | class | The dtype to use for this instance (if None, infer from value) | None |
| default | any | Specify default value for new agents. This can be: * A scalar with the same dtype (or castable to the same dtype) as the Arr; * A callable, with a single argument for the number of values to produce; * A ss.Dist instance. |
None |
| nan | any | the value to use to represent NaN (not a number); also used as the default value if not supplied | None |
| label | str | The human-readable name for the state | None |
| raw | array | If provided, initialize the array with these raw values | None |
| skip_init | bool | Whether to skip initialization with the People object (used for uid and slot states) | False |
| people | [ss.People](starsim.people.People |
Optionally specify an initialized People object, used to construct temporary Arr instances | None |
| mock | int | if provided, create a mock People object (of length mock, unless raw is provided) to initialize the array (for debugging purposes) |
None |
Attributes
| Name | Description |
|---|---|
| auids | Link to the indices of active agents – sim.people.auids |
| isnan | Return BoolArr for NaN values |
| notnan | Return BoolArr for non-NaN values |
| notnanvals | Return values that are not-NaN |
| values | Return the values of the active agents |
Methods
| Name | Description |
|---|---|
| asnew | Duplicate and copy (rather than link) data, optionally resetting the array |
| astype | Convert the Arr type |
| convert | Check if an object is an array, and convert if so |
| false | Reverse of true(); return UIDs of falsy values |
| grow | Add new agents to an Arr |
| init_vals | Actually populate the initial values and mark as initialized; only to be used on initialization |
| link_people | Link a People object to this state, for access auids |
| set | Set the values for the specified UIDs |
| set_nan | Shortcut function to set values to NaN |
| to_json | Export to JSON |
| true | Efficiently convert truthy values to UIDs |
asnew
arrays.Arr.asnew(arr=None, cls=None, name=None, copy=None)Duplicate and copy (rather than link) data, optionally resetting the array
astype
arrays.Arr.astype(cls, copy=False)Convert the Arr type
convert
arrays.Arr.convert(obj, copy=None)Check if an object is an array, and convert if so
false
arrays.Arr.false()Reverse of true(); return UIDs of falsy values
grow
arrays.Arr.grow(new_uids=None, new_vals=None)Add new agents to an Arr
This method is normally only called via People.grow().
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| new_uids | array | Numpy array of UIDs for the new agents being added | None |
| new_vals | array | If provided, assign these state values to the new UIDs | None |
init_vals
arrays.Arr.init_vals()Actually populate the initial values and mark as initialized; only to be used on initialization
link_people
arrays.Arr.link_people(people)Link a People object to this state, for access auids
set
arrays.Arr.set(uids, new_vals=None)Set the values for the specified UIDs
set_nan
arrays.Arr.set_nan(uids)Shortcut function to set values to NaN
to_json
arrays.Arr.to_json()Export to JSON
true
arrays.Arr.true()Efficiently convert truthy values to UIDs
BaseArr
arrays.BaseArr(self, values, *args, **kwargs)An object that acts exactly like a NumPy array, except stores the values in self.values.
Methods
| Name | Description |
|---|---|
| asnew | Duplicate and copy (rather than link) data |
| convert | Check if an object is an array, and convert if so |
| disp | Full display of object |
| to_json | Return a dictionary representation of the Arr |
| update | Update the attributes, skipping None values and raising an error if extra keys are added |
asnew
arrays.BaseArr.asnew(values=None, cls=None, **kwargs)Duplicate and copy (rather than link) data
convert
arrays.BaseArr.convert(obj)Check if an object is an array, and convert if so
disp
arrays.BaseArr.disp()Full display of object
to_json
arrays.BaseArr.to_json()Return a dictionary representation of the Arr
update
arrays.BaseArr.update(skip_none=True, overwrite=True, force=False, **kwargs)Update the attributes, skipping None values and raising an error if extra keys are added
BoolArr
arrays.BoolArr(self, name=None, **kwargs)Subclass of Arr with defaults for booleans
Attributes
| Name | Description |
|---|---|
| uids | Alias to Arr.true |
Methods
| Name | Description |
|---|---|
| split | Return UIDs of values that are true and false as separate arrays |
split
arrays.BoolArr.split()Return UIDs of values that are true and false as separate arrays
BoolState
arrays.BoolState(self, name=None, **kwargs)A boolean array being used as a state.
Although functionally identical to BoolArr, a BoolState is handled differently in terms of automation: specifically, results are automatically generated from a BoolState (but not a BoolArr).
BoolStates are typically used to keep track of externally-facing variables (e.g. disease.susceptible), while BoolArrs can be used to keep track of internal ones (e.g. disease.has_immunity). A BoolState named “susceptible” will automatically generate a result named “n_susceptible”, for example.
Note on terminology: the term “states” is often used to refer to all ss.Arr objects, (e.g. in module.define_states(), whether or not they are BoolStates.
FloatArr
arrays.FloatArr(self, name=None, **kwargs)Subclass of ss.Arr with defaults for floats and ints.
Note: Starsim does not support integer arrays by default since they introduce ambiguity in dealing with NaNs, and float arrays are suitable for most purposes.
IndexArr
arrays.IndexArr(self, name=None, label=None)A special class of Arr used for UIDs and RNG IDs; not to be used as an integer array (for that, use FloatArr)
Attributes
| Name | Description |
|---|---|
| uids | Alias to self.values, to allow Arr.uids like BoolArr |
Methods
| Name | Description |
|---|---|
| grow | Change the size of the array |
grow
arrays.IndexArr.grow(new_uids=None, new_vals=None)Change the size of the array
IntArr
arrays.IntArr(self, name=None, **kwargs)Subclass of Arr with defaults for ints.
Note: Because integer arrays do not handle NaN values natively, users are recommended to use ss.FloatArr() in most cases instead.
uids
arrays.uids()Class to specify that integers should be interpreted as UIDs.
For all practical purposes, behaves like a NumPy integer array. However, has additional methods uids.concat() (instance method), ss.uids.cat() (class method), uids.remove(), and uids.intersect() to simplify common UID operations.
Methods
| Name | Description |
|---|---|
| cat | Equivalent to np.concatenate(), but return correct type |
| concat | Equivalent to np.concatenate(), but return correct type |
| intersect | Keep only UIDs that are also present in the other array |
| remove | Remove provided UIDs from current array |
| to_numpy | Return a view as a standard NumPy array |
| union | Return all UIDs present in both arrays |
| unique | Return unique UIDs; equivalent to np.unique() |
| xor | Return UIDs present in only one of the arrays |
cat
arrays.uids.cat(*args, **kw)Equivalent to np.concatenate(), but return correct type
concat
arrays.uids.concat(other, **kw)Equivalent to np.concatenate(), but return correct type
intersect
arrays.uids.intersect(other, **kw)Keep only UIDs that are also present in the other array
remove
arrays.uids.remove(other, **kw)Remove provided UIDs from current array
to_numpy
arrays.uids.to_numpy()Return a view as a standard NumPy array
union
arrays.uids.union(other, **kw)Return all UIDs present in both arrays
unique
arrays.uids.unique(return_index=False)Return unique UIDs; equivalent to np.unique()
xor
arrays.uids.xor(other, **kw)Return UIDs present in only one of the arrays