Module thunderlab.datawriter

Writing numpy arrays of floats to data files.

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 insert_container_metadata(metadata, data_dict, metadatakey='metadata')

Insert flattened metadata to data dictionary for a container file format.

Parameters

metadata : nested dict
Nested dictionary with key-value pairs of the meta data.
data_dict : dict
Dictionary of the data items contained in the container to which the metadata should be added.
metadatakey : str or list of str
Name of the variable holding the metadata.
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:]