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 NDDataset
In [4]: from spectrochempy import * # strongly discouraged
In [5]: 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.
However instead of the second syntax, one can always use the following way to import objects or functions:
In [6]: from spectrochempy import NDDataset
In [7]: nd = NDDataset()
The NDDataset Object#
The NDDataset is the main object use by SpectroChemPy .
Like numpy.ndarray`s, `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 coordinates 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 Guides for more information about such possible applications.
The main N-dimensional dataset class used by |
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 [8]: import numpy as np
In [9]: X = np.random.random((4,4))
In [10]: nd = NDDataset(X)
The above code in SpectroChemPy can be simplified using the random creation method:
In [11]: X = NDDataset.random((4,4))
(see the Guides for a large set of examples on how to use this constructor.)
Many SpectroChemPy methods mimic numpy equivalent, but output a NDDataset object.
Basic creation methods#
Return a new |
|
Return a new |
|
Return a new |
|
Return a new |
|
Return a new uninitialized |
|
Return a |
|
Return |
|
Return a |
|
Return a 2-D array with ones on the diagonal and zeros elsewhere. |
|
Return the identity |
|
Return random floats in the half-open interval [0.0, 1.0). |
|
Return samples from a normal (Gaussian) distribution. |
|
Extract a diagonal or construct a diagonal array. |
Creation from existing data#
Construct a nddataset by executing a function over each coordinate. |
|
Create a new 1-dimensional array from an iterable object. |
Creation from numerical ranges#
Select data in a NDDataset#
Take elements from an array. |
Import/export#
Import a NDDataset from external source#
Reader functions may return either a single NDDataset or a list-like
ScpObjectList when several datasets are discovered and not merged. In that
case, helper methods such as datasets.names,
datasets.select_largest(ndim=2), and datasets.select_by_name("spectra")
make it easier to pick the dataset you want while staying in the public API.
The SOC readers read_soc, read_ddr, read_hdr and read_sdr are
kept as explicit public entry points. Their .ddr, .hdr and .sdr
files are SPA-compatible and share the private OMNIC SPA parser, but the SOC
readers preserve SOC provenance and their established multi-file defaults.
The reader catalog lists formats,
explicit readers and required plugins. With spectrochempy-nmr installed,
use scp.nmr.read(…) for NMR format detection.
The compatibility aliases scp.read_topspin()
and scp.read_agilent()
are documented in the plugin API. The read_perkinelmer alias
requires spectrochempy-perkinelmer.
Load a native SpectroChemPy dataset or project from a |
|
Migrate a legacy SCP/PSCP file to the safe raw-base64 format. |
|
Read data from various file formats. |
|
Open CSV (comma-separated values) files. |
|
Open a Surface Optics Corp. |
|
Read an entire directory. |
|
Open a Surface Optics Corp. |
|
Open infrared, Raman, UV-visible, and supported processed 1D and real 2D NMR |
|
Open Raman LABSPEC files. |
|
Open a Thermo Nicolet OMNIC file. |
|
Open Bruker OPUS file(s). |
|
Open PerkinElmer |
|
Open a Pfeiffer Vacuum's QUADERA mass spectrometer software file. |
|
Open a Surface Optics Corp. |
|
Read a Surface Optics Corp. |
|
Open a Thermo Nicolet file or a list of files with extension |
|
Open Galactic files. |
|
Open a Thermo Nicolet file or a list of files with extension |
|
Open a Thermo Nicolet file or a list of files with extension |
|
Open Renishaw Wire files. |
|
Open Renishaw Wire files. |
|
Open Matlab files. |
|
Open Matlab files. |
|
Build a minimal |
|
Reconstruct an |
|
Upload the classical "iris" dataset. |
|
Upload IR spectra from NIST webbook. |
Export a NDDataset#
Save dataset in native .scp format. |
|
Save the current NDDataset in SpectroChemPy format (.scp). |
|
Write the current dataset. |
|
Write a dataset in CSV format. |
|
Write a dataset in JCAMP-DX format. |
|
This method is an alias of |
|
This method is an alias of |
|
Return a numpy masked array. |
|
Persist this dataset to NetCDF using the canonical xarray mapping. |
|
Convert a NDDataset instance to an |
Plotting#
Route plotting to the appropriate backend. |
|
Plot of one-dimensional data. |
|
Plot a 1D dataset with line rendering. |
|
Plot a 1D dataset with marker-based scatter rendering. |
|
Plot a 1D dataset with solid pen by default. |
|
Plot a 2D dataset as a stacked plot with its transposition in a second axe. |
|
Plot a 1D dataset as a bar chart. |
|
Plot of 2D array. |
|
Plot a 2D dataset as a contour plot. |
|
Plot a 2D dataset as a filled contour (image-like) plot. |
|
Plot a 2D dataset with image-like filled rendering. |
|
Plot a 2D dataset as a stack plot with lines. |
|
Plot a 2D dataset as a contour map. |
|
Plot a 2D dataset as a stack plot. |
|
Plot of 2D array as 3D plot. |
|
Plot a 2D dataset as a a 3D-surface. |
|
Plot a 2D dataset as a a 3D-waterfall plot. |
|
Overlay several 1D datasets on a single Matplotlib axes. |
|
Arrange datasets on a grid of Matplotlib axes. |
|
Plot a multiplot with 2D contour type plots. |
|
Plot a multiplot with 2D filled contour (image-like) type plots. |
|
Plot a multiplot with 1D linetype plots. |
|
Plot a multiplot with 1D scatter type plots. |
|
Plot a 2D dataset as a stacked plot with its transposition in a second axe. |
|
Force display of existing Matplotlib figures. |
Plot PCA scores as a 2D or 3D scatter plot. |
|
Plot a scree plot with explained variance bars and cumulative curve. |
|
Compare two datasets (X vs X_ref) with optional residual. |
|
Plot merit for an analysis object. |
|
Plot original, baseline, and corrected spectra in two stacked axes. |
|
Plot predicted vs measured values (parity plot). |
Processing#
Transpose-like operations#
Changing number of dimensions#
Remove single-dimensional entries from the shape of a NDDataset. |
Changing type#
Set the object data as complex. |
Joining or splitting datasets#
Chemometric preprocessing#
Normalize data along a dimension. |
|
Subtract the mean along a dimension (mean-centering). |
|
Mean-center and scale to unit variance along a dimension. |
|
Apply Standard Normal Variate (SNV) correction. |
|
Multiplicative Scatter Correction (MSC). |
|
Apply Pareto scaling along a dimension. |
|
Scale data by the range along a dimension. |
|
Apply robust scaling along a dimension. |
|
Apply a logarithmic transform. |
|
Mean-centering transformer. |
|
Autoscaling (z-score) transformer. |
|
Standard Normal Variate (SNV) transformer. |
|
Normalization transformer. |
|
Multiplicative Scatter Correction (MSC) transformer. |
|
Pareto scaling transformer. |
|
Range scaling transformer. |
|
Robust scaling transformer. |
|
Logarithmic transform. |
Indexing#
Sorting#
Return the dataset sorted along a given dimension. |
Minimum and maximum#
Indexes of minimum of data along axis. |
|
Indexes of maximum of data along axis. |
|
Find oordinates of the mainimum of data along axis. |
|
Find coordinates of the maximum of data along axis. |
|
Return the maximum of the dataset or maxima along given dimensions. |
|
Return the maximum of the dataset or maxima along given dimensions. |
|
Return the maximum of the dataset or maxima along given dimensions. |
|
Return the maximum of the dataset or maxima along given dimensions. |
|
Range of values (maximum - minimum) along a dimension. |
Clipping and rounding#
Algebra#
Logic functions#
Sums, integral, difference#
Sum of array elements over a given axis. |
|
Return the cumulative sum of the elements along a given axis. |
|
Integrate using the composite trapezoidal rule. |
|
Integrate using the composite Simpson's rule. |
|
Integrate the multilinear interpolant over one physical ND box. |
|
One physical integral with standard uncertainty and detached provenance. |
Complex#
Masks#
MASKED and NOMASK are the public sentinels used to set and represent
dataset masks. MaskedArray and MaskedConstant retain their NumPy identities for
interoperability; routine workflows should keep data in NDDataset. See
Units, quantities, and masks for their SpectroChemPy roles and verified examples.
Remove all masks previously set on this array. |
Units manipulation#
ur is the unit registry configured by SpectroChemPy; Unit and Quantity use
that registry while retaining their Pint identities. DimensionalityError is the
original Pint exception class retained for interoperability. See
Units, quantities, and masks for project-specific construction, conversion, mutation,
dimensionless-value, and error-handling guidance.
Raised when trying to convert between incompatible units. |
|
Return the object with data rescaled to different units. |
|
Return an array rescaled to base units. |
|
Return an array scaled in place to reduced units. |
|
Inplace scaling to different units. |
|
Inplace rescaling to base units. |
|
Quantity scaled in place to reduced units, inplace. |
|
Check the compatibility of units with another object. |
Mathematical operations#
Statistical operations#
Compute the arithmetic mean along the specified axis. |
|
Compute the weighted average along the specified axis. |
|
Compute the root mean square magnitude. |
|
Compute the standard deviation along the specified axis. |
|
Sum of array elements over a given axis. |
|
Compute the variance along the specified axis. |
Baseline correction#
Baseline Correction processor. |
|
Automatic subtraction of a reference to the dataset. |
|
Compute a baseline using the Baseline class processor. |
|
Compute a baseline corrected dataset using the Baseline class processor. |
|
Remove a polynomial trend along the last dimension of a dataset. |
|
Asymmetric Least Squares Smoothing baseline correction. |
|
Perform the Simple Non-Iterative Peak (SNIP) detection algorithm. |
Fourier transform#
Phasing#
Time-domain processing#
Offset correction#
Time domain baseline correction. |
Zero-filling#
Rolling#
Apodization#
Calculate Bartlett apodization (triangular window with end points at zero). |
|
Calculate a minimum 4-term Blackman-Harris apodization. |
|
Calculate generalized Hamming (== Happ-Genzel) apodization. |
|
Calculate generalized Hamming apodization. |
|
Return a Hann window. |
|
Calculate triangular apodization with non-null extremities and maximum value normalized to 1. |
|
Calculate exponential apodization. |
|
Calculate lorentz-to-gauss apodization. |
|
Calculate apodization with a Sine window multiplication. |
|
Strictly equivalent to |
|
Equivalent to |
|
Equivalent to |
Smoothing, filtering, denoising#
Filters/smoothers processor. |
|
Differentiate a spectrum using a Savitzky-Golay polynomial filter. |
|
Savitzky-Golay filter. |
|
Smooth the data using a window with requested size. |
|
Smooth the data using the Whittaker smoothing algorithm. |
|
Denoise the data using a PCA method. |
|
Remove spikes from the data. |
Alignment, interpolation#
Align individual |
|
Interpolate dataset onto new coordinates. |
Miscellaneous#
Apply func(self, *args, **kwargs). |
Analysis#
Pipeline composition#
Linear composition of allowlisted SpectroChemPy preprocessing and estimators. |
Linear regression#
Non-linear optimization and curve fit#
Non-linear curve fitting driven by the SpectroChemPy fitting DSL. |
Partial Least Square regression#
Supervised cross-validation#
cross_validate evaluates one fixed PLS or PLS-ending Pipeline
configuration. It does not perform hyperparameter search or nested
cross-validation. KFold, GroupKFold, and LeaveOneOut are thin,
documented SpectroChemPy subclasses of the corresponding scikit-learn classes.
They reuse scikit-learn’s partitioning algorithms to produce fold positions,
while cross_validate handles NDDataset alignment and sample_dim,
fold-local estimator cloning and preprocessing, out-of-fold predictions, and
metrics. The original scikit-learn classes remain accepted explicitly.
KFold partitions observations into folds, with optional shuffling and a
reproducible random seed. GroupKFold keeps each supplied group entirely in
calibration or validation within a fold. LeaveOneOut validates one
observation per fold. Calling a splitter’s split method directly requires
an array-like input appropriate for scikit-learn; the splitter alone does not
interpret NDDataset dimensions or coordinates.
Evaluate a fixed supervised regression configuration by cross-validation. |
|
Split observations into consecutive cross-validation folds. |
|
Split observations while keeping each group in a single validation fold. |
|
Use each observation once as a one-observation validation fold. |
Structured result returned by |
Two-dimensional correlation spectroscopy#
correlation_spectroscopy calculates synchronous and asynchronous maps from a
two-dimensional spectral series. The perturbation coordinate must be real and
classified as linear by Coord; its sigdigits and linearize_below
settings determine how near-linear source coordinates are normalized. A
default Coord uses linearize_below=0.1; set a stricter value when source
deviations must remain visible to validation. Interpolate missing acquisitions
before calculation. The asynchronous sign follows the perturbation order.
Maps returned by |
Calculate synchronous and asynchronous 2D correlation spectra. |
Evolving factor analysis#
Evolving Factor Analysis (EFA). |
Multivariate Curve Resolution - Alternating Least Squares#
Multivariate Curve Resolution Alternating Least Squares (MCRALS). |
MCRALS Constraints#
These public classes describe scientific prior knowledge about the
concentration ("C") or spectral ("St") profiles estimated by
MCRALS. They form the foundation of the future constraint-based
API for MCRALS and are currently declarative containers and
validators only — they are not yet connected to the internal ALS
constraint engine. See the project RFC for the planned migration path.
Import them from the spectrochempy.analysis.constraints submodule:
from spectrochempy.analysis import constraints
constraints.NonNegative("C")
constraints.Closure("C")
constraints.ReferenceProfile("St", component=0, data=reference)
Abstract base class for MCRALS constraints. |
|
Closure (constant sum) constraint. |
|
Fixed-values constraint. |
|
Monotonicity constraint. |
|
Non-negativity constraint. |
|
Profile generator constraint. |
|
Reference-profile constraint. |
|
Selectivity constraint. |
|
Unimodality constraint. |
|
Zero-region constraint. |
Independent Component Analysis#
Fast algorithm for Independent Component Analysis (FastICA). |
Non-Negative Matrix Factorization#
Non-Negative Matrix Factorization (NMF). |
Singular value decomposition and Principal component analysis#
SIMPLe to use Interactive Self-modeling Mixture Analysis#
SIMPLe to use Interactive Self-modeling Mixture Analysis (SIMPLISMA). |
Phase Sensitive Detection#
PSD (Phase-Sensitive Detection) for demodulating spectroscopic data. |
Utilities#
Lineshape models#
Return a 1D polynomial profile. |
|
Return a Gaussian profile. |
|
1D Gaussian function. |
|
Return a Lorentzian profile. |
|
A standard Lorentzian function (also known as the Cauchy distribution). |
|
Return a pseudo-Voigt profile. |
|
A pseudo-Voigt model. |
|
Return a Voigt profile. |
|
A Voigt model constructed as the convolution of a |
|
Return an asymmetric Voigt profile. |
|
An asymmetric Voigt model. |
|
Return a sigmoid profile. |
|
A Sigmoid function. |
|
Arbitrary-degree polynomial (degree limited to 10, however). |
|
Simulate an additive spectrum of separable peaks on a coordinate grid. |
Find peaks#
Find and analyze peaks in spectroscopic data with advanced filtering options. |
|
Structured result returned by |
|
Dependency-light tabular view of detected peaks. |
|
Measure sampled peak positions, heights and apparent FWHM in a spectrum. |
|
Group detected peaks and measure apparent axial widths on a 2D spectrum. |
|
Per-peak measurements, group membership and structured provenance. |
Segmentation#
Label connected regions above a threshold in a real 1D or 2D spectrum. |
Kinetics#
An object which stores a reaction network of elementary reactions. |
|
Project management#
Lightweight hierarchical container for datasets and subprojects. |
Utilities#
Logging#
Set the logging level for SpectroChemPy. |
|
Get current logging level. |
|
Forward to the |
|
Forward to the |
|
Forward to the |
|
Forward to the |
Misc#
Print the versions of spectrochempy and its dependencies. |
Multi-object files#
A list subclass for groups of SpectroChemPy objects returned by public APIs. |
File#
Clean a path or a series of path. |