io

from_cache(cache_file, *, file_type='pickle', indices=None)

Helper function to read an object from a cache file using pickle.

Parameters:

  • cache_file (str | Path) – The path to the cache file.

  • file_type (Literal['pickle', 'h5'] | None)

  • indices (ndarray | None)

Return type:

Any

Returns:

The object read from the cache file.

Raises:

FileNotFoundError – If the cache file does not exist.

from_yaml(file_name)

Helper function to read an object from a YAML file.

Note that all lists are loaded as tuples.

Parameters:

file_name (str | Path) – The name of the file to read the YAML from.

Return type:

Any

load_data(data_file, data_path=None, exclude=None)

Loads data (ndarray or nested dict of ndarray) from an HDF5 file.

Parameters:

  • data_file (str | Path) – The name of the HDF5 file to load data from.

  • data_path (str | None, default: None) – The path to the data within the HDF5 file.

  • exclude (list[str] | None, default: None) – A list of keys to exclude from the loaded data.

Return type:

dict[str, ndarray] | ndarray | dict[str, dict[str, ndarray] | ndarray | dict[str, Data]]

Returns:

The loaded data.

load_dataset(dataset_name, *, directory='.', target, load_observations=True, categories=None, background_category, observation_suffix='annotations')

Load a dataset from a HDF5 file that was created with save_dataset().

Parameters:

  • dataset_name (str) – Name of the dataset.

  • directory (str | Path, default: '.') – Directory to load the dataset from.

  • target (Literal['individual', 'dyad']) – Target of the dataset.

  • load_observations (bool, default: True) – Whether to load observations.

  • categories (tuple[str, ...] | None, default: None) – Categories (of the observations) to load.

  • background_category (str) – Background category (of the observations).

  • observation_suffix (str, default: 'annotations') – Suffix for the observation file.

Return type:

AnnotatedDataset | Dataset

Returns:

The loaded dataset.

load_trajectories(trajectory_file, data_path=None, exclude=None)

Load trajectories from an HDF5 file that was created with save_trajectories().

Parameters:

  • trajectory_file (str | Path) – The path to the HDF5 file containing the trajectories.

  • data_path (str | None, default: None) – An optional path within the HDF5 file to the trajectories.

  • exclude (list[str] | None, default: None) – An optional list of keys to exclude from loading.

Return type:

dict[str | int, Trajectory]

Returns:

A dictionary mapping individual identifiers to trajectories.

remove_cache(cache_file)

Helper function to remove a cache file.

Returns whether the file was successfully removed (False if the file does not exist).

Parameters:

cache_file (str | Path) – The path to the cache file.

Return type:

bool

Returns:

Whether the file was successfully removed.

save_data(data_file, data, data_path=None, exclude=None)

Saves data (mapping of str and ndarray) to an HDF5 file.

Parameters:

  • data_file (str | Path) – The name of the HDF5 file to save data to.

  • data (Mapping[str, ndarray]) – The data to save.

  • data_path (str | None, default: None) – The path to the data within the HDF5 file.

  • exclude (list[str] | None, default: None) – A list of keys to exclude from the saved data.

Return type:

None

Returns:

None

save_dataset(dataset, *, dataset_name, directory='.', observation_suffix='annotations')

Save a dataset to a HDF5 file.

Parameters:

  • dataset (Dataset) – Dataset to save.

  • dataset_name (str) – Name of the dataset.

  • directory (str | Path, default: '.') – Directory to save the dataset to.

  • observation_suffix (Literal['annotations', 'predictions'], default: 'annotations') – Suffix for the observation file.

Return type:

None

Returns:

None

save_trajectories(trajectory_file, trajectories, prefix=None, exclude=None)

Save trajectories to an HDF5 file.

Parameters:

  • trajectory_file (str | Path) – The name of the HDF5 file to save trajectories to.

  • trajectories (dict[int | str, Trajectory]) – A dictionary mapping individual identifiers to trajectories.

  • prefix (str | None, default: None) – An optional prefix to prepend to the trajectory paths.

  • exclude (list[str] | None, default: None) – An optional list of keys to exclude from saving.

Return type:

None

Returns:

None

to_cache(obj, cache_file=None, directory=None, *, file_type='pickle')

Helper function to write an object to a cache file using pickle.

Parameters:

  • obj (Any) – The object to write.

  • cache_file (str | Path | None, default: None) – The basename of the cache file.

  • directory (str | Path | None, default: None) – The directory to write the cache file to. If None, the current directory is used.

  • file_type (Literal['pickle', 'h5'] | None)

Return type:

str

Returns:

The path to the cache file.

to_yaml(dump, *, file_name)

Helper function to write an object to a YAML file.

Parameters:

  • dump (Any) – The object to be dumped.

  • file_name (str | Path) – The name of the file to write the YAML to.

Return type:

None