Subject

Description

Default class defining a subject, that can contain multiple sequences. This class can be used in the stats functions to calculate variances across participants.

Initialisation

class krajjat.classes.subject.Subject(name: str = None, group: str | int = None, gender: str = None, age: int = None)

Creates an instance from the class Subject, and returns a Subject object, which matches one individual that performed one or multiple recordings. Upon creation, a Subject instance contains no Trial instances. They can be directly added with the method Subject.add_trial().

New in version 2.0.

Parameters:

name (str or None, optional) – The name or identifier of the subject.
group (str or None, optional) – The experimental group the subject belongs to.
gender (str or None, optional) – The gender of the subject (e.g. "F"```or ``"Female").
age (int or None, optional) – The age of the subject, in years.

name

The name or identifier of the subject.

Type:: str

group

The experimental group the subject belongs to.

Type:: str, int or None

gender

The gender of the subject (e.g. "F" or "Female").

Type:: str or None

age

The age of the subject, in years.

Type:: int or None

trials

An ordered dictionary of Trial instances.

Type:: OrderedDict(str or int: Trial)

Example

>>> subject = Subject("Trisha", 30, "F", "Control")
>>> trial1 = Trial("R001", sequence=Sequence("Trisha/sequence_01.csv"), audio=Audio("Trisha/audio_01.wav"))
>>> trial2 = Trial("R002", sequence=Sequence("Trisha/sequence_02.csv"), audio=Audio("Trisha/audio_02.wav"))
>>> trial3 = Trial("R003", sequence=Sequence("Trisha/sequence_03.csv"), audio=Audio("Trisha/audio_03.wav"))
>>> subject.add_trials(trial1, trial2, trial3)

Magic methods

Subject.__len__()

Returns the total number of trials present in the Subject instance.

New in version 2.0.

Returns:: The number of trials present in the Subject instance.
Return type:: int

Example

>>> subject = Subject("Amets", 30, "F", "Basque")
>>> trial1 = Trial("R001", sequence=Sequence("Amets/sequence_01.csv"))
>>> trial2 = Trial("R002", sequence=Sequence("Amets/sequence_02.csv"), audio=Audio("Amets/audio_02.wav"))
>>> subject.add_trials(trial1, trial2)
>>> len(subject)
2

Subject.__getitem__(trial_id)

Returns a trial, given a trial ID.

New in version 2.0.

Parameters:: trial_id (str|int) – The ID of the trial to retrieve.
Returns:: A Trial instance (if a Trial with the given ID exists).
Return type:: Trial

Example

>>> subject = Subject("Leire", 30, "F", "Basque")
>>> trial1 = Trial("R001", sequence=Sequence("Leire/sequence_01.csv"))
>>> subject.add_trial(trial1)
>>> subject["R001"]  # Equivalent to subject.get_trial("R001")

Subject.__repr__()

Returns a string representation of the Subject instance, containing basic information about the subject, and the amount of trials present.

New in version 2.0.

Returns:: A string containing the subject name, age, gender, group, and the amount of trials, sequences and audios attached to it.
Return type:: str

Example

>>> subject = Subject("Itziar", 40, "F", "Basque")
>>> trial1 = Trial("R001", sequence=Sequence("Itziar/sequence_01.csv"))
>>> trial2 = Trial("R002", sequence=Sequence("Itziar/sequence_02.csv"), audio=Audio("Itziar/audio_02.wav"))
>>> subject.add_trials(trial1, trial2)
>>> print(subject)
Subject Itziar (F, 40) · Basque · 2 trials, 2 sequences, 1 audio.

Subject.__eq__(other)

Returns True if the subject trials are the same as the ones from another instance.

New in version 2.0.

Parameters:: other (Subject) – Another Subject instance.
Returns:: True if the subject trials are the same as the ones from another instance.
Return type:: bool

Example

>>> subject1 = Subject("Svetlana", 30, "F", "French")
>>> trial1 = Trial("R001", sequence=Sequence("Svetlana/sequence_01.csv"))
>>> subject1.add_trial(trial1)
>>> subject2 = Subject("Brendan", 40, "M", "English")
>>> trial2 = Trial("R001", sequence=Sequence("Brendan/sequence_01.csv"))
>>> subject2.add_trial(trial2)
>>> subject1 == subject2
False
>>> subject3 = Subject()
>>> subject3.add_trial(trial1)
>>> subject1 == subject3
True

Setter functions

Subject.set_name(name)

Sets the attribute Subject.name of the Subject instance.

New in version 2.0.

Parameters:: name (str) – The name or identifier of the subject.

Example

>>> subject = Subject("Nicola")
>>> subject.set_name("Mikel")

Subject.set_group(group)

Sets the attribute Subject.group of the Subject instance.

New in version 2.0.

Parameters:: group (str) – The experimental group the subject belongs to.

Example

>>> subject = Subject("Manolo")
>>> subject.set_group("Control")

Subject.set_gender(gender)

Sets the attribute Subject.gender of the Subject instance.

New in version 2.0.

Parameters:: gender (str) – The gender of the subject (e.g. "F"```or ``"Female").

