Module `thunderlab.datawriter`

Writing numpy arrays of floats to data files.

write_data(): write data into a file.
available_formats(): supported data and audio file formats.
available_encodings(): encodings of a data file format.
format_from_extension(): deduce data file format from file extension.
recode_array(): recode array of floats.

Global variables

var data_modules: Dictionary with availability of various modules needed for writing data. Keys are the module names, values are booleans.
var data_formats_funcs: List of implemented formats functions.

Each element of the list is a tuple with the format's name, the module's name in data_modules or None, and the formats function.
var data_encodings_funcs: List of implemented encodings functions.

Each element of the list is a tuple with the module's name and the encodings function.
var data_writer_funcs: Dictionary of implemented write functions.

Keys are the format's name and values the corresponding write function.

Functions

def format_from_extension(filepath)

Deduce data file format from file extension.

Parameters

filepath : str: Name of the data file.

Returns

format : str: Data format deduced from file extension.

def recode_array(data, amax, encoding)

Recode array of floats.

Parameters

data : array of floats: Data array with values ranging between -1 and 1
amax : float: Maximum amplitude of data range.
encoding : str: Encoding, one of PCM_16, PCM_32, PCM_64, FLOAT or DOUBLE.

Returns

buffer : array: The data recoded according to encoding.

def formats_relacs()

Data format of the relacs file format.

Returns

formats : list of str: List of supported file formats as strings.

def encodings_relacs(format=None)

Encodings of the relacs file format.

Parameters

format : str: The file format.

Returns

encodings : list of str: List of supported encodings as strings.

def write_relacs(filepath, data, rate, amax=1.0, unit=None, metadata=None, locs=None, labels=None, format=None, encoding=None)

Write data as relacs raw files.

Parameters

filepath : str: Full path of folder where to write relacs files.
data : 1-D or 2-D array of floats: Array with the data (first index time, optional second index channel).
rate : float: Sampling rate of the data in Hertz.
amax : float: Maximum possible amplitude of the data in unit.
unit : str: Unit of the data.
metadata : nested dict: Additional metadata saved into info.dat.
locs : None or 1-D or 2-D array of ints: Marker positions (first column) and spans (optional second column) for each marker (rows).
labels : None or 2-D array of string objects: Labels (first column) and texts (optional second column) for each marker (rows).
format : str or None: File format, only None or 'RELACS' are supported.
encoding : str or None: Encoding of the data. Only None or 'FLOAT' are supported.

Returns

filepath : str or None: On success, the actual file name used for writing the data.

Raises

ValueError: Invalid filepath.
ValueError: File format or encoding not supported.

def formats_fishgrid()

Data format of the fishgrid file format.

Returns

formats : list of str: List of supported file formats as strings.

def encodings_fishgrid(format=None)

Encodings of the fishgrid file format.

Parameters

format : str: The file format.

Returns

encodings : list of str: List of supported encodings as strings.

def write_fishgrid(filepath, data, rate, amax=1.0, unit=None, metadata=None, locs=None, labels=None, format=None, encoding=None)

Write data as fishgrid raw files.

Parameters

filepath : str: Full path of the folder where to write fishgrid files.
data : 1-D or 2-D array of floats: Array with the data (first index time, optional second index channel).
rate : float: Sampling rate of the data in Hertz.
amax : float: Maximum possible amplitude of the data in unit.
unit : str: Unit of the data.
metadata : nested dict: Additional metadata saved into the fishgrid.cfg.
locs : None or 1-D or 2-D array of ints: Marker positions (first column) and spans (optional second column) for each marker (rows).
labels : None or 2-D array of string objects: Labels (first column) and texts (optional second column) for each marker (rows).
format : str or None: File format, only None or 'FISHGRID' are supported.
encoding : str or None: Encoding of the data. Only None or 'FLOAT' are supported.

Returns

filepath : str or None: On success, the actual file name used for writing the data.

Raises

ValueError: Invalid filepath.
ValueError: File format or encoding not supported.

def formats_pickle()

Data formats supported by pickle.dump().

Returns

formats : list of str: List of supported file formats as strings.

def encodings_pickle(format=None)

Encodings of the pickle format.

Parameters

format : str: The file format.

Returns

encodings : list of str: List of supported encodings as strings.

def write_pickle(filepath, data, rate, amax=1.0, unit=None, metadata=None, locs=None, labels=None, format=None, encoding=None)

