I/O functions
Description
Functions to load and save multiple sequences, audio clips, and statistics.
Functions
- io_functions.load_sequences(input_folder, recursive=False, output_type='list', ignore_empty_sequences=True, ignore_loading_errors=False, verbose=1)
Loads multiple sequences and returns a list or a dict containing them.
New in version 2.0.
- Parameters:
input_folder (str) – The absolute path of the directory in which to look for sequences (starting from the root of the drive, e.g.
C:/Users/Desmond/Documents/Recordings
).recursive (bool, optional) – If set on
True
, all the subdirectories of theinput_folder
will be analyzed to look for sequences.output_type (str, optional) – If set on
"list"
(default), the function will return a list of the loaded sequences. If set on"dict"
, the function will return a dict, in which each key will be the absolute path to the sequence, and the corresponding values will be the loaded sequences.ignore_empty_sequences (bool, optional) –
If set on
True
(default), the function will not stop if it tries to load an empty file or folder. If set onFalse
, the function will stop at anyEmptySequenceException
.Note
If you set
recursive
onTrue
, you should also setignore_empty_sequences
onTrue
: as the recursive loading starts from the top, the first sequence this function will try to load is the parent folder, which will probably not contain any sequence. The function will then return an EmptySequenceException and stop if you setignore_empty_sequences
onFalse
.ignore_loading_errors (bool, optional) – If set on
True
, the function will not stop if it tries to load a sequence that raises anInvalidPathException
or anImpossibleTimeTravelException
. In that case, the sequences in question will not be added to the output of the function, and the reason of the error will be printed in the console ifverbose
is 1 or more. If set onFalse
(default), anyInvalidPathException
orImpossibleTimeTravelException
will stop the function.verbose (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 list or dict (defined by the parameter
output_type
) of the loaded sequences. If the output is a dict, each key is the absolute path to the sequence, and the corresponding values are the loaded sequences.- Return type:
list or dict
- io_functions.load_audios(input_folder, recursive=False, output_type='list', ignore_empty_audios=True, ignore_loading_errors=False, verbose=1)
Loads multiple audio clips and returns a list or a dict containing them.
New in version 2.0.
- Parameters:
input_folder (str) – The absolute path of the directory in which to look for audio clips (starting from the root of the drive, e.g.
C:/Users/Greg/Documents/Audio_clips
).recursive (bool, optional) – If set on
True
, all the subdirectories of theinput_folder
will be analyzed to look for audio clips.output_type (str, optional) – If set on
"list"
(default), the function will return a list of the loaded audio clips. If set on"dict"
, the function will return a dict, in which each key will be the absolute path to the audio clip, and the corresponding values will be the loaded audio clip.ignore_empty_audios (bool, optional) –
If set on
True
(default), the function will not stop if it tries to load an empty file or folder. If set onFalse
, the function will stop at anyEmptyAudioException
.Note
If you set
recursive
onTrue
, you should also setignore_empty_audios
onTrue
: as the recursive loading starts from the top, the first sequence this function will try to load is the parent folder, which will probably not contain any audio clip. The function will then return an EmptyAudioException and stop if you setignore_empty_audios
onFalse
.ignore_loading_errors (bool, optional) – If set on
True
, the function will not stop if it tries to load an audio clip that raises anInvalidPathException
or aImpossibleTimeTravelException
. In that case, the audio clips in question will not be added to the output of the function, and the reason of the error will be printed in the console ifverbose
is 1 or more. If set onFalse
(default), anyInvalidPathException
orImpossibleTimeTravelException
will stop the function.verbose (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 list or dict (defined by the parameter
output_type
) of the loaded audio clips. If the output is a dict, each key is the absolute path to the audio clip, and the corresponding values are the loaded audio clips.- Return type:
list or dict
- io_functions.save_sequences(sequence_or_sequences, folder_out='', names=None, file_format='json', individual=False, use_relative_timestamps=True, keep_subdirectory_structure=True, verbose=1)
Saves one or multiple Sequence instances on the disk.
New in version 2.0.
- Parameters:
sequence_or_sequences (Sequence or list(Sequence)) – A Sequence instance or a list of Sequence instances.
folder_out (str, optional) – The path in which to save the sequences. If one or more subfolders of the path do not exist, they will be created automatically.
names (list(str) or None, optional) – The names to give to the saved sequences. If set on None, the attribute
Sequence.name
will be used to name the output file or folder. If a list of names is provided, the list must be the same length as the parametersequence_or_sequences
. Ifsequence_or_sequences
is a single Sequence instance, or is a list containing a single Sequence instance,names
can be a string. If you provide a name, do not provide the file extension with it: provide the extension in the parameterfile_format
instead.file_format (str, optional) –
The file format in which to save the sequences. 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).
Warning
While it is possible to save sequences as
.mat
or custom extensions, the toolbox will not recognize these files upon opening. The support for.mat
and custom extensions as input may come in a future release, but for now these are just offered as output options.individual (bool, optional) – If set on
False
(default), the function will save each sequence in a unique file. If set onTrue
, the function will save each pose of the sequences in an individual file, appending an underscore and the index of the pose (starting at 0) after the name.use_relative_timestamps (bool, optional) – Defines if the timestamps that will be saved are absolute (
False
) or relative to the first pose (True
).keep_subdirectory_structure (bool, optional) – If set on
True
, sequences in distinct subfolders will remain separated according to the same structure in the output directory. For example, if two sequences have for original pathsC:/Recordings/Subject_01/March_14/recording.json
andC:/Recordings/Subject_02/May_04/recording.json
, and thefolder_out
provided isD:/Resampled/
, the recordings will be saved asD:/Resampled/Subject_01/March_14/recording.json
andD:/Resampled/Subject_02/May_04/recording.json
.verbose (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.
- io_functions.save_audios(audio_or_audios, folder_out='', names=None, file_format='json', individual=False, keep_subdirectory_structure=True, verbose=1)
Saves one or multiple Audio instances on the disk.
New in version 2.0.
- Parameters:
audio_or_audios (Audio or list(Audio)) – An Audio instance or a list of Audio instances.
folder_out (str, optional) – The path in which to save the audio clips. If one or more subfolders of the path do not exist, they will be created automatically.
names (list(str), str or None, optional) – The names to give to the saved audio clips. If set on None, the attribute
Audio.name
will be used to name the output file or folder. If a list of names is provided, the list must be the same length as the parameteraudio_or_audios
. Ifaudio_or_audios
is a single Audio instance, or is a list containing a single Audio instance,names
can be a string. If you provide a name, do not provide the file extension with it: provide the extension in the parameterfile_format
instead.file_format (str, optional) –
The file format in which to save the sequences. The file format must be
"json"
(default),"xlsx"
,"txt"
,"csv"
,"tsv"
,"wav"
, 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."wav"
files can be opened with any compatible software; that being said, wav files that have been heavily downsampled may sound unintelligible.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 audio clips as
.mat
or custom extensions, the toolbox will not recognize these files upon opening. The support for.mat
and custom extensions as input may come in a future release, but for now these are just offered as output options.individual (bool, optional) –
If set on
False
(default), the function will save each audio clip in a unique file. If set onTrue
, the function will save each sample of each audio clip in an individual file, appending an underscore and the index of the pose (starting at 0) after the name.Note
This incredibly tedious way of opening and saving audio files has only been implemented to follow the same logic as for the Sequence files, and should be avoided.
keep_subdirectory_structure (bool, optional) – If set on
True
, audio clips in distinct subfolders will remain separated according to the same structure in the output directory. For example, if two audio clips have for original pathsC:/Recordings/Subject_01/April_27/recording.wav
andC:/Recordings/Subject_02/October_21/recording.wav
, and thefolder_out
provided isD:/Resampled/
, the recordings will be saved asD:/Resampled/Subject_01/April_27/recording.wav
andD:/Resampled/Subject_02/October_21/recording.wav
.verbose (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.
- io_functions.save_stats(sequence_or_sequences, folder_out='', name='stats', file_format='json', individual=False, keys_to_exclude=None, keys_to_include=None, verbose=1)
Saves the statistics of one or multiple sequences on the disk.
New in version 2.0.
- Parameters:
sequence_or_sequences (Sequence or list(Sequence)) – A Sequence instance or a list of Sequence instances.
folder_out (str, optional) – The path in which to save the stats. If one or more subfolders of the path do not exist, they will be created automatically. If the string provided is empty (by default), the stats will be saved in the current working directory. If the string provided contains a file with an extension, the fields
name
andfile_format
will be ignored.name (str, optional) – Defines the name of the file where to save the stats. By default, it is set on
"stats"
. Ifindividual
is set onTrue
, theclasses.sequence.Sequence.name
will be appended to the name defined in this function for each file.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).
individual (bool, optional) – If set on
False
(default), the function will save the stats of all the sequences in the same file, with one entry/row per sequence. If set onTrue
, the function will save the stats of each sequence individually, by appending the attributeclasses.sequence.Sequence.name
of each sequence to the parametername
of this function. If the attributeclasses.sequence.Sequence.name
of a Sequence is set onNone
, a number will be appended instead.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
classes.sequence.Sequence.get_stats()
. If set onNone
, all the stats will be saved, unless some keys are specified inkeys_to_include
.keys_to_include (list(str) or None, optional) – A list of the stats that you wish to save. Each string must be a valid entry among the keys saved by the function
classes.sequence.Sequence.get_stats()
. If set onNone
, all the stats will be saved, unless some keys are specified inkeys_to_exclude
. If at least one key is entered, all the absent keys will not be saved. This parameter will only be considered ifkeys_to_exclude
is None.verbose (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.