collection

class InstanceCollection(*, data=None, cfg=None, validate_on_init=True)

Bases: ConfiguredData

The base class to represent an unordered collection of instances, possibly from more than one animal.

Implements the __getitem__ and __setitem__ methods to provide indexing, slicing, and dictionary-like access to the data.

Parameters:

  • data (Mapping[str, ndarray] | None, default: None) – A dictionary containing the data for the collection.

  • cfg (Config | None, default: None) – The configuration object.

  • validate_on_init (bool, default: True) – Whether to validate the data during initialization.

classmethod concatenate(*collections, copy_config=False, validate=True)

Concatenates multiple collections into a single one.

Parameters:

  • collections (Self) – The collections to concatenate.

  • copy_config (bool, default: False) – Whether to copy the configuration of the first collection.

  • validate (bool, default: True) – Whether to validate equality of configurations and concatenated data on the resulting collection.

Return type:

Self

Returns:

The concatenated collection.

Raises:

  • AssertionError – If no collections are provided, or if the configurations of the collections are not equal when validation is enabled.

  • ValueError – If the identity types of the collections are not compatible.

copy(*, copy_config=False)

Copies the collection.

Parameters:

copy_config (bool, default: False) – Whether to copy the configuration.

Return type:

Self

Returns:

the copied collection.

property data: dict[str, ndarray]

Property that returns the underlying data dictionary. The property can be set to update the data if the data passes validation.

init_other(*, data, copy_config=False, validate_on_init=False)

Initializes a new collection from provided data with the same configuration.

Parameters:

  • data (dict[str, ndarray]) – A dictionary containing the data for the new InstanceCollection.

  • copy_config (bool, default: False) – Whether to copy or use the configuration from the current instance.

  • validate_on_init (bool, default: False) – Whether to validate the data during initialization.

Return type:

Self

Returns:

The new collection.

property length: int

Returns the number of instances in the collection.

select(*, timestamp=None, identity=None)

Selects a subset of instances based on timestamp and/or identity.

Parameters:
Return type:

Self

Returns:

The selected collection.

Raises:

ValueError – If timestamp/identity selection is attempted without the corresponding keys defined in the configuration.

select_index(index)

Selects a subset of the data based on the provided index. Allows indexing as in numpy, and will return a view if possible.

Parameters:

index (ndarray) – The indices to select.

Return type:

Self

Returns:

The selected collection.

validate(validate)

Yields a context where data validation is enabled or disabled.

Parameters:

validate (bool) – Whether to enable validation.

Return type:

Generator

validate_data(data, *, allow_duplicated_timestamps=True, allow_missing_keys=False, try_broadcasting=True, require_array_like=False)

Validates the input data against the specified requirements.

Parameters:

  • data (Mapping[str, ndarray | int | float | str | integer | floating]) – The data to validate.

  • allow_duplicated_timestamps (bool, default: True) – Whether to allow duplicated timestamps.

  • allow_missing_keys (bool, default: False) – Whether to allow missing keys.

  • try_broadcasting (bool, default: True) – Whether to try broadcasting.

  • require_array_like (default: False) – Whether to require array-like values.

Returns:

If the data passed validation.

Return type:

bool

Raises:

ValueError – If the data fails any of the validation checks, such as key mismatches, length mismatches, or invalid timestamp or identity data types.