gaitanalysis Package

The following documentation provides both the pubic and private API for the modules included in the gaitanalysis package. We will try our best to follow semantic versioning with respect to the public API. The private member functions, starts with _, are subject to change during development and will not be held to semantic versioning. Use at your own risk.

motek Module

class gaitanalysis.motek.DFlowData(mocap_tsv_path=None, record_tsv_path=None, meta_yml_path=None)

Bases: object

A class to store and manipulate the data outputs from Motek Medical’s D-Flow software.

_analog_column_labels(labels)

Returns a list of analog channel column labels and the indices of the labels.

Parameters:

labels : list of strings

This should be a superset of column labels, some of which may be human body model results, and should include the default analog channel labels output from the D-Flow mocap model, i.e. “Channel[1-99].Anlg”.

Returns:

analog_labels : list of strings

The labels of analog channels in the order found in labels.

analog_indices : list of integers

The indices of the analog columns with respect to the indices of labels.

emg_column_labels : list of strings

The labels of emg channels in the order found in labels

accel_column_labels : list of strings

The labels of accelerometer channels in the order found in labels

_c = 'Z'
_calibrate_accel_data(data_frame, y1=0, y2=-9.81)

Two-point calibration of accelerometer signals. Converts from voltage to meters/second^2

Parameters:

data_frame : pandas.DataFrame

Accelerometer data in volts to be calibrated

y1 : float, optional

y2 : float, optional

Returns:

data_frame : pandas.DataFrame

Calibrated accelerometer data in m/s^2

Notes

A calibration file must be specified in the meta file and its structure is as follows: There must be a column for each accelerometer signal to be calibrated, so three columns per sensor. There must be three rows of accelerometer readings. The first row is the reading when the sensors are placed with z-axis pointing straight up. The second row is the reading when the x-axis is pointing straight up. The third row is the reading when the y-axis is pointing straight up. (xyz) —– (001) (100) (010)

_clean_compensation_data(data_frame)

Returns a the data frame with Delsys signals shifted and all signals low pass filtered.

Parameters:

data_frame : pandas.DataFrame

This data frame should contain only the columns needed for the compensation calculations: accelerometers and forces/moments.

Returns:

data_frame : pandas.DataFrame

The cleaned compensation data.

_compensate(mocap_data_frame, markers_missing=False)

Returns the data frame with the forces compensated.

Parameters:

mocap_data_frame : pandas.DataFrame

A data frame that contains the force plate forces and moments to be compensated, along with the measurements of the markers and accelerometers that were attached to the treadmill.

markers_missing : pandas.DataFrame

If the treadmill markers have missing markers, this should be true so that they are fixed before the compensation.

Returns:

mocap

Notes

This method does the following:

  1. Pulls the compensation file path from meta data.

  2. Loads the compensation file (only the necessary columns).

  3. Identifies the missing markers in the compensation file and interpolates to fill them.

  4. Shifts the Delsys signals to correct time.

  5. Filter the forces, accelerometer, and treadmill markers at 6 hz low pass.

  6. Compute the compensated forces (apply inertial compensation and express

    in global reference frame)

  7. Replace the force/moment measurements in the mocap data file with the

    compensated forces/moments.

_compensate_forces(calibration_data_frame, data_frame)

Computes the forces and moments which are due to the lateral and pitching motions of the treadmill and subtracts them from the measured forces and moments based on linear acceleration measurements of the treadmill.

_compensation_needed()

Returns true if the meta data includes:

‘trial: stationary-platform: False’

_end = 'Z'
_express(data_frame, rotation_matrix)

Returns a new data frame in which the marker, force, moment, and center of pressure vectors are expressed in a different reference frame using the provided rotation matrix.

Parameters:

data_frame : pandas.DataFrame

A data frame which contains columns for the DFlow marker, force, moment, and center of pressure outputs.

rotation_matrix : array_like, shape(3, 3)

A rotation matrix which will be premultiplied to all vectors in the provided data frame.

Returns:

rotated_data_frame : pandas.DataFrame

A copy of the provided data frame in which all vectors are expressed in a new reference frame.

Notes

If v_df is a vector expressed in data frame’s original coordinate system and v_new is the same vector expressed in the desired coordinate system, then:

v_new = rotation_matrix * v_df

This function does nothing with the segment columns. As it stands it is not clear what the .Rot[XYZ] columns are so all segment columns are left alone.

This function also does not currently deal with any human body model columns, e.g. the center of mass.

_express_in_isb_standard_coordinates(data_frame)

Returns a new data frame in which the marker, force, moment, and center of pressure vectors are expressed in the the ISB standard coordinate system given in [Wu1995]. This referene frame has the X axis aligned in the directin of travel, the Y axis vertical and opposite of gravity, and the Z axis to the right, following the right hand rule.

Parameters:

data_frame : pandas.DataFrame

