Data containers

Experimental Raman spectroscopic data can be very diverse, depending on their data acquisition modality and instrumental origin. This usually makes any consecutive operations heavily application-specific, which in turn impedes the development of transferable and reusable workflows.

RamanSPy resolves this by decoupling its data management core from its preprocessing and analysis functionalities. This is achieved by establishing efficient and scalable data representation classes built upon numpy ndarrays, which capture and define relevant information and behaviour in the background to allow a smooth, modification-free experience, regardless of the data of interest.

This includes a generic spectral container class SpectralContainer, as well as the more specialised Spectrum, SpectralImage and SpectralVolume classes, which correspond to single spectra, Raman imaging data and volumetric Raman data respectively.

For the most part, the construction of these classes is automated through the various Data loading and Datasets methods in RamanSPy. However, the containers can be populated manually as well, if required.

Note

While these data containers provide a common data format that facilitates the integration of data across acquisition modalities, instruments, vendors, labs and applications, it is important to note this must be done while respecting the inherent differences and scientific contexts of different data sources.

Generic container

class ramanspy.SpectralContainer(spectral_data, spectral_axis)

The base class that settles as the backbone of the package. It encapsulates a spectral data container of an arbitrary dimension and defines relevant behaviour and information.

Parameters:

• spectral_data (array_like of shape (x, y, z, ..., B)) – The intensity values to store. Last dimension must be the spectral dimension.

• spectral_axis (array_like of shape (B, )) – The Raman wavenumber axis (in cm^-1). Order and length must match the last dimension of spectral_data.

Note

If your spectral data is not in Raman wavenumber units (cm^-1) but in Raman wavelength (nm) instead, simply use the ramanspy.utils.wavelength_to_wavenumber() method to convert your spectral_axis before initialising a SpectralContainer instance.

Note that you will need to put in the excitation wavelength (nm) of the laser used to acquire the data of interest to make the conversion.

Example

import numpy as np
import ramanspy as rp

spectral_data = np.random.rand(20, 1500)
spectral_axis = np.linspace(100, 3600, 1500)

# if the spectral axis is in wavelength units (nm) and needs converting
spectral_axis = rp.utils.wavelength_to_wavenumber(spectral_axis)

raman_object = rp.SpectralContainer(spectral_data, spectral_axis)

band(spectral_band: Number) → ndarray

Returns a spectral slice across the closest spectral band in the axis to the one given.

property flat: SpectralContainer

Flatten all spatial dimensions of the spectral object into a single one.

Return type:

numpy.ndarray of shape (dim_1*dim_2*…*dim_n, B)

classmethod from_stack(stack: List[Spectrum]) → SpectralContainer

Returns the combined Raman object defined by stacking the collection of individual spectra given.

The spectral axes of the spectra provided must match.

static load(filename: str)

Load a spectral object from a pickle file.

Parameters:

filename (str) – The name of the file to load a spectral object from. Must be the full path or the path relative to the working directory.

property mean: Spectrum

Returns the mean spectrum in the spectral object.

save(filename: str, directory: str = None)

Save the spectral object to a pickle file.

Parameters:

• filename (str) – The name of the file to save the spectral object to.

• directory (str, optional) – The name of the directory to save the file in. Must be the full path to the directory or the path relative to the working directory. If not provided (default), the file will be saved in the working directory.

property shape: tuple[int]

Returns the (spatial) shape of the spectral object (i.e. without the last dimension).

property spectral_length: int

Returns the spectral length B of the spectral object.

tolist() → list[Spectrum]

Returns the spectral object as a list of Spectrum objects.

See also

Check the Storing generic data tutorial for more information about how to define and use spectral data containers in RamanSPy.

Specialised containers

Additional data-specific information is added through the specialised Spectrum, SpectralImage and SpectralVolume classes. These ensure that the data management of single spectra, imaging and volumetric Raman data is appropriately dealt with without the need for any data-related user modifications.

Spectra

class ramanspy.Spectrum(spectral_data, spectral_axis)

Bases: SpectralContainer

The Spectrum class defines a 1D spectroscopic signal of an arbitrary spectral length.

Example

import numpy as np
import ramanspy as rp

spectral_data = np.random.rand(1500)
spectral_axis = np.linspace(100, 3600, 1500)

raman_spectrum = rp.Spectrum(spectral_data, spectral_axis)

peaks(*, height=None, threshold=None, distance=None, prominence=None, width=None, wlen=None, rel_height=0.5, plateau_size=None)

plot(**kwargs)

Plots the spectrum.

Parameters:

**kwargs (keyword arguments, optional,) – Check the :meth:`ramanspy.plot.spectra’ method for a list of keyword parameters.

See also

Check the Storing spectra tutorial for more information about how to define and use Spectrum data containers in RamanSPy.

Imaging

class ramanspy.SpectralImage(spectral_data, spectral_axis)

Bases: SpectralContainer

The SpectralImage class defines a 2D spectroscopic image. Dimensions must be in the order of (x, y, B).

Example

import numpy as np
import ramanspy as rp

spectral_data = np.random.rand(50, 50, 1500)
spectral_axis = np.linspace(100, 3600, 1500)

raman_image = rp.SpectralImage(spectral_data, spectral_axis)

plot(bands: Number | List[Number], **kwargs)

Plots the spectral image slice(s) across the spectral image, defined by the band(s) provided (using the closest band(s) in the spectral axis of the image to the one(s) given).

Parameters:

• bands (Number or List[Number]) – The spectral bands to plot across.

• **kwargs (keyword arguments, optional,) – Check the :meth:`ramanspy.plot.image’ method for a list of keyword parameters.

See also

Check the Storing imaging data tutorial for more information about how to define and use SpectralImage data containers in RamanSPy.

Volumetric

class ramanspy.SpectralVolume(spectral_data, spectral_axis)

Bases: SpectralContainer

The SpectralVolume class defines a 3D spectroscopic volume. Dimensions must be in the order of (x, y, z, B).

Example

import numpy as np
import ramanspy as rp

spectral_data = np.random.rand(50, 50, 10, 1500)
spectral_axis = np.linspace(100, 3600, 1500)

raman_volume = rp.SpectralVolume(spectral_data, spectral_axis)

classmethod from_image_stack(image_stack: List[SpectralImage]) → SpectralVolume

Returns the volumetric Raman object defined by z-stacking the collection of spectral images given.

All dimensions of the spectral images must match, as well as their spectral axes.

layer(layer_index: int) → SpectralImage

Returns the SpectralImage layer specified by the given index as a SpectralImage. Index must be between 0 and |z dimension|-1.

plot(bands, **kwargs)

Plots the spectral volume slice(s) across the spectral volume, defined by the band(s) provided (using the closest band(s) in the spectral axis of the image to the one(s) given).

Parameters:

• bands (Number or List[Number]) – The spectral bands to plot across.

• **kwargs (keyword arguments, optional,) – Check the :meth:`ramanspy.plot.volume’ method for a list of keyword parameters.

See also

Check the Storing volumetric data tutorial for more information about how to define and use SpectralVolume data containers in RamanSPy.