Example

>>> subject = Subject("Manuela")
>>> subject.set_gender("F")

Subject.set_age(age)

Sets the attribute Subject.age of the Subject instance.

New in version 2.0.

Parameters:: age (int or None) – The age of the subject, in years.

Example

>>> subject = Subject("Marta")
>>> subject.set_age(7)

Subject.set_age_from_dob(birth_date, session_date=None)

Sets the attribute Subject.age of the Subject instance, based on a date of birth and the date of the session. If no session date is provided, the current date is used to calculate the age of the subject. Dates must be provided in the gregorian calendar.

New in version 2.0.

Parameters:

birth_date (str|tuple|datetime) – The date of birth of the subject. This parameter can be a string in the format DD/MM/YYYY or YYYY-MM-DD, a tuple of three integers (YYYY, MM, DD), or a datetime object.
session_date (str|tuple|datetime|None, optional) – The date of the recording session. If not provided, the current date is used. This parameter can be a string in the format DD/MM/YYYY or YYYY-MM-DD, a tuple of three integers (YYYY, MM, DD), or a datetime object.

Example

>>> subject = Subject("Vincenzo")
>>> subject.set_age_from_dob("01/01/1995")
>>> subject.set_age_from_dob(("1995", "01", "01"), "2025-01-01")
>>> subject.set_age_from_dob(datetime.datetime(1995, 1, 1))

Getter functions

Subject.get_name()

Returns the attribute name of the Subject instance.

New in version 2.0.

Returns:: The name or identifier of the subject.
Return type:: str

Example

>>> subject = Subject("José")
>>> subject.get_name()
José

Subject.get_group()

Returns the attribute group of the Subject instance.

New in version 2.0.

Returns:: The experimental group the subject belongs to.
Return type:: str

Example

>>> subject = Subject("Giada", "Control")
>>> subject.get_group()
Control

Subject.get_gender()

Returns the attribute gender of the Subject instance.

New in version 2.0.