A data frame which contains columns for the DFlow marker, force, moment, and center of pressure outputs. The coordinate system for the vectors must be the Cortex default system (X to the right, Y up, Z backwards).

Returns:

rotated_data_frame : pandas.DataFrame

A copy of the provided data frame in which all vectors are expressed in the ISB standard coordinate system.

Notes

See DflowData._express for more details.

References

[Wu1995](1, 2) Wu G. and Cavanagh, P. R., 1995, “ISB recommendations for standardization in the reporting of kinematic data”, J. Biomechanics, Vol 28, No 10.
_extract_events_from_record_file()

Returns a dictionary of events and times. The event names will be the default A-F which is output by D-Flow unless you specify unique names in the meta data file. If there are no events in the record file, this will return nothing.

_force_column_labels(without_center_of_pressure=False)

Returns a list of force column labels.

Parameters:

without_center_of_pressure: boolean, optional, default=False

If true, the center of pressure labels will not be included in the list.

Returns:

labels : list of strings

A list of the force plate related signals.

_generate_cortex_time_stamp(data_frame)

Returns the data frame with a new index based on the constant sample rate from Cortex.

_hbm_column_labels(labels)

Returns a list of human body model column labels, the indices of the labels, and the indices of the non-hbm labels in relation to the rest of the header.

Parameters:

labels : list of strings

This should be a superset of column labels, some of which may be human body model results.

Returns:

hbm_labels : list of strings

The labels of columns of HBM data time series in the order found in labels.

hbm_indices : list of integers

The indices of the HBM columns with respect to the indices of labels.

non_hbm_indices : list of integers

The indices of the non-HBM columns with respect to the indices of labels.

static _header_labels(path_to_file, delimiter='t')

Returns a list of labels from the header, i.e. the first line of a delimited text file.

Parameters:

path_to_file : string

Path to the delimited text file with a header on the first line.

delimiter : string, optional, default=’ ‘

The delimiter used in the file.

Returns:

header_labels : list of strings

A list of the headers in order as included from the file.

_identify_missing_markers(data_frame)

Returns the data frame in which all marker columns have had constant marker values replaced with NaN.

Parameters:

data_frame : pandas.DataFrame, size(n, m)

A data frame which contains columns of marker position time histories. The marker time histories may contain periods of constant values.

Returns:

data_frame : pandas.DataFrame, size(n, m)

The same data frame which was supplied expect that constant values in the marker columns have been replaced with NaN.

Notes

D-Flow replaces missing marker values with the last available measurement in time. This method is used to properly replace them with a unique idnetifier, NaN. If two adjacent measurements in time were actually the same value, then this method will replace the subsequent ones with NaNs, and is not correct, but the likelihood of this happening is low.

_load_compensation_data()

Returns a data frame which includes the treadmill forces/moments, and the accelerometer signals as time series with respect to the D-Flow time stamp.

_load_mocap_data(ignore_hbm=False, id_na=False)

Returns a data frame generated from the mocap TSV file.

Parameters:

ignore_hbm : boolean, optional, default=False

If true, the columns associated with D-Flow’s real time human body model computations will not be loaded.

id_na : boolean, optional, default=False

If true the marker and/or HBM columns will be loaded with all ‘0.000000’ and ‘-0.000000’ strings in the HBM columns replaced with numpy.NaN. This is dependent on the D-Flow version as, versions <= 3.16.1 stored missing markers as the previous valid value.

Returns:

data_frame : pandas.DataFrame

_load_record_data()

Returns a data frame containing the data from the record module.

_marker_column_labels(labels)

Returns a list of column labels that correpsond to markers, i.e. ones that end in ‘.PosX’, ‘.PosY’, or ‘.PosZ’, given a master list.

Parameters:

labels : list of strings

This should be a superset of column labels, some of which may be marker column labels.

Returns:

marker_labels : list of strings

The labels of columns of marker time series in the order found in labels.

_merge_mocap_record()

Returns a data frame that is a merger of the mocap and record data, if needed.

_missing_markers_are_zeros()

Returns True if the mocap module marker missing values are represented as strings of zeros, ‘-0.000000’ and ‘0.000000’ and False if missing markers are represented as the previous valid value. This depends on the D-Flow version being present in the trial meta data. If it isn’t then it is assumed that missing markers are represented as strings of zeros, i.e. latest D-Flow behavior.

_mocap_column_labels()

Returns a list of strings containing the motion capture file’s column labels. The list is in the same order as in the mocap tsv file.

_orient_accelerometers(data_frame)
Parameters:

mocap_data_frame : pandas.DataFrame

DataFrame containing accelerometer signals to be placed in treadmill reference frame.

Returns:

mocap_data_frame : pandas.DataFrame

DataFrame containing accelerometer signals in treadmill reference frame.

_parse_meta_data_file()

Returns a dictionary containing the meta data stored in the optional meta data file.

_relabel_analog_columns(data_frame)