Write data into python pickle file.

Documentation

https://docs.python.org/3/library/pickle.html

Parameters

filepath : str: Full path and name of the file to write.
data : 1-D or 2-D array of floats: Array with the data (first index time, optional second index channel). Stored under the key "data".
rate : float: Sampling rate of the data in Hertz. Stored under the key "rate".
amax : float: Maximum possible amplitude of the data in unit. Stored under the key "amax".
unit : str: Unit of the data. Stored under the key "unit".
metadata : nested dict: Additional metadata saved into the pickle. Stored under the key "metadata".
locs : None or 1-D or 2-D array of ints: Marker positions (first column) and spans (optional second column) for each marker (rows).
labels : None or 2-D array of string objects: Labels (first column) and texts (optional second column) for each marker (rows).
format : str or None: File format, only None or 'PKL' are supported.
encoding : str or None: Encoding of the data.

Returns

filepath : str or None: On success, the actual file name used for writing the data.

Raises

ImportError: The pickle module is not available.
ValueError: Invalid filepath.
ValueError: File format or encoding not supported.

def formats_numpy()

Data formats supported by numpy.savez().

Returns

formats : list of str: List of supported file formats as strings.

def encodings_numpy(format=None)

Encodings of the numpy file format.

Parameters

format : str: The file format.

Returns

encodings : list of str: List of supported encodings as strings.

def write_numpy(filepath, data, rate, amax=1.0, unit=None, metadata=None, locs=None, labels=None, format=None, encoding=None)

Write data into numpy npz file.

Documentation

https://numpy.org/doc/stable/reference/generated/numpy.savez.html

Parameters

filepath : str: Full path and name of the file to write.
data : 1-D or 2-D array of floats: Array with the data (first index time, optional second index channel). Stored under the key "data".
rate : float: Sampling rate of the data in Hertz. Stored under the key "rate".
amax : float: Maximum possible amplitude of the data in unit. Stored under the key "amax".
unit : str: Unit of the data. Stored under the key "unit".
metadata : nested dict: Additional metadata saved into the numpy file. Flattened dictionary entries stored under keys starting with "metadata__".
locs : None or 1-D or 2-D array of ints: Marker positions (first column) and spans (optional second column) for each marker (rows).
labels : None or 2-D array of string objects: Labels (first column) and texts (optional second column) for each marker (rows).
format : str or None: File format, only None or 'NPZ' are supported.
encoding : str or None: Encoding of the data.

Returns

filepath : str or None: On success, the actual file name used for writing the data.

Raises

ImportError: The numpy module is not available.
ValueError: Invalid filepath.
ValueError: File format or encoding not supported.

def formats_mat()

Data formats supported by scipy.io.savemat().

Returns

formats : list of str: List of supported file formats as strings.

def encodings_mat(format=None)

Encodings of the matlab format.

Parameters

format : str: The file format.

Returns

encodings : list of str: List of supported encodings as strings.

def write_mat(filepath, data, rate, amax=1.0, unit=None, metadata=None, locs=None, labels=None, format=None, encoding=None)

Write data into matlab file.

Documentation

https://docs.scipy.org/doc/scipy/reference/generated/scipy.io.savemat.html

Parameters

filepath : str: Full path and name of the file to write. Stored under the key "data".
data : 1-D or 2-D array of floats: Array with the data (first index time, optional second index channel). Stored under the key "data".
rate : float: Sampling rate of the data in Hertz. Stored under the key "rate".
amax : float: Maximum possible amplitude of the data in unit. Stored under the key "amax".
unit : str: Unit of the data. Stored under the key "unit".
metadata : nested dict: Additional metadata saved into the mat file. Stored under the key "metadata".
locs : None or 1-D or 2-D array of ints: Marker positions (first column) and spans (optional second column) for each marker (rows).
labels : None or 2-D array of string objects: Labels (first column) and texts (optional second column) for each marker (rows).
format : str or None: File format, only None or 'MAT' are supported.
encoding : str or None: Encoding of the data.

Returns

filepath : str or None: On success, the actual file name used for writing the data.

Raises

ImportError: The scipy.io module is not available.
ValueError: Invalid filepath.
ValueError: File format or encoding not supported.

def formats_audioio()

Data formats supported by audioio.

Returns

formats : list of str: List of supported file formats as strings.

