TrackingData Class Reference

The class to define tracking data. More...

Inheritance diagram for TrackingData:

Public Member Functions
function	getVariableIdx (in obj, in subtable)
	Function to get indices of a specific row.
function	save (in obj, in filename)
	Function to save the TrackingData object.
function	saveStruct (in obj, in filename)
	Function to save the TrackingData object as struct.
function	setProperty (in obj, in name, in value)
	Function to set a property.
function	TrackingData (in varargin)
	Constructor setting default TrackingData object.

Static Public Member Functions
static function	loadStruct (in filename)
	Function to load the data into an object which was previously saved using saveStruct()
static function	struct2object (in dataStruct)
	Function to get a TrackingData object from a struct.

Public Attributes
Property	comment
	String: Personal comment.
Property	filename
	String: Filename with path, without extension.
Constant Property	VARIABLEIDENTIFIER = {'type', 'name', 'unit', 'position', 'direction', 'segment'}
	Cell containing Strings: Column names of TrackingData.variables which are needed to identify an unique variable row.

Protected Attributes
Property	nSamples
	Double: Number of samples (same for each variable)
Property	nTrials
	Double: Number of trials.
Property	nVariables
	Double: Number of variables.

Private Member Functions
function	correctGyroSum (in obj, in plotIt)
	Function to set the sum of a periodic gyro signal to 0.
function	correctVariance (in obj, in plotIt)
	Function to prevent small variances of the variables.
function	extractData (in obj, in type, in names, in directions, in positions, in units)
	Function to extract only specific data from the TrackingData object.
function	inclineGRF (in obj, in incline)
	Function to change a treadmill's incline.
function	preprocessData (in obj, in nNodes)
	Function to preprocess tracking data.
function	resampleData (in obj, in nNodes, in plotIt, in plotSamples, in plotVariance)
	Function to resample tracking data.
function	trimData (in obj, in iStart, in iEnd, in plotIt, in plotSamples, in plotVariance)
	Function to trim tracking data.
function	useHalfGaitCycleData (in obj)
	Function to cut the tracking data such that only half is used.
function	writeMotionToOsim (in obj, in model, in filename)
	Function to write motion from tracking data object to OpenSim files.

Static Private Member Functions
static function	createDefaultProcessingTable ()
	Function to load the data into an object which was previously saved using saveStruct()
function	takeMeanAndVar (in plotIt, in varargin)
	Function to compute the mean and variance of several data sets.

Private Attributes
Property	computerName
	String: Name of the computer (Will be automatically set in the constructor)
Property	creationTime
	Datetime: Creation date with 'dd-MMM-yyyy HH:mm:ss' (Will be automatically set in the constructor)
Property	gitHashString
	String: Git hash of the current commit (Will be automatically set in the constructor)
Property	gitURL
	String: Url of git repository (Will be automatically set in the constructor)
Property	isSymmetric
	Boolean: 1 if symmetry assumption can be used, i.e.
Property	movementDescription
	String: More detailed description of the movement.
Property	movementEvents
	Table: Movement events saved with name and index.
Property	movementType
	String: Movement type which was recorded (e.g. walking)
Property	participantAge
	Double: Age of participant in years.
Property	participantGender
	String: Gender of participant ('female' or 'male')
Property	participantHeight
	Double: Height of participant in m.
Property	participantMass
	Double: Mass of participant in kg.
Property	participantName
	String: Name of the participant.
Property	performedProcessing
	Table: Information about performed processing.
Property	runningStyle
	String: Running style of the participant (i.e. 'rearfoot', 'midfoot', 'forefoot')
Property	studyDate
	Datetime: dd-MMM-yyyy of the study created using:
Property	studyName
	String: Name of the study.
Property	trialList
	Cell array of strings: Description of the single data trials (nTrials x 1)
Property	userName
	String: User name of the computer (Will be automatically set in the constructor)
Property	variables
	Table: Data with columns type, name, mean, var (=variance), unit, and optionally segment, position, and direction for IMU and marker data.

Detailed Description

The class to define tracking data.

This class was implemented to ensure a consistent data structure of tracking data

