gaitmap.trajectory_reconstruction.RegionLevelTrajectory#

class gaitmap.trajectory_reconstruction.RegionLevelTrajectory(*, ori_method: BaseOrientationMethod | None = cf(SimpleGyroIntegration(initial_orientation=array([0., 0., 0., 1.]), memory=None)), pos_method: BasePositionMethod | None = cf(ForwardBackwardIntegration(gravity=array([0., 0., 9.81]), level_assumption=True, steepness=0.08, turning_point=0.5)), trajectory_method: BaseTrajectoryMethod | None = None, align_window_width: int = 8)[source]#

Estimate the trajectory over the duration of an entire gait sequence or region of interest.

This class will take any of the implemented orientation, position, and trajectory methods and apply them to all regions of interest or gait sequences provided. Note that this class assumes that each gait sequence starts with a static resting period and certain methods might require the integration regions to end in a static region as well. Check the documentation of the individual methods for details.

Note, that by default this wrapper uses simple integration methods. These will not provide the best results under most scenarios, but as they do not have any tunable parameters, it is a good start. However, it is advisable to chose a more suffisticated method and tune the parameter to your specific usecase.

Parameters:

ori_method: An instance of any available orientation method with the desired parameters set. This method is called with the data of each region to actually calculate the orientation. Note, the the initial_orientation parameter of this method will be overwritten, as this class estimates new per-roi initial orientations.
pos_method: An instance of any available position method with the desired parameters set. This method is called with the data of each region to actually calculate the position. The provided data is already transformed into the global frame using the orientations calculated by the ori_method on the same stride.
trajectory_method: Instead of providing a separate ori_method and pos_method, a single trajectory_method can be provided that calculates the orientation and the position in one go. This method is called with the data of each region. If a trajectory_method is provided the values for ori_method and pos_method are ignored. Note, the initial_orientation parameter of this method will be overwritten, as this class estimates new per-roi initial orientations.
align_window_width: This is the width of the window that will be used to align the beginning of the signal of each region with gravity. To do so, half the window size before and half the window size after the start of the region will be used to obtain the median value of acceleration data in this phase. Note, that +-np.floor(align_window_size/2) around the start sample will be used for this. For the first region, start of the stride might coincide with the start of the signal. In that case the start of the window would result in a negative index, thus the window to get the initial orientation will be reduced (from 0 to start+np.floor(align_window_size/2))

Other Parameters:

data: The data passed to the estimate or estimate_intersect method.
regions_of_interest: The list of regions passed to the estimate or estimate_intersect method.
stride_event_list: The list of strides passed to the estimate_intersect
sampling_rate_hz: The sampling rate of the data.

Attributes:

orientation_: Output of the selected orientation method applied per region. The first orientation is obtained by aligning the acceleration data at the start of each region with gravity. This contains len(data) + 1 orientations for each region, as the initial orientation is included in the output. In case estimate_intersect is used, this will not be per region, but per stride. Note, that the initial values are not reset per stride.
position_: Output of the selected position method applied per region. The initial value of each region is assumed to be [0, 0, 0]. This contains len(data) + 1 values for each region, as the initial position is included in the output. In case estimate_intersect is used, this will not be per region, but per stride. Note, that the initial values are not reset per stride.
velocity_: The velocity as provided by the selected position method applied per region. The initial value of the velocity is assumed to be [0, 0, 0]. This contains len(data) + 1 values for each region, as the initial velocity is included in the output. In case estimate_intersect is used, this will not be per region, but per stride. Note, that the initial values are not reset per stride.

See also

gaitmap.trajectory_reconstruction: Implemented algorithms for orientation and position estimation

Examples

You can pick any orientation, position, or trajectory estimation method that is implemented for this wrapper. However, simple integrations might lead to significant drift if the integration regions are longer.

