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 krajjat.classes.sequence.Sequence(path=None, path_audio=None, name=None, condition=None, time_unit='auto', system='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, 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 _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().
system (str or None, optional) – Defines the type of system used to record the sequence. Can be manually set on "kinect", "qualisys", "kualisys", or "auto" (default). If set on "auto", the function will try to detect the type of system based on the joint labels present in the recording. This parameter can also be set on None. In that case, the functions using pre-sets for the aforementioned systems might not work properly.
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

condition

Defines in which experimental condition the sequence was recorded.

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)

is_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

metadata

A dictionary containing metadata about the recording, extracted from the file.

Type:: dict

time_unit

The time unit of the timestamps.

Type:: str

joint_labels

A list containing the joint labels present in each pose of the sequence.

Type:: list(str)

Examples

>>> seq1 = Sequence("sequences/John/seq_001.tsv")
>>> seq2 = Sequence("sequences/Paul/seq_001.xlsx", name="Paul_001")
>>> seq3 = Sequence(name="George_001")
>>> seq4 = Sequence("sequences/Ringo/seq_001.json", name="Ringo_001", condition="English", time_unit="ms", system="Kinect", verbosity=0)
>>> seq5 = Sequence()

Magic methods

Sequence.__len__()

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)
802701

Sequence.__getitem__(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)

Sequence.__repr__()

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

Sequence.__eq__(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

>>> seq7 = Sequence("C:/Users/Mario/Sequences/seq7/seq7.tsv")
>>> seq7.name
seq7
>>> seq7.set_name("Sequence story telling 7")
>>> seq7.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.

Examples

>>> seq8 = Sequence("C:/Users/Harold/Sequences/English/seq8.xlsx")
>>> seq8.set_condition("English")
>>> seq9 = Sequence("C:/Users/Harold/Sequences/Spanish/seq9.xlsx")
>>> seq9.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.

Example

>>> seq10 = Sequence("C:/Users/Link/Sequences/seq_10.xlsx")
>>> seq10.set_path_audio("C:/Users/Link/Audios/audio_10.wav")

Sequence.set_first_timestamp(first_timestamp, time_unit='s')

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|int) – The new timestamp of the first pose of the sequence.
time_unit (str, optional) – The unit of time of first_timestamp (default: "s"). 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".

Note

If 0 is passed as a parameter, the absolute timestamps of the sequence will be equal to its relative timestamps.

Example

>>> seq11 = Sequence("C:/Users/MarkS/Sequences/seq_11.xlsx")
>>> seq11.get_timestamps()
[0, 0.1, 0.2]
>>> seq11.set_first_timestamp(4.8)
>>> seq11.get_timestamps()
[4.8, 4.9, 5.0]

Sequence.set_date_recording(date)

Sets the date_recording attribute of the Sequence instance.

New in version 2.0.

Parameters:: date (datetime) – A datetime object representing the date of the recording.

Example

Pose functions

Sequence.add_pose(pose, replace_if_exists=False, verbosity=1)

Adds a pose to the sequence.

New in version 2.0.

Parameters:

pose (Pose) – A Pose instance.
replace_if_exists (bool, optional) – If True, replaces the pose if it already exists in the sequence. If False (default), returns an error if the Sequence object contains a Pose with the same timestamp as the one being added.
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.

Raises:

PoseAlreadyExistsException – If a pose with the same timestamp already exists in the sequence.

Example

>>> joint = Joint("Head", 1, 2, 3)
>>> pose = Pose(1)
>>> pose.add_joint(joint)
>>> seq = Sequence()
>>> seq.add_pose(pose)

Sequence.add_poses(*poses, replace_if_exists=False, verbosity=1)

Adds poses to the sequence.

New in version 2.0.

Parameters:

poses (Pose) – One or multiple Pose instances.
replace_if_exists (bool, optional) – If True, replaces the pose if it already exists in the sequence. If False (default), returns an error if the Sequence object contains a Pose with the same timestamp as the one being added.
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.

Raises:

PoseAlreadyExistsException – If a pose with the same timestamp already exists in the sequence.

Example

>>> pose1 = Pose(1)
>>> pose2 = Pose(2)
>>> pose3 = Pose(3)
>>> seq = Sequence()
>>> seq.add_poses(pose1, pose2, pose3)

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

Examples

>>> sequence = Sequence("recordings/sequence_12.tsv")
>>> sequence.get_path()
recordings\sequence_12.tsv
>>> sequence = Sequence("test_sequences/test_sequence_individual/*.tsv")
>>> sequence.get_path()
test_sequences\test_sequence_individual

Sequence.get_name()

Returns the attribute name of the sequence.

New in version 2.0.

Returns:: The name of the sequence.
Return type:: str

Examples

>>> sequence = Sequence("test_sequence_13.tsv")
>>> sequence.get_name()
test_sequence_13.tsv
>>> sequence = Sequence("test_sequence_14.tsv", name="seq_14")
>>> sequence.get_name()
seq_15
>>> sequence = Sequence("test_sequence_individual/*.tsv", name="seq_15")
>>> sequence.get_name()
test_sequence_indiviual
>>> sequence = Sequence()
>>> sequence.get_name()
Unnamed sequence

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

Examples

>>> sequence = Sequence("test_sequence_16.tsv")
>>> sequence.get_condition()
None
>>> sequence = Sequence("test_sequence_17.tsv", condition="English")
>>> sequence.get_condition()
English

Sequence.get_system()

Returns the attribute system of the sequence.

New in version 2.0.

Returns:: The recording system used to perform the recording.
Return type:: str

Examples

>>> sequence = Sequence("sequences/kinect/sequence_18.json")
>>> sequence.get_system()
kinect
>>> sequence = Sequence("sequences/qualisys/sequence_19.tsv")
>>> sequence.get_system()
qualisys

Sequence.get_joint_labels()

Returns the joint labels present in each pose of the Sequence.

New in version 2.0.

Returns:: The list of the joint labels present in each pose of the Sequence.
Return type:: list

Example

>>> sequence = Sequence("Sequences/Fiona/sequence_20.tsv")
>>> sequence.get_joint_labels()
["Head", "HandRight", "HandLeft"]