def encodings_audio(format)

Encodings of any audio format.

Parameters

format : str: The file format.

Returns

encodings : list of str: List of supported encodings as strings.

def write_audioio(filepath, data, rate, amax=1.0, unit=None, metadata=None, locs=None, labels=None, format=None, encoding=None, gainkey=['AIMaxVolt', 'gain'], sep='.')

Write data into audio file.

If a gain setting is available in the metadata, then the data are divided by the gain before they are stored in the audio file. After this operation, the data values need to range between -1 and 1, in particular if the data are encoded as integers (i.e. PCM_16, PCM_32 and PCM_64). Note, that this function does not check for this requirement!

Documentation

https://bendalab.github.io/audioio/

Parameters

filepath : str: Full path and name of the file to write.
data : 1-D or 2-D array of floats: Array with the data (first index time, optional second index channel).
rate : float: Sampling rate of the data in Hertz.
amax : float: Maximum possible amplitude of the data in unit.
unit : str: Unit of the data. If supplied and a gain is found in the metadata it has to match the unit of the gain. If no gain is found in the metadata and metadata is not None, then a gain of one with this unit is added to the metadata using the first key in gainkey.
metadata : nested dict: Metadata saved into the audio file. If it contains a gain, the gain factor is used to divide the data down into a range between -1 and 1.
locs : None or 1-D or 2-D array of ints: Marker positions (first column) and spans (optional second column) for each marker (rows).
labels : None or 2-D array of string objects: Labels (first column) and texts (optional second column) for each marker (rows).
format : str or None: File format. If None deduce file format from filepath. See available_formats() for possible values.
encoding : str or None: Encoding of the data. See available_encodings() for possible values. If None or empty string use 'PCM_16'.
gainkey : str or list of str: Key in the file's metadata that holds some gain information. If found, the data will be multiplied with the gain, and if available, the corresponding unit is returned. See the audioio.get_gain() function for details.
sep : str: String that separates section names in gainkey.

Returns

filepath : str or None: On success, the actual file name used for writing the data.

Raises

ImportError: The audioio module is not available.
ValueError: Invalid filepath or unit does not match gain in metadata.

def available_formats()

Data and audio file formats supported by any of the installed modules.

Returns

formats : list of str: List of supported file formats as strings.

def available_encodings(format)

Encodings of a data file format.

Parameters

format : str: The file format.

Returns

encodings : list of str: List of supported encodings as strings.

def write_data(filepath, data, rate, amax=1.0, unit=None, metadata=None, locs=None, labels=None, format=None, encoding=None, verbose=0, **kwargs)

Write data into a file.

Parameters

filepath : str: Full path and name of the file to write. File format is determined from extension.
data : 1-D or 2-D array of floats: Array with the data (first index time, second index channel).
rate : float: Sampling rate of the data in Hertz.
amax : float: Maximum possible amplitude of the data in unit.
unit : str: Unit of the data.
metadata : nested dict: Additional metadata.
locs : None or 1-D or 2-D array of ints: Marker positions (first column) and spans (optional second column) for each marker (rows).
labels : None or 2-D array of string objects: Labels (first column) and texts (optional second column) for each marker (rows).
format : str or None: File format. If None deduce file format from filepath. See available_formats() for possible values.
encoding : str or None: Encoding of the data. See available_encodings() for possible values. If None or empty string use 'PCM_16'.
verbose : int: If >0 show detailed error/warning messages.
kwargs : dict: Additional, file format specific keyword arguments.

Returns

filepath : str or None: On success, the actual file name used for writing the data.

Raises

ValueError: filepath is empty string or unspecified format.
IOError: Requested file format not supported.

Example

import numpy as np
from thunderlab.datawriter import write_data

rate = 28000.0
freq = 800.0
time = np.arange(0.0, 1.0, 1/rate)     # one second
data = 2.5*np.sin(2.0*np.p*freq*time)        # 800Hz sine wave
md = dict(Artist='underscore_')          # metadata
write_data('audio/file.npz', data, rate, 'mV', md)

def demo(file_path, channels=2, format=None)

Demo of the datawriter functions.

Parameters

file_path : str: File path of a data file.
format : str or None: File format to be used.

def main(*cargs)

Call demo with command line arguments.

Parameters

cargs : list of str: Command line arguments as provided by sys.argv[1:]