Relabels analog channels in data frame to names defined in the yml meta file. Channels not specified in the meta file are keep their original names. self.analog_column_labels, self.emg_column_labels, and self.accel_column_labels are updated with the new names.

Parameters:

data_frame : pandas.DataFrame, size(n, m)

Returns:

data_frame : pandas.DataFrame, size(n, m

The same data frame with columns relabeled.

_relabel_markers(data_frame)

Returns the data frame with the columns renamed to reflect the provided mapping and updates the marker column and mocap column label attributes to reflect the new names. If there is no marker map in the meta data the data frame is returned unmodified.

Parameters:

data_frame : pandas.DataFrame

A data frame with column names which match the keys in the meta data:trial:marker-map.

_resample_record_data(data_frame)

Resamples the raw data from the record file at the sample rate of the mocap file.

_segment = 'rtoes'
_shift_delsys_signals(data_frame, time_col='TimeStamp')

Returns a data frame in which the Delsys columns are linearly interpolated (and extrapolated) at the time they were actually measured.

_store_compensation_data_path()

Stores the path to the compensation data file.

Notes

The meta data yaml file must include a relative file path to a mocap file that contains time series data appropriate for computing the force inertial and rotational compensations. The yaml declaration should look like this example:

files:
mocap: mocap-378.txt record: record-378.txt meta: meta-378.yml compensation: ../path/to/mocap/file.txt
_suffix = '.RotZ'
_suffix_beg = '.Cop'
analog_channel_regex = '^Channel[0-9]+\\.Anlg$'
c = 'Z'
clean_data(ignore_hbm=False, id_na=True, interpolate=True, interpolation_order=1)

Returns the processed, “cleaned”, data.

Parameters:

ignore_hbm : boolean, optional, default=False

HBM columns will not be loaded from the mocap model data TSV file. This can save some load time if you are not using that data.

id_na : boolean, optional, default=True

Identifies any missing values in the marker and/or HBM data and replaces the with np.NaN.

interpolate : boolean, optional, default=True

If true, the missing values in the markers and/or HBM columns will be interpolated. Note that if force compensation is needed, the markers on the treadmill will always have the missing values interpolated regardless of this flag. This argument is ignored if id_na is False, as there are no identified missing marker values available to interpolate over.

interpolation_order : integer, optional, default=1

The spline interpolation order (between 1 and 5). See scipy.interpolate.InterpolatedUnivariateSpline.

Notes

  1. Loads the mocap and record modules into Pandas DataFrames.

  2. Relabels the columns headers to more meaningful names if this is specified in the meta data.

  3. Shifts the Delsys signals in the mocap module data to accomodate for the wireless time delay. The value of the delay is stored in DflowData.delsys_time_delay.

  4. Identifies the missing values in the mocap marker data and replaces them with numpy.nan.

  5. Optionally, interpolates the missing marker and HBM values and replaces them with interpolated estimates.

  6. Compensates the force measurments for the motion of the treadmill base, if needed.

    1. Pulls the compensation mocap file path from meta data.
    2. Loads the compensation mocap file (only the necessary columns).
    3. Identifies the missing markers and interpolates to fill them.
    4. Shifts the Delsys signals to correct time.
    5. Filter the forces, accelerometer, and treadmill markers with a 6 hz low pass 2nd order Butterworth filter.
    6. Computes the compensated forces by subtracting the inertial forces and expressing the forces in the camera reference frame.
    7. Replaces the force/moment measurements in the mocap data file with the compensated forces/moments.
  1. Merges the data from the mocap module and record module into one data frame.
constant_marker_tolerance = 1e-16
cortex_sample_rate = 100
delsys_time_delay = 0.096
dflow_segments = ['pelvis', 'thorax', 'spine', 'pelvislegs', 'lfemur', 'ltibia', 'lfoot', 'toes', 'rfemur', 'rtibia', 'rfoot', 'rtoes']
extract_processed_data(event=None, index_col=None, isb_coordinates=False)

Returns the processed data in a data frame. If an event name is provided, then a data frame with only that event is returned.

Parameters:

event : string, optional, default=None

A name of a detected event. Must be a valid key in self.events. This will be either the D-Flow auto-named events (A, B, C, D, E, F) or the names specified in the meta data file.

index_col : string, optional, default=None

A name of a column in the data frame. If provided the the column will be removed from the data frame and used as the index. This is useful for assigning one of the time columns as the index.

isb_coordinates : boolean, optional, default=False

If True, the marker, force, moment, and center of pressure vectors will be expressed in the ISB standard coordinate system instead of the Cortex default coordinate system.

Returns:

data_frame : pandas.DataFrame

The processed data.

force_plate_names = ['FP1', 'FP2']
force_plate_regex = '^FP[12]\\.[For|Mom|Cop][XYZ]$'
force_plate_suffix = ['.ForX', '.MomX', '.CopX', '.ForY', '.MomY', '.CopY', '.ForZ', '.MomZ', '.CopZ']
hbm_column_regexes = ['^\\s?[LR]_.*', '.*\\.Mom$', '.*\\.Ang$', '.*\\.Pow$', '.*\\.COM.[XYZ]$']
hbm_na = ['0.000000', '-0.000000']
low_pass_cutoff = 6.0
marker_coordinate_regex = '.*\\.Pos[XYZ]$'
marker_coordinate_suffixes = ['.PosX', '.PosY', '.PosZ']
missing_value_statistics(data_frame)

Returns a report of missing values in the data frame.

rotation_suffixes = ['.RotX', '.RotY', '.RotZ']
segment_labels = ['pelvis.PosX', 'pelvis.PosY', 'pelvis.PosZ', 'pelvis.RotX', 'pelvis.RotY', 'pelvis.RotZ', 'thorax.PosX', 'thorax.PosY', 'thorax.PosZ', 'thorax.RotX', 'thorax.RotY', 'thorax.RotZ', 'spine.PosX', 'spine.PosY', 'spine.PosZ', 'spine.RotX', 'spine.RotY', 'spine.RotZ', 'pelvislegs.PosX', 'pelvislegs.PosY', 'pelvislegs.PosZ', 'pelvislegs.RotX', 'pelvislegs.RotY', 'pelvislegs.RotZ', 'lfemur.PosX', 'lfemur.PosY', 'lfemur.PosZ', 'lfemur.RotX', 'lfemur.RotY', 'lfemur.RotZ', 'ltibia.PosX', 'ltibia.PosY', 'ltibia.PosZ', 'ltibia.RotX', 'ltibia.RotY', 'ltibia.RotZ', 'lfoot.PosX', 'lfoot.PosY', 'lfoot.PosZ', 'lfoot.RotX', 'lfoot.RotY', 'lfoot.RotZ', 'toes.PosX', 'toes.PosY', 'toes.PosZ', 'toes.RotX', 'toes.RotY', 'toes.RotZ', 'rfemur.PosX', 'rfemur.PosY', 'rfemur.PosZ', 'rfemur.RotX', 'rfemur.RotY', 'rfemur.RotZ', 'rtibia.PosX', 'rtibia.PosY', 'rtibia.PosZ', 'rtibia.RotX', 'rtibia.RotY', 'rtibia.RotZ', 'rfoot.PosX', 'rfoot.PosY', 'rfoot.PosZ', 'rfoot.RotX', 'rfoot.RotY', 'rfoot.RotZ', 'rtoes.PosX', 'rtoes.PosY', 'rtoes.PosZ', 'rtoes.RotX', 'rtoes.RotY', 'rtoes.RotZ']
treadmill_markers = ['ROT_REF.PosX', 'ROT_REF.PosY', 'ROT_REF.PosZ', 'ROT_C1.PosX', 'ROT_C1.PosY', 'ROT_C1.PosZ', 'ROT_C2.PosX', 'ROT_C2.PosY', 'ROT_C2.PosZ', 'ROT_C3.PosX', 'ROT_C3.PosY', 'ROT_C3.PosZ', 'ROT_C4.PosX', 'ROT_C4.PosY', 'ROT_C4.PosZ']
write_dflow_tsv(filename, na_rep='NA')
class gaitanalysis.motek.MissingMarkerIdentifier(data_frame)

Bases: object

_c = 'Z'
constant_marker_tolerance = 1e-16
identify(columns=None)

Returns the data frame in which all or the specified columns have had constant values replaced with NaN.

Returns:

data_frame : pandas.DataFrame, size(n, m)

The same data frame which was supplied with constant values replaced with NaN.

columns : list of strings, optional, default=None

The specific list of columns in the data frame that should be analyzed. This is typically a list of all marker columns.

Notes

D-Flow replaces missing marker values with the last available measurement in time. This method is used to properly replace them with a unique identifier, NaN. If two adjacent measurements in time were actually the same value, then this method will replace the subsequent ones with NaNs, and is not correct, but the likelihood of this happening is low.

marker_coordinate_suffixes = ['.PosX', '.PosY', '.PosZ']
statistics()

Returns a data frame containing the number of missing samples and maximum number of consecutive missing samples for each column.

gaitanalysis.motek.low_pass_filter(data_frame, columns, cutoff, sample_rate, **kwargs)

Returns the data frame with indicated columns filtered with a low pass second order forward/backward Butterworth filter.

Parameters:

data_frame : pandas.DataFrame

A data frame with time series columns.

columns : sequence of strings

The columns that should be filtered.

cutoff : float

The low pass cutoff frequency in Hz.

sample_rate : float

The sample rate of the time series in Hz.

kwargs : key value pairs

Any addition keyword arguments to pass to dtk.process.butterworth.

Returns:

data_frame : pandas.DataFrame

The same data frame which was passed in with the specified columns replaced by filtered versions.

gaitanalysis.motek.markers_for_2D_inverse_dynamics(marker_set='lower')

Returns lists of markers from the D-Flow human body model marker protocol(lower or full), that should be used with leg2d.m.

Parameters:

marker_set : string, optional, default=’lower’

Specify either ‘lower’ or ‘full’ depending on which marker set you used.

Returns:

left_marker_coords : list of strings, len(12)

The X and Y coordinates for the 6 left markers.

right_marker_coords : list of strings, len(12)

The X and Y coordinates for the 6 right markers.

left_forces : list of strings, len(3)

The X and Y ground reaction forces and the Z ground reaction moment of the left leg.

right_forces : list of strings, len(3)

The X and Y ground reaction forces and the Z ground reaction moment of the left leg.

Notes

The returned marker labels correspond to the ISB standard coordinate system for gait, with X in the direction of travel, Y opposite to gravity, and Z to the subject’s right.

D-Flow/Cortex output data (and marker labels) in a different coordinate system and follow this conversion:

  • The D-Flow X unit vector is equal to the ISB Z unit vector.
  • The D-Flow Y unit vector is equal to the ISB Y unit vector.
  • The D-FLow Z unit vector is equal to the ISB -X unit vector.

So it is up to the user to ensure that the marker and force data that corresponds to the returned labels is expressed in the ISB coordinate frame before passing it into leg2d.m. DFlowData has methods that can express the data in the correct coordinate system on output.

The forces and moments must also be normalized by body mass before using with leg2d.m.

gaitanalysis.motek.spline_interpolate_over_missing(data_frame, abscissa_column, order=1, columns=None)

Returns the data frame with all missing values replaced by some interpolated or extrapolated values derived from a spline.

Parameters:

data_frame : pandas.DataFrame

A data frame which contains a column for the abscissa and other columns which may or may not have missing values, i.e. NaN.

abscissa_column : string

The column name which represents the abscissa.

order : integer, optional, default=1

The order of the spline. Can be 1 through 5 for linear through quintic splines. The default is a linear spline. See documentation for scipy.interpolate.InterpolatedUnivariateSpline.

columns : list of strings, optional, default=None

If only a particular set of columns need interpolation, they can be specified here.

Returns:

data_frame : pandas.DataFrame

The same data frame passed in with all NaNs in the specified columns replaced with interpolated or extrapolated values.

gait Module

class gaitanalysis.gait.GaitData(data)

Bases: object

A class to store typical gait data.

attrs_to_store = ['data', 'gait_cycles', 'gait_cycle_stats', 'strikes', 'offs']
grf_landmarks(right_vertical_signal_col_name, left_vertical_signal_col_name, method='force', do_plot=False, min_time=None, max_time=None, **kwargs)

Returns the times at which heel strikes and toe offs happen in the raw data.

Parameters:

right_vertical_signal_col_name : string

The name of the column in the raw data frame which corresponds to the right foot vertical ground reaction force.

left_vertical_signal_col_name : string

The name of the column in the raw data frame which corresponds to the left foot vertical ground reaction force.

method: string {force|accel}

Whether to use force plate data or accelerometer data to calculate landmarks

Returns:

right_strikes : np.array

All indices at which right_grfy is non-zero and it was 0 at the preceding time index.

left_strikes : np.array

Same as above, but for the left foot.

right_offs : np.array

All indices at which left_grfy is 0 and it was non-zero at the preceding time index.

left_offs : np.array

Same as above, but for the left foot.

Notes

This is a simple wrapper to gait_landmarks_from_grf and supports all the optional keyword arguments that it does.

inverse_dynamics_2d(left_leg_markers, right_leg_markers, left_leg_forces, right_leg_forces, body_mass, low_pass_cutoff)

Computes the hip, knee, and ankle angles, angular rates, joint moments, and joint forces and adds them as columns to the data frame.

Parameters:

left_leg_markers : list of strings, len(12)

The names of the columns that give the X and Y marker coordinates for six markers.

right_leg_markers : list of strings, len(12)

The names of the columns that give the X and Y marker coordinates for six markers.

left_leg_forces : list of strings, len(3)

The names of the columns of the ground reaction forces and moments (Fx, Fy, Mz).

right_leg_forces : list of strings, len(3)

The names of the columns of the ground reaction forces and moments (Fx, Fy, Mz).

body_mass : float

The mass, in kilograms, of the subject.

low_pass_cutoff : float

The cutoff frequency in hertz.

Returns:

data_frame : pandas.DataFrame

The main data frame now with columns for the new variables. Note that the force coordinates labels (X, Y) are relative to the coordinate system described herein.

Notes

This computation assumes the following coordinate system:

Y
 ^ _ o _
 |   |   ---> v
 |  /             -----> x

where X is forward (direction of walking) and Y is up.

Make sure the sign conventions of the columns you pass in are correct!

The markers should be in the following order:
  1. Shoulder
  2. Greater trochanter
  3. Lateral epicondyle of knee
  4. Lateral malleolus
  5. Heel (placed at same height as marker 6)
  6. Head of 5th metatarsal

The underlying function low pass filters the data before computing the inverse dynamics. You should pass in unfiltered data.

load(filename)

Loads data from disk via HDF5 (PyTables).

Parameters:

filename : string

Path to an HDF5 file.

plot_gait_cycles(*col_names, **kwargs)

Plots the time histories of each gait cycle.

Parameters:

col_names : string

A variable number of strings naming the columns to plot.

mean : boolean, optional

If true the mean and standard deviation of the cycles will be plotted.

kwargs : key value pairs

Any extra kwargs to pass to the matplotlib plot command.

plot_landmarks(col_names, side, event='both', index=0, window=None, num_cycles_to_plot=None, curve_kwargs=None, heel_kwargs=None, toe_kwargs=None)

Creates a plot of the desired signal(s) with the gait event times overlaid on top of the signal.

Parameters:

col_names : sequence of strings

A variable number of strings naming the columns to plot.

side : string, {right|left}

Whether to plot the gait landmarks from the right or left leg.

event : string, {heelstrikes|toeoffs|both|none}

Which gait landmarks to plot.

index : integer, optional, default=0

The index of the first time sample in the plot. This is useful if you want to plot the cycles starting at an arbitrary point in time in the data.

window : integer, optional, default=None

The number of time samples to plot. This is useful when a trial has many cycles and you only want to view some of them in the plot.

num_cycles_to_plot : integer, optional, default=None

This is an alternative way to specify the window. If this is provided, the window argment is ignored and the window is estimated by the desired number of cycles.

curve_kwargs : dictionary, optional

Valid matplotlib kwargs that will be used for the signal curves.

heel_kwargs : dictionary, optional

Valid matplotlib kwargs that will be used for the heel-strike lines.

toe_kwargs : dictionary, optional

Valid matplotlib kwargs that will be used for the toe-off lines.

Returns:

axes : matplotlib.Axes

The list of axes for the subplots or a single axes if only one column was supplied. Same as matplotlib.pyplot.subplots returns.

Notes

The index, window and num_cycles_to_plot arguments do not simply set the x limit to bound the data of interest, they do not plot any data outside the desired range (and is thus faster).

save(filename)

Saves data to disk via HDF5 (PyTables).

Parameters:

filename : string

Path to an HDF5 file.

split_at(side, section='both', num_samples=None, belt_speed_column=None)

Forms a pandas.Panel which has an item for each cycle. The index of each cycle data frame will be a percentage of gait cycle.

Parameters:

side : string {right|left}

Split with respect to the right or left side heel strikes and/or toe-offs.

section : string {both|stance|swing}

Whether to split around the stance phase, swing phase, or both.

num_samples : integer, optional

If provided, the time series in each gait cycle will be interpolated at values evenly spaced at num_sample in time across the gait cycle. If None, the maximum number of possible samples per gait cycle will be used.

belt_speed_column : string, optional

The column name corresponding to the belt speed on the corresponding side.

Returns:

gait_cycles : pandas.Panel

A panel where each item is a gait cycle. Each cycle has the same number of time samples and the index is set to the percent of the gait cycle.

time_derivative(col_names, new_col_names=None)

Numerically differentiates the specified columns with respect to the time index and adds the new columns to self.data.

Parameters:

col_names : list of strings

The column names for the time series which should be numerically time differentiated.

new_col_names : list of strings, optional

The desired new column name(s) for the time differentiated series. If None, then a default name of Time derivative of <origin column name> will be used.

tpose(data_frame)

Computes the mass of the subject. Computes to orientation of accelerometers on a subject during quiet standing relative to treadmill Y-axis

gaitanalysis.gait.find_constant_speed(time, speed, plot=False, filter_cutoff=1.0)

Returns the indice at which the treadmill speed becomes constant and the time series when the treadmill speed is constant.

Parameters:

time : array_like, shape(n,)

A monotonically increasing array.

speed : array_like, shape(n,)

A speed array, one sample for each time. Should ramp up and then stablize at a speed.

plot : boolean, optional

If true a plot will be displayed with the results.

filter_cutoff : float, optional

The filter cutoff frequency for filtering the speed in Hertz.

Returns:

indice : integer

The indice at which the speed is consider constant thereafter.

new_time : ndarray, shape(n-indice,)

The new time array for the constant speed section.

gaitanalysis.gait.gait_landmarks_from_accel(time, right_accel, left_accel, threshold=0.33, **kwargs)

Obtain right and left foot strikes from the time series data of accelerometers placed on the heel.

Parameters:

time : array_like, shape(n,)

A monotonically increasing time array.

right_accel : array_like, shape(n,)

The vertical component of accel data for the right foot.

left_accel : str, shape(n,)

Same as above, but for the left foot.

threshold : float, between 0 and 1

Increase if heelstrikes/toe-offs are falsly detected

Returns:

right_foot_strikes : np.array

All times at which a right foot heelstrike is determined

left_foot_strikes : np.array

Same as above, but for the left foot.

right_toe_offs : np.array

All times at which a right foot toeoff is determined

left_toe_offs : np.array

Same as above, but for the left foot.

gaitanalysis.gait.gait_landmarks_from_grf(time, right_grf, left_grf, threshold=1e-05, filter_frequency=None, **kwargs)

Obtain gait landmarks (right and left foot strike & toe-off) from ground reaction force (GRF) time series data.

Parameters:

time : array_like, shape(n,)

A monotonically increasing time array.

right_grf : array_like, shape(n,)

The vertical component of GRF data for the right leg.

left_grf : str, shape(n,)

Same as above, but for the left leg.

threshold : float, optional

Below this value, the force is considered to be zero (and the corresponding foot is not touching the ground).

filter_frequency : float, optional, default=None

If a filter frequency is provided, in Hz, the right and left ground reaction forces will be filtered with a 2nd order low pass filter before the landmarks are identified. This method assumes that there is a constant (or close to constant) sample rate.

Returns:

right_foot_strikes : np.array

All times at which right_grfy is non-zero and it was 0 at the preceding time index.

left_foot_strikes : np.array

Same as above, but for the left foot.

right_toe_offs : np.array

All times at which left_grfy is 0 and it was non-zero at the preceding time index.

left_toe_offs : np.array

Same as above, but for the left foot.

Notes

Source modifed from:

https://github.com/fitze/epimysium/blob/master/epimysium/postprocessing.py

gaitanalysis.gait.interpolate(data_frame, time)

Returns a data frame with a index based on the provided time array and linear interpolation.

Parameters:

data_frame : pandas.DataFrame

A data frame with time series columns. The index should be in same units as the provided time array.

time : array_like, shape(n,)

A monotonically increasing array of time in seconds at which the data frame should be interpolated at.

Returns:

interpolated_data_frame : pandas.DataFrame

The data frame with an index matching time_vector and interpolated values based on data_frame.

gaitanalysis.gait.plot_gait_cycles(gait_cycles, *col_names, **kwargs)

Plots the time histories from each gait cycle on one graph.

Parameters:

gait_cycles : pandas.Panel

A panel of gait cycles. Each item should be a cycle DataFrame with time histories of variables. The index should be the percent gait cycle.

col_names : string

A variable number of strings naming the columns to plot.

mean : boolean, optional, default=False

If true the mean and standard deviation of the gait cycles will be plotted instead of the individual lines.

kwargs : key value pairs

Any extra kwargs to pass to the matplotlib plot command.

controlid Module

class gaitanalysis.controlid.SimpleControlSolver(data, sensors, controls, validation_data=None)

Bases: object

This assumes a simple linear control structure at each time instance in a gait cycle.

The measured joint torques equal some limit cycle joint torque plus a matrix of gains multiplied by the error in the sensors and the nominal value of the sensors.

m_measured(t) = m_nominal + K(t) [s_nominal(t) - s(t)] = m*(t) - K(t) s(t)

This class solves for the time dependent gains and the “commanded” controls using a simple linear least squares.

compute_estimated_controls(gain_matrices, nominal_controls)

Returns the predicted values of the controls and the contributions to the controls given gains, K(t), and nominal controls, m*(t), for each point in the gait cycle.

Parameters:

gain_matrices : ndarray, shape(n, q, p)

The estimated gain matrices for each time step.

control_vectors : ndarray, shape(n, q)

The nominal control vector plus the gains multiplied by the reference sensors at each time step.

Returns:

panel : pandas.Panel, shape(m, n, q)

There is one data frame to correspond to each gait cycle in self.validation_data. Each data frame has columns of time series which store m(t), m*(t), and the individual components due to K(t) * se(t).

Notes

m(t) = m0(t) + K(t) * [ s0(t) - s(t) ] = m0(t) + K(t) * se(t) m(t) = m*(t) - K(t) * s(t)

This function returns m(t), m0(t), m*(t) for each control and K(t) * [s0(t) - s(t)] for each sensor affecting each control. Where s0(t) is estimated by taking the mean with respect to the gait cycles.

controls
deconstruct_solution(x, covariance)

Returns the gain matrices, K(t), and m*(t) for each time step in the gait cycle given the solution vector and the covariance matrix of the solution.

m(t) = m*(t) - K(t) s(t)

Parameters:

x : array_like, shape(n * q * (p + 1),)

The solution matrix containing the gains and the commanded controls.

covariance : array_like, shape(n * q * (p + 1), n * q * (p + 1))

The covariance of x with respect to the variance in the fit.

Returns:

gain_matrices : ndarray, shape(n, q, p)

The gain matrices at each time step, K(t).

control_vectors : ndarray, shape(n, q)

The nominal control vector plus the gains multiplied by the reference sensors at each time step.

gain_matrices_variance : ndarray, shape(n, q, p)

The variance of the found gains (covariance is neglected).

control_vectors_variance : ndarray, shape(n, q)

The variance of the found commanded controls (covariance is neglected).

Notes

x looks like:
[k11(0), k12(0), ..., kqp(0), m1*(0), ..., mq*(0), ...,
k11(n), k12(0), ..., kqp(n), m1*(n), ..., mq*(n)]

If there is a gain omission matrix then nan’s are substituted for all gains that were set to zero.

form_a_b()

Returns the A matrix and the b vector for the linear least squares fit.

Returns:

A : ndarray, shape(n * q, n * q * (p + 1))

The A matrix which is sparse and contains the sensor measurements and ones.

b : ndarray, shape(n * q,)

The b vector which constaints the measured controls.

Notes

In the simplest fashion, you can put:

m(t) = m*(t) - K * s(t)

into the form:

Ax = b

with:

b = m(t)
A = [-s(t) 1]
x = [K(t) m*(t)]^T

[-s(t) 1] * [K(t) m*(t)]^T = m(t)
form_control_vectors()

Returns an array of control vectors for each cycle and each time step in the identification data.

Returns:

control_vectors : ndarray, shape(m, n, q)

The sensor vector form the i’th cycle and the j’th time step will look like [control_0, ..., control_(q-1)].

form_sensor_vectors()

Returns an array of sensor vectors for each cycle and each time step in the identification data.

Returns:

sensor_vectors : ndarray, shape(m, n, p)

The sensor vector form the i’th cycle and the j’th time step will look like [sensor_0, ..., sensor_(p-1)].

gain_inclusion_matrix
identification_data
least_squares(A, b, ignore_cov=False)

Returns the solution to the linear least squares and the covariance matrix of the solution.

Parameters:

A : array_like, shape(n, m)

The coefficient matrix of Ax = b.

b : array_like, shape(n,)

The right hand side of Ax = b.

ignore_cov: boolean, optional, default=False

The covariance computation for a very large A matrix can be extremely slow. If this is set to True, then the computation is skipped and the covariance of the identified parameters is set to zero.

Returns:

x : ndarray, shape(m,)

The best fit solution.

variance : float

The variance of the fit.

covariance : ndarray, shape(m, m)

The covariance of the solution.

plot_control_contributions(estimated_panel, max_num_gait_cycles=4)

Plots two graphs for each control and each gait cycle showing contributions from the linear portions. The first set of graphs shows the first few gait cycles and the contributions to the control moments. The second set of graph shows the mean contributions to the control moment over all gait cycles.

Parameters:

panel : pandas.Panel, shape(m, n, q)

There is one data frame to correspond to each gait cycle. Each data frame has columns of time series which store m(t), m*(t), and the individual components due to K(t) * se(t).

plot_estimated_vs_measure_controls(estimated_panel, variance)

Plots a figure for each control where the measured control is shown compared to the estimated along with a plot of the error.

Parameters:

estimated_panel : pandas.Panel

A panel where each item is a gait cycle.

variance : float

The variance of the fit.

Returns:

axes : array of matplotlib.axes.Axes, shape(q,)

The plot axes.

plot_gains(gains, gain_variance, y_scale_function=None)

Plots the identified gains versus percentage of the gait cycle.

Parameters:

gain_matrix : ndarray, shape(n, q, p)

The estimated gain matrices for each time step.

gain_variance : ndarray, shape(n, q, p)

The variance of the estimated gain matrices for each time step.

y_scale_function : function, optional, default=None

A function that returns the portion of a control and sensor label that can be used for scaling the y axes.

Returns:

axes : ndarray of matplotlib.axis, shape(q, p)

sensors
solve(sparse_a=False, gain_inclusion_matrix=None, ignore_cov=False)

Returns the estimated gains and sensor limit cycles along with their variance.

Parameters:

sparse_a : boolean, optional, default=False

If true a sparse A matrix will be used along with a sparse linear least squares solver.

gain_inclusion_matrix : boolean array_like, shape(q, p)

A matrix which is the same shape as the identified gain matrices which has False in place of gains that should be assumed to be zero and True for gains that should be identified.

ignore_cov: boolean, optional, default=False

The covariance computation for a very large A matrix can be extremely slow. If this is set to True, then the computation is skipped and the covariance of the identified parameters is set to zero.

Returns:

gain_matrices : ndarray, shape(n, q, p)

The estimated gain matrices for each time step.

control_vectors : ndarray, shape(n, q)

The nominal control vector plus the gains multiplied by the reference sensors at each time step.

variance : float

The variance in the fitted curve.

gain_matrices_variance : ndarray, shape(n, q, p)

The variance of the found gains (covariance is neglected).

control_vectors_variance : ndarray, shape(n, q)

The variance of the found commanded controls (covariance is neglected).

estimated_controls : pandas.Panel

validation_data