Public API reference

The SpectroChemPy API publicly exposes many objects and functions. They are listed below exhaustively. What is not listed here is reserved for developers and should not normally be necessary for normal use of SpectroChemPy .

Loading the API

To use the API, you must import it using one of the following syntax:

In [1]: import spectrochempy as scp  # Recommended!

In [2]: nd = scp.NDDataset()
In [3]: from spectrochempy import *

In [4]: nd = NDDataset()

With the second syntax, as often in python, the access to objects/functions can be greatly simplified. For example, we can use NDDataset without a prefix instead of scp.NDDataset which is the first syntax) but there is always a risk of overwriting some variables or functions already present in the namespace. Therefore, the first syntax is generally highly recommended.

The NDDataset Object

The NDDataset is the main object use by SpectroChemPy .

Like numpy ndarrays, NDDataset have the capability to be sliced, sorted and subject to mathematical operations.

But, in addition, NDDataset may have units, can be masked and each dimension can also have coordinated with units. This make NDDataset aware of unit compatibility, e.g.,, for binary operation such as additions or subtraction or during the application of mathematical operations. In addition or in replacement of numerical data for coordinates, NDDataset can also have labeled coordinates where labels can be different kinds of objects (strings, datetime, numpy nd.ndarray or other NDDatasets, etc…).

This offers a lot of flexibility in using NDDatasets that, we hope, will be useful for applications. See the Tutorials for more information about such possible applications.

NDDataset

The main N-dimensional dataset class used by SpectroChemPy .

Creating NDDataset

A NDDataset can be created using the NDDataset class constructor, for instance here we create a dataset from a random two-dimensional array:

In [5]: import numpy as np

In [6]: X = np.random.random((4,4))

In [7]: nd = NDDataset(X)

The above code in SpectroChemPy can be simplified using the random creation method:

In [8]: X = NDDataset.random((4,4))

(see the User’s Guide for a large set of examples on how to use this constructor.)

Many SpectroChemPy methods mimics numpy equivalent, but output a NDDataset object.

Basic creation methods

empty

Return a new NDDataset of given shape and type, without initializing entries.

zeros

Return a new NDDataset of given shape and type, filled with zeros.

ones

Return a new NDDataset of given shape and type, filled with ones.

full

Return a new NDDataset of given shape and type, filled with fill_value.

empty_like

Return a new uninitialized NDDataset .

zeros_like

Return a NDDataset of zeros.

ones_like

Return NDDataset of ones.

full_like

Return a NDDataset of fill_value.

eye

Return a 2-D array with ones on the diagonal and zeros elsewhere.

identity

Return the identity NDDataset of a given shape.

random

Return random floats in the half-open interval [0.0, 1.0).

diag

Extract a diagonal or construct a diagonal array.

Creation from existing data

copy

Make a disconnected copy of the current object.

fromfunction

Construct a nddataset by executing a function over each coordinate.

fromiter

Create a new 1-dimensional array from an iterable object.

Creation from numerical ranges

arange

Return evenly spaced values within a given interval.

linspace

Return evenly spaced numbers over a specified interval.

logspace

Return numbers spaced evenly on a log scale.

geomspace

Return numbers spaced evenly on a log scale (a geometric progression).

Creation from from external sources

load

Open data from a '*.scp' (NDDataset) or '.pscp' (Project) file.

read

Generic read method.

read_bruker_nmr

read_carroucell

Open .spa files in a directory after a carroucell experiment.

read_csv

Open a *.csv file or a list of *.csv files.

read_ddr

Open a Surface Optics Corps.

read_dir

Read an entire directory.

read_dx

read_hdr

Open a Surface Optics Corps.

read_jcamp

Open Infrared JCAMP-DX files with extension .jdx or .dx.

read_jdx

read_labspec

Read a single Raman spectrum or a series of Raman spectra.

read_mat

Read a matlab file with extension .mat and return its content as a list.

read_matlab

Read a matlab file with extension .mat and return its content as a list.

read_omnic

Open a Thermo Nicolet OMNIC file.

read_opus

Open Bruker OPUS file(s).

read_quadera

Read a Pfeiffer Vacuum's QUADERA® mass spectrometer software file with extension .asc.

read_remote

Download and read files or an entire directory on github spectrochempy_data repository.

read_sdr

Open a Surface Optics Corps.

read_soc

Open a Surface Optics Corps.

read_spa

Open a Thermo Nicolet file or a list of files with extension .spa.

read_spc

Open a Thermo Nicolet file or a list of files with extension .spg.

read_spg

Open a Thermo Nicolet file or a list of files with extension .spg.

read_srs

Open a Thermo Nicolet file or a list of files with extension .srs.

read_topspin

Open Bruker TOPSPIN (NMR) dataset.

read_zip

Open a zipped list of data files.

read_carroucell

Open .spa files in a directory after a carroucell experiment.

download_nist_ir

Upload IR spectra from NIST webbook

Export a NDDataset

NDDataset.save

Save the current object in SpectroChemPy format.

NDDataset.save_as

Save the current NDDataset in SpectroChemPy format (*.scp).