>>> from gaitmap.trajectory_reconstruction import RtsKalman
>>> # Create custom instances of the methods you want to use
>>> trajectory_method = RtsKalman()
>>> # Create an instance of the wrapper
>>> per_region_traj = RegionLevelTrajectory(trajectory_method=trajectory_method)
>>> # Apply the method
>>> data = ...
>>> sampling_rate_hz = 204.8
>>> roi_list = ...
>>> per_region_traj = per_region_traj.estimate(
...     data, regions_of_interest=roi_list, sampling_rate_hz=sampling_rate_hz
... )
>>> per_region_traj.position_
<Dataframe or dict with all the positions per region>
>>> per_region_traj.orientation_
<Dataframe or dict with all the orientations per region>

If you want to have the trajectory per stride but still use integration methods that could benefit from performing the integration on entire regions, you can use estimate_intersect to cut out the per-stride trajectories.

>>> from gaitmap.trajectory_reconstruction import SimpleGyroIntegration
>>> from gaitmap.trajectory_reconstruction import ForwardBackwardIntegration
>>> # Create custom instances of the methods you want to use
>>> trajectory_method = RtsKalman()
>>> # Create an instance of the wrapper
>>> per_region_traj = RegionLevelTrajectory(trajectory_method=trajectory_method)
>>> # Apply the method
>>> data = ...
>>> sampling_rate_hz = 204.8
>>> roi_list = ...
>>> stride_list = ...
>>> per_region_traj = per_region_traj.estimate_intersect(
...     data, regions_of_interest=roi_list, stride_event_list=stride_list, sampling_rate_hz=sampling_rate_hz
... )
>>> per_region_traj.position_
<Dataframe or dict with all the positions per stride>
>>> per_region_traj.orientation_
<Dataframe or dict with all the orientations per stride>

Methods

`clone`()	Create a new instance of the class with all parameters copied over.
`estimate`(data, regions_of_interest, *[, ...])	Use the initial rotation and the gyroscope signal to estimate the orientation to every time point .
`estimate_intersect`(data, ...)	Estimate the trajectory for all regions and then cut out the trajectory of individual strides.
`from_json`(json_str)	Import an gaitmap object from its json representation.
`get_params`([deep])	Get parameters for this algorithm.
`intersect`(stride_event_list[, return_data])	Cut out the trajectory of individual strides from the region trajectories.
`set_params`(**params)	Set the parameters of this Algorithm.
`to_json`()	Export the current object parameters as json.

__init__(*, ori_method: BaseOrientationMethod | None = cf(SimpleGyroIntegration(initial_orientation=array([0., 0., 0., 1.]), memory=None)), pos_method: BasePositionMethod | None = cf(ForwardBackwardIntegration(gravity=array([0., 0., 9.81]), level_assumption=True, steepness=0.08, turning_point=0.5)), trajectory_method: BaseTrajectoryMethod | None = None, align_window_width: int = 8) → None[source]#

clone() → Self[source]#

Create a new instance of the class with all parameters copied over.

This will create a new instance of the class itself and all nested objects

estimate(data: DataFrame | dict[Union[collections.abc.Hashable, str], pandas.core.frame.DataFrame], regions_of_interest: DataFrame | dict[Union[collections.abc.Hashable, str], pandas.core.frame.DataFrame], *, stride_event_list: DataFrame | dict[Union[collections.abc.Hashable, str], pandas.core.frame.DataFrame] | None = None, sampling_rate_hz: float) → Self[source]#

Use the initial rotation and the gyroscope signal to estimate the orientation to every time point .

Parameters:

data: At least must contain 3D-gyroscope and 3D-accelerometer data.
regions_of_interest: List of regions for one or multiple sensors. For each region, the orientation and position will be calculated separately.
stride_event_list: An optional stride event list that will be forwarded to the traj/ori/pos methods. The stride event list will be intersected with the region of interest list and the respective pieces will be provided to the detect method of the underlying methods.
sampling_rate_hz: Sampling rate with which IMU data was recorded.

