Sequence
Description
Default class for motion sequences in the toolbox. An instance of this class will be one motion sequence. The class contains several methods to perform pre-processing or displaying summarized data in text form (see public methods).
Initialisation
- class classes.sequence.Sequence(path=None, path_audio=None, name=None, condition=None, time_unit='auto', start_timestamps_at_zero=False, verbosity=1)
Creates an instance from the class Sequence and returns a Sequence object, allowing to be manipulated for processing or displaying. Upon creation, the function tries to assign a name to it based on the provided name parameter or path parameter. It then proceeds to load the sequence if a path has been provided.
New in version 2.0.
- Parameters:
path (str or None, optional) – Absolute path to the motion sequence (starting from the root of the drive, e.g.
C:/Users/Elliot/Documents/Recordings
). The path may point to a folder or a single file. For the acceptable file types, see Compatible files. If the path isNone
, an empty sequence will be created.path_audio (str or None, optional) – Absolute path to an audio file corresponding to the sequence. The path should point to a .wav file. This path will be stored as an attribute of the Sequence object, and may be used automatically by functions using an audio file (typically,
Sequence.synchronize()
andsequence_reader()
). This parameter is however far from vital in the definition of a Sequence instance, and can be skipped safely.name (str or None, optional) – Defines a name for the Sequence instance. If a string is provided, the attribute
name
will take its value. If not, seeSequence._define_name_init()
.condition (str or None, optional) – Optional field to represent in which experimental condition the sequence was recorded.
time_unit (str or None, optional) –
The unit of time of the timestamps in the original file. Depending on the value put as parameter, the timestamps will be converted to seconds.
If set on
"auto"
, the functionSequence._calculate_relative_timestamps()
will try to automatically detect the unit of the timestamps based on the difference of time between the two first frames, and will divide the timestamps by 10 000 000 (if it detects the timestamps to be in 100 ns), by 1 000 (if the timestamps are in ms), or won’t divide them (if the timestamps are already in s).If set on
"100ns"
, divides the timestamps from the file by 10 000 000. Typically, this is due to the output timestamps from Kinect being in tenth of microsecond (C# system time).If set on
"ms"
, divides the timestamps from the file by 1 000.If set on
"s"
, the function will preserve the timestamps as they are in the file.
The parameter also allows other units:
"ns"
,"1ns"
,"10ns"
,"100ns"
,"µs"
,"1µs"
,"10µs"
,"100µs"
,"ms"
,"1ms"
,"10ms"
,"100ms"
,"s"
,"sec"
,"1s"
,"min"
,"mn"
,"h"
,"hr"
,"d"
,"day"
. See the documentation for the functionSequence._calculate_relative_timestamps()
.start_timestamps_at_zero (bool, optional) – If set on
True
, the timestamp of the first pose of the sequence will be set at 0, and the timestamps of the other poses will be reassigned to keep the same delay from the first pose. As such, the attributes timestamp and relative_timestamp from every pose will be equal.verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- path
Path to the sequence passed as a parameter upon creation.
- Type:
str
- path_audio
Path to the audio file corresponding to the sequence.
- Type:
str
- name
Custom name given to the sequence. If no name has been provided upon initialisation, it will be defined by
Sequence._define_name_init()
.- Type:
str
- files
List of files contained in the path. The list will be of size 1 if the path points to a single file.
- Type:
list(str)
- randomized
Testifies if the starting position of the joints have been randomized by the function
Sequence.randomize()
. IsFalse
upon initialisation.- Type:
bool
- date_recording
The date at which the recording was performed, extracted from the file.
- Type:
datetime
- time_unit
The time unit of the timestamps.
- Type:
str
Magic methods
- class classes.sequence.Sequence.__len__(self)
Returns the number of poses in the sequence (i.e., the length of the attribute poses).
New in version 2.0.
- Returns:
The number of poses in the sequence.
- Return type:
int
Example
>>> sequence = Sequence("C:/Users/Dumbledore/Sequences/seq1/") >>> len(sequence) 420
- class classes.sequence.Sequence.__getitem__(self, index)
Returns the pose of index specified by the parameter
index
.- Parameters:
index (int) – The index of the pose to return.
- Returns:
A pose from the sequence instance.
- Return type:
Example
>>> sequence = Sequence("C:/Users/Homer/Sequences/seq1/") >>> sequence[42] Timestamp: 0.7673687 Relative timestamp: 0.7673687 Joints (21): Head: (0.2580389, 0.4354536, 2.449435) Neck: (0.2200405, 0.2870165, 2.452467) SpineShoulder: (0.2213234, 0.2103061, 2.444264) SpineMid: (0.224096, -0.02492883, 2.409717) SpineBase: (0.2265415, -0.3467222, 2.352579) ShoulderLeft: (0.08861267, 0.1529641, 2.387205) ElbowLeft: (0.05989294, -0.05652162, 2.338059) WristLeft: (0.1408673, -0.2341767, 2.213683) HandLeft: (0.1808563, -0.2797168, 2.203833) ShoulderRight: (0.3932458, 0.1480468, 2.420666) ElbowRight: (0.410402, -0.09375393, 2.338974) WristRight: (0.3219678, -0.2662066, 2.203344) HandRight: (0.2747259, -0.3047626, 2.200738) HipLeft: (0.1522616, -0.3320134, 2.309463) KneeLeft: (0.1468181, -0.8557156, 2.233713) AnkleLeft: (0.08108322, -1.155779, 2.15636) FootLeft: (0.1320685, -1.193715, 2.080927) HipRight: (0.2934242, -0.3502887, 2.319931) KneeRight: (0.2045003, -0.8930826, 2.275977) AnkleRight: (0.2089309, -1.175371, 2.194727) FootRight: (0.2288543, -1.20977, 2.095591)
- class classes.sequence.Sequence.__repr__(self)
Returns the
name
attribute of the sequence.- Returns:
The attribute
name
of the sequence instance.- Return type:
str
Examples
>>> sequence = Sequence("C:/Users/Fiona/Sequences/seq1/") >>> print(sequence) seq1
>>> sequence = Sequence("C:/Users/Fiona/Sequences/seq1/", name="my_sequence") >>> print(sequence) my_sequence
Public methods
Setter functions
- Sequence.set_name(name)
Sets the
name
attribute of the Sequence instance. This name can be used as display functions or as a means to identify the sequence (typically,plot_functions.joint_temporal_plotter()
).New in version 2.0.
- Parameters:
name (str) – The name you want to give to the sequence.
Example
>>> seq = Sequence("C:/Users/Mario/Sequences/seq1/") >>> seq.set_name("Sequence story telling 7")
- Sequence.set_condition(condition)
Sets the
condition
attribute of the Sequence instance. This attribute can be used to save the experimental condition in which the sequence instance was recorded.New in version 2.0.
- Parameters:
condition (str) – The experimental condition in which the sequence was recorded.
Example
>>> seq1 = Sequence("C:/Users/Harold/Sequences/English/seq.xlsx") >>> seq1.set_condition("English") >>> seq2 = Sequence("C:/Users/Harold/Sequences/Spanish/seq.xlsx") >>> seq2.set_condition("Spanish")
- Sequence.set_path_audio(path_audio)
Sets the
path_audio
attribute of the Sequence instance. This path may be used automatically by functions using an audio file (typically,Sequence.trim_to_audio()
andgraphic_functions.sequence_reader()
).New in version 2.0.
- Parameters:
path_audio (str) – The absolute path to the .wav file corresponding to the sequence.
- Sequence.set_first_timestamp(first_timestamp)
Attributes a new timestamp to the first pose of the sequence and delays the timestamps of the other poses accordingly.
New in version 2.0.
- Parameters:
first_timestamp (float or int) – The new timestamp of the first pose of the sequence.
Note
If 0 is passed as a parameter, the absolute timestamps of the sequence will be equal to its relative timestamps.
Getter functions
General
- Sequence.get_path()
Returns the attribute
path
of the sequence.New in version 2.0.
- Returns:
The path of the sequence.
- Return type:
str
- Sequence.get_name()
Returns the attribute
name
of the sequence.New in version 2.0.
- Returns:
The name of the sequence.
- Return type:
str
- Sequence.get_condition()
Returns the attribute
condition
of the sequence.New in version 2.0.
- Returns:
The experimental condition in which the recording of the sequence was performed.
- Return type:
str
- Sequence.get_joint_labels()
Returns the joint labels present in the first pose of the sequence.
New in version 2.0.
- Returns:
The list of the joint labels in the first pose of the sequence.
- Return type:
list
- Sequence.get_date_recording()
Returns the date and time of the recording as a datetime object, if it exists. If the date of the recording was not specified in the original file, the value will be None.
New in version 2.0.
- Returns:
The date and time of the first frame of the recording.
- Return type:
datetime
- Sequence.get_printable_date_recording()
Returns the date and time of the recording as a string, if it exists. The string returned will contain the weekday, day, month (in letters), year, hour, minutes and seconds (e.g.
"Wednesday 21 October 2015, 07:28:00"
) at which the recording was started. If the attribute date_recording of the sequence is None, the value returned is"No date found"
.New in version 2.0.
- Returns:
A formatted string of the date of the recording.
- Return type:
string
- Sequence.get_subject_height(verbosity=1)
Returns an estimation of the height of the subject, in meters, based on the successive distances between a series of joints. The successive distances are calculated for each pose, and averaged across all poses. Some joints are imaginary, based on the average of the position of two or four joints.
New in version 2.0.
For the Kinect system, the joints used are
"Head"
,"Neck"
,"SpineShoulder"
,"SpineMid"
,"SpineBase"
, the average between"KneeRight"
and"KneeLeft"
, the average between"AnkleRight"
and"AnkleLeft"
, and the average between"FootRight"
and"FootLeft"
.For the Qualisys system, the joints used are
"Head Top"
, the average between"ShoulderTopRight"
and"ShoulderTopLeft"
,"Chest"
, the average between"WaistBackRight"
,"WaistBackLeft"
,"WaistFrontRight"
and"WaistFrontLeft"
, the average between"KneeRight"
and"KneeLeft"
, the average between"AnkleRight"
and"AnkleLeft"
, and the average between"ForefootOutRight"
and"ForefootOutLeft"
.
- Parameters:
verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Returns:
The estimated height of the subject, in meters.
- Return type:
float
- Sequence.get_subject_arm_length(side='left', verbosity=1)
Returns an estimation of the length of the left or right arm of the subject, in meters. The length of the arm is calculated for each pose, and averaged across all poses.
New in version 2.0.
For the Kinect system, the joints used to get the length of the left arm are
"ShoulderLeft"
,"ElbowLeft"
,"WristLeft"
and"HandLeft"
. For the right arm, the joints are their equivalent on the right side.For the Qualisys system, the joints used to get the length of the left arm are
"ShoulderTopLeft"
,"ArmLeft"
,"ElbowLeft"
,"WristOutLeft"
and"HandOutLeft"
. For the right arm, the joints are their equivalent on the right side.
- Parameters:
side (str) – The side of the arm you want to measure, either
"Left"
or"Right"
.verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Returns:
The estimated arm length of the subject, in meters.
- Return type:
float
- Sequence.get_stats(tabled=False)
Returns a series of statistics regarding the sequence.
New in version 2.0.
- Parameters:
tabled (bool, optional) – If set on False (default), the stats are returned as an OrderedDict. If set on True, the stats are returned as two-dimensional list.
- Returns:
If the returned object is an OrderedDict, the keys are the title of a statistic, and the values are their matching value. If the returned object is a two-dimensional list, each sublist contains the title as the first element, and the value as the second element. The statistics included are:
"Path"
: Thepath
attribute of the sequence."Date of recording"
: Output ofSequence.get_printable_date_recording()
."Duration"
: Output ofSequence.get_duration()
(seconds)."Number of poses"
: Output ofSequence.get_number_of_poses()
."Subject height"
: Output ofSequence.get_subject_height()
(meters)."Left arm length"
: Output ofSequence.get_subject_arm_length()
for the left arm (meters)."Right arm length"
: Output ofSequence.get_subject_arm_length()
for the right arm (meters)."Average framerate"
: Output ofSequence.get_average_framerate()
."SD framerate"
: Standard deviation of the framerate of the sequence."Min framerate"
: Output ofSequence.get_min_framerate()
."Max framerate"
: Output ofSequence.get_max_framerate()
."Average velocity X"
: Output ofSequence.get_total_velocity_single_joint()
divided by the total number of poses. This key has one entry per joint label.
- Return type:
OrderedDict or List(List)
Poses
- Sequence.get_poses()
Returns the attribute
poses
of the sequence.New in version 2.0.
- Returns:
A list containing all the Pose objects in the sequence, in chronological order.
- Return type:
list(Pose)
- Sequence.get_pose(pose_index)
Returns the pose instance corresponding to the index passed as parameter.
New in version 2.0.
- Parameters:
pose_index (int) – The index of the pose.
- Returns:
A pose from the sequence.
- Return type:
- Sequence.get_pose_index_from_timestamp(timestamp, method='closest')
Returns the closest pose index from the provided timestamp.
New in version 2.0.
- Parameters:
timestamp (float) – A relative timestamp, in seconds.
method (str, optional) –
This parameter can take multiple values:
If set on
"closest"
(default), returns the closest pose index from the timestamp.If set on
"below"
,"lower"
or"under"
, returns the closest pose index below the timestamp.If set on
"above"
,"higher"
or"over"
, returns the closest pose index above the timestamp.
- Sequence.get_pose_from_timestamp(timestamp, method='closest')
Returns the closest pose from the provided timestamp.
New in version 2.0.
Note
This function is a wrapper for the function
get_pose_index_from_timestamp()
.- Parameters:
timestamp (float) – A relative timestamp.
method (str, optional) –
This parameter can take multiple values:
If set on
"closest"
(default), returns the closest pose index from the timestamp.If set on
"below"
,"lower"
or"under"
, returns the closest pose index below the timestamp.If set on
"above"
,"higher"
or"over"
, returns the closest pose index above the timestamp.
- Sequence.get_number_of_poses()
Returns the number of poses in the sequence.
New in version 2.0.
- Returns:
The number of poses in the sequence.
- Return type:
int
Time
- Sequence.get_timestamps(relative=False)
Returns a list of the timestamps for every pose, in seconds.
New in version 2.0.
- Parameters:
relative (boolean) – Defines if the returned timestamps are relative to the first pose (in that case, the timestamp of the first pose will be 0), or the original timestamps.
- Returns:
List of the timestamps of all the poses of the sequence, in seconds.
- Return type:
list(float)
- Sequence.get_time_between_two_poses(pose_index1, pose_index2)
Returns the difference between the timestamps of two poses, in seconds.
New in version 2.0.
- Parameters:
pose_index1 (int) – The index of the first pose.
pose_index2 (int) – The index of the second pose.
- Returns:
The time difference (in seconds) between the two poses.
- Return type:
float
Note
If the index of the second pose is inferior to the index of the first pose, the difference will be negative.
- Sequence.get_duration()
Returns the duration of the sequence, in seconds.
New in version 2.0.
- Returns:
The duration of the sequence, in seconds.
- Return type:
float
Framerate
- Sequence.get_framerates()
Returns a list of the frequencies of poses per second and a list of the matching timestamps. This function calculates, for each pose, the inverse of the time elapsed since the previous pose (in seconds), in order to obtain a list of framerates across time. It returns the list of framerates, and the corresponding timestamps (starting on the second pose).
New in version 2.0.
- Returns:
list(float) – Framerates for all the poses of the sequence, starting on the second pose.
list(float) – Timestamps of the sequence, starting on the second pose.
Note
Because the framerates are calculated by consecutive pairs of poses, the two lists returned by the function have a length of \(n-1\), with \(n\) being the number of poses of the sequence.
- Sequence.get_framerate()
Returns the number of poses per second of the sequence, only if this one is stable. If the frequency is variable, the function returns an error message.
New in version 2.0.
- Returns:
The number of poses per second for the sequence if this number is stable.
- Return type:
float
- Sequence.get_average_framerate()
Returns the average number of poses per second of the sequence.
New in version 2.0.
- Returns:
Average number of poses per second for the sequence.
- Return type:
float
- Sequence.get_min_framerate()
Returns the minimum frequency of poses per second of the sequence, which is equal to 1 over the maximum time between two poses in the sequence.
New in version 2.0.
- Returns:
Minimum number of poses per second for the sequence.
- Return type:
float
- Sequence.get_max_framerate()
Returns the maximum frequency of poses per second of the sequence, which is equal to 1 over the minimum time between two poses in the sequence.
New in version 2.0.
- Returns:
Maximum number of poses per second for the sequence.
- Return type:
float
Metrics: single joint
- Sequence.get_joint_coordinate_as_list(joint_label, axis)
Returns a list of all the values for one specified axis of a specified joint label.
New in version 2.0.
- Parameters:
joint_label (str) – The label of the joint (e.g.
"Head"
).axis (str) – The required axis (
"x"
,"y"
or"z"
).
- Returns:
A chronological list of the values (in meters) on one axis for the specified joint.
- Return type:
list(float)
Note
The values returned by the function can be paired with the timestamps obtained with
Sequence.get_timestamps()
.
- Sequence.get_joint_distance_as_list(joint_label, axis=None)
Returns a list of all the distances travelled for a specific joint. If an axis is specified, the distances are calculated on this axis only.
New in version 2.0.
- Parameters:
joint_label (str) – The label of the joint (e.g.
"Head"
).axis (str or None, optional) – If specified, the returned distances travelled will be calculated on a single axis. If
None
(default), the distance travelled will be calculated based on the 3D coordinates.
- Returns:
A chronological list of the distances travelled (in meters) for the specified joint.
- Return type:
list(float)
Note
Because the velocities are calculated by consecutive poses, the list returned by the function have a length of \(n-1\), with \(n\) being the number of poses of the sequence.
- Sequence.get_joint_velocity_as_list(joint_label)
Returns a list of all the velocities (distance travelled over time) for a specified joint.
New in version 2.0.
- Parameters:
joint_label (str) – The label of the joint (e.g.
"Head"
).- Returns:
A chronological list of the velocities (in meters per second) for the specified joint.
- Return type:
list(float)
Note
Because the velocities are calculated by consecutive poses, the list returned by the function have a length of \(n-1\), with \(n\) being the number of poses of the sequence.
- Sequence.get_joint_acceleration_as_list(joint_label, absolute=False)
Returns a list of all the accelerations (differences of velocity over time) for a specified joint.
New in version 2.0.
- Parameters:
joint_label (str) – The label of the joint (e.g.
"Head"
).absolute (boolean, optional) – If set on
True
(default), returns the maximum absolute acceleration value. If set onFalse
, returns the maximum acceleration value, even if a negative value has a higher absolute value.
- Returns:
A chronological list of the accelerations (in meters per second squared) for the specified joint.
- Return type:
list(float)
Note
Because the accelerations are calculated by consecutive pairs of poses, the list returned by the function have a length of \(n-2\), with \(n\) being the number of poses of the sequence.
- Sequence.get_joint_time_series_as_list(joint_label, time_series='velocity')
For a specified joint, returns a list containing one of its time series (x coordinate, y coordinate, z coordinate, distance travelled, velocity, or acceleration).
New in version 2.0.
- Parameters:
joint_label (str) – The label of the joint (e.g.
"Head"
).time_series (str, optional) –
Defines the time_series to return to the list. This parameter can be:
"x"
,"y"
or"z"
, to return the values of the coordinate on a specified axis, for each timestamp.The
"distance"
travelled over time (in meters), between consecutive poses.The
"velocity"
, defined by the distance travelled over time (in meters per second), between consecutive poses.The
"acceleration"
, defined by the velocity over time (in meters per second squared), between consecutive pairs of poses.
- Returns:
A chronological list of the velocities (in meters per second) for the specified joint.
- Return type:
list(float)
Note
Because the distances and velocities are calculated by consecutive poses, the list returned by the function have a length of \(n-1\), with \(n\) being the number of poses of the sequence. Following the same idea, accelerations are calculate by consecutive pairs of poses. The list returned by the function would then have a length of \(n-2\).
Metrics: all joints
- Sequence.get_single_coordinates(axis, verbosity=1)
Returns a dictionary containing the values of the coordinates on a single axis for all the joints. The dictionary will contain the joints labels as keys, and a list of coordinates as values. The coordinates are returned in meters.
New in version 2.0.
- Parameters:
axis (str) – The axis from which to extract the coordinate:
"x"
,"y"
or"z"
.verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Returns:
OrderedDict(str – Dictionary with joint labels as keys, and coordinates values on a specified axis as values (in meters), ordered chronologically.
- Return type:
list(float))
- Sequence.get_distances(axis=None, verbosity=1)
Returns a dictionary containing the joint labels as keys, and a list of distances (distance travelled between two poses) as values. Distances are calculated using the
tool_functions.calculate_distance()
function, and are defined by the distance travelled between two poses (in meters). The distances are returned in meters.New in version 2.0.
- Parameters:
axis (str or None, optional) – If specified, the returned distances travelled will be calculated on a single axis. If
None
(default), the distance travelled will be calculated based on the 3D coordinates.verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Returns:
OrderedDict(str – Dictionary with joint labels as keys, and lists of distances travelled as values (in meters), ordered chronologically.
- Return type:
list(float))
Note
Because the distances are calculated between consecutive poses, the lists returned by the function have a length of \(n-1\), with \(n\) being the number of poses of the sequence.
- Sequence.get_distance_between_hands()
Returns a vector containing the distance (in meters) between the two hands across time. If the joint label system is Kinect, the distance will be calculated between
"HandRight"
and"HandLeft"
. If the joint label system is Qualisys, the distance will be calculated between"HandOutRight"
and"HandOutLeft"
.New in version 2.0.
Note
This function is a wrapper for the function
Sequence.get_distance_between_joints()
.- Returns:
A list of distances between the two hands, in meters.
- Return type:
list(float)
- Sequence.get_distance_between_joints(joint_label1, joint_label2)
Returns a vector containing the distance (in meters) between the two joints provided across time.
New in version 2.0.
- Parameters:
joint_label1 (str) – The label of the first joint (e.g.,
"Head"
).joint_label2 (str) – The label of the second joint (e.g.,
"FootRight"
).
- Returns:
A list of distances between the two specified joints, in meters.
- Return type:
list(float)
- Sequence.get_velocities(verbosity=1)
Returns a dictionary containing the joint labels as keys, and a list of velocities (distance travelled over time between two poses) as values. Velocities are calculated using the
tool_functions.calculate_velocity()
function, and are defined by the distance travelled between two poses (in meters), divided by the time elapsed between these two poses (in seconds). The velocities are returned in meters per second.New in version 2.0.
- Parameters:
verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Returns:
OrderedDict(str – Dictionary with joint labels as keys, and lists of velocity as values (in meters per second), ordered chronologically.
- Return type:
list(float))
Note
Because the velocities are calculated between consecutive poses, the lists returned by the function have a length of \(n-1\), with \(n\) being the number of poses of the sequence.
- Sequence.get_accelerations(absolute=False, verbosity=1)
Returns a dictionary containing the joint labels as keys, and a list of accelerations (differences of velocity over time between two poses) as values. Accelerations are calculated using the
tool_functions.calculate_acceleration()
function, and are defined by the difference of velocity between two consecutive pairs of poses (in meters per second), divided by the time elapsed between these last pose of each pair (in seconds). The accelerations are returned in meters per second squared.New in version 2.0.
- Parameters:
absolute (boolean, optional) – If set on
True
, returns the absolute acceleration values. If set onFalse
(default), returns the original, signed acceleration values.verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Returns:
OrderedDict(str – Dictionary with joint labels as keys, and lists of accelerations as values (in meters per second squared), ordered chronologically.
- Return type:
list(float))
Note
Because the accelerations are calculated between consecutive pairs of poses, the lists returned by the function have a length of \(n-2\), with \(n\) being the number of poses of the sequence.
Metrics: max values
- Sequence.get_max_distance_whole_sequence(axis=None)
Returns the single maximum value of the distance travelled between two poses across every joint of the sequence. The distances are first calculated using the
Sequence.get_distances()
function. The distance travelled by a joint is returned in meters.New in version 2.0.
- Parameters:
axis (str or None, optional) – If specified, the returned distances travelled will be calculated on a single axis. If
None
(default), the distance travelled will be calculated based on the 3D coordinates.- Returns:
Maximum value of the distance travelled between two poses across every joint of the sequence, in meters.
- Return type:
float
- Sequence.get_max_velocity_whole_sequence()
Returns the single maximum value of the velocity across every joint of the sequence. The velocities are first calculated using the
Sequence.get_velocities()
function. The velocity of a joint is defined by the distance travelled between two poses (in meters), divided by the time elapsed between these two poses (in seconds). The velocity is returned in meters per second.New in version 2.0.
- Returns:
Maximum value of the velocity across every joint of the sequence, in meters per second.
- Return type:
float
- Sequence.get_max_acceleration_whole_sequence(absolute=True)
Returns the single maximum value of the acceleration across every joint of the sequence. The acceleration values are first calculated using the
Sequence.get_accelerations()
function. The acceleration is defined by the difference of velocity between two consecutive pairs of poses (in meters per second), divided by the time elapsed between these last pose of each pair (in seconds). The accelerations are returned in meters per second squared.New in version 2.0.
- Parameters:
absolute (boolean, optional) – If set on
True
(default), returns the maximum absolute acceleration value. If set onFalse
, returns the maximum acceleration value, even if a negative value has a higher absolute value.- Returns:
Maximum value of the velocity across every joint of the sequence, in meters per second.
- Return type:
float
- Sequence.get_max_distance_single_joint(joint_label, axis=None)
Returns the maximum value of the distance travelled between two poses for a given joint, across the whole sequence. The distances are first calculated using the
Sequence.get_distances()
function. The distance travelled by a joint between two poses is defined in meters.New in version 2.0.
- Parameters:
joint_label (str) – The label of the joint (e.g.
"Head"
).axis (str or None, optional) – If specified, the returned distances travelled will be calculated on a single axis. If
None
(default), the distance travelled will be calculated based on the 3D coordinates.
- Returns:
Maximum value of the distance travelled for a given joint between two poses, in meters.
- Return type:
float
- Sequence.get_max_velocity_single_joint(joint_label)
Returns the maximum value of the velocity for a given joint, across the whole sequence. The velocities are first calculated using the
Sequence.get_velocities()
function. The velocity of a joint is defined by the distance travelled between two poses (in meters), divided by the time elapsed between these two poses (in seconds). The velocity is returned in meters per second.New in version 2.0.
- Parameters:
joint_label (str) – The label of the joint (e.g.
"Head"
).- Returns:
Maximum value of the velocity for a given joint, in meters per second.
- Return type:
float
- Sequence.get_max_acceleration_single_joint(joint_label, absolute=True)
Returns the maximum value of the acceleration for a given joint, across the whole sequence. The acceleration values are first calculated using the
Sequence.get_accelerations()
function. The acceleration is defined by the difference of velocity between two consecutive pairs of poses (in meters per second), divided by the time elapsed between these last pose of each pair (in seconds). The accelerations are returned in meters per second squared.New in version 2.0.
- Parameters:
joint_label (str) – The label of the joint (e.g.
"Head"
).absolute (boolean, optional) – If set on
True
(default), returns the maximum absolute acceleration value. If set onFalse
, returns the maximum acceleration value, even if a negative value has a higher absolute value.
- Returns:
Maximum value of the acceleration for a given joint, in meters per second squared.
- Return type:
float
- Sequence.get_max_distance_per_joint(axis=None)
Returns the maximum value of the distance travelled between two poses for each joint of the sequence. The distances are first calculated using the
Sequence.get_distances()
function. The distance travelled by a joint between two poses is defined in meters.New in version 2.0.
- Parameters:
axis (str or None, optional) – If specified, the returned distances travelled will be calculated on a single axis. If
None
(default), the distance travelled will be calculated based on the 3D coordinates.- Returns:
OrderedDict(str – Dictionary with joint labels as keys, and maximum velocities as values (in meters per second).
- Return type:
float)
- Sequence.get_max_velocity_per_joint()
Returns the maximum value of the velocity for each joint of the sequence. The velocities are first calculated using the
Sequence.get_velocities()
function. The velocity of a joint is defined by the distance travelled between two poses (in meters), divided by the time elapsed between these two poses (in seconds). The velocities are returned in meters per second.New in version 2.0.
- Returns:
OrderedDict(str – Dictionary with joint labels as keys, and maximum velocities as values (in meters per second).
- Return type:
float)
- Sequence.get_max_acceleration_per_joint(absolute=True)
Returns the maximum value of the acceleration for each joint of the sequence. The acceleration values are first calculated using the
Sequence.get_accelerations()
function. The acceleration is defined by the difference of velocity between two consecutive pairs of poses (in meters per second), divided by the time elapsed between these last pose of each pair (in seconds). The accelerations are returned in meters per second squared.New in version 2.0.
- Parameters:
absolute (boolean, optional) – If set on
True
(default), returns the maximum absolute acceleration values. If set onFalse
, returns the maximum acceleration value, even if a negative value has a higher absolute value.- Returns:
OrderedDict(str – Dictionary with joint labels as keys, and maximum accelerations as values (in meters per second squared).
- Return type:
float)
Metrics: total values
- Sequence.get_total_distance_whole_sequence(axis=None)
Returns the sum of the distances travelled by every joint across all the poses of the sequence. This allows to provide a value representative of the global “quantity of movement” produced during the sequence. The distances are first calculated using the Sequence.get_distances() function. The distance travelled by a joint between two poses is defined in meters.
New in version 2.0.
- Parameters:
axis (str or None, optional) – If specified, the returned distances travelled will be calculated on a single axis. If
None
(default), the distance travelled will be calculated based on the 3D coordinates.- Returns:
Sum of the distances travelled across every joint and poses of the sequence, in meters.
- Return type:
float
- Sequence.get_total_velocity_whole_sequence()
Returns the sum of the velocities of every joint across all the poses of the sequence. This allows to provide a value representative of the global “quantity of movement” produced during the sequence. The velocities are first calculated using the Sequence.get_velocities() function. The velocity of a joint is defined by the distance travelled between two poses (in meters), divided by the time elapsed between these two poses (in seconds). The velocities are returned in meters per second.
New in version 2.0.
- Returns:
Sum of the velocities across every joint and poses of the sequence, in meters per second.
- Return type:
float
- Sequence.get_total_acceleration_whole_sequence()
Returns the sum of the absolute accelerations of every joint across all the poses of the sequence. This allows to provide a value representative of the global “quantity of movement” produced during the sequence. The acceleration values are first calculated using the
Sequence.get_accelerations()
function. The acceleration is defined by the difference of velocity between two consecutive pairs of poses (in meters per second), divided by the time elapsed between these last pose of each pair (in seconds). The accelerations are returned in meters per second squared.New in version 2.0.
- Returns:
Sum of the accelerations across every joint and poses of the sequence, in meters per second squared.
- Return type:
float
- Sequence.get_total_distance_single_joint(joint_label, axis=None)
Returns the total distance travelled for a given joint, across the whole sequence. The distances are first calculated using the Sequence.get_joint_distance_as_list() function. The distance travelled by a joint between two poses is defined in meters.
New in version 2.0.
- Parameters:
joint_label (str) – The label of the joint (e.g.
"Head"
).axis (str or None, optional) – If specified, the returned distances travelled will be calculated on a single axis. If
None
(default), the distance travelled will be calculated based on the 3D coordinates.
- Returns:
Sum of the distances travelled across all poses for a single joint, in meters.
- Return type:
float
- Sequence.get_total_velocity_single_joint(joint_label)
Returns the sum of the velocities for a given joint, across the whole sequence. The velocities are first calculated using the Sequence.get_joint_velocity_as_list() function. The velocity of a joint is defined by the distance travelled between two poses (in meters), divided by the time elapsed between these two poses (in seconds). The velocity is returned in meters per second.
New in version 2.0.
- Parameters:
joint_label (str) – The label of the joint (e.g.
"Head"
).- Returns:
Sum of the velocities across all poses for a single joint, in meters per second.
- Return type:
float
- Sequence.get_total_acceleration_single_joint(joint_label)
Returns the sum of the absolute accelerations for a given joint, across the whole sequence. The acceleration values are first calculated using the
Sequence.get_joint_acceleration_as_list()
function. The acceleration is defined by the difference of velocity between two consecutive pairs of poses (in meters per second), divided by the time elapsed between these last pose of each pair (in seconds). The accelerations are returned in meters per second squared.New in version 2.0.
- Parameters:
joint_label (str) – The label of the joint (e.g.
"Head"
).- Returns:
Sum of the accelerations across all poses for a single joint, in meters per second squared.
- Return type:
float
- Sequence.get_total_distance_per_joint(axis=None)
Returns the sum of the distances travelled for each individual joint of the sequence. The distances are first calculated using the Sequence.get_total_distance_single_joint() function. The distance travelled between two poses of a joint is returned in meters.
New in version 2.0.
- Parameters:
axis (str or None, optional) – If specified, the returned distances travelled will be calculated on a single axis. If
None
(default), the distance travelled will be calculated based on the 3D coordinates.- Returns:
OrderedDict(str – Dictionary with joint labels as keys, and sum of distances travelled across all poses as values (in meters).
- Return type:
float)
- Sequence.get_total_velocity_per_joint()
Returns the sum of the velocities for each individual joint of the sequence. The velocities are first calculated using the Sequence.get_total_velocity_single_joint() function. The velocity of a joint is defined by the distance travelled between two poses (in meters), divided by the time elapsed between these two poses (in seconds). The velocities are returned in meters per second.
New in version 2.0.
- Returns:
OrderedDict(str – Dictionary with joint labels as keys, and sum of velocities across all poses as values (in meters per second).
- Return type:
float)
- Sequence.get_total_acceleration_per_joint()
Returns the sum of the absolute acceleration values for each individual joint of the sequence. The acceleration values are first calculated using the
Sequence.get_joint_acceleration_as_list()
function. The acceleration is defined by the difference of velocity between two consecutive pairs of poses (in meters per second), divided by the time elapsed between these last pose of each pair (in seconds). The accelerations are returned in meters per second squared.New in version 2.0.
- Returns:
OrderedDict(str – Dictionary with joint labels as keys, and sum of absolute acceleration values across all poses as values (in meters per second squared).
- Return type:
float)
Correction functions
- Sequence.correct_jitter(velocity_threshold, window, window_unit='poses', method='default', name=None, verbosity=1)
Detects and corrects rapid twitches and jumps in a motion sequence. These rapid movements, typically due to poor automatic detection of a joint in space, result in aberrant, unrealistic displacements from the joints. Though originally developed to handle Kinect data, the algorithm can be used for any 3D-tracked biological movement data having timestamps and X, Y and Z coordinates for each pose. The
velocity_threshold
parameter defines the threshold of velocity, in meters per second, over which a movement is considered as aberrant; thewindow parameter
, defined in individual poses or in milliseconds (via the parameterwindow_unit
), defines the maximum duration of an aberrant movement – if the duration exceeds the window, the joint is corrected and smoothed out for all the poses of the window, using the definedmethod
(linear by default).New in version 2.0.
- Parameters:
velocity_threshold (float) – The threshold of velocity over which a movement is considered as abnormal, hence to correct. It is defined in meters per second. A good threshold must correct jumps and twitches without correcting valid, biological movement (e.g. between 0.1 and 1 m/s).
window (float or int) – The amount of poses (by default) or time allowed for a joint to come back below threshold. If the parameter
window_unit
is set on poses, the window should be adjusted depending on the framerate of the recording. A window of 3 to 5 poses for a Kinect recording between 10 and 15 poses per second has been shown to give good results.window_unit (str, optional) –
The unit for the parameter window.
If set on
"pose"
, the parameterwindow
will be interpreted as a number of poses. Recommended for recordings with variable framerate.If set on
"s"
or"ms"
, the parameterwindow
will be interpreted as being an amount of seconds or milliseconds, respectively. The algorithm will then, on every iteration, calculate the amount of poses that has a duration the closes to the provided window value.
method (str, optional) –
The method as to how smoothen out the data of the joints detected has being part of a twitch or a jump.
If set on
"default"
, the movement is corrected linearly by taking as reference the last pose before the aberrant movement, and the first pose below threshold (in case of a twitch) or the last pose of the window (in case of a jump).If set on
"old"
, the movement is corrected the same way as for default, but the method to check the velocity threshold is based on an old, incorrect version of the algorithm. This option is deprecated and has only been left there for version 2.0 for retro-compatibility and comparisons with old, processed files. This method will be removed in an ulterior release.This parameter also allows for all the values accepted for the
kind
parameter in the functionscipy.interpolate.interp1d()
:"linear"
,"nearest"
,"nearest-up"
,"zero"
,"slinear"
,"quadratic"
,"cubic"
”,"previous"
, and"next"
. See the documentation for this Python module for more. In case one of these values is used, all the corrected joints are first set to (0, 0, 0) by the function, before calling theSequence.correct_zeros()
function to interpolate the missing values.
name (str or None, optional) – Defines the name of the output sequence. If set on
None
, the name will be the same as the input sequence, with the suffix"+CJ"
.verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Returns:
A new sequence having the same amount of poses and timestamps as the original, but with corrected joints coordinates.
- Return type:
- Sequence.re_reference(reference_joint_label='auto', place_at_zero=True, name=None, verbosity=1)
Changes the position of all the joints of a sequence to be relative to the position of a reference joint, across all poses.
New in version 2.0.
- Parameters:
reference_joint_label (str, optional) – The label of the joint to take as reference. If set on
"auto"
, the function will try to detect the presence of"SpineMid"
(Kinect data), or"Chest"
(Qualisys data) and assign it as the reference joint.place_at_zero (boolean, optional) – If set on
True
, the positions of the joint with the labelreference_joint
will be set at coordinate (0, 0, 0). If set onFalse
, the positions of the joint with the label reference_joint will be set at the position from the first pose of the sequence.name (str or None, optional) – Defines the name of the output sequence. If set on
None
, the name will be the same as the input sequence, with the suffix"+RF"
.verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Returns:
A new sequence having the same amount of poses and timestamps as the original, but with re-referenced coordinates.
- Return type:
- Sequence.trim(start=None, end=None, use_relative_timestamps=False, name=None, verbosity=1, add_tabs=0)
Trims a sequence according to a starting timestamp (by default the beginning of the original sequence) and an ending timestamp (by default the end of the original sequence). Timestamps must be provided in seconds.
New in version 2.0.
- Parameters:
start (int or None, optional) – The timestamp after which the poses will be preserved. If set on
None
, the beginning of the sequence will be set as the timestamp of the first pose.end (int or None, optional) – The timestamp before which the poses will be preserved. If set on
None
, the end of the sequence will be set as the timestamp of the last pose.use_relative_timestamps (bool, optional) – Defines if the timestamps
start
andend
refer to the original timestamps or the relative timestamps.name (str or None, optional) – Defines the name of the output sequence. If set on
None
, the name will be the same as the input sequence, with the suffix"+TR"
.verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
add_tabs (int, optional) – Adds the specified amount of tabulations to the verbosity outputs. This parameter may be used by other functions to encapsulate the verbosity outputs by indenting them. In a normal use, it shouldn’t be set by the user.
- Returns:
A new sequence containing a subset of the poses of the original sequence.
- Return type:
- Sequence.trim_to_audio(delay=0, audio=None, name=None, verbosity=1)
Synchronizes the timestamps to the duration of an audio file.
New in version 2.0.
- Parameters:
delay (float, optional) – The relative timestamp after which the poses will be preserved. If set on 0, the first pose will be included in the returned subsequence.
audio (str or Audio or None, optional) – An instance of the Audio class, a string containing the path of the audio file, or
None
. In the case of a string, the function will internally create an instance of the Audio class. In the case where the value is set onNone
, the function will check for a path to the audio file in thepath_audio
attribute (created upon initialization or via theSequence.set_path_audio()
method). If this attribute is alsoNone
, the function will raise an error.name (str or None, optional) – Defines the name of the output sequence. If set on
None
, the name will be the same as the input sequence, with the suffix"+TR"
.verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Returns:
A new sequence containing a subset of the poses of the original sequence.
- Return type:
Note
This function is a wrapper for
Sequence.trim()
, withdelay
set asstart
, and the duration ofaudio
+delay
set asend
.
- Sequence.resample(frequency, mode='cubic', name=None, verbosity=1)
Resamples a sequence with a constant or variable framerate to the frequency parameter. It first creates a new set of timestamps at the desired frequency, and then interpolates the original data to the new timestamps.
New in version 2.0.
- Parameters:
frequency (float) – The frequency, in hertz, at which you want to resample the sequence. A frequency of 4 will return resample joints at 0.25 s intervals.
mode (str, optional) –
This parameter also allows for all the values accepted for the
kind
parameter in the functionscipy.interpolate.interp1d()
:"linear"
,"nearest"
,"nearest-up"
,"zero"
,"slinear"
,"quadratic"
,"cubic"
”,"previous"
, and"next"
. See the documentation for this Python module for more.name (str or None, optional) – Defines the name of the output sequence. If set on
None
, the name will be the same as the input sequence, with the suffix"+RS"
.verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Returns:
A new sequence containing resampled timestamps and joints coordinates.
- Return type:
Warning
This function allows both the upsampling and the downsampling of sequences, along with stabilizing a recording to a constant framerate. However, during any of these operations, the algorithm only estimates the real coordinates of the joints. You should then consider the upsampling (and the downsampling, to a lesser extent) with care. You can control the frequency of your original sequence with
Sequence.get_average_frequency()
,Sequence.get_min_frequency()
andSequence.get_max_frequency()
.
- Sequence.correct_zeros(mode='cubic', name=None, min_duration_warning=0.1, verbosity=1, add_tabs=0)
Detects the joints set at (0, 0, 0) and correct their coordinates by interpolating the data from the neighbouring temporal points. Typically, this function is used to correct the zeroes set by the Qualisys system when a specific joint is not tracked. In the case where an edge pose (first or last pose of the sequence) has (0, 0, 0) coordinates, the closest non-zero coordinate is assigned to the pose. The (0, 0, 0) coordinates are then considered as missing and are new values are interpolated using tool_functions.interpolate_data().
New in version 2.0.
- Parameters:
mode (str, optional) –
This parameter also allows for all the values accepted for the
kind
parameter in the functionscipy.interpolate.interp1d()
:"linear"
,"nearest"
,"nearest-up"
,"zero"
,"slinear"
,"quadratic"
,"cubic"
”,"previous"
, and"next"
. See the documentation for this Python module for more.name (str or None, optional) – Defines the name of the output sequence. If set on
None
, the name will be the same as the input sequence, with the suffix"+CZ"
.min_duration_warning (float, optional) – Defines the time over which an uninterrupted series of (0, 0, 0) coordinates will trigger a warning if the parameter verbosity is 1 or more.
verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
add_tabs (int, optional) – Adds the specified amount of tabulations to the verbosity outputs. This parameter may be used by other functions to encapsulate the verbosity outputs by indenting them. In a normal use, it shouldn’t be set by the user.
- Returns:
A new sequence having the same amount of poses and timestamps as the original, but with re-referenced coordinates.
- Return type:
Warning
Please note that for long series of 0 coordinates, the interpolation of the data may not be accurate. When running this function with a verbosity of 1 or more, the longest duration of a 0 coordinate will be displayed.
- Sequence.randomize(verbosity=1)
Returns a sequence that randomizes the starting position of all the joints of the original sequence. The randomization follows a uniform distribution:
x coordinate randomized between -0.2 and 0.2
y coordinate randomized between -0.3 and 0.3
z coordinate randomized between -0.5 and 0.5
The randomization preserves the direction of movement, timestamps and all the other metrics of the sequence; the starting position only of the joints is randomized, and the coordinates of the joints of the subsequent poses are adapted using the new starting position as reference.
New in version 2.0.
- Parameters:
verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Returns:
A new sequence having the same amount of poses and timestamps as the original, but with randomized starting coordinates. The attribute
randomized
of this new Sequence will be set on True.- Return type:
Copy functions
- Sequence.copy_pose(pose_index)
Returns a deep copy of a specified pose.
New in version 2.0.
- Parameters:
pose_index (int) – The index of the pose to copy (starting at 0).
- Returns:
The copy of a Pose instance.
- Return type:
- Sequence.copy_joint(pose_index, joint_label)
Returns a deep copy of a specified joint from a specified pose.
New in version 2.0.
- Parameters:
pose_index (int) – The index of the pose to copy (starting at 0).
joint_label (str) – The label of the joint (e.g.
"Head"
).
- Returns:
The copy of a Joint instance.
- Return type:
Print functions
- Sequence.print_pose(pose_index)
Prints the information related to one specific pose of the sequence.
New in version 2.0.
- Parameters:
pose_index (int) – The index of the pose to copy (starting at 0).
- Sequence.print_stats()
Prints a series of statistics related to the sequence, using the output of the function
Sequence.get_stats()
.New in version 2.0.
Conversion functions
- Sequence.convert_to_table(use_relative_timestamps=False)
Returns a list of lists where each sublist contains a timestamp and the coordinates for each joint. The coordinates are grouped by sets of three, with the values on the x, y and z axes respectively. The first sublist contains the headers of the table. The output then resembles the table found in Tabled formats.
New in version 2.0.
- Parameters:
use_relative_timestamps (bool, optional) – Defines if the timestamps used in the table are absolute (
False
) or relative to the first pose (True
).- Returns:
A list of lists that can be interpreted as a table, containing headers, and with the timestamps and the coordinates of the joints from the sequence on each row.
- Return type:
list(list)
- Sequence.convert_to_json(use_relative_timestamps=False)
Returns a list ready to be exported in JSON. The structure followed by the dictionary is the same as the output dictionary from Kinect, for compatibility purposes. The output then resembles the table found in JSON formats.
New in version 2.0.
- Parameters:
use_relative_timestamps (bool, optional) – Defines if the timestamps used in the table are absolute (
False
) or relative to the first pose (True
).- Returns:
A list containing the data of the sequence, ready to be exported in JSON.
- Return type:
list
Saving functions
- Sequence.save(folder_out='', name=None, file_format='json', individual=False, use_relative_timestamps=True, verbosity=1)
Saves a sequence in a file or a folder. The function saves the sequence under
folder_out/name.file_format
. All the non-existent subfolders present in thefolder_out
path will be created by the function. The function also updates thepath
attribute of the Sequence.New in version 2.0.
- Parameters:
folder_out (str, optional) – The path to the folder where to save the file or files. If one or more subfolders of the path do not exist, the function will create them. If the string provided is empty (by default), the sequence will be saved in the current working directory. If the string provided contains a file with an extension, the fields
name
andfile_format
will be ignored.name (str or None, optional) – Defines the name of the file or files where to save the sequence. If set on
None
, the name will be set on the attributename
of the sequence; if that attribute is also set onNone
, the name will be set on"out"
. Ifindividual
is set onTrue
, each pose will be saved as a different file, having the index of the pose as a suffix after the name (e.g. if the name is"pose"
and the file format is"txt"
, the poses will be saved aspose_0.txt
,pose_1.txt
,pose_2.txt
, etc.).file_format (str or None, optional) –
The file format in which to save the sequence. The file format must be
"json"
(default),"xlsx"
,"txt"
,"csv"
,"tsv"
, or, if you are a masochist,"mat"
. Notes:"xls"
will save the file with an.xlsx
extension.Any string starting with a dot will be accepted (e.g.
".csv"
instead of"csv"
)."csv;"
will force the value separator on;
, while"csv,"
will force the separator on,
. By default, the function will detect which separator the system uses."txt"
and"tsv"
both separate the values by a tabulation.Any other string will not return an error, but rather be used as a custom extension. The data will be saved as in a text file (using tabulations as values separators).
Warning
While it is possible to save sequences as
.mat
or custom extensions, the toolbox will not recognize these files upon opening. The support for.mat
and custom extensions as input may come in a future release, but for now these are just offered as output options.individual (bool, optional) – If set on
False
(default), the function will save the sequence in a unique file. If set onTrue
, the function will save each pose of the sequence in an individual file, appending an underscore and the index of the pose (starting at 0) after the name.use_relative_timestamps (bool, optional) – Defines if the timestamps that will be saved are absolute (
False
) or relative to the first pose (True
).verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Sequence.save_stats(folder_out='', name=None, file_format='json', keys_to_exclude=None, keys_to_include=None, verbosity=1)
Saves the statistics provided by :meth:
Sequence.get_stats
on the disk.New in version 2.0.
- Parameters:
folder_out (str, optional) – The path to the folder where to save the file containing the stats. If one or more subfolders of the path do not exist, the function will create them. If the string provided is empty (by default), the sequence will be saved in the current working directory. If the string provided contains a file with an extension, the fields
name
andfile_format
will be ignored.name (str, optional) – Defines the name of the file or files where to save the stats. If set on
None
, the name will be set on"stats_"
plus the attributename
of the sequence; if that attribute is also set onNone
, the name will be set on"stats"
.file_format (str, optional) –
The file format in which to save the stats. The file format must be
"json"
(default),"xlsx"
,"txt"
,"csv"
,"tsv"
, or, if you are a masochist,"mat"
. Notes:"xls"
will save the files with an.xlsx
extension.Any string starting with a dot will be accepted (e.g.
".csv"
instead of"csv"
)."csv;"
will force the value separator on;
, while"csv,"
will force the separator on,
. By default, the function will detect which separator the system uses."txt"
and"tsv"
both separate the values by a tabulation.Any other string will not return an error, but rather be used as a custom extension. The data will be saved as in a text file (using tabulations as values separators).
keys_to_exclude (list(str) or None, optional) – A list of the stats that you do not wish to save. Each string must be a valid entry among the keys saved by the function
Sequence.get_stats()
. If set onNone
, all the stats will be saved, unless some keys are specified inkeys_to_include
.keys_to_include (list(str) or None, optional) – A list of the stats that you wish to save. Each string must be a valid entry among the keys saved by the function
Sequence.get_stats()
. If set onNone
, all the stats will be saved, unless some keys are specified inkeys_to_exclude
. If at least one key is entered, all the absent keys will not be saved. This parameter will only be considered ifkeys_to_exclude
is None.verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
Miscellaneous functions
- Sequence.average_qualisys_to_kinect(joints_labels_to_exclude=None, remove_averaged_joints=False, remove_non_kinect_joints=False)
Creates missing Kinect joints from the Qualisys labelling system by averaging the distance between Qualisys joints. The new joints are located at the midpoint of the arithmetic distance between two or more joints. The list of averaged joints is set from the
res/kualisys_to_kinect.txt
file:New joint
Averaged joints
Head
HeadTop
HeadFront
HeadRight
HeadLeft
Neck
Head
SpineShoulder
ShoulderLeft
ShoulderTopLeft
ShoulderTopRight
ShoulderRight
ShoulderTopRight
ShoulderBackRight
SpineMid
Chest
BackRight
BackLeft
HipLeft
WaistBackLeft
WaistFrontLeft
HipRight
WaistBackRight
WaistFrontRight
SpineBase
HipLeft
HipRight
WristLeft
WristOutLeft
WristInLeft
WristRight
WristOutRight
WristInRight
HandLeft
HandOutLeft
HandInLeft
HandRight
HandOutRight
HandInRight
FootLeft
ForefootOutLeft
ForefootInLeft
ToetipLeft
HeelLeft
FootRight
ForefootOutRight
ForefootInRight
ToetipRight
HeelRight
New in version 2.0.
- Parameters:
joints_labels_to_exclude (list(str) or None, optional) – List of joint labels that will not be created from the function.
remove_averaged_joints (bool, optional) – If
True
, removes the joints that are part of an averaging from every pose of the sequence.remove_non_kinect_joints (bool, optional) – If
True
, removes the joints from Qualisys that are not found in the Kinect labelling system.
- Sequence.average_joints(joints_labels_to_average, new_joint_label, remove_averaged_joints=False)
Create a joint located at the average arithmetic distance of specified joint labels.
New in version 2.0.
- Parameters:
joints_labels_to_average (list(str)) – A list of the labels of the joints to average.
new_joint_label (str) – The label of the newly created joint.
remove_averaged_joints (bool, optional) – If
True
, removes the joints that are part of an averaging from every pose of the sequence.
- Sequence.concatenate(other, delay)
Adds all the poses of another sequence at the end of the sequence.
New in version 2.0.
- Parameters:
other (
Sequence
) – The sequence to concatenate.delay (float) – The delay to apply, in seconds, between the last pose of the original sequence and the first pose of the new sequence.
Private methods
Initialisation functions
- Sequence._define_name_init(name, path, verbosity=1)
Sets the name attribute for an instance of the Sequence class, using the name provided during the initialization, or the path. If no
name
is provided, the function will create the name based on thepath
provided, by defining the name as the last element of the path hierarchy (last subfolder, or file name). For example, ifpath
is"C:/Users/Darlene/Documents/Recording001/"
, the function will define the name on"Recording001"
. If bothname
andpath
are set onNone
, the sequence name will be defined as"Unnamed sequence"
.New in version 2.0.
- Parameters:
name (str) – The name passed as parameter in
Sequence.__init__()
path (str) – The path passed as parameter in
Sequence.__init__()
verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Sequence._load_from_path(verbosity=1)
Loads the sequence data from the
path
provided during the initialization, and calculates the relative timestamps from the first pose for each pose.New in version 2.0.
- Parameters:
verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Sequence._fetch_files_from_folder(verbosity=1)
Finds all the files ending with the accepted extensions (
.csv
,.json
,.tsv
,.txt
, or.xlsx
) in the folder defined by path, and orders the files according to their name.New in version 2.0.
Note
- This functions ignores the elements of the directory defined by
path
if: They don’t have an extension
They are a folder
Their extension is not one of the accepted ones (
.csv
,.json
,.tsv
,.txt
, or.xlsx
)The file name does not contain an underscore (
_
)
If a file has a valid extension, the function tries to detect an underscore (
_
) in the name. The file names should bexxxxxx_0.ext
, wherexxxxxx
can be any series of characters,0
must be the index of the pose (with or without leading zeros), andext
must be an accepted extension (.csv
,.json
,.tsv
,.txt
, or.xlsx
). The first pose of the sequence must have the index 0. If the file does not have an underscore in the name, it is ignored. The indices must be coherent with the chronological order of the timestamps.The function uses the number after the underscore to order the poses. This is due to differences in how file systems handle numbers without leading zeros: some place
pose_11.json
alphabetically beforepose_2.json
(1 comes before 2), while some other systems place it after as 11 is greater than 2. In order to avoid these, the function converts the number after the underscore into an integer to place it properly according to its index.- Parameters:
verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- This functions ignores the elements of the directory defined by
- Sequence._load_poses(verbosity=1)
Loads the single pose files or the global file containing all the poses. Depending on the input, this function calls either
Sequence._load_single_pose_file()
orSequence._load_sequence_file()
.New in version 2.0.
- Parameters:
verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Sequence._load_single_pose_file(pose_index, path, verbosity=1)
Loads the content of a single pose file into a Pose object. Depending on the file type, this function handles the content differently (see Compatible files).
- Parameters:
pose_index (int) – The index of the pose.
path (str) – The path of a file containing a single pose.
verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Sequence._load_sequence_file(verbosity=1)
Loads the content of a global sequence file containing individual poses into Pose objects. Depending on the file type, this function handles the content differently (see Compatible files).
- Parameters:
verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Sequence._create_pose_from_table_row(table, row=1)
Reads the content of a table, considering the first row as containing headers, and converts the content of a specific row into a pose.
New in version 2.0.
- Parameters:
table (list(list)) – A table, where the first elements are the headers.
row (int, optional) – The row containing the data of the pose. 0 being the header row, row should be 1 or more.
- Sequence._create_pose_from_json(data)
Reads the content of a json file containing a single pose, and converts the content of a specified pose index into a pose object.
New in version 2.0.
- Parameters:
data (list or dict) – The content of a json file.
- Sequence._load_date_recording(data, verbosity=1)
Loads the date of a recording from the information contained in the file(s). For recordings performed with the Qualisys system, the function simply gets the date from the line starting with
"TIME_STAMP"
. For the recordings performed with Kinect, the timestamp value of the first pose is converted to a date.New in version 2.0.
- Parameters:
data (dict or list) – The data from the file containing the full recording, or containing the first pose of the recording.
verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Sequence._calculate_relative_timestamps()
For all the poses of the sequence, sets and converts the relative_timestamp attribute taking the first pose of the sequence as reference. This function is called internally any time a sequence is created. It first defines the unit if the attribute
time_unit
is set on"auto"
. To do so, it checks if the difference between the timestamps of the two first poses of the sequence:If it is over 1000, the function presumes that the unit is in hundreds of ns (C# precision unit, Kinect output unit).
If it is between 1 and 1000, it presumes that the unit is in milliseconds (Qualisys output unit).
If it is below that threshold, or if there is only one pose in the sequence, it presumes that the unit is in seconds.
Otherwise, it is possible to manually define the unit, among the following values:
"ns"
,"1ns"
,"10ns"
,"100ns"
,"µs"
,"1µs"
,"10µs"
,"100µs"
,"ms"
,"1ms"
,"10ms"
,"100ms"
,"s"
,"sec"
,"1s"
,"min"
,"mn"
,"h"
,"hr"
,"d"
,"day"
.New in version 2.0.
Correction functions
- Sequence._correct_jitter_window(new_sequence, start_pose_index, end_pose_index, joint_label, number_of_realigned_points, verbosity=1)
Corrects linearly the jumps and twitches of the positions of a joint, between two given time points. This is a sub-function of
Sequence.correct_jitter()
.For a given
joint_label
, and two time pointsstart_pose_number
andend_pose_number
between which a movement has been detected as being over threshold by the functionSequence.correct_jitter()
, this function corrects the position of the joint between the two time points, by calling the functionSequence._correct_jitter_single_joint()
for each individual time point. This function does not perform the correction if the size of the window is of size 0 or 1.New in version 2.0.
- Parameters:
new_sequence (Sequence) – Corrected sequence that is used by and will be returned by
Sequence.correct_jitter()
.start_pose_index (int) – Last pose index before the jump or twitch.
end_pose_index (int) – First pose index after the jump or twitch.
joint_label (str) – The label of the joint (e.g.
"Head"
).number_of_realigned_points (int) – The number of time points corrected since the beginning of the execution of
Sequence.correct_jitter()
.verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Returns:
Sequence – Sequence provided in input with corrected window.
int – Number of time points corrected, provided in input, incremented by the number of corrections performed.
- Sequence._correct_jitter_single_joint(joint_before, joint_after, pose_index_before, pose_index_current, pose_index_after, verbosity=1)
Corrects linearly a Joint object following the algorithm in
Sequence.correct_jitter()
. Given ajoint_before
on posepose_index_before
(last pose before the jump or twitch) andjoint_after
on posepose_index_after
(first pose after the jump on twitch), this function calculates the percentage of time elapsed atpose_index_current
and uses this percentage as a ratio to calculate and return the new position of the x, y and z coordinates.New in version 2.0.
- Parameters:
joint_before (Joint) – Last joint before the detected jump or twitch.
joint_after (Joint) – First joint after the detected jump or twitch.
pose_index_before (int) – Pose index of
joint_before
.pose_index_current (int) – Pose index of the joint being corrected.
pose_index_after (int) – Pose index of
joint_after
.verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Returns:
int – Corrected x coordinate.
int – Corrected y coordinate.
int – Corrected z coordinate.
Saving functions
- Sequence._save_json(folder_out, name=None, individual=False, use_relative_timestamps=False, verbosity=1)
Saves a sequence as a json file or files. This function is called by the
Sequence.save()
method, and saves the Sequence instance asfolder_out/name.file_format
.New in version 2.0.
- Parameters:
folder_out (str) – The path to the folder where to save the file or files. If one or more subfolders of the path do not exist, the function will create them.
name (str or None, optional) – Defines the name of the file or files where to save the sequence. If set on
None
, the name will be set on"out"
if individual isFalse
, or on"pose"
if individual isTrue
.individual (bool, optional) – If set on
False
(default), the function will save the sequence in a unique file. If set onTrue
, the function will save each pose of the sequence in an individual file, appending an underscore and the index of the pose (starting at 0) after the name.use_relative_timestamps (bool, optional) – Defines if the timestamps used in the table are absolute (
False
) or relative to the first pose (True
).verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Sequence._save_mat(folder_out, name=None, individual=False, use_relative_timestamps=True, verbosity=1)
Saves a sequence as a Matlab .mat file or files. This function is called by the
Sequence.save()
method, and saves the Sequence instance asfolder_out/name.file_format
.New in version 2.0.
Important
This function is dependent of the module scipy.
- Parameters:
folder_out (str) – The path to the folder where to save the file or files. If one or more subfolders of the path do not exist, the function will create them.
name (str or None, optional) – Defines the name of the file or files where to save the sequence. If set on
None
, the name will be set on"out"
if individual isFalse
, or on"pose"
if individual isTrue
.individual (bool, optional) – If set on
False
(default), the function will save the sequence in a unique file. If set onTrue
, the function will save each pose of the sequence in an individual file, appending an underscore and the index of the pose (starting at 0) after the name.use_relative_timestamps (bool, optional) – Defines if the timestamps used in the table are absolute (
False
) or relative to the first pose (True
).verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Sequence._save_xlsx(folder_out, name=None, individual=False, use_relative_timestamps=True, verbosity=1)
Saves a sequence as an Excel .xlsx file or files. This function is called by the
Sequence.save()
method, and saves the Sequence instance asfolder_out/name.file_format
.New in version 2.0.
Important
This function is dependent of the module openpyxl.
- Parameters:
folder_out (str) – The path to the folder where to save the file or files. If one or more subfolders of the path do not exist, the function will create them.
name (str or None, optional) – Defines the name of the file or files where to save the sequence. If set on
None
, the name will be set on"out"
if individual isFalse
, or on"pose"
if individual isTrue
.individual (bool, optional) – If set on
False
(default), the function will save the sequence in a unique file. If set onTrue
, the function will save each pose of the sequence in an individual file, appending an underscore and the index of the pose (starting at 0) after the name.use_relative_timestamps (bool, optional) – Defines if the timestamps used in the table are absolute (
False
) or relative to the first pose (True
).verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Sequence._save_txt(folder_out, name=None, file_format='csv', individual=False, use_relative_timestamps=True, verbosity=1)
Saves a sequence as .txt, .csv, .tsv, or custom extension files or file. This function is called by the
Sequence.save()
method, and saves the Sequence instance asfolder_out/name.file_format
.New in version 2.0.
- Parameters:
folder_out (str) – The path to the folder where to save the file or files. If one or more subfolders of the path do not exist, the function will create them.
name (str or None, optional) – Defines the name of the file or files where to save the sequence. If set on
None
, the name will be set on"out"
if individual isFalse
, or on"pose"
if individual isTrue
.file_format (str, optional) – The file format in which to save the sequence. The file format can be
"txt"
,"csv"
(default) or"tsv"
."csv;"
will force the value separator on";"
, while"csv,"
will force the separator on","
. By default, the function will detect which separator the system uses."txt"
and"tsv"
both separate the values by a tabulation. Any other string will not return an error, but rather be used as a custom extension. The data will be saved as in a text file (using tabulations as values separators).individual (bool, optional) – If set on
False
(default), the function will save the sequence in a unique file. If set onTrue
, the function will save each pose of the sequence in an individual file, appending an underscore and the index of the pose (starting at 0) after the name.use_relative_timestamps (bool, optional) – Defines if the timestamps used in the table are absolute (
False
) or relative to the first pose (True
).verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
Miscellaneous functions
- Sequence._create_new_sequence_with_timestamps(verbosity=1)
Creates a sequence with the same number of poses as in the original, but only containing timestamps. This function is used by
Sequence.correct_jitter()
andSequence.re_reference()
to obtain placeholder poses. The sequence created has the same number of Pose objects as the original sequence in theposes
attribute; however, for every Pose object, the attributejoints
is an OrderedDict that has the joint labels as keys, butNone
as values, apart from the first pose, that preserves the coordinates for all the joints; the attributespose_number
andtimestamp
are preserved from the original sequence.New in version 2.0.
- Parameters:
verbosity (int, optional) –
Sets how much feedback the code will provide in the console output:
0: Silent mode. The code won’t provide any feedback, apart from error messages.
1: Normal mode (default). The code will provide essential feedback such as progression markers and current steps.
2: Chatty mode. The code will provide all possible information on the events happening. Note that this may clutter the output and slow down the execution.
- Returns:
A
Sequence
instance that has the same number of Pose objects as the original sequence in theposes
attribute; however, for every Pose object, the attributejoints
is an OrderedDict that has the joint labels as keys, butNone
as values, apart from the first pose, that preserves the coordinates for all the joints; the attributespose_number
andtimestamp
are preserved from the original sequence.- Return type: