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 the input_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 on False, the function will stop at any EmptySequenceException.

    Note

    If you set recursive on True, you should also set ignore_empty_sequences on True: 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 set ignore_empty_sequences on False.

  • ignore_loading_errors (bool, optional) – If set on True, the function will not stop if it tries to load a sequence that raises an InvalidPathException or an ImpossibleTimeTravelException. 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 if verbose is 1 or more. If set on False (default), any InvalidPathException or ImpossibleTimeTravelException 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 the input_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 on False, the function will stop at any EmptyAudioException.

    Note

    If you set recursive on True, you should also set ignore_empty_audios on True: 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 set ignore_empty_audios on False.

  • ignore_loading_errors (bool, optional) – If set on True, the function will not stop if it tries to load an audio clip that raises an InvalidPathException or a ImpossibleTimeTravelException. 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 if verbose is 1 or more. If set on False (default), any InvalidPathException or ImpossibleTimeTravelException 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 parameter sequence_or_sequences. If sequence_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 parameter file_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 on True, 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 paths C:/Recordings/Subject_01/March_14/recording.json and C:/Recordings/Subject_02/May_04/recording.json, and the folder_out provided is D:/Resampled/, the recordings will be saved as D:/Resampled/Subject_01/March_14/recording.json and D:/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 parameter audio_or_audios. If audio_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 parameter file_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 on True, 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 paths C:/Recordings/Subject_01/April_27/recording.wav and C:/Recordings/Subject_02/October_21/recording.wav, and the folder_out provided is D:/Resampled/, the recordings will be saved as D:/Resampled/Subject_01/April_27/recording.wav and D:/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 and file_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". If individual is set on True, the classes.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 on True, the function will save the stats of each sequence individually, by appending the attribute classes.sequence.Sequence.name of each sequence to the parameter name of this function. If the attribute classes.sequence.Sequence.name of a Sequence is set on None, 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 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 classes.sequence.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.

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