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 is None, 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() and sequence_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, see Sequence._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 function Sequence._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 function Sequence._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)

poses

List of all the Pose objects of the Sequence.

Type:

list(Pose)

randomized

Testifies if the starting position of the joints have been randomized by the function Sequence.randomize(). Is False 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:

Pose

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
class classes.sequence.Sequence.__eq__(self, other)

Returns True if all the poses in the attribute poses have identical joints between the two Sequence objects.

New in version 2.0.

Parameters:

other (Sequence) – Another Sequence object.

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() and graphic_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:

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:

Pose

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 on False, 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 on False (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 on False, 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 on False, 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 on False, 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; the window parameter, defined in individual poses or in milliseconds (via the parameter window_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 defined method (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 parameter window will be interpreted as a number of poses. Recommended for recordings with variable framerate.

    • If set on "s" or "ms", the parameter window 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 function scipy.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 the Sequence.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

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 label reference_joint will be set at coordinate (0, 0, 0). If set on False, 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

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 and end 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

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 on None, the function will check for a path to the audio file in the path_audio attribute (created upon initialization or via the Sequence.set_path_audio() method). If this attribute is also None, 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:

Sequence

Note

This function is a wrapper for Sequence.trim(), with delay set as start, and the duration of audio + delay set as end.

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 function scipy.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:

Sequence

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() and Sequence.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 function scipy.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:

Sequence

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:

Sequence

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:

Pose

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:

Joint

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 the folder_out path will be created by the function. The function also updates the path 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 and file_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 attribute name of the sequence; if that attribute is also set on None, the name will be set on "out". If individual is set on True, 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 as pose_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 on True, 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 and file_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 attribute name of the sequence; if that attribute is also set on None, 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 on None, all the stats will be saved, unless some keys are specified in keys_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 on None, all the stats will be saved, unless some keys are specified in keys_to_exclude. If at least one key is entered, all the absent keys will not be saved. This parameter will only be considered if keys_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 the path provided, by defining the name as the last element of the path hierarchy (last subfolder, or file name). For example, if path is "C:/Users/Darlene/Documents/Recording001/", the function will define the name on "Recording001". If both name and path are set on None, 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 be xxxxxx_0.ext, where xxxxxx can be any series of characters, 0 must be the index of the pose (with or without leading zeros), and ext 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 before pose_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.

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() or Sequence._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 points start_pose_number and end_pose_number between which a movement has been detected as being over threshold by the function Sequence.correct_jitter(), this function corrects the position of the joint between the two time points, by calling the function Sequence._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 a joint_before on pose pose_index_before (last pose before the jump or twitch) and joint_after on pose pose_index_after (first pose after the jump on twitch), this function calculates the percentage of time elapsed at pose_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 as folder_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 is False, or on "pose" if individual is True.

  • individual (bool, optional) – If set on False (default), the function will save the sequence in a unique file. If set on True, 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 as folder_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 is False, or on "pose" if individual is True.

  • individual (bool, optional) – If set on False (default), the function will save the sequence in a unique file. If set on True, 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 as folder_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 is False, or on "pose" if individual is True.

  • individual (bool, optional) – If set on False (default), the function will save the sequence in a unique file. If set on True, 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 as folder_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 is False, or on "pose" if individual is True.

  • 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 on True, 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() and Sequence.re_reference() to obtain placeholder poses. The sequence created has the same number of Pose objects as the original sequence in the poses attribute; however, for every Pose object, the attribute joints is an OrderedDict that has the joint labels as keys, but None as values, apart from the first pose, that preserves the coordinates for all the joints; the attributes pose_number and timestamp 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 the poses attribute; however, for every Pose object, the attribute joints is an OrderedDict that has the joint labels as keys, but None as values, apart from the first pose, that preserves the coordinates for all the joints; the attributes pose_number and timestamp are preserved from the original sequence.

Return type:

Sequence