Sequence.get_number_of_joints()

Returns the number of joints in each pose of the sequence.

New in version 2.0.

Returns:: The number of joints in each pose of the sequence.
Return type:: int

Example

>>> sequence = Sequence("Sequences/Kinect/sequence_21.json")
>>> sequence.get_number_of_joints()
21

Sequence.get_date_recording(return_type='datetime')

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.

Parameters:: return_type (str, optional) – The format of the date to return. By default, “datetime” is used. If set on “str”, a string containing the weekday, day, month (in letters), year, hour (24-hour format), minutes and seconds will be returned (e.g. "Wednesday 21 October 2015, 07:28:00").
Returns:: The date and time of the first frame of the recording.
Return type:: datetime|str

Example

>>> sequence = Sequence("Sequences/Arthur/sequence_22.json")
>>> sequence.get_date_recording()
datetime.datetime(2015, 10, 21, 7, 28, 0)
>>> sequence.get_date_recording("str")
Wednesday 21 October 2015, 07:28:00

Sequence.get_subject_height(joints_list=None, 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".

Note

This method is based on estimations and might not reflect the true height of the subjects - which depends also on the quality of the data.

Parameters:

joints_list (list, optional) – A list of joint labels, of which the successive distances will be calculated. If set on None (default), this parameter is ignored and the height is estimated by using the pre-set joints listed above. If set, the joints used in this parameter replace the presets.
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

Raises:

NoExistingJointListPresetException – If the recording system is not set for a Sequence instance.
InvalidJointLabelException – If at least one joint in a preset is missing from the Sequence instance.

Example

>>> sequence = Sequence("Sequences/Nora/sequence_23.json")
>>> sequence.get_subject_height()
1.7356669872340

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

Raises:

NoExistingJointListPresetException – If the recording system is not set for a Sequence instance.
InvalidJointLabelException – If at least one joint in a preset is missing from the Sequence instance.

Example

>>> sequence = Sequence("Sequences/Nora/sequence_23.json")
>>> sequence.get_subject_arm_length("left")
0.7321786536565029

Sequence.get_info(return_type='dict', full=True, verbosity=1)

Returns information and statistics regarding the sequence.

New in version 2.0.

Parameters:

return_type (bool, optional) – If set on "dict" (default), the info is returned as an OrderedDict. If set on "table", the info is returned as a two-dimensional list, ready to be exported as a table. If set on "str", a printable string is returned.
full (bool, optional) – If set on True (default), the method returns all the elements mentioned below. If set on False, a subset of these elements is returned (name, condition (if set), date of recording, duration, number of poses, and number of joint labels). If return_type is set on "str", the elements are printed on different lines if full is set on True, and on one line if set on False.
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:

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 data included contains:

"Name": The name attribute of the sequence.
"Path": The path attribute of the sequence.
"Condition": The condition attribute of the sequence (if set).
"Duration": Output of Sequence.get_duration() (seconds).
"Number of poses": Output of Sequence.get_number_of_poses().
"Number of joint labels": The length of joint_labels attribute of the sequence.
"Date of recording": Output of Sequence.get_printable_date_recording().
"Subject height": Output of Sequence.get_subject_height() (meters).
"Left arm length": Output of Sequence.get_subject_arm_length() for the left arm (meters).
"Right arm length": Output of Sequence.get_subject_arm_length() for the right arm (meters).
"Average framerate": Output of Sequence.get_average_framerate().
"SD framerate": Standard deviation of the framerate of the sequence.
"Min framerate": Output of Sequence.get_min_framerate().
"Max framerate": Output of Sequence.get_max_framerate().
"Fill level X": Output of Sequence.get_fill_level_per_joint().
"Average velocity X": Output of Sequence.get_total_velocity_single_joint() divided by the total number of poses. This key has one entry per joint label.

Return type:

OrderedDict|list(list)|str

Example

>>> sequence = Sequence("Sequences/Jacob/sequence_24.json")
>>> sequence.get_info()
OrderedDict({'Name': 'sequence_24', 'Condition': None, Path': 'Sequences\Jacob\sequence_24.json',
'Date of recording': 'Tuesday 10 August 2021, 15:08:40', 'Duration': 79.0833823, 'Number of poses': 1269,
'Number of joint labels': 21, 'Subject height': 1.6200255058925102, ...})

Sequence.get_fill_level(joint_label=None)

Returns the ratio of poses for which a coordinates of one or multiple joints are not equal to (0, 0, 0), or (None, None, None). If the ratio is 1, the joint was tracked correctly for the whole duration of the sequence.

New in version 2.0.

Parameters:: joint_label (list(str)|str|None) – A joint label (e.g. "Head"), a list of joint labels (e.g. ["Head", "HandRight"]), or None (default - in that case, the fill level will be calculated for all the joints).
Returns:: dict(str – A dictionary with the joint labels as keys, and the ratio (between 0 and 1) of poses where the coordinates of the joint are present - if a single joint has been passed as parameter, the ratio is returned directly.
Return type:: float)|float

Examples

>>> sequence = Sequence("Walt/sequence_39.json")
>>> sequence.get_fill_level()
{"Head": 1.0, "HandRight": 0.998}
>>> sequence.get_fill_level("Head")
1.0

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)

Example

>>> sequence = Sequence("Barney/sequence_25.json")
>>> sequence.get_poses()

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
Raises:: InvalidPoseIndexException – If the index is not an integer, below 0, or over the length of the Sequence.

Example

>>> sequence = Sequence("Jack/sequence_26.json")
>>> sequence.get_pose(42)

Sequence.get_pose_index_from_timestamp(timestamp, method='closest', use_relative_timestamps=True)

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) or "nearest", 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.
use_relative_timestamps (bool, optional) – Defines if the timestamps start and end refer to the original timestamps or the relative timestamps.

Note

If the provided timestamp matches exactly the timestamp of a pose from the sequence, the pose index is returned, and the parameter method is ignored.

Examples