write

Write the current dataset.

write_csv

Write a dataset in CSV format.

write_excel

This method is an alias of write_excel.

write_jcamp

This method is an alias of write_jcamp.

write_jdx

This method is an alias of write_jcamp.

write_mat

This method is an alias of write_matlab.

write_matlab

This method is an alias of write_matlab.

write_xls

This method is an alias of write_excel.

to_array

Return a numpy masked array.

to_xarray

Convert a NDDataset instance to an DataArray object.

Select data in a NDDataset

take

Take elements from an array.

Plotting functions

plot

Generic plot function.

plot_1D

Plot of one-dimensional data.

plot_pen

Plot a 1D dataset with solid pen by default.

plot_scatter

Plot a 1D dataset as a scatter plot (points can be added on lines).

plot_scatter_pen

Plot a 1D dataset with solid pen by default.

plot_with_transposed

Plot a 2D dataset as a stacked plot with its transposition in a second axe.

plot_bar

Plot a 1D dataset with bars.

plot_2D

Plot of 2D array.

plot_map

Plot a 2D dataset as a contoured map.

plot_stack

Plot a 2D dataset as a stack plot.

plot_image

Plot a 2D dataset as an image plot.

plot_3D

Plot of 2D array as 3D plot

plot_surface

Plot a 2D dataset as a a 3D-surface.

plot_waterfall

Plot a 2D dataset as a a 3D-waterfall plot.

plot_multiple

Plot a series of 1D datasets as a scatter plot with optional lines between markers.

multiplot

Generate a figure with multiple axes arranged in array (n rows, n columns).

multiplot_image

Plot a multiplot with 2D image type plots.

multiplot_lines

Plot a multiplot with 1D linetype plots.

multiplot_map

Plot a multiplot with 2D map type plots.

multiplot_scatter

Plot a multiplot with 1D scatter type plots.

multiplot_stack

Plot a multiplot with 2D stack type plots.

multiplot_with_transposed

Plot a 2D dataset as a stacked plot with its transposition in a second axe.

show

Method to force the matplotlib figure display.

Processing

Transpose-like oprations

transpose

Permute the dimensions of a NDDataset.

NDDataset.T

Transposed NDDataset .

swapdims

Interchange two dimensions of a NDDataset.

Changing number of dimensions

squeeze

Remove single-dimensional entries from the shape of a NDDataset.

Changing type

set_complex

Set the object data as complex.

set_hypercomplex

Alias of set_quaternion.

set_quaternion

Alias of set_quaternion.

Joining or splitting datasets

concatenate

Concatenation of NDDataset objects along a given axis.

stack

Stack of NDDataset objects along a new dimension.

Indexing

diag

Extract a diagonal or construct a diagonal array.

diagonal

Return the diagonal of a 2D array.

take

Take elements from an array.

Sorting

sort

Return the dataset sorted along a given dimension.

Minimum and maximum

argmin

Indexes of minimum of data along axis.

argmax

Indexes of maximum of data along axis.

coordmin

Find oordinates of the mainimum of data along axis.

coordmax

Find coordinates of the maximum of data along axis.

amin

Return the maximum of the dataset or maxima along given dimensions.

amax

Return the maximum of the dataset or maxima along given dimensions.

min

Return the maximum of the dataset or maxima along given dimensions.

max

Return the maximum of the dataset or maxima along given dimensions.

ptp

Range of values (maximum - minimum) along a dimension.

Clipping and rounding

clip

Clip (limit) the values in a dataset.

around

Evenly round to the given number of decimals.

round

Evenly round to the given number of decimals.

Algebra

dot

Return the dot product of two NDDatasets.

SVD

Performs a Singular Value Decomposition of a dataset.

LSTSQ

Least-squares solution to a linear matrix equation.

NNLS

Least-squares solution to a linear matrix equation with non-negativity constraints.

Logic functions

all

Test whether all array elements along a given axis evaluate to True.

any

Test whether any array element along a given axis evaluates to True.

Sums, integal, difference

sum

Sum of array elements over a given axis.

cumsum

Return the cumulative sum of the elements along a given axis.

trapz

An alias of trapezoid kept for backwards compatibility.

trapezoid

Integrate using the composite trapezoidal rule.

simps

simpson

Integrate using the composite Simpson's rule.

Complex

NDDataset.real

The array with real component of the data.

NDDataset.imag

The array with imaginary component of the data.

NDDataset.RR

The array with real component in both dimension of hypercomplex 2D data.

NDDataset.RI

The array with real-imaginary component of hypercomplex 2D data.

NDDataset.IR

The array with imaginary-real component of hypercomplex 2D data.

NDDataset.II

The array with imaginary-imaginary component of hypercomplex 2D data.

NDDataset.component

Take selected components of an hypercomplex array (RRR, RIR, ...).

conj

Conjugate of the NDDataset in the specified dimension.

conjugate

Conjugate of the NDDataset in the specified dimension.

abs

Calculate the absolute value of the given NDDataset element-wise.

absolute

Calculate the absolute value of the given NDDataset element-wise.