This class contains methods which are generally applicable to load or process tracking data. Project specific methods should be saved in our personal scripts folder!

This class inherits from matlab.mixin.Copyable. This means that we can make a deep copy of a TrackingData object:

trackingData2 = copy(trackingData);

The method plotVarTable(trackingData.variables) can be used for visualization:

plotVarTable(trackingData.variables);

Todo:

The property isSymmetric is very confusing. Because it is not telling something about the symmetry of the data. If we would like to track other movements later we should have both isSymmetric and isPeriodic.

Todo:

Test the implementation with IMU data.

Examples

/home/runner/work/BioMAC-Sim-Toolbox/BioMAC-Sim-Toolbox/ExampleScripts/+IntroductionExamples/script2D.m, /home/runner/work/BioMAC-Sim-Toolbox/BioMAC-Sim-Toolbox/ExampleScripts/+IntroductionExamples/script3D.m, /home/runner/work/BioMAC-Sim-Toolbox/BioMAC-Sim-Toolbox/ExampleScripts/+IntroductionExamples/scriptPlotting.m, and /home/runner/work/BioMAC-Sim-Toolbox/BioMAC-Sim-Toolbox/ExampleScripts/+Treadmill/script2D.m.

Constructor & Destructor Documentation

TrackingData()

function TrackingData

(

in

varargin

)

Constructor setting default TrackingData object.

Parameters

varargin

(optional) Parameter settings: Parameter name as string followed by the parameter value. Multiple parameters can be set. E.g.: TrackingData('sourceInfo', sourceInfo, 'triallist', triallist);

Return values

obj	TrackingData class object

Member Function Documentation

correctGyroSum()

function correctGyroSum ( in  obj, in  plotIt  )

private

Function to set the sum of a periodic gyro signal to 0.

Parameters

obj	TrackingData class object which should be corrected
plotIt	(optional) Boolean: If true, plot the signal before and after correction for comparison. (default: 0)

correctVariance()

function correctVariance ( in  obj, in  plotIt  )

private

Function to prevent small variances of the variables.

• If nTrial = 1: Sets the variance to 0 if this is not already the case.

• If nTrial > 1: Sets all variances below 10% of the mean variance to 10% of the mean variance. If the mean variance is smaller than 10% of the minimum variance, than minimum variance is used. The minimum variances were chosen empirically:

  • angle: var = 4 deg² (sd = 2 deg)
  • translation: var = 0.0001 m² (sd = 0.01 m)
  • GRF: var = 0.0004 BW² (sd = 0.02 BW)
  • speed: var = 0.0001 (m/s)² (sd = 0.01 m/s)
  • duration: var = 0.0001 s² (sd = 0.01 s)
  • acc: var = 1 (m/s²)² (sd = 1 m/s²)
  • gyro: var = 0.1 (rad/s)² (sd = 0.3162 rad/s)

  Todo:

  If nTrial > 1, we set the minimum variance of speed and duration to 0.0001. This was an arbitrarily chosen value. We should think about this.

Parameters

obj	TrackingData class object which should be corrected
plotIt	(optional) Boolean: If true, plot the signal before and after correction of the variance for comparison. (default: 0)

createDefaultProcessingTable()

static function createDefaultProcessingTable ( )

staticprivate

Function to load the data into an object which was previously saved using saveStruct()

Fields:

• type: This has to set in all functions manipulating the data. It's the name of the function which manipulated the data.
• processingOfTrial: This is used in TrackingData.takeMeanAndVar. It constains a table with the columns trialList and all the columns contained in TrackingData.performedProcessing.
• entriesCorrected: This is used in TrackingData.correctGyroSum and in TrackingData.correctVariance. It is a subtable of the variable table describing the variables which were corrected.
• nSamplesIn and nSamplesOut: These are used in TrackingData.resampleData. They contain the number of samples of the input and of the output, respectively.
• iStart and iEnd: These are used in TrackingData.trimData. They contain the index of start and end used to trim the data.

Return values

T	Table: Default table which is used for TrackingData.performedProcessing

extractData()