>>> sequence = Sequence("Kate/sequence_27.json", time_unit="s")  # Timestamps: 0, 1, 2, 3, 4
>>> sequence.get_pose_index_from_timestamp(2)
2
>>> sequence.get_pose_index_from_timestamp(2.2)
2
>>> sequence.get_pose_index_from_timestamp(1.8)
2
>>> sequence.get_pose_index_from_timestamp(1.5)
1
>>> sequence.get_pose_index_from_timestamp(1.8, "lower")
1
>>> sequence.get_pose_index_from_timestamp(2.2, "higher")
3

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) or "nearest", 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.

Examples

>>> sequence = Sequence("Charlie/sequence_28.json", time_unit="s")  # Timestamps: 0, 1, 2, 3, 4
>>> sequence.get_pose_from_timestamp(2)  # Returns Pose with index 2
>>> sequence.get_pose_from_timestamp(2.2)  # Returns Pose with index 2
>>> sequence.get_pose_from_timestamp(1.8)  # Returns Pose with index 2
>>> sequence.get_pose_from_timestamp(1.5)  # Returns Pose with index 1
>>> sequence.get_pose_from_timestamp(1.8, "lower")  # Returns Pose with index 1
>>> sequence.get_pose_from_timestamp(2.2, "higher")  # Returns Pose with index 3

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

Example

>>> sequence = Sequence("Sayid/sequence_29.json", time_unit="s")
>>> sequence.get_number_of_poses()
108

Time

Sequence.get_timestamps(relative=False, timestamp_start=None, timestamp_end=None)

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.
timestamp_start (float or None, optional) – If provided, the return values having a timestamp below the one provided will be ignored from the output. This timestamp is inclusive.
timestamp_end (float or None, optional) – If provided, the return values having a timestamp above the one provided will be ignored from the output. This timestamp is inclusive.

Returns:

List of the timestamps of all the poses of the sequence, in seconds.

Return type:

list(float)

Examples

>>> sequence = Sequence("Shannon/sequence_30.json", time_unit="s")
>>> sequence.get_timestamps()
[14.23, 14.235, 14.24, 14.245, 14.25]
>>> sequence.get_timestamps(relative=True)
[0, 0.005, 0.01, 0.015, 0.02]
>>> sequence.get_timestamps(relative=True, timestamp_start=0.01, timestamp_end=0.5)
[0.01, 0.015, 0.02]

Sequence.get_time_between_poses(index_pose_1, index_pose_2)

Returns the difference between the timestamps of two poses, in seconds.

New in version 2.0.

Parameters:

index_pose_1 (int) – The index of the first pose.
index_pose_2 (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.

Example

>>> sequence = Sequence("Boone/sequence_31.json")
>>> sequence.get_timestamps()
[0, 0.5, 1, 1.5, 2, 2.5, 3]
>>> sequence.get_time_between_poses(2, 5)
1.5

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

Example

>>> sequence = Sequence("John/sequence_32.json")
>>> sequence.get_duration()
38.72

Sampling rate

Sequence.get_sampling_rate()

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 (or Hertz) for the sequence, if this number is stable.
Return type:: float
Raises:: VariableSamplingRateException – If the sampling rate of the sequence is not constant across all poses.

Example

>>> sequence = Sequence("Claire/sequence_33.json")
>>> sequence.get_sampling_rate()
200

Sequence.get_sampling_rates()

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.

New in version 2.0.

Returns:: Framerates for all the poses of the sequence, starting on the second pose.
Return type:: list(float)

Note

Because the framerates are calculated by consecutive pairs of poses, the returned list has a length of \(n-1\), with \(n\) being the number of poses of the sequence.

Example

>>> sequence = Sequence("Claire/sequence_33.json")
>>> sequence.get_sampling_rates()
[100, 102.32, 99.48, 101.9, 103.5]

Sequence.has_stable_sampling_rate()

Returns a boolean indicating if the sequence has a stable sampling rate.

New in version 2.0.

Returns:: A boolean indicating if the sequence has a stable sampling rate.
Return type:: bool

Examples

>>> sequence = Sequence("Nikki/sequence_34.json")  # Timestamps [0, 0.1, 0.2]
>>> sequence.has_stable_sampling_rate()
True
>>> sequence = Sequence("Paulo/sequence_35.json")  # Timestamps [0, 0.09, 0.21]
>>> sequence.has_stable_sampling_rate()
False

Metrics

Sequence.get_measure(measure, joint_label=None, timestamp_start=None, timestamp_end=None, window_length=7, poly_order=None, absolute=False, use_relative_timestamps=True, verbosity=1)

Returns an array of coordinates, distances, or derivatives of the distance for one or multiple joints from the Sequence instance.

New in version 2.0.

Parameters:

measure (str|int) –
The measure to return for each of the joints. This parameter can take multiple values:
- For the x-coordinate: "x", "x_coord", "coord_x", or "x_coordinate".
- For the y-coordinate: "y", "y_coord", "coord_y", or "y_coordinate".
- For the z-coordinate: "z", "z_coord", "coord_z", or "z_coordinate".
- For all the coordinates: "xyz", "coordinates", "coord", "coords", or "coordinate".
- For the consecutive distances: "d", "distances", "dist", "distance", or 0.
- For the consecutive distances on the x-axis: "dx", "distance_x", "x_distance", "dist_x", or "x_dist".
- For the consecutive distances on the y-axis: "dy", "distance_y", "y_distance", "dist_y", or "y_dist".
- For the consecutive distances on the z-axis: "dz", "distance_z", "z_distance", "dist_z", or "z_dist".
- For the velocity: "v", "vel", "velocity", "velocities", "speed", or 1.
- For the acceleration: "a", "acc", "acceleration", "accelerations", or 2.
- For the jerk: "j", "jerk", or 3.
- For the snap: "s", "snap", "joust" or 4.
- For the crackle: "c", "crackle", or 5.
- For the pop: "p", "pop", or 6.
- For any derivative of a higher order, set the corresponding integer.
The measure can be suffixed by _abs to obtain its absolute values. In that case, the parameter absolute is ignored.
joint_label (str|list(str)|None, optional) – The joint labels or joint labels you want to return the measures from. If set on None (default), a dictionary containing all the joints as keys will be returned. If set on a string, an array matching the requested measure for the specified joint label will be returned. Finally, if set on a list of joint labels, a dictionary containing the specified subset of joint labels will be returned.
timestamp_start (float or None, optional) – If provided, the return values having a timestamp below the one provided will be ignored from the output. This parameter is inclusive: if a timestamp is equal to this value, the corresponding pose will be included.
timestamp_end (float or None, optional) – If provided, the return values having a timestamp above the one provided will be ignored from the output. This parameter is inclusive: if a timestamp is equal to this value, the corresponding pose will be included.
window_length (int, optional) – The length of the window for the Savitzky–Golay filter when calculating a derivative (default: 7). See scipy.signal.savgol_filter for more info.
poly_order (int|None, optional) –
The order of the polynomial for the Savitzky–Golay filter. If set on None, the polynomial will be set to one over the derivative rank. See scipy.signal.savgol_filter for more info.
absolute (bool, optional) – If set on True, the returned values will be absolute. By default, the parameter is set on False.
use_relative_timestamps (bool, optional) – Defines if the timestamps timestamp_start and timestamp_end refer to the original timestamps or the relative timestamps, and if the returned timestamps should be original or relative.
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.

Note

When selecting single coordinates, for each joint, the array will be of dimension \(1̀×p\), with \(p\) being the number of poses in the sequence (or a subset if timestamp_start or timestamp_end have been specified). When selecting all the coordinates, the array will be of dimension \(3×p\). For every other measure, because the distances are calculated on consecutive poses, the array will be of dimension \(1×(p-1)\).

Note

The derivatives can only be calculated if the sampling rate of the sequence is constant. If it is not, the function will raise an exception.

Important

If using single letters for the parameter measure, beware that "s" stands for "snap" (4th derivative of the distance) and not for "speed" - use "v" for "velocity" instead.

Returns:: np.ndarray|dict(str – An array containing the requested measure if a single joint has been requested, or a dictionary where an array of the measure is associated to each joint label.
Return type:: np.ndarray)

Examples

>>> sequence = Sequence("Bernard/sequence_36.json")
>>> sequence.get_measure("x", "Head")
[0.95845, 0.94222, 0.89631]
>>> sequence.get_measure("velocity", "Head")
[1.32268, 1.48962]
>>> sequence.get_measure("acceleration")
{"Head": [14.32589, 98.74512], "HandRight": [-48.15162, -3.42108]}

Sequence.get_extremum_measure(measure, joint_label=None, value='both', per_joint=True, timestamp_start=None, timestamp_end=None, window_length=7, poly_order=None, absolute=False, verbosity=1)

Returns the minimum, maximum or both values of the measure for one or multiple joints from the Sequence.

New in version 2.0.

Parameters:

measure (str|int) –
The measure to return for each of the joints. This parameter can take multiple values:
- For the x-coordinate: "x", "x_coord", "coord_x", or "x_coordinate".
- For the y-coordinate: "y", "y_coord", "coord_y", or "y_coordinate".
- For the z-coordinate: "z", "z_coord", "coord_z", or "z_coordinate".
- For all the coordinates: "xyz", "coordinates", "coord", "coords", or "coordinate".
- For the consecutive distances: "d", "distances", "dist", "distance", or 0.
- For the consecutive distances on the x-axis: "dx"`, ``"distance_x", "x_distance", "dist_x", or "x_dist".
- For the consecutive distances on the y-axis: "dy"`, ``"distance_y", "y_distance", "dist_y", or "y_dist".
- For the consecutive distances on the z-axis: "dz"`, ``"distance_z", "z_distance", "dist_z", or "z_dist".
- For the velocity: "v", "vel", "velocity", "velocities", "speed", or 1.
- For the acceleration: "a", "acc", "acceleration", "accelerations", or 2.
- For the jerk: "j", "jerk", or 3.
- For the snap: "s", "snap", "joust" or 4.
- For the crackle: "c", "crackle", or 5.
- For the pop: "p", "pop", or 6.
- For any derivative of a higher order, set the corresponding integer.
joint_label (str|list(str)|None, optional) – The joint labels or joint labels you want to return the measures from. If set on None (default), a dictionary containing all the joints as keys will be returned. If set on a string, an array matching the requested measure for the specified joint label will be returned. Finally, if set on a list of joint labels, a dictionary containing the specified subset of joint labels will be returned.
value (str, optional) – Defines the value to return. Can be either "min", "max", or "both" (default). In that last case, a tuple will be returned for each joint, with the min and the max values, respectively.
per_joint (bool, optional) – If set on True (default), returns the value(s) for each joint in a dictionary (or directly if only one joint is specified). If set on False, the extreme value(s) across all provided joints will be returned.
timestamp_start (float or None, optional) – If provided, the return values having a timestamp below the one provided will be ignored from the output. This parameter is inclusive: if a timestamp is equal to this value, the corresponding pose will be included.
timestamp_end (float or None, optional) – If provided, the return values having a timestamp above the one provided will be ignored from the output. This parameter is inclusive: if a timestamp is equal to this value, the corresponding pose will be included.
window_length (int, optional) –
The length of the window for the Savitzky–Golay filter when calculating a derivative (default: 7). See scipy.signal.savgol_filter for more info.
poly_order (int|None, optional) –
The order of the polynomial for the Savitzky–Golay filter. If set on None, the polynomial will be set to one over the derivative rank. See scipy.signal.savgol_filter for more info.
absolute (bool, optional) – If set on True, the returned values will be absolute. By default, the parameter is set on False.
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:

dict(str – A dictionary with joint labels as keys, and an extreme value or a tuple of extreme values as values; if only one joint_label has been provided, the returned value will be a single extreme value or a tuple of the extreme value(s).

Return type:

float)|dict(str: (float, float)|(float, float)|float

Examples

>>> sequence = Sequence("Rose/sequence_37.json")
>>> sequence.get_extremum_measure("x", "Head", "min")
0.12345
>>> sequence.get_extremum_measure("x", "Head", "min")
1.42369
>>> sequence.get_extremum_measure("x", "Head", "both")
(0.12345, 1.42369)
>>> sequence.get_extremum_measure("distance")
{"Head": (14.23695, 89.23647), "HandRight": (1.42367, 8.69511)}

Sequence.get_sum_measure(measure, joint_label=None, per_joint=True, timestamp_start=None, timestamp_end=None, window_length=7, poly_order=None, absolute=False, verbosity=1)

Returns the sum of the values of the measure for one or multiple joints from the Sequence.

New in version 2.0.

Parameters:

measure (str|int) –
The measure to return for each of the joints. This parameter can take multiple values:
- For the x-coordinate: "x", "x_coord", "coord_x", or "x_coordinate".
- For the y-coordinate: "y", "y_coord", "coord_y", or "y_coordinate".
- For the z-coordinate: "z", "z_coord", "coord_z", or "z_coordinate".
- For all the coordinates: "xyz", "coordinates", "coord", "coords", or "coordinate".
- For the consecutive distances: "d", "distances", "dist", "distance", or 0.
- For the consecutive distances on the x-axis: "dx"`, ``"distance_x", "x_distance", "dist_x", or "x_dist".
- For the consecutive distances on the y-axis: "dy"`, ``"distance_y", "y_distance", "dist_y", or "y_dist".
- For the consecutive distances on the z-axis: "dz"`, ``"distance_z", "z_distance", "dist_z", or "z_dist".
- For the velocity: "v", "vel", "velocity", "velocities", "speed", or 1.
- For the acceleration: "a", "acc", "acceleration", "accelerations", or 2.
- For the jerk: "j", "jerk", or 3.
- For the snap: "s", "snap", "joust" or 4.
- For the crackle: "c", "crackle", or 5.
- For the pop: "p", "pop", or 6.
- For any derivative of a higher order, set the corresponding integer.
joint_label (str|list(str)|None, optional) – The joint labels or joint labels you want to return the measures from. If set on None (default), a dictionary containing all the joints as keys will be returned. If set on a string, an array matching the requested measure for the specified joint label will be returned. Finally, if set on a list of joint labels, a dictionary containing the specified subset of joint labels will be returned.
per_joint (bool, optional) – If set on True (default), returns the value for each joint in a dictionary (or directly if only one joint is specified). If set on False, the sum across all provided joints will be returned.
timestamp_start (float or None, optional) – If provided, the return values having a timestamp below the one provided will be ignored from the output. This parameter is inclusive: if a timestamp is equal to this value, the corresponding pose will be included.
timestamp_end (float or None, optional) – If provided, the return values having a timestamp above the one provided will be ignored from the output. This parameter is inclusive: if a timestamp is equal to this value, the corresponding pose will be included.
window_length (int, optional) –
The length of the window for the Savitzky–Golay filter when calculating a derivative (default: 7). See scipy.signal.savgol_filter for more info.
poly_order (int|None, optional) –
The order of the polynomial for the Savitzky–Golay filter. If set on None, the polynomial will be set to one over the derivative rank. See scipy.signal.savgol_filter for more info.
absolute (bool, optional) – If set on True, the returned values will be absolute. By default, the parameter is set on False.
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:

dict(str – A dictionary with joint labels as keys, and the sum of the measure for each joint label as values; if only one joint_label has been provided, or if the sum of all the joints have been requested, the returned value will be a single sum value.

Return type:

float)|float

Examples

>>> sequence = Sequence("Michael/sequence_38.json")
>>> sequence.get_sum_measure("x", "Head")
19.65475
>>> sequence.get_sum_measure("distance")
{"Head": 586.36524, "HandRight": 10.00001}
>>> sequence.get_sum_measure("distance", per_joint=False)
596.36525

Correction functions

Sequence.correct_jitter(velocity_threshold, window, window_unit='poses', method='default', correct_twitches=True, correct_jumps=True, 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).
- 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.
correct_twitches (bool, optional) – If set on True (default), corrects the abnormal movements where the joints come back below threshold within the specified window. If set on False, the jitter correction will not correct the twitches.
correct_jumps (bool, optional) – If set on True (default), corrects the abnormal movements where the joints do not come back below threshold within the specified window. If set on False, the jitter correction will not correct the jumps.
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

Example

>>> sequence = Sequence("Walt/sequence_39.xlsx")
>>> sequence_cj = sequence.correct_jitter(1, 5)

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

Example

>>> sequence = Sequence("Sawyer/sequence_40.xlsx")
>>> sequence_rf = sequence.re_reference("SpineMid", True)

Sequence.trim(start=None, end=None, use_relative_timestamps=False, name=None, error_if_out_of_bounds=False, 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 (inclusive). If set on None, or if set on a value lower than the first timestamp, 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 (inclusive). If set on None, or if set on a value higher than the last timestamp, 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".
error_if_out_of_bounds (bool, optional) – Defines if to return an error if the timestamps are out of bounds. If set on True, the function will raise an Exception if start is below 0, or if end is above the length of the audio.
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

Example

>>> sequence = Sequence("Hurley/sequence_41.tsv")  # Sequence with 100 poses at 10 Hz.
>>> sequence_t = sequence.trim(0, 5)
>>> sequence_t.get_number_of_poses()
51  # Remember: the last pose is inclusive. If you wish not to include it, set the end to 4.999

Sequence.trim_to_audio(delay=0, audio=None, name=None, error_if_out_of_bounds=False, 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".
error_if_out_of_bounds (bool, optional) – Defines if to return an error if the timestamps are out of bounds. If set on True, the function will raise an Exception if start is below 0, or if end is above the length of the audio.
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.

Important

The function will trim the Sequence to the pose that has the closest time above the one provided for the parameter delay. This means that the difference between the delay entered and the actual timestamp might be significant. This difference will be printed if verbosity is set to 1 or more.

Example

>>> sequence = Sequence("Jin/sequence_42.tsv")  # Sequence with 100 poses at 10 Hz.
>>> audio = Audio("Jin/audio_42.wav")  # Audio duration of 5 s.
>>> sequence_ta = sequence.trim(2, audio)
>>> sequence_ta.get_number_of_poses()
51

Sequence.filter_frequencies(filter_below=None, filter_over=None, padtype='constant', padlen=None, name=None, verbosity=1)

Applies a low-pass, high-pass or band-pass filter to the positions of the joints.

Parameters:

filter_below (float or None, optional) – The value below which you want to filter the data. If set on None or 0, this parameter will be ignored. If this parameter is the only one provided, a high-pass filter will be applied to the data; if filter_over is also provided, a band-pass filter will be applied to the data.
filter_over (float or None, optional) – The value over which you want to filter the data. If set on None or 0, this parameter will be ignored. If this parameter is the only one provided, a low-pass filter will be applied to the data; if filter_below is also provided, a band-pass filter will be applied to the data.
padtype (str, optional) – What type of padding to use. See the documentation of scipy.signal.filtfilt for more information (default: "constant" - warning: this default is not scipy’s default ("odd").)
padlen (int, optional) –
The number of elements for the padding. See the documentation of scipy.signal.filtfilt for more information.
name (str or None, optional) – Defines the name of the output sequence. If set on None, the name will be the same as the original sequence, with the suffix "+FF".
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 Sequence instance, with filtered values.

Return type:

Sequence

Raises:

ValueError – If filter_below is below 0, or filter_above is superior or equal to the frequency of the Sequence divided by two.
VariableSamplingRateException – If the sampling rate of the Sequence is not fixed.

Note

This function uses the scipy functions scipy.signal.butter to create the filter, and scipy.signal.filtfilt to apply it.

Example

>>> sequence = Sequence("Sun/sequence_43.tsv")  # Sequence with 100 poses at 10 Hz.
>>> audio = Audio("Sun/audio_43.wav")
>>> sequence_ta = sequence.trim(2, audio)
>>> sequence_ta.get_number_of_poses()

Sequence.resample(frequency, method='cubic', window_size=10000000.0, overlap_ratio=0.5, 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.
method (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.
window_size (int, optional) – The size of the windows in which to cut the points to perform the resampling. Cutting long arrays in windows allows to speed up the computation. If this parameter is set on None, the window size will be set on the number of samples. A good value for this parameter is generally 10 million (1e7). If this parameter is set on 0, on None or on a number of samples bigger than the amount of samples in the Sequence instance, the window size is set on the length of the samples.
overlap_ratio (float, optional) – The ratio of points overlapping between each window. If this parameter is not None, each window will overlap with the previous (and, logically, the next) for an amount of samples equal to the number of samples in a window times the overlap ratio. Then, only the central values of each window will be preserved and concatenated; this allows to discard any “edge” effect due to the windowing. If the parameter is set on None or 0, the windows will not overlap. By default, this parameter is set on 0.5, meaning that each window will overlap for half of their values with the previous, and half of their values with the next.
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().

Example

>>> sequence = Sequence("Ben/sequence_44.tsv")  # Sequence with 100 poses at 10 Hz.
>>> sequence_rs = sequence.resample(5)
>>> sequence_rs.get_number_of_poses()
50

Sequence.interpolate_missing_data(method='cubic', which='both', name=None, min_duration_warning=0.1, verbosity=1, add_tabs=0)

Detects the joints set at (0, 0, 0) and/or (None, None, None), considers them as missing, and correct their coordinates by interpolating the data from the neighbouring temporal points. Typically, this function is used to correct the zeros 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 missing coordinates, the closest non-zero coordinate is assigned to the pose. The missing coordinates are then considered as missing and are new values are interpolated using tool_functions.interpolate_data().

New in version 2.0.

Parameters:

method (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.
which (str|int|None, optional) – Whether to correct for zeros ("zero", "zeros", 0, (0, 0, 0)), for None (None, "none", (None, None, None)) or both (default, "both").
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 "+IM".
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.

Example

>>> sequence = Sequence("Juliet/sequence_45.tsv")
>>> sequence_im = sequence.resample("linear", "both")

Sequence.randomize(x_scale=0.2, y_scale=0.3, z_scale=0.5, name=None, 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 (default)

y coordinate randomized between -0.3 and 0.3 (default)

z coordinate randomized between -0.5 and 0.5 (default)

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:

x_scale (float) – The absolute maximum value of the random uniform distribution on the x-axis.
y_scale (float) – The absolute maximum value of the random uniform distribution on the y-axis.
z_scale (float) – The absolute maximum value of the random uniform distribution on the z axis.
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 "+RD".
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

Example

>>> sequence = Sequence("Desmond/sequence_46.tsv")
>>> sequence_rd = sequence.randomize()

Conversion functions

Sequence.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)

Example

>>> sequence = Sequence("Ana-Lucia/sequence_47.tsv")
>>> sequence.to_table()
[["Timestamp", "Head_X", "Head_Y", "Head_Z"],
[0, 4, 8, 15],
[0.01, 16, 23, 42],
[0.02, 108, 316, 815]]

Sequence.to_json(include_metadata=True, 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:

include_metadata (bool, optional) – Whether to include the metadata in the output dictionary.
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 dictionary containing the data of the sequence, ready to be exported in JSON.

Return type:

dict

Example

>>> sequence = Sequence("Miles/sequence_48.tsv")
>>> sequence.to_json()
['Poses':
    [{'Bodies':
        [{'Joints':
            [{'JointType':
                'Head',
              'Position':
                  {'X': 0.160617024, 'Y': 0.494735048, 'Z': -0.453307693},
              'Timestamp': 0.0}]}]}]

Sequence.to_dict(use_relative_timestamps=False)

Returns a dictionary containing the data of the sequence. 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 dataframe containing the timestamps and coordinates of the sequence.
Return type:: dict

Example

>>> sequence = Sequence("Daniel/sequence_49.tsv")
>>> sequence.to_dict()
{"Timestamp": [0, 0.001, 0.002], "Head_X": [1, 2, 3], "Head_Y": [4, 5, 6], "Head_Z": [7, 8, 9]}

Sequence.to_dataframe(use_relative_timestamps=False)

Returns a Pandas dataframe containing the data of the sequence. 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 dataframe containing the timestamps and coordinates of the sequence.
Return type:: Pandas.dataframe

Example

>>> sequence = Sequence("Charlotte/sequence_50.tsv")
>>> sequence.to_dataframe()
    Timestamp    Head_X    Head_Y  ...  HandLeft_X  HandLeft_Y  HandLeft_Z
0      0.000  0.160617  0.494735  ...   -1.395066    2.653739   -0.483164
1      0.001  1.769412  0.885312  ...   -0.806453    1.460889    2.557279
2      0.002 -1.678118  0.850645  ...   -1.418790    0.283037   -0.221482

Saving functions

Sequence.save(folder_out='', name=None, file_format='json', encoding='utf-8', individual=False, include_metadata=True, 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", "pkl", 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.
- "pkl" or "pickle" will save the sequence using pickling.
- 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.
encoding (str, optional) – The encoding of the file to save. By default, the file is saved in UTF-8 encoding. This input can take any of the official Python accepted formats.
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.
include_metadata (bool, optional) –
Whether to include the metadata in the file (default: True). This parameter does not apply to individually saved files.
- For json files, the metadata is saved at the top level. Metadata keys will be saved next to the "Poses" key.
- For mat files, the metadata is saved at the top level of the structure.
- For xlsx files, the metadata is saved in a second sheet.
- For pkl files, the metadata will always be saved as the object is saved as-is - this parameter is thus ignored.
- For all the other formats, the metadata is saved at the beginning of the file.
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.

Examples

>>> sequence_1 = Sequence("MarkS/sequence_1.json")
>>> sequence_1.save("MarkS/sequence_1.tsv")
>>> sequence_1.save("MarkS/sequence_1.mat", include_metadata=False)

Sequence.save_info(folder_out='', name=None, file_format='json', encoding='utf-8', 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).
encoding (str, optional) –
The encoding of the file to save. By default, the file is saved in UTF-8 encoding. This input can take any of the official Python accepted formats.
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.

Example

>>> sequence = Sequence("HellyR/sequence_2.json")
>>> sequence.save_info("HellyR/stats.csv")

Sequence.save_json(folder_out, name=None, individual=False, include_metadata=True, encoding='utf-8', 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, or the complete path to the file. 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. This parameter is ignored if folder_out already contains the name of the file.
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.
include_metadata (bool, optional) – Whether to include the metadata in the file (default: True).
encoding (str, optional) –
The encoding of the file to save. By default, the file is saved in UTF-8 encoding. This input can take any of the official Python accepted formats.
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.

Example

>>> sequence = Sequence("IrvingB/sequence_3.tsv")
>>> sequence.save_json("IrvingB", "sequence_3")
>>> sequence.save_json("IrvingB/sequence_3.json")

Sequence.save_mat(folder_out, name=None, individual=False, include_metadata=True, 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, or the complete path to the file. 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. This parameter is ignored if folder_out already contains the name of the file.
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.
include_metadata (bool, optional) – Whether to include the metadata in the file (default: True).
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.

Example

>>> sequence = Sequence("DylanG/sequence_4.tsv")
>>> sequence.save_mat("DylanG", "sequence_4")
>>> sequence.save_mat("DylanG/sequence_4.mat")

Sequence.save_excel(folder_out, name=None, individual=False, sheet_name='Data', include_metadata=True, metadata_sheet_name='Metadata', 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, or the complete path to the file. 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. This parameter is ignored if folder_out already contains the name of the file.
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.
sheet_name (str|None, optional) – The name of the sheet containing the data. If None, a default name will be attributed to the sheet ("Sheet").
include_metadata (bool, optional) – Whether to include the metadata in the Excel file (default: True). The metadata is saved in a separate sheet in the same Excel file.
metadata_sheet_name (str|None, optional) – The name of the sheet containing the metadata. If None, a default name will be attributed to the sheet ("Metadata").
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.

Example

>>> sequence = Sequence("Mr. Milkshake/sequence_5.tsv")
>>> sequence.save_excel("Mr. Milkshake", "sequence_5")
>>> sequence.save_excel("Mr. Milkshake/sequence_5.xlsx")

Sequence.save_pickle(folder_out, name=None, individual=False, verbosity=1)

Saves a sequence by pickling it. This allows to reopen the sequence as a Sequence object.

New in version 2.0.

Parameters:

folder_out (str) – The path to the folder where to save the file or files, or the complete path to the file. 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. This parameter is ignored if folder_out already contains the name of the file.
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.
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.

Example

>>> sequence = Sequence("Ms. Cobel/sequence_6.tsv")
>>> sequence.save_pickle("Ms. Cobel", "sequence_6")
>>> sequence.save_pickle("Ms. Cobel/sequence_6.pkl")

Sequence.save_txt(folder_out, name=None, file_format='csv', encoding='utf-8', individual=False, include_metadata=True, 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, or the complete path to the file. 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. This parameter is ignored if folder_out already contains the name of the file.
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). This parameter is ignored if folder_out already contains the name of the file.
encoding (str, optional) –
The encoding of the file to save. By default, the file is saved in UTF-8 encoding. This input can take any of the official Python accepted formats.
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.
include_metadata (bool, optional) – Whether to include the metadata in the file (default: True). The metadata is saved on the first lines of the file.
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.

Example

>>> sequence = Sequence("Ms. Casey/sequence_7.json")
>>> sequence.save_txt("Ms. Casey", "sequence_7", "txt")
>>> sequence.save_txt("Ms. Casey/sequence_7.csv")

Miscellaneous functions

Sequence.average_qualisys_to_kinect(joints_labels_to_exclude=None, remove_non_kinect_joints=False, verbosity=1)

Creates missing Kinect joints from the Qualisys labelling system by averaging the distance between Qualisys joints, and returns the resulting sequence. 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_non_kinect_joints (bool, optional) – If True, removes the joints from Qualisys that are not found in the Kinect labelling system.
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 with the averaged joints.

Return type:

Sequence

Example

>>> sequence = Sequence("Frank/sequence_51.tsv")  # Qualisys sequence, 44 joints
>>> sequence.average_qualisys_to_kinect(remove_non_kinect_joints=True)  # Kinect converted sequence, 21 joints

Sequence.average_joints(joints_labels_to_average, new_joint_label, remove_averaged_joints=False, verbosity=0)

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.
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.

Note

Compared to Sequence.average_qualisys_to_kinect(), this function modifies the Sequence instance in-place.

Example

>>> sequence = Sequence("Jacob/sequence_52.tsv")
>>> sequence.poses[0].joints["HeadFront"].get_position()
(0, 0, 0)
>>> sequence.poses[0].joints["HeadBack"].get_position()
(2, 2, 2)
>>> sequence.average_joints(["HeadFront", "HeadBack"], "Head", False)
>>> sequence.poses[0].joints["Head"].get_position()
(1, 1, 1)

Sequence.concatenate(other, delay=None, name=None, verbosity=0)

Returns a new Sequence, result of the concatenation of another sequence to the end of the current instance, with a delay.

New in version 2.0.

Parameters:

other (Sequence) – The sequence to concatenate.
delay (float, optional) – The delay to apply, in seconds, between the last pose of the original sequence and the first pose of the new sequence. If set on None, the applied delay will be the 1 over the sampling rate of the current instance.
name (str or None, optional) – Defines the name of the output sequence. If set on None, the name will be the concatenation of the name of both sequences, separated by a space.
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 instance concatenating the poses of the two Sequences, separated by a delay. The preserved metadata in the new instance is the same as the current instance.

Return type:

Sequence

Example

>>> sequence_1 = Sequence("Richard/sequence_53_part1.tsv")  # 3 poses at 10 Hz
>>> sequence_2 = Sequence("Richard/sequence_53_part2.tsv")  # 3 poses at 10 Hz
>>> sequence_3 = sequence_1.concatenate(sequence_2, "sequence_53_full")
>>> sequence_3.get_timestamps()
[0, 0.1, 0.2, 0.3, 0.4, 0.5]

Sequence.copy()

Returns a deep copy of the Sequence object.

New in version 2.0.

Returns:: A new Sequence object, copy of the original.
Return type:: Sequence

Example

>>> sequence = Sequence("Libby/sequence_54.tsv")
>>> sequence_copy = sequence.copy()

Sequence.print_all(include_metadata=False)

Successively prints the poses, their timestamps and the coordinates of each of the joints. If specified, also prints the metadata of the sequence.

New in version 2.0.

Important

For long sequences, the output can be quite long, so use this function with care, or on a subset of the sequence (by using the Sequence.trim() function first).

Parameters:: include_metadata (bool, optional) – If set on True, the output will be led the metadata of the sequence. Default: False.

Example

>>> sequence = Sequence("Penny/sequence_55.tsv")
>>> sequence.print_all()
#################
## sequence_55 ##
#################

Poses

Pose 1/3 Timestamp: 0.0 Relative timestamp: 0.0 Joints (3): Head: (0.160617024, 0.494735048, -0.453307693) HandRight: (0.127963375, 0.873208589, 0.408531847) HandLeft: (-1.395065714, 2.653738732, -0.483163821)

Pose 2/3 Timestamp: 0.001 Relative timestamp: 0.001 Joints (3): Head: (1.769412418, 0.885312165, -0.785718175) HandRight: (0.948776526, 2.805260745, 2.846927978) HandLeft: (-0.80645271, 1.460889453, 2.557279205)

Pose 3/3 Timestamp: 0.002 Relative timestamp: 0.002 Joints (3): Head: (-1.678118013, 0.85064505, 1.37303521) HandRight: (-1.612589342, -0.059736892, -1.456678185) HandLeft: (-1.418789803, 0.283037432, -0.221482265)

Private methods

Initialisation functions

Sequence._define_name_init(verbosity=1)

Sets the name attribute for an instance of the 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 object name will be defined as "Unnamed x", with x being the class name (audio, sequence, or one of the audio derivatives).

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._set_time_unit()

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".

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._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, verbosity=1)

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.
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._set_timestamps_time_unit(): Sets the timestamps for each pose according to the attribute time_unit.

New in version 2.0.

Sequence._load_json_metadata(data, verbosity=1)

Loads the data from the file apart from the joint positions, and saves it in the attribute metadata. For Kinect data, this function will load all the elements from the JSON file apart from “Bodies”.

New in version 2.0.

Parameters:

data (dict) – 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._load_date_recording(verbosity=1)

Loads the date of a recording from the information contained in the recording metadata.

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._set_joint_labels(verbosity=1, add_tabs=0)

Scans through all the poses of the Sequence instance, and sets the parameter Sequence.joint_labels with the joint labels appearing at least once.

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.
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.

Sequence._apply_joint_labels(default_value=None, check_length_only=True, verbosity=1, add_tabs=0)

Verifies if each pose of the Sequence instance contains a Joint object for each of the joint labels present in Sequence.joint_labels. If some Joint objects are missing (typically, if the skeleton was not detected for one frame), the function creates Joint objects with all the coordinates equal to default_value.

New in version 2.0.

Parameters:

default_value (None, numpy.nan, int or float (optional)) – The default value to set to all the coordinates for the missing joint labels. By default, it is equal to None, but it can be set on 0 (in that case, missing joints will have a coordinate of (0, 0, 0)), numpy.nan or any other numerical value.
check_length_only (bool, optional) – If set on True (default), the function only checks if the number of joint labels in the pose is equal to the number of labels in the attribute joint_labels of the Sequence instance. If you want to check thoroughly that the name of the joint labels is exactly the same, set this parameter on False - the computation time may be impacted.
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.

Sequence._set_system(verbosity=1)

Sets the recording system of the Sequence, based on its joint labels.

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._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.

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.

Miscellaneous functions

Sequence._create_new_sequence_with_timestamps(verbosity=1, add_tabs=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.
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 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

Sequence._set_attributes_from_other_sequence(other)

Sets the attributes condition, system, dimensions, is_randomized, date_recording, metadata and time_unit of the Sequence from another instance.

New in version 2.0.

Parameters:: other (Sequence) – Another Sequence instance, from which to copy some of the parameters.