pybaselines

pybaselines is a Python library designed for baseline correction on experimental data (e.g., Raman, FTIR, NMR, XRD, XRF, PIXE, MALDI-TOF, LIBS). It provides a semi-unified API to facilitate testing and comparing different algorithms on a single dataset. The library includes over 50 algorithms, many of which are adapted directly from literature to preserve their original names.

Key algorithms include:

• AsLS
• airPLS
• ModPoly
• SNIP
• Penalized spline versions of Whittaker-smoothing-based algorithms

When using Whittaker-smoothing-based algorithms for two-dimensional data, the lam parameter controls the smoothness of the baseline. You can provide it in two ways:

1. Single value: A single number applied to both rows and columns ($\lambda_r = \lambda_c$).
2. Sequence of two values: A tuple or list (lambda_r, lambda_c) to specify different penalty values for rows and columns respectively.

Polynomial baseline algorithms in pybaselines modify the standard least-squares approach to avoid being pulled by peaks. There are three primary strategies:

1. Selective Masking: Fitting only to data in regions where only the baseline exists. This is primarily used with the .poly() method. It is noted as being time-consuming and potentially hard to reproduce.
2. Thresholding: An iterative method where the fit is updated by taking the element-wise minimum between the current data and the current fit. This is used by .modpoly(), .imodpoly(), and .loess() (if use_threshold=True).
3. Penalizing Outliers: Incorporating a penalty into the cost function or applying lower weights to outliers. This is used by .penalized_poly() and .loess() (if use_threshold=False).

Morphological baseline algorithms in pybaselines use mathematical morphology operations—specifically dilation, erosion, opening, and closing—to estimate the baseline of a signal. These operations use moving windows to compute the maximum, minimum, or a combination of the two within each window.

• Dilation: Computes the maximum value within the window.
• Erosion: Computes the minimum value within the window.
• Closing: Performs an erosion followed by a dilation.
• Opening: Performs a dilation followed by an erosion.

import numpy as np
from scipy.ndimage import grey_closing, grey_dilation, grey_erosion, grey_opening

# Example of basic morphological operations on a signal 'y' with a 'window' size
dilation = grey_dilation(y, window)
erosion = grey_erosion(y, window)
closing = grey_closing(y, window)
opening = grey_opening(y, window)

pybaselines provides 2D extensions for a subset of its 1D baseline correction algorithms. These are intended for 2D data that possesses a global baseline.

If your data does not have a global baseline, or if performance is a priority, it is recommended to apply 1D algorithms to each row or column individually. You can achieve this using the .individual_axes method of the Baseline2D class or by using the standard Baseline class within manual loops.

The pybaselines library provides a semi-unified API for baseline correction. The primary interfaces are:

• Baseline: For one-dimensional data.
• Baseline2D: For two-dimensional data.

When calling a baseline correction algorithm, the method will return two items:

1. A numpy array containing the calculated baseline.
2. A dictionary containing potentially useful parameters used during the calculation.

To use the API, you typically instantiate a Baseline object with your x-axis data and then call specific algorithm methods on that object.

from pybaselines import Baseline

# Initialize with x-axis data
baseline_fitter = Baseline(x_data=x)

# Call an algorithm
bkg, params = baseline_fitter.asls(y, lam=1e7, p=0.02)

When using Whittaker-smoothing-based methods, the penalty scale factor lam ($\lambda$) must be adjusted based on the number of data points in your signal. As the number of data points increases, the required lam value to achieve the same baseline fit also increases.

The relationship is approximately: $$\log(\lambda) \propto \log(\text{number of data points})$$

Example scaling:

• 100 points: lam $\approx 10^3$
• 1,000 points: lam $\approx 10^7$
• 10,000 points: lam $\approx 10^{11}$

All morphological baseline algorithms in Baseline2D use a half_window parameter to define the size of the window used for morphological operators.

Important: half_window is index-based, not based on the physical units of your data. You must manually convert your desired physical window size into index offsets before passing them to the algorithm.

The recommended way to perform baseline correction on one-dimensional data is to use the Baseline class. This class provides a unified interface for all available algorithms, including polynomial, Whittaker smoothing, morphological, spline, and various other specialized methods. Instead of calling individual functions, you instantiate or use the Baseline object to access the specific algorithm required for your signal.

from pybaselines import Baseline

# Initialize the baseline object
baseline = Baseline()

# Use an algorithm (example: poly)
# baseline_values, params = baseline.poly(signal, ...)