API reference

Kinematic Center of Mass

class center_of_mass.Kinematics(Position, Labels, sex)

A class representing the kinematics

Attributes:

sexstr: sex of the person whose kinematics were recorded, either ‘male’ or ‘female’
Labelslist: list of the marker names whose trajectories were recorded
Position(dict of str(3, NbOfSamples) numpy.ndarray): Dictionary of ‘marker name’: 3D trajectory of the marker
Joint_centers(dict of str(3, NbOfSamples) numpy.ndarray): Dictionary of ‘joint name’: 3D trajectory of the joint’s center
SegmentCoordinateSystem(dict of str(3, 3, NbOfSamples) numpy.ndarray): Dictionary of ‘segment name’: numpy.array([x_segment, y_segment, z_segment]), where x_segment, y_segment and z_segment are the 3D trajectories of the segment coordinate system’s antero-posterior (forwards), longitudinal (upwards) and lateral (rightwards) axes.
SegmentLength(dict of str: float): Dictionary of ‘segment name’: length of the segment
SegmentOrigin(dict of str(3, NbOfSamples) numpy.ndarray): Dictionary of ‘segment name’: 3D trajectory of the segment’s origin

Methods

`calculate_CoM`()	calculates the whole body Center of Mass
`calculate_Head`(Labels)	calculates the coordinate system, length and origin of the head
`calculate_LowerLimbs`(Labels)	calculates the coordinate systems, lengths and origins and joint centers of the lower limb segments: shank, thigh and foot of the left and right sides
`calculate_Pelvis`(Labels)	calculates the coordinate system, length and origin of the pelvis segment, and the lumbar, right hip and left hip joint centers
`calculate_Trunk`(Labels)	calculates the coordinate system, length and origin of the trunk segments (either the Torso, or the Abdomen and Thorax, depending on the markers available), and the cervical, right shoulder and left shoulder centers
`calculate_UpperLimbs`(Labels)	calculates the coordinate systems, lengths and origins and joint centers of the upper limb segments: upper arm, lower arm and hand of the left and right sides
`calculate_segment_CoM`(segment)	calculates the mass and trajectory of the Center of Mass of the segment

calculate_CoM()

calculates the whole body Center of Mass

Returns:

(3, NbOfSamples) numpy.ndarray: 3D trajectory of the whole body Center of Mass

calculate_Head(Labels)

calculates the coordinate system, length and origin of the head

Parameters:

Labelslist: The list of markers used for calculating the head.

calculate_LowerLimbs(Labels)

calculates the coordinate systems, lengths and origins and joint centers of the lower limb segments: shank, thigh and foot of the left and right sides

Parameters:

Labelslist: The list of markers used for calculating the lower limbs (must include ‘LFLE’,’LLMAL’,’RFLE’ and ‘RLMAL’)

calculate_Pelvis(Labels)

calculates the coordinate system, length and origin of the pelvis segment, and the lumbar, right hip and left hip joint centers

Parameters:

Labelslist: The list of markers used for calculating the pelvis (must include ‘LASI’,’RASI’ and either ‘PSI’ or ‘LPSI’ and ‘RPSI’).

calculate_Trunk(Labels)

calculates the coordinate system, length and origin of the trunk segments (either the Torso, or the Abdomen and Thorax, depending on the markers available), and the cervical, right shoulder and left shoulder centers

Parameters:

Labelslist: The list of markers used for calculating the trunk.

calculate_UpperLimbs(Labels)

calculates the coordinate systems, lengths and origins and joint centers of the upper limb segments: upper arm, lower arm and hand of the left and right sides

Parameters:

Labelslist: The list of markers used for calculating the upper limbs (must include ‘LELL’,’LWRU’,’RELL’ and’RWRU’)

calculate_segment_CoM(segment)

calculates the mass and trajectory of the Center of Mass of the segment

Parameters:

segment: str: name of the segment

Returns:

segment_mass: float: fraction of the body mass attributed to the segment
segment_com: (3, NbOfSamples) numpy.ndarray: 3D trajectory of the segment Center of Mass

Center of Mass estimator

center_of_mass.estimator.com_acceleration(GroundReactionForce, mass, gravity_direction=array([0, 0, -1]))

Calculates the CoM acceleration from the Ground reaction force and mass

Parameters:

