Model

Note

This module contains classes and functions to structure, save and load mocap data. Be aware that the storage is highly customized to the library. If you want to use the output it is recommended to us functions of xarray to save the needed data.

This module provides classes for structuring, storing and loading trial data.

class gaitalytics.model.BaseTrial

Abstract base class for trials.

This class provides a common interface for trials to load and save data.

to_hdf5(file_path: Path, base_group: str | None = None)

Saves the trial data to an HDF5 file.

Args:

file_path: The path to the HDF5 file. base_group: The base group to save the data. If None, the data will be saved in the root of the file. Default = None

Raises:

FileExistsError: If the file already exists. ValueError: If the trial is a segmented trial and the file path is a single file. ValueError: If the trial is a trial and the file path is a folder.

class gaitalytics.model.DataCategory(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Enum class for the array categories.

This class provides the categories for the data arrays.

Attributes:

MARKERS: The marker’s category. ANALOGS: The analog’s category. ANALYSIS: The analysis category.

class gaitalytics.model.Trial

Represents a trial.

A trial is a collection of data arrays (typically markers & analogs) and events.

add_data(category: DataCategory, data: DataArray)

Adds data to the trial.

Args:

category: The category of the data. data: The data array to be added.

property events: DataFrame | None

Gets the events in the trial.

Returns:

pd.DataFrame: A pandas DataFrame containing the events if present. None: If no events are present.

get_all_data() → dict[DataCategory, DataArray]

Gets all data from the trial.

Returns:

A dictionary containing the data arrays.

get_data(category: DataCategory) → DataArray

Gets the data from the trial.

Args:

category: The category of the data.

Returns:

The data array.

class gaitalytics.model.TrialCycles

Represents a segmented trial.

add_cycle(context: str, cycle_id: int, segment: Trial)

Adds a Cycle to the segmented trial.

Args:

context: The context of the cycle. cycle_id: The id of the cycle. segment: The segment to be added.

get_all_cycles() → dict[str, dict[int, Trial]]

Gets all cycles from the segmented trial.

Returns:

A nexted dictionary containing the cycles. Whereas the key of the first dictionary is the context and the second key is the cycle number.

get_cycle(context: str, cycle_id: int) → Trial

Gets a cycle from the segmented trial.

Args:

context: The context of the cycle. cycle_id: The id of the cycle.

Raises:

KeyError: If the cycle does not exist.

get_cycles_per_context(context: str) → dict[int, Trial]

Gets all cycles from the segmented trial for a specific context.

Args:

context: The context of the cycles.

Returns:

A dictionary containing the cycles for the specified context.

gaitalytics.model.trial_from_hdf5(file_path: Path) → Trial | TrialCycles

Loads trial data from an HDF5 file.

Following structure is expected: Trial:

  • file_path (folder)
    • Left (context)
      • markers

        • xarray.DataArray

      • analogs

        • xarray.DataArray

      • events

        • xarray.Dataset

    • Right (context)

      • …

TrialCycles:

  • file_path (folder)
    • 0.h5 (cycle_id)
      • Left (context)
        • markers

          • xarray.DataArray

        • analogs

          • xarray.DataArray

        • events

          • xarray.Dataset

      • Right (context)

        • …

Args:

file_path: The path to the HDF5 file or folder with the expected structure.

Returns:

Trial: A new instance of the Trial class if file_path is a single file. TrialCycles: A new instance of the TrialCycles class if file_path is a folder.