function extractData ( in  obj, in  type, in  names, in  directions, in  positions, in  units  )

private

Function to extract only specific data from the TrackingData object.

All inputs except type can also be empty. If it is empty it is ignored.

Example:

trackingDataExtracted = trackingData.extractData('gyro', '', [1, 0, 0]);

Parameters

obj	TrackingData class object which should be used to extract data. This object will not be manipulated.
type	Char: Type which will be extracted
names	(optional) Char or cell of chars: Names which will be extracted
directions	(optional) Vector or cell of vectors: Directions which will be extracted (Used for IMUs)
positions	(optional) Vector or cell of vectors: Positions which will be extracted (Used for IMUs)
units	(optional) Char or cell of chars: Units which will be extracted

Return values

obj_out

TrackingData class object with the extracted data

getVariableIdx()

function getVariableIdx	(	in	obj,
		in	subtable
	)

Function to get indices of a specific row.

Parameters

obj	TrackingData class object
subtable	Table: Subtable with one row containing all columns which should be identical

Return values

idxRow

Double array: Indices of the rows which are identically to the entries in the subtable

inclineGRF()

function inclineGRF ( in  obj, in  incline  )

private

Function to change a treadmill's incline.

Parameters

obj	TrackingData class object which should be corrected
incline	Angle of treadmill incline, rad

loadStruct()

static function loadStruct ( in  filename )

static

Function to load the data into an object which was previously saved using saveStruct()

Parameters

filename

String: Name of the file containing a struct called data

Return values

obj	TrackingData class object

Examples

/home/runner/work/BioMAC-Sim-Toolbox/BioMAC-Sim-Toolbox/ExampleScripts/+IntroductionExamples/script3D.m, and /home/runner/work/BioMAC-Sim-Toolbox/BioMAC-Sim-Toolbox/ExampleScripts/+IntroductionExamples/scriptPlotting.m.

preprocessData()

function preprocessData ( in  obj, in  nNodes  )

private

Function to preprocess tracking data.

This function calls:

• TrackingData::resampleData()
• TrackingData::correctGyroSum()
• TrackingData::correctVariance()

Parameters

obj	TrackingData class object which should be processed
nNodes	Double: Number of nodes

resampleData()

function resampleData ( in  obj, in  nNodes, in  plotIt, in  plotSamples, in  plotVariance  )

private

Function to resample tracking data.

• This function uses interp1().

• It resamples only data of the type 'angle', 'translation', 'moment','GRF', 'CoP', 'GRM', 'acc', 'gyro', 'marker', or 'time'. Thus 'speed' and 'duration' are not resampled.

  Todo:

  Rethink the adaption of the events. Currently we keep only the start at 1 and the end at nSamples+1. However, the events are not exactly at the index 1 or nSamples+1

Parameters

obj	TrackingData class object which should be resampled
nNodes	Double: Number of nodes
plotIt	(optional) Boolean: If true, plot the signal before and after resampling for comparison. (default: 0)
plotSamples	(optional) Boolean: If true, plot the single sample points explecitly. (default: 0)
plotVariance	(optional) Boolean: If true, plot the variance. (default: 0)

save()

function save	(	in	obj,
		in	filename
	)

Function to save the TrackingData object.

The TrackingData object will be saved in a variable called 'data' and saved using the given filename.

Parameters

obj	Result class object
filename	(optional) String: Filename with path, without extension (default: TrackingData.filename)

saveStruct()

function saveStruct	(	in	obj,
		in	filename
	)

Function to save the TrackingData object as struct.

The TrackingData object will be saved in a struct called 'dataStruct' and saved using the given filename.

Parameters

obj	TrackingData class object
filename	(optional) String: Filename with path, without extension (default: TrackingData.filename)

setProperty()

function setProperty	(	in	obj,
		in	name,
		in	value
	)

Function to set a property.

Warning: It is not checked weather the type of the value is correct!

Parameters

obj	TrackingData class object
name	String: Name of the property
value	Not defined: Value of the property

struct2object()

static function struct2object ( in  dataStruct )

static

Function to get a TrackingData object from a struct.

Parameters

dataStruct

Struct: TrackingData content

Return values

obj	TrackingData class object

takeMeanAndVar()

function takeMeanAndVar ( in  plotIt, in  varargin  )

staticprivate

Function to compute the mean and variance of several data sets.

It will set the properties using the following rules:

• TrackingData.trialList: Combine all trial lists
• TrackingData.movementEvents: Use the first and last event

We compute the mean and the variance using the data saved in the column 'mean' without considering the column 'var'.

Warning:

• After calling TrackingData.takeMeanAndVar, you have to call again the preprocessing functions like TrackingData.correctGyroSum or TrackingData.correctVariance before starting the simulation.
• The mean of severel means is not equal to the mean of all the single trials.

Examplary function call using filenames:

datafiles = {'file1.mat', 'file2.mat', 'file3.mat'};
meanTrackingData = TrackingData.takeMeanAndVar(1, datafiles{:});

Examplary function call using TrackingData objects:

meanTrackingData = TrackingData.takeMeanAndVar(1, trackingData1, trackingData2);

Todo:

We have to ensure if we can simply take the mean of the translations. If we do this, we are assuming that the cycle is always at the same position in the global reference frame.

Parameters

plotIt	Boolean: If true, plot all signals and the mean and variance
varargin	String: Filenames of files containing TrackingData struct ... or ... TrackingData: TrackingData objects Requirements: varargin must contain at least two entries to compute the mean and the variance out of them. Same studyName, subjectName, movementType, isSymmetric Start and end with the same movmentEvents if there are events listed Contain the same variables (Consitent type, name and unit)

Return values

meanTrackingData

TrackingData: Containing the mean and variance of the input.

trimData()

function trimData ( in  obj, in  iStart, in  iEnd, in  plotIt, in  plotSamples, in  plotVariance  )

private

Function to trim tracking data.

• It trims the data of the type 'angle', 'translation', 'moment','GRF', 'CoP', 'GRM', 'acc', 'gyro', 'marker', or 'time'.
• Thus 'speed' and 'duration' are only single samples and are currently not trimmed, but removed since they are not valid anymore. But there might be another better approach.
• Only the events between iStart and iEnd+1 are kept. If there no events for 1 and N+1, "Start" and "End" are added since they are required in other functions.

Parameters

obj	TrackingData class object which should be trimmed
iStart	Int: Index of start sample (inclusive)
iEnd	Int: Index of end sample (inclusive)
plotIt	(optional) Boolean: If true, plot the signal before and after resampling for comparison. (default: 0)
plotSamples	(optional) Boolean: If true, plot the single sample points explecitly. (default: 0)
plotVariance	(optional) Boolean: If true, plot the variance. (default: 0)

useHalfGaitCycleData()

function useHalfGaitCycleData ( in  obj )

private

Function to cut the tracking data such that only half is used.

Function to use only half the tracking data if the motion is symmetric but the data is of the complete gait cycle.

It is just taking the half without taking the movement events into account for cutting.

It cuts data of the type 'angle', 'translation', 'moment','GRF', 'CoP', 'GRM', 'acc', 'gyro', 'marker', 'time'. It also halves the 'duration'. The 'speed' is not changed.

Parameters

obj	TrackingData class object which should be divided

writeMotionToOsim()

function writeMotionToOsim ( in  obj, in  model, in  filename  )

private

Function to write motion from tracking data object to OpenSim files.

Saves the motion to the following files:

1. <filename>_kinematics.mot containing the joint angles
2. <filename>_kinetics_GRFs.mot containing GRFs
3. <filename>_kinetics_moments.sto containing moments

No resampling is applied.

Parameters

obj	TrackingData class object which should saved to OpenSim files. It has to contain the following fields: Type Name duration angle all joint angles of the model translation all translations of the model GRF 'GRF_x_r', 'GRF_y_r', 'GRF_z_r', 'GRF_x_l', 'GRF_y_l', 'GRF_z_l' CoP 'CoP_x_r', 'CoP_y_r', 'CoP_z_r', 'CoP_x_l', 'CoP_y_l', 'CoP_z_l' GRM 'GRM_x_r', 'GRM_y_r', 'GRM_z_r', 'GRM_x_l', 'GRM_y_l', 'GRM_z_l' moment all DOFs of the model
model	Model: Model associated with the tracking data. This is required to obtain names of DOFs, bodymass, and gravity
filename	String: Filename to save the results. See details for the used postfixes

