loader

This package provides a collection of modules for handling various file formats and converting their contents into a unified DataCube format.

The wizard.read() function serves as the main entry point for users. It abstracts the file handling process and automatically determines the appropriate handler based on the file type. For example:

from wizard import read

# Reading an FSM file
datacube = read('test.fsm')

# Reading a CSV file
datacube = read('data.csv')

Supported DataCube File Formats
Extension	Read Supported	Write Supported
.csv	✅	✅
.xlsx	✅	✅
.tdms	✅	❌
.fsm	✅	❌
.folder	✅	❌
.nrrd	✅	❌
.image	✅	❌
.hdr	✅	✅

Each file format has a corresponding module with specialized functions for reading and writing data.

csv 

This module includes functions for reading and writing .csv files.

Functions

wizard._utils._loader.csv._read_csv(filepath)[source]

Read a CSV file and convert it into a DataCube.

The CSV file should have: - ‘x’ and ‘y’ as the first two columns (integer values representing spatial coordinates). - The remaining columns as spectral data with corresponding wavelengths in the header.

Parameters:: filepath (str) – Path to the CSV file.
Returns:: A DataCube containing the parsed data.
Return type:: DataCube

wizard._utils._loader.csv._write_csv(dc, filename)[source]

Write a DataCube to a CSV file.

The output CSV file will have: - ‘x’ and ‘y’ as the first two columns. - The remaining columns containing spectral data.

Parameters:

dc (DataCube) – The DataCube to be written.
filename (str) – Name of the output CSV file.

Return type:

None

folder 

This module includes functions for reading images from files and converting them into a DataCube.

Functions

wizard._utils._loader.folder._read_folder(path, **kwargs)[source]

Load a folder of images into a DataCube.

This function reads all images in the specified folder, filters them by type, and loads them into a DataCube.

Parameters:

path (str) – Path to the directory containing image files.

Returns:

A DataCube containing the loaded images.

Return type:

DataCube

Raises:

FileNotFoundError – If the specified directory does not exist.
ValueError – If no valid image files are found in the directory.

fsm 

This module includes functions for reading .fsm files, typically from Perkin Elmer instruments.

Functions

wizard._utils._loader.fsm._read_fsm(path)[source]

Read function for FSM files from Perkin Elmer. Tested with FTIR data.

Parameters:

path (str) – Path to the FSM file.

Returns:

DataCube containing the spectral data and wavelengths.

Return type:

DataCube

Raises:

FileNotFoundError – If the specified file does not exist.
ValueError – If the file format is incorrect.

Note

The FSM module in this package was inspired by the specio repository by paris-saclay-cds. The original repository can be found at GitHub.

nrrd 

This module includes functions for reading and writing .nrrd files, which are commonly used to store multi-dimensional data, particularly in the field of medical imaging.

Functions

wizard._utils._loader.nrrd._read_nrrd(path)[source]

Read a NRRD file and convert it into a DataCube.

Parameters:

path (str) – The file path to the NRRD file.

Returns:

A DataCube containing the data from the NRRD file.

Return type:

DataCube

Raises:

FileNotFoundError – If the specified file does not exist.
ValueError – If the NRRD file does not contain the expected metadata.

wizard._utils._loader.nrrd._write_nrrd(dc, path)[source]

Write a DataCube to a NRRD file.

Parameters:

dc (DataCube) – The DataCube to write to the NRRD file.
path (str) – The file path where the NRRD file will be saved.

Returns:

None

Raises:

ValueError – If the DataCube is empty or does not contain valid data.

Return type:

None

pickle 

This module includes functions for reading pickle files that store serialized Python objects, specifically NumPy arrays.

Functions

wizard._utils._loader.pickle._read_pickle(path)[source]

Load a pickled NumPy array and convert it into a DataCube.

Parameters:

path (str) – The file path to the pickle file.

Returns:

A DataCube containing the loaded NumPy array.

Return type:

DataCube

Raises:

FileNotFoundError – If the specified file does not exist.
ValueError – If the loaded data is not in the expected format.

wizard._utils._loader.pickle._write_pickle(data, path)[source]

Save a DataCube object to a pickle file.

Parameters:

data (DataCube) – The DataCube object to be saved.
path (str) – The file path where the DataCube will be saved.

Returns:

None

Raises:

TypeError – If the data cannot be pickled.
IOError – If there is an error writing to the file.

Return type:

None

tdms 

This module includes functions for reading .tdms files, specifically designed to extract spectral data and organize it into a DataCube format.

Functions

wizard._utils._loader.tdms._read_tdms(path)[source]

Optimized TDMS reader: reads the file, cleans and filters columns, vectorizes operations, and builds DataCube efficiently.

Parameters:: path (str)
Return type:: DataCube

xlsx 

This module includes functions for reading from and writing to .xlsx files, facilitating the import and export of spectral data organized in a DataCube format.

Functions

wizard._utils._loader.xlsx._read_xlsx(filepath)[source]

Read a .xlsx file and convert its contents into a DataCube.

This function extracts spectral data from the specified Excel file, organizing it into a structured DataCube format. It expects the first two columns to contain ‘x’ and ‘y’ coordinates, with the remaining columns representing spectral data.

Parameters:

filepath (str) – The path to the .xlsx file to be read.

Returns:

A DataCube containing the parsed data from the Excel file.

Return type:

DataCube

Raises:

FileNotFoundError – If the specified file does not exist.
ValueError – If the data cannot be parsed correctly.

wizard._utils._loader.xlsx._write_xlsx(dc, filename)[source]

Write a DataCube to a .xlsx file.

This function exports the provided DataCube and its associated wavelengths to an Excel file.

Parameters:

datacube (wizard.DataCube) – The data to be written, structured as a 3D NumPy array.
filename (str) – The name of the file to which the data will be saved (without extension).
dc (DataCube)

Raises:

ValueError – If the dimensions of the datacube and wavelengths do not match.

Return type:

None

hdr / envi 

This module includes functions for reading from and writing to .hdr files, facilitating the import and export of spectral data organized in a DataCube format.

Functions

wizard._utils._loader.hdr._read_hdr(path, image_path=None)[source]

Read an ENVI file and convert it into a DataCube.

This function supports both standard and custom ENVI setups: - If only the header file is provided, the associated binary file is inferred from the metadata. - If both header and binary paths are provided, they are used explicitly.

Parameters:

path (str) – Path to the ENVI header (.hdr) file.
image_path (str, optional) – Path to the binary image file, if different or located elsewhere.

Returns:

A DataCube containing the spectral image data and wavelengths.

Return type:

DataCube

Raises:

FileNotFoundError – If the header or associated image file is not found.

Examples

>>> import wizard
>>> dc = wizard.read("/path/to/image.hdr")
>>> dc = wizard.read(path='/path/to/image.hdr', image_path='/path/to/image.img')

wizard._utils._loader.hdr._write_hdr(dc, file_path)[source]

Write a DataCube to an ENVI file.

The function exports the DataCube into ENVI format with a header and binary file. Wavelengths are stored in the header metadata.

Parameters:

dc (DataCube) – The DataCube to be written to disk.
file_path (str) – Path to the ENVI header (.hdr) file (without extension or with .hdr).

Return type:

None

Examples

>>> import wizard
>>> wizard._utils._loader.hdr._write_hdr("/path/to/output")