× ⚠️ You are reading the development version documentation.
Read here the documentation of the last stable release.

spectrochempy.read_matlab

read_matlab(*paths, **kwargs)

Open Matlab files.

This is the explicit Matlab reader in the public import API. Use spectrochempy.read for generic format autodetection and scp.matlab.read(...) or spectrochempy.read_matlab when the Matlab format is already known.

A Matlab file may contain one or several numeric variables. Compatible variables can be grouped into a single dataset, while non-merged multi-file or multi-variable reads may return a list-like ScpObjectList with helper methods for dataset selection. See spectrochempy.read for the complete description of the generic import convention and multi-object return behavior.

Parameters:

• *paths (str, Path object objects or valid urls, optional) – The data source(s) can be specified by the name or a list of name for the file(s) to be loaded:

  • e.g., ( filename1, filename2, …, kwargs )

  If the list of filenames are enclosed into brackets:

  • e.g., ( [filename1, filename2, …], kwargs )

  The returned datasets are merged to form a single dataset, except if merge is set to False.

• **kwargs (keyword parameters, optional) – See Other Parameters.

Returns:

object (NDDataset or ScpObjectList of NDDataset) – The returned dataset(s). When several datasets are returned, the result is a list-like ScpObjectList with helper attributes such as .names, .select_largest(), .select_by_name(), .filter_by_ndim(), and .filter_by_shape().

Other Parameters:

• content (bytes object, optional) – Instead of passing a filename for further reading, a bytes content can be directly provided as bytes objects. The most convenient way is to use a dictionary. This feature is particularly useful for a web application to handle drag and drop of files into a Browser.

• csv_delimiter (str, optional, default: csv_delimiter) – Set the column delimiter in CSV file.

• description (str, optional) – A custom description.

• directory (Path object objects or valid urls, optional) – From where to read the files.

• download_only (bool, optional, default: False) – Used only when url are specified. If True, only downloading and saving of the files is performed, with no attempt to read their content.

• merge (bool, optional, default: False) – If True and several filenames or a directory have been provided as arguments, then a single NDDataset with merged dataset (stacked along the first dimension) is returned. In the case not all datasets have compatible dimensions or types/origins, then several NDDatasets can be returned for different groups of compatible datasets.

• origin (str, optional) – If provided it may be used to define the type of experiment: e.g., ‘ir’, ‘raman’,.. or the origin of the data, e.g., ‘omnic’, ‘opus’, … It is often provided by the reader automatically, but can be set manually.

  It is used, for instance, when reading a directory with different types of files and merging compatible datasets into separate groups by origin.

  It is also used when reading with the CSV protocol. In order to properly interpret CSV file it can be necessary to set the origin of the spectra. Up to now only 'omnic' and 'tga' have been implemented.

• pattern (str, optional) – A pattern to filter the files to read.

  Added in version 0.7.2.

• protocol (str, optional) – Protocol used for reading, for example 'scp', 'omnic', 'opus', 'matlab', 'jcamp', 'csv', or 'excel'. If not provided, the correct protocol is inferred whenever possible from the filename extension.

• read_only (bool, optional, default: True) – Used only when url are specified. If True, saving of the files is performed in the current directory, or in the directory specified by the directory parameter.

• recursive (bool, optional, default: False) – Read also in subfolders.

• replace_existing (bool, optional, default: False) – Used only when url are specified. By default, existing files are not replaced so not downloaded.

• sortbydate (bool, optional, default: True) – Sort multiple filename by acquisition date.

See also

read

Generic reader inferring protocol from the filename extension.

spectrochempy.read_zip

Read Zip archives (containing spectrochempy readable files)

spectrochempy.read_dir

Read an entire directory.

spectrochempy.read_opus

Read OPUS spectra.

spectrochempy.read_labspec

Read Raman LABSPEC spectra (.txt).

spectrochempy.read_omnic

Read Omnic spectra (.spa, .spg, .srs).

spectrochempy.read_soc

Read Surface Optics Corps. files (.ddr , .hdr or .sdr).

spectrochempy.read_spc

Read Galactic files (.spc).

spectrochempy.read_quadera

Read a Pfeiffer Vacuum’s QUADERA mass spectrometer software file.

spectrochempy.read_csv

Read CSV files (.csv).

spectrochempy.read_jcamp

Read Infrared JCAMP-DX files (.jdx, .dx).

spectrochempy.read_wire

Read Renishaw Wire files (.wdf).

Notes

A single Matlab file may hold several variables. Each numeric variable is converted to an NDDataset named after the Matlab variable; the importer then groups them by compatible shape, stacking same-shape arrays into a single NDDataset and returning incompatible ones as separate datasets. Non-numeric variables (e.g. character arrays) and Matlab-internal entries (__header__, __version__, __globals__) are skipped. When a file holds a single numeric variable a lone NDDataset is returned.

When several datasets are returned, the result keeps the Matlab variable names and can be queried directly, for example with .names, .select_largest(), .select_by_name(), .filter_by_ndim(), or .filter_by_shape().

If the file matches the minimal exchange payload written by spectrochempy.write_matlab (i.e. it contains the data, dims, coords, coord_units, coord_titles, name, and title variables with the expected shapes and dtypes), a single NDDataset is reconstructed directly from those fields instead of going through the generic per-variable import: values, dimension names, coordinates (values, units, titles), name, title, units, and description are all restored. Masked values are not reconstructed, since the exchange payload stores them as plain NaN with no separate mask array; they come back unmasked. Any other mat file, including ones that only partially match this structure, is read through the generic path described above.

Examples

Reading a single Matlab file

>>> scp.read_matlab('irdata/matlab/matlabdata.mat')
NDDataset: [float64] a.u. (shape: (y:1, x:3))

Using the explicit namespace API

>>> scp.matlab.read('irdata/matlab/matlabdata.mat')
NDDataset: [float64] a.u. (shape: (y:1, x:3))

Selecting datasets from a multi-variable Matlab file

>>> datasets = scp.read_matlab('irdata/matlab/matlabdata.mat', merge=False)
>>> names = datasets.names
>>> len(names)
1
>>> largest = datasets.select_largest()
>>> largest.ndim
2
>>> filtered = datasets.filter_by_ndim(2)
>>> len(filtered)
1
>>> datasets.select_by_name('data').name
'data'

Examples using spectrochempy.read_matlab

SIMPLISMA example

SIMPLISMA example