GroundReactionForce: (NbOfDimensions,NbOfSamples) numpy.ndarray: Ground reaction force (in Newton)
mass: float: subject’s mass (in kg)
gravity_direction: (NbOfDimensions) numpy.ndarray, optional: direction of the gravity vector used to subtract the subject’s weight, default is numpy.array([0,0,-1])

Returns:

Acceleration: (NbOfDimensions,NbOfSamples) numpy.ndarray: Acceleration of the Center of Mass (in m/s^2)

center_of_mass.estimator.estimator(Acc_measurement, Pos_measurement, l1, l2, T, Initial_conditions)

Estimation of the position and velocity, given (noisy) measurements of position and acceleration, estimator gains, and initial conditions

Parameters:

Acc_measurement: (NbOfSamples,) numpy.ndarray: Acceleration measurement (in m/s^2)
Pos_measurement: (NbOfSamples,) numpy.ndarray: Position measurement (in m)
l1: float or (NbOfDimensions,) numpy.ndarray: Position estimator gain (dimensionless)
l2: float or (NbOfDimensions,) numpy.ndarray: Velocity estimator gain (dimensionless)
T: float: duration (in seconds) between successive samples (i.e. 1/Sampling_frequency)
Initial_conditions: (2,) numpy.ndarray: initial estimates of position (in m) and velocity (in m/s)

Returns:

Pos_estimate: (NbOfSamples,) numpy.ndarray: Position estimate (in m)
Vel_estimate: (NbOfSamples,) numpy.ndarray: Velocity estimate (in m/s)

center_of_mass.estimator.estimator_backandforth(Acc_measurement, Pos_measurement, l1, l2, Frequency, Initial_conditions=None, Final_conditions=None, initial_samples=10)

The estimator is applied, for each dimension separately, both forwards and backwards in time, and the forwards and backwards estimates are then merged.

Parameters:

Acc_measurement: (NbOfDimensions, NbOfSamples) numpy.ndarray: Acceleration measurement (in m/s^2)
Pos_measurement: (NbOfDimensions, NbOfSamples) numpy.ndarray: Position measurement (in m)
l1: float or (NbOfDimensions,) numpy.ndarray: Position estimator gain (dimensionless)
l2: float or (NbOfDimensions,) numpy.ndarray: Velocity estimator gain (dimensionless)
Frequency: float: Sampling frequency (in Hertz)
Initial_conditions: (NbOfDimensions,2) numpy.ndarray, optional: Initial estimates of position (in m) and velocity (in m/s), used when the estimator is applied forwards in time (default is None). If None, the initial conditions are determined by a least-squares fit on the first few samples.
Final_conditions: (NbOfDimensions,2) numpy.ndarray, optional: Final estimates of position (in m) and velocity (in m/s), used when the estimator is applied backwards in time (default is None). If None, the final conditions are determined by a least-squares fit on the first few samples.
initial_samples: int, optional: Number of samples used to estimate initial and final position and velocity (default is 10)

Returns:

Pos_estimate: (NbOfDimensions, NbOfSamples) numpy.ndarray: Position estimate (in m)
Vel_estimate: (NbOfDimensions, NbOfSamples) numpy.ndarray: Velocity estimate (in m/s)

center_of_mass.estimator.estimator_gains(Force_std, Position_std, Frequency, mass)

Calculates the optimal estimator gains according to the measurement errors and sampling frequency

Parameters:

Force_std: float or (NbOfDimensions,) numpy.ndarray: Standard deviation of the error in Ground reaction force (in N) (can be provided for each dimension independently)
Position_std: float or (NbOfDimensions,) numpy.ndarray: Standard deviation of the error in CoM position obtained from the kinematics (in m) (can be provided for each dimension independently)
Frequency: int: Sampling frequency of the (sub-sampled) CoM position and acceleration
mass: float: Mass of the subject (in kg)

Returns:

l1: float or (NbOfDimensions,) numpy.ndarray: Optimal estimator gain for position (dimensionless)
l2: float or (NbOfDimensions,) numpy.ndarray: Optimal estimator gain for velocity (dimensionless)

center_of_mass.estimator.initial_conditions(Pos_measurement, T, initial_samples=10)

The initial estimates of position and velocity are obtained as a least-squares fit on the first few samples of the position measurement.

Parameters:

Pos_measurement: (NbOfSamples,) numpy.ndarray: Position measurement (in m)
T: float: duration (in seconds) between successive samples (i.e. 1/Sampling_frequency)
initial_samples: int, optional: Number of samples used to estimate initial position and velocity (default is 10)

Returns:

pos_initial: float: Initial position estimate (in m)
vel_initial: float: Initial velocity estimate (in m/s)

center_of_mass.estimator.optimal_combination(GroundReactionForce, Force_frequency, Kinematic_com, Kinematic_frequency, mass, Force_std=2, Position_std=0.002, gravity_direction=array([0, 0, -1]), sub_frequency=None, Initial_conditions=None, Final_conditions=None, initial_samples=10)

Combines the Center of Mass position obtained from kinematic measurements with Ground reaction force to estimate the Center of Mass position and velocity

Parameters:

GroundReactionForce: (NbOfDimensions,NbOfSamples1) numpy.ndarray: Ground reaction force (in Newton)
Force_frequency: int: Sampling frequency (in Hertz) of the Ground reaction force
Kinematic_com: (NbOfDimensions,NbOfSamples2) numpy.ndarray: Center of Mass position obtained from kinematic measurements (in m)
Kinematic_frequency: int: Sampling frequency (in Hertz) of the kinematics
mass: float: subject’s mass (in kg)
Force_std: float or (NbOfDimensions,) numpy.ndarray, optional: Standard deviation of the error in Ground reaction force (in N) (can be provided for each dimension independently), default is 2 N
Position_std: float or (NbOfDimensions,) numpy.ndarray, optional: Standard deviation of the error in CoM position obtained from the kinematics (in m) (can be provided for each dimension independently), default is 0.002 m
gravity_direction: (NbOfDimensions) numpy.ndarray, optional: direction of the gravity vector used to subtract the subject’s weight, default is numpy.array([0,0,-1])
sub_frequency: int, optional: Desired sub-sampling frequency (in Hertz), default is None
Initial_conditions: (NbOfDimensions,2) numpy.ndarray, optional: Initial estimates of position (in m) and velocity (in m/s), used when the estimator is applied forwards in time (default is None). If None, the initial conditions are determined by a least-squares fit on the first few samples.
Final_conditions: (NbOfDimensions,2) numpy.ndarray, optional: Final estimates of position (in m) and velocity (in m/s), used when the estimator is applied backwards in time (default is None). If None, the final conditions are determined by a least-squares fit on the first few samples.
initial_samples: int, optional: Number of samples used to estimate initial and final position and velocity (default is 10)

Returns:

Pos_estimate: (NbOfDimensions, NbOfSamples) numpy.ndarray: Position estimate (in m)
Vel_estimate: (NbOfDimensions, NbOfSamples) numpy.ndarray: Velocity estimate (in m/s)
Frequency: int: Sampling frequency of the position and velocity estimates

center_of_mass.estimator.subsample_one_signal(signal, signal_frequency, sub_frequency)

Subsample a signal at a given Frequency

Parameters:

signal: (NbOfDimensions, NbOfSamples) numpy.ndarray: Signal to subsample
signal_frequency: int: Sampling frequency (in Hertz) of the signal
sub_frequency: int: Desired sub-sampling frequency (in Hertz)

Returns:

signal_subsampled: (NbOfDimensions, NbOfSamples_sub) numpy.ndarray: Subsampled signal

center_of_mass.estimator.subsample_two_signals(signal1, frequency1, signal2, frequency2, sub_frequency=None)

Subsample two signals at a common frequency

Parameters:

signal1: (NbOfDimensions,NbOfSamples1) numpy.ndarray: First signal
frequency1: int: Sampling frequency (in Hertz) of the first signal
signal2: (NbOfDimensions,NbOfSamples2) numpy.ndarray: Second signal
frequency2: int: Sampling frequency (in Hertz) of the second signal
sub_frequency: int, optional: Desired sub-sampling frequency (in Hertz), default is None

Returns:

signal1_subsampled: (NbOfDimensions,NbOfSamples_sub) numpy.ndarray: Subsampled first signal
signal2_subsampled: (NbOfDimensions,NbOfSamples_sub) numpy.ndarray: Subsampled second signal
sub_frequency: int: Subsampling frequency (in Hertz) If the sub-sampling frequency was not specified by the user, this is the greatest common divisor of frequency1 and frequency2