Masks

remove_masks

Remove all masks previously set on this array.

Units manipulation

Unit

Quantity

to

Return the object with data rescaled to different units.

to_base_units

Return an array rescaled to base units.

to_reduced_units

Return an array scaled in place to reduced units.

ito

Inplace scaling to different units.

ito_base_units

Inplace rescaling to base units.

ito_reduced_units

Quantity scaled in place to reduced units, inplace.

is_units_compatible

Check the compatibility of units with another object.

set_nmr_context

Set a NMR context relative to the given Larmor frequency.

mathematical operations

mc

Modulus calculation.

ps

Power spectrum.

Statistical operations

mean

Compute the arithmetic mean along the specified axis.

average

Compute the weighted average along the specified axis.

std

Compute the standard deviation along the specified axis.

sum

Sum of array elements over a given axis.

var

Compute the variance along the specified axis.

Baseline correction

BaselineCorrection

Baseline Correction processor.

BaselineCorrector

Launch a GUI for baseline corrections.

autosub

Automatic subtraction of a reference to the dataset.

ab

Alias of abc.

abc

Automatic baseline correction.

basc

Compute a baseline correction using the BaselineCorrection processor.

detrend

Remove linear trend along dim from dataset.

dc

Time domain baseline correction.

Fourier transform

fft

Apply a complex fast fourier transform.

ifft

Apply a inverse fast fourier transform.

ht

Hilbert transform.

fsh

Frequency shift by Fourier transform.

fsh2

Frequency Shift by Fourier transform.

Zero-filling

zf

Zero fill to given size.

zf_auto

Zero fill to next largest power of two.

zf_double

Zero fill by doubling original data size once or multiple times.

zf_size

Zero fill to given size.

Rolling

cs

Circular shift.

ls

Left shift and zero fill.

roll

Roll dimensions.

rs

Right shift and zero fill.

Phasing

pk

Linear phase correction.

pk_exp

Exponential Phase Correction.

Smoothing, apodization

savgol_filter

Apply a Savitzky-Golay filter to a NDDataset.

smooth

Smooth the data using a window with requested size.

bartlett

Calculate Bartlett apodization (triangular window with end points at zero).

blackmanharris

Calculate a minimum 4-term Blackman-Harris apodization.

hamming

Calculate generalized Hamming (== Happ-Genzel) apodization.

general_hamming

Calculate generalized Hamming apodization.

hann

Return a Hann window.

triang

Calculate triangular apodization with non-null extremities and maximum value normalized to 1.

em

Calculate exponential apodization.

gm

Calculate lorentz-to-gauss apodization.

sp

Calculate apodization with a Sine window multiplication.

sine

Strictly equivalent to sp.

qsin

Equivalent to sp, with pow = 2 (squared sine bell apodization window).

sinm

Equivalent to sp, with pow = 1 (sine bell apodization window).

Alignment, interpolation

align

Align individual NDDataset along given dimensions using various methods.

interpolate

Miscellaneous

pipe

Apply func(self, *args, **kwargs).

Fitting

Fit

Fit a 1D or 2D dataset, or a list of datasets.

ParameterScript

This class allow some manipulation of the parameter list for modelling.

FitParameters

Allow passing a dictionary of parameters with additional properties to the fit function.

CurveFit

Use non-linear least squares to fit a function, f, to data.

LSTSQ

Least-squares solution to a linear matrix equation.

NNLS

Least-squares solution to a linear matrix equation with non-negativity constraints.

Fitting models

gaussianmodel

Normalized 1D gaussian function.

lorentzianmodel

A standard Lorentzian function (also known as the Cauchy distribution).

voigtmodel

A Voigt model constructed as the convolution of a GaussianModel and a LorentzianModel.

asymmetricvoigtmodel

An asymmetric Voigt model.

sigmoidmodel

A Sigmoid function.

polynomialbaseline

Arbitrary-degree polynomial (degree limited to 10, however).

Analysis

find_peaks

Wrapper and extension of scpy.signal.find_peaks().

EFA

Evolving Factor Analysis.

PCA

Principal Component Analysis.

NNMF

Performs a Non Negative Matrix Factorization of a NDDataset .

SIMPLISMA

SIMPLe to use Interactive Self-modeling Mixture Analysis.

MCRALS

Performs MCR-ALS of a dataset knowing the initial C or St matrix.

IRIS

Integral inversion solver for spectroscopic data.

kern

Compute kernel of Fredholm equation of the 1st kind.

Project management

Project

A manager for projects, datasets and scripts.

Scripting

This is rather experimental

Script

Executable scripts.

run_script

Execute a given project script in the current context.

run_all_scripts

Execute all scripts in a project following their priority.

Utilities

Logging

set_loglevel

get_loglevel

debug_

Formatted debug message.

info_

Formatted info message.

warning_

Formatted warning message.

error_

Formatted error message.

Misc

show_versions

print the versions of spectrochempy and its dependencies

File

FileSelector

IPyWidgets interface for picking files.

pathclean

Clean a path or a series of path in order to be compatible with windows and unix-based system.