Returns:: The gender of the subject (e.g. "F"```or ``"Female").
Return type:: str

Example

>>> subject = Subject("Noemi", "Experimental", "F")
>>> subject.get_gender()
F

Subject.get_age()

Returns the attribute age of the Subject instance.

New in version 2.0.

Returns:: The age of the subject, in years.
Return type:: int

Example

>>> subject = Subject("Hadeel", "Group A", "F", 20)
>>> subject.get_age()
20

Subject.get_joint_labels()

Returns a list of all the unique joint labels contained in the trials sequences.

New in version 2.0.

Returns:: A list of joint labels.
Return type:: list(str)

Example

>>> subject = Subject("David")
>>> subject.add_trial(Trial(1, sequence=Sequence("David/sequence_01.tsv"))  # Contains Head
>>> subject.add_trial(Trial(2, sequence=Sequence("David/sequence_02.tsv"))  # Contains HandRight and HandLeft
>>> subject.get_joint_labels()
["Head", "HandRight", "HandLeft"]

Subject.get_trial(trial_id)

Returns a Trial instance from the subject that matches the specified trial ID, if it exists.

New in version 2.0.

Parameters:: trial_id (str|int) – The ID of the trial to retrieve.
Returns:: The corresponding Trial, if it exists.
Return type:: Trial

Example

>>> subject = Subject("Li-Chuan")
>>> subject.add_trial(Trial("R001", sequence=Sequence("Li-Chuan/sequence_01.tsv"))
>>> subject.get_trial("R001")

Subject.get_trials(trial_ids=None, condition=None, return_type='dict', **kwargs)

Returns a dictionary or a list containing all or a subset of the subject’s trials.

New in version 2.0.

Parameters:

trial_ids (list(str|int)|str|int|None, optional) – Defines a list of trial IDs to gather specifically; if set, the returned dictionary will only contain the trials matching the given IDs. The function will return an error if an ID does not match any ID present in the subject.
condition (str or int, optional) – If set, the function will return the trials that have an attribute Trial.condition matching the given value. This parameter can be used in conjunction with trial_ids to select only the trials in the list that also match the given condition.
return_type (str, optional) – Defines if to return the trials as a dictionary or a list. The default value is "dict", which returns the trials as a dictionary with the trial IDs as keys. If set to "list", the function will return a list containing the trials in the same order as their IDs passed as parameter.

Note

The function also allows for other arguments, as long as each argument is a custom attribute set to the Trial instances.

Returns:: A dictionary or a list of Trial instances.
Return type:: Dict(Trial)|List(Trial)

Example

>>> subject = Subject("Ana")
>>> trial1 = Trial("R001", sequence=Sequence("Ana/sequence_01.tsv"), condition="Spanish")
>>> trial2 = Trial("R002", sequence=Sequence("Ana/sequence_02.tsv"), condition="English")
>>> trial3 = Trial("R003", sequence=Sequence("Ana/sequence_03.tsv"), condition="English")
>>> subject.add_trials(trial1, trial2, trial3)
>>> subject.get_trials()  # Returns all the trials
>>> subject.get_trials(condition="English")  # Returns all the trials with condition "English" (2 and 3)
>>> subject.get_trials(trial_ids=["R001", "R002"])  # Returns the trials with IDs "R001" and "R002"

Subject.get_trials_id(condition=None, **kwargs)

Returns a list of the trial IDs, in the order the trials were added to the subject.

New in version 2.0.

Parameters:

condition (str|None, optional) – If specified, returns the IDs of the trials matching the given condition.
**kwargs (any, optional) – If specified, returns the IDs of the trials matching the given attributes.

Returns:

A list of the trial IDs.

Return type:

list(str|int)

Example

>>> subject = Subject("Sandra")
>>> trial1 = Trial("R001", sequence=Sequence("Sandra/sequence_01.tsv"))
>>> trial2 = Trial("R002", sequence=Sequence("Sandra/sequence_02.tsv"))
>>> trial3 = Trial("R003", sequence=Sequence("Sandra/sequence_03.tsv"))
>>> subject.add_trials(trial1, trial2, trial3)
>>> subject.get_trials_id()
["R001", "R002", "R003"]

Subject.get_number_of_trials(condition=None, **kwargs)

Returns the total amount of Trial elements present in the Subject instance, or the amount of Trial elements matching the condition or other attributes.

New in version 2.0.

Parameters:

condition (str|None, optional) – If specified, returns the amount of trials matching the given condition.
**kwargs (any, optional) – If specified, returns the amount of trials matching the given attributes.

Returns:

The number of Trial elements matching the given attributes in the Subject instance.

Return type:

int

Example

>>> subject = Subject("Tiger")
>>> trial1 = Trial("R001", sequence=Sequence("Tiger/sequence_01.tsv"))
>>> trial2 = Trial("R002", sequence=Sequence("Tiger/sequence_02.tsv"))
>>> trial3 = Trial("R003", sequence=Sequence("Tiger/sequence_03.tsv"))
>>> subject.add_trials(trial1, trial2, trial3)
>>> subject.get_number_of_trials()
3

Subject.get_sequence(trial_id)

Returns the sequence matching the given trial ID.

New in version 2.0.

Returns:: A Sequence instance included in the Trial instance matching the given trial ID.
Return type:: Sequence

Example

>>> subject = Subject("Catherine")
>>> trial = Trial("R001", sequence=Sequence("Catherine/sequence_01.tsv"))
>>> subject.add_trial(trial)
>>> sequence = subject.get_sequence("R001")

Subject.get_sequences(trial_ids=None, condition=None, return_type='dict', **kwargs)

Returns a list containing the sequences of the Trial instances of the subject.

Parameters:

trial_ids (list(str) or None, optional) – Defines a list of trial IDs to gather specifically; if set, the returned list will only contain the sequences included in the trials matching the given IDs. The function will return an error if an ID does not match any ID present in the subject.
condition (str or int, optional) – If set, the function will return the sequences included in the trials having an attribute Trial.condition matching the given value. This parameter can be used in conjunction with trial_ids to select only the trials in the list that also match the given condition.
return_type (str, optional) – Defines if to return the sequences as a dictionary or a list. The default value is "dict", which returns the sequences as a dictionary with the trial IDs as keys. If set to "list", the function will return a list containing the sequences in the same order as their trial IDs passed as parameter.

Note

The function also allows for other arguments, as long as each argument is a custom attribute set to the Trial instances.

Note

As the trials are in an OrderedDict, the returned sequences will be sorted in the order the trials were added. If some trials do not contain sequences, the corresponding list entries will be None.

New in version 2.0.

Returns:: A dictionary or a list of Sequence instances.
Return type:: dict(Sequence)|list(Sequence)

Examples

>>> subject = Subject("Irene")
>>> trial1 = Trial("R001", sequence=Sequence("Irene/sequence_01.tsv", condition="English"))
>>> trial1.session = 1
>>> trial2 = Trial("R002", sequence=Sequence("Irene/sequence_02.tsv", condition="Spanish"))
>>> trial2.session = 1
>>> trial3 = Trial("R003", sequence=Sequence("Irene/sequence_03.tsv", condition="Spanish"))
>>> trial3.session = 2
>>> subject.add_trials(trial1, trial2, trial3)
>>> sequences = subject.get_sequences(["ROO1", "R003"])
>>> sequences = subject.get_sequences(condition="Spanish", return_type="list")  # Returns R002 and R003
>>> sequences = subject.get_sequences(session=1)  # Returns R001 and R002

Subject.get_audio(trial_id)

Returns the audio matching the given trial ID.

New in version 2.0.

Returns:: An Audio instance included in the Trial instance matching the given trial ID.
Return type:: Audio

Examples

>>> subject = Subject("Maialen")
>>> trial1 = Trial("R001", audio=Audio("Maialen/recording_01.wav", condition="English"))
>>> subject.add_trial(trial1)
>>> audio = subject.get_audio("ROO1")

Subject.get_audios(trial_ids=None, condition=None, return_type='dict', **kwargs)

Returns a list containing the audios of the Trial instances of the subject.

Parameters:

trial_ids (list(str) or None, optional) – Defines a list of trial IDs to gather specifically; if set, the returned list will only contain the audios included in the trials matching the given IDs. The function will return an error if an ID does not match any ID present in the subject.
condition (str or int, optional) – If set, the function will return the audios included in the trials having an attribute Trial.condition matching the given value. This parameter can be used in conjunction with trial_ids to select only the trials in the list that also match the given condition.
return_type (str, optional) – Defines if to return the audios as a dictionary or a list. The default value is "dict", which returns the audios as a dictionary with the trial IDs as keys. If set to "list", the function will return a list containing the audios in the same order as their trial IDs passed as parameter.

Note

The function also allows for other arguments, as long as each argument is a custom attribute set to the Trial instances.

Note

As the trials are in an OrderedDict, the returned audios will be sorted in the order the trials were added. If some trials do not contain audios, the corresponding list entries will be None.

New in version 2.0.

Returns:: A list of Audio instances.
Return type:: list(Audio|AudioDerivative)

Examples

>>> subject = Subject("Clara")
>>> trial1 = Trial("R001", audio=Audio("Clara/recording_01.wav", condition="English"))
>>> trial1.session = 1
>>> trial2 = Trial("R002", audio=Audio("Clara/recording_02.wav", condition="Spanish"))
>>> trial2.session = 1
>>> trial3 = Trial("R003", audio=Audio("Clara/recording_03.wav", condition="Spanish"))
>>> trial3.session = 2
>>> subject.add_trials(trial1, trial2, trial3)
>>> audios = subject.get_audios(["ROO1", "R003"])
>>> audios = subject.get_audios(condition="Spanish", return_type="list")  # Returns R002 and R003
>>> audios = subject.get_audios(session=1)  # Returns R001 and R002

Subject.get_recording_session_duration()

Returns an estimation of the duration of the recording session by calculating the time between the recording date of the sequence with the earliest recording date, and the recording date plus duration of the sequence with the latest recording date.

New in version 2.0.

Returns:: The duration between the beginning of the first and the end of the last sequence.
Return type:: datetime.timedelta

Example

>>> subject = Subject("Manex")
>>> trial1 = Trial("R001", sequence=Sequence("Manex/sequence_01.txt"))  # Recorded 2025-01-01 10:00:00
>>> trial2 = Trial("R002", sequence=Sequence("Manex/sequence_02.txt"))  # Recorded 10:03:00, duration 00:01:00
>>> subject.add_trials(trial1, trial2)
>>> subject.get_recording_session_duration()
datetime.timedelta(seconds=240)

Subject.get_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 height is calculated across all poses for each Sequence present in each Trial (see sequence.Sequence.get_subject_height()), and the resulting heights are averaged across all sequences.

New in version 2.0.

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.

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 a Sequence instance.

Returns:

The estimated height of the subject, in meters.

Return type:

float

Example

>>> subject = Subject("Maite")
>>> trial1 = Trial("R001", sequence=Sequence("Maite/sequence_01.csv"))
>>> trial2 = Trial("R002", sequence=Sequence("Maite/sequence_02.csv"))
>>> subject.add_trials(trial1, trial2)
>>> subject.get_subject_height()
1.68123456879

Subject.get_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 across all poses for each Sequence present in each Trial (see sequence.Sequence.get_subject_arm_length()).

New in version 2.0.

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

Example

>>> subject = Subject("Janire")
>>> trial1 = Trial("R001", sequence=Sequence("Janire/sequence_01.csv"))
>>> trial2 = Trial("R002", sequence=Sequence("Janire/sequence_02.csv"))
>>> subject.add_trials(trial1, trial2)
>>> subject.get_arm_length(side="left")
0.754815162342

Predicate functions

Subject.has_sequence_in_each_trial()

Returns True if each Trial element present in the Subject instance contains a Sequence.

New in version 2.0.

Returns:: Whether the Subject instance contains a Sequence in each Trial element.
Return type:: bool

Example

>>> subject = Subject("Larraitz")
>>> trial1 = Trial("R001", sequence=Sequence("Larraitz/sequence_01.csv"))
>>> trial2 = Trial("R002", sequence=None)
>>> subject.add_trials(trial1, trial2)
>>> subject.has_sequence_in_each_trial()
False
>>> subject.trials["R002"].add_sequence(Sequence("Larraitz/sequence_02.csv"))
>>> subject.has_sequence_in_each_trial()
True

Subject.has_audio_in_each_trial()

Returns True if each Trial element present in the Subject instance contains an Audio or AudioDerivative.

New in version 2.0.

Returns:: Whether the Subject instance contains an Audio or an AudioDerivative in each Trial element.
Return type:: bool

Example

>>> subject = Subject("Eider")
>>> trial1 = Trial("R001", audio=Audio("Eider/audio_01.wav"))
>>> trial2 = Trial("R002", audio=None)
>>> subject.add_trials(trial1, trial2)
>>> subject.has_audio_in_each_trial()
False
>>> subject.trials["R002"].add_audio(Audio("Eider/audio_02.wav"))
>>> subject.has_audio_in_each_trial()
True

Subject.are_timestamps_equal_per_trial()

Returns True if, for each trial in the Subject instance, the timestamps of the Sequence and the Audio or AudioDerivative are equal. The function will return an error if a sequence or an audio/audio derivative is missing.

New in version 2.0.

Returns:: Whether the timestamps of the Sequence and the Audio or AudioDerivative are equal for all trials.
Return type:: bool

Example

>>> subject = Subject("Ihintza")
>>> trial1 = Trial("R001", sequence=Sequence("Ihintza/sequence_01.mat"), audio=Audio("Ihintza/audio_01.wav"))
>>> trial2 = Trial("R002", sequence=Sequence("Ihintza/sequence_02.mat"), audio=Audio("Ihintza/audio_02.wav"))
>>> subject.add_trials(trial1, trial2)
>>> subject.are_timestamps_equal_per_trial()
True

Subject.are_frequencies_equal()

Returns True if the frequencies for all the sequences and audio/audio derivatives are equal across all trials. The function will return an error if a sequence or an audio/audio derivative is missing.

New in version 2.0.

Returns:: Whether the frequencies for all the sequences and audio/audio derivatives are equal across all trials.
Return type:: bool

Example

>>> subject = Subject("Mo")
>>> trial1 = Trial("R001", sequence=Sequence("Mo/sequence_01.mat"), audio=Audio("Mo/audio_01.wav"))  # 20 Hz
>>> trial2 = Trial("R002", sequence=Sequence("Mo/sequence_02.mat"), audio=Audio("Mo/audio_02.wav"))  # 25 Hz
>>> subject.add_trials(trial1, trial2)
>>> subject.are_frequencies_equal()
False

Trial functions

Subject.add_trial(trial, replace_if_exists=False, verbosity=1)

Adds a Trial instance to the current subject.

New in version 2.0.

Parameters:

trial (Trial) – A Trial instance.
replace_if_exists (bool, optional) – If False (default), returns an error if a trial with the same ID already exists for the subject. If True, the existing trial with the same ID will be replaced by the new trial.
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

>>> subject = Subject("Macarena")
>>> trial1 = Trial("R001", sequence=Sequence("Macarena/sequence_01.csv"), audio=Audio("Macarena/audio_01.wav"))
>>> subject.add_trial(trial1)

Subject.add_trials(*trials, replace_if_exists=False, verbosity=1)

Adds one or more Trial instances to the current subject.

New in version 2.0.

Parameters:

trials (Trial) – One or many Trial instances.
replace_if_exists (bool, optional) – If False (default), returns an error if a trial with the same ID already exists for the subject. If True, the existing trial with the same ID will be replaced by the new trial.
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

>>> subject = Subject("Martin")
>>> trial1 = Trial("R001", sequence=Sequence("Martin/sequence_01.csv"), audio=Audio("Martin/audio_01.wav"))
>>> trial2 = Trial("R002", sequence=Sequence("Martin/sequence_02.csv"), audio=Audio("Martin/audio_02.wav"))
>>> trial3 = Trial("R003", sequence=Sequence("Martin/sequence_03.csv"), audio=Audio("Martin/audio_03.wav"))
>>> subject.add_trials(trial1, trial2, trial3)