estimate_intersect(data: DataFrame | dict[Union[collections.abc.Hashable, str], pandas.core.frame.DataFrame], regions_of_interest: DataFrame | dict[Union[collections.abc.Hashable, str], pandas.core.frame.DataFrame], *, stride_event_list: DataFrame | dict[Union[collections.abc.Hashable, str], pandas.core.frame.DataFrame], sampling_rate_hz: float) → Self[source]#

Estimate the trajectory for all regions and then cut out the trajectory of individual strides.

This basically calls estimate and then intersect and stores the results in the object. This means that the results (position_, …) will be on stride level and not on region level. Calculated values outside of strides will simply be dropped.

See the Notes sections for some caveats.

Parameters:

data: At least must contain 3D-gyroscope and 3D-accelerometer data.
regions_of_interest: List of regions for one or multiple sensors. For each region, the orientation and position will be calculated separately.
stride_event_list: List of strides within the provided regions. The trajectories of these strides will be cut out of the trajectories calculated for the respective region.
sampling_rate_hz: Sampling rate with which IMU data was recorded.

Notes

Make sure you follow the these tips to avoid errors:

The stride list must have information for all the sensors that are also in the roi list
The method cuts out the sample before the start of each stride as initial value (in case stride starts at start of region, this will be the estimated initial value). This makes the output structure equivalent to StrideLevelTrajectory, however, the initial values are not reset per stride. This means, that for example the position of each stride will not start at [0, 0, 0]
If you provide ROI lists that have overlaps (THIS SHOULD BE AVOIDED!) the stride trajectory from the last ROI is used.
Strides are considered to be part of an ROI, if they are fully contained (start >= roi_start, end <= roi_end).
Strides that have only partial or now overlap with a ROI are omitted from the output.

classmethod from_json(json_str: str) → Self[source]#

Import an gaitmap object from its json representation.

For details have a look at the this example.

You can use the to_json method of a class to export it as a compatible json string.

Parameters:

json_str: json formatted string

get_params(deep: bool = True) → dict[str, Any][source]#

Get parameters for this algorithm.

Parameters:

deep: Only relevant if object contains nested algorithm objects. If this is the case and deep is True, the params of these nested objects are included in the output using a prefix like nested_object_name__ (Note the two “_” at the end)

Returns:

params: Parameter names mapped to their values.

intersect(stride_event_list: DataFrame | dict[Union[collections.abc.Hashable, str], pandas.core.frame.DataFrame], return_data: tuple[typing_extensions.Literal['orientation', 'position', 'velocity'], ...] = ('orientation', 'position', 'velocity')) → tuple[Union[pandas.core.frame.DataFrame, dict[Union[collections.abc.Hashable, str], pandas.core.frame.DataFrame]], ...][source]#

Cut out the trajectory of individual strides from the region trajectories.

This method can only be used after estimate was called. Calling estimate_intersect before, does not work!

For more information about how the intersect works, see estimate_intersect.

Parameters:

stride_event_list: List of strides within the provided regions. The trajectories of these strides will be cut out of the trajectories calculated for the respective region.
return_data: Which results should be returned per stride

Returns:

result_tuple: A tuple with the outputs, following the order provided in return_data.

set_params(**params: Any) → Self[source]#

Set the parameters of this Algorithm.

To set parameters of nested objects use nested_object_name__para_name=.

to_json() → str[source]#

Export the current object parameters as json.

For details have a look at the this example.

You can use the from_json method of any gaitmap algorithm to load the object again.

Warning

This will only export the Parameters of the instance, but not any results!

Examples using `gaitmap.trajectory_reconstruction.RegionLevelTrajectory`#

Region Level Trajectory reconstruction

gaitmap.trajectory_reconstruction.RegionLevelTrajectory#

Examples using gaitmap.trajectory_reconstruction.RegionLevelTrajectory#

Examples using `gaitmap.trajectory_reconstruction.RegionLevelTrajectory`#