Member Data Documentation

comment

Property comment

String: Personal comment.

computerName

Property computerName

private

String: Name of the computer (Will be automatically set in the constructor)

creationTime

Property creationTime

private

Datetime: Creation date with 'dd-MMM-yyyy HH:mm:ss' (Will be automatically set in the constructor)

filename

Property filename

String: Filename with path, without extension.

gitHashString

Property gitHashString

private

String: Git hash of the current commit (Will be automatically set in the constructor)

gitURL

Property gitURL

private

String: Url of git repository (Will be automatically set in the constructor)

isSymmetric

Property isSymmetric

private

Boolean: 1 if symmetry assumption can be used, i.e.

only one half of the movement (e.g. a half gait cycle) is contained in the tracking data and we assume that the second have is identically to get a periodic movement. 0 if we have already a periodic movement which can directy be used in the periodicity constraint.

movementDescription

Property movementDescription

private

String: More detailed description of the movement.

Like that they were walking at prefered speed

movementEvents

Property movementEvents

private

Table: Movement events saved with name and index.

This is should contain at least a description of the start and the end of the data.

movementType

Property movementType

private

String: Movement type which was recorded (e.g. walking)

nSamples

Property nSamples

protected

Double: Number of samples (same for each variable)

nTrials

Property nTrials

protected

Double: Number of trials.

nVariables

Property nVariables

protected

Double: Number of variables.

participantAge

Property participantAge

private

Double: Age of participant in years.

participantGender

Property participantGender

private

String: Gender of participant ('female' or 'male')

participantHeight

Property participantHeight

private

Double: Height of participant in m.

participantMass

Property participantMass

private

Double: Mass of participant in kg.

participantName

Property participantName

private

String: Name of the participant.

performedProcessing

Property performedProcessing

private

Table: Information about performed processing.

The default table is created in TrackingData.createDefaultProcessingTable where all the fields are explained. If you are writing a new function manipulating the data, please also log this in performedProcessing.

runningStyle

Property runningStyle

private

String: Running style of the participant (i.e. 'rearfoot', 'midfoot', 'forefoot')

studyDate

Property studyDate

private

Datetime: dd-MMM-yyyy of the study created using:

t = datetime(2018,12,31)

studyName

Property studyName

private

String: Name of the study.

trialList

Property trialList

private

Cell array of strings: Description of the single data trials (nTrials x 1)

userName

Property userName

private

String: User name of the computer (Will be automatically set in the constructor)

VARIABLEIDENTIFIER

Constant Property VARIABLEIDENTIFIER = {'type', 'name', 'unit', 'position', 'direction', 'segment'}

Cell containing Strings: Column names of TrackingData.variables which are needed to identify an unique variable row.

Position, direction, and segment are only needed for IMU and marker data.

variables

Property variables

private

Table: Data with columns type, name, mean, var (=variance), unit, and optionally segment, position, and direction for IMU and marker data.

• Each row must have an unique identifier defined by the columns specified in TrackingData.VARIABLEIDENTIFIER
• The following types are supported in this class: 'angle', 'translation', 'moment', 'GRF', 'CoP', 'GRM', 'acc', 'gyro', 'marker', 'duration', 'speed'
• If only one trial was used, the variance of a variable has to be a zero vector.
• Data can be extracted using for example:

  trackingData.variables.mean{strcmp(trackingData.variables.type, 'speed')}

Examples

/home/runner/work/BioMAC-Sim-Toolbox/BioMAC-Sim-Toolbox/ExampleScripts/+IntroductionExamples/script3D.m.

---

The documentation for this class was generated from the following file:

• BioMAC-Sim-Toolbox/src/trackingData/@TrackingData/TrackingData.m