0
# Morphological Methods
1

2
Mathematical morphology operations for baseline estimation using structuring elements and morphological transformations. These methods are particularly effective for chromatographic and mass spectrometry data, using operations like opening, closing, and erosion/dilation to separate baseline from peak features based on geometric properties.
3

4
## Capabilities
5

6
### Morphological Penalized Least Squares (mPLS)
7

8
Combines morphological operations with penalized least squares for hybrid baseline correction.
9

10
```python { .api }
11
def mpls(data, half_window=None, lam=1e6, p=0.0, diff_order=2, tol=None, max_iter=None, weights=None, x_data=None):
12
    """
13
    Morphological penalized least squares baseline correction.
14
    
15
    Parameters:
16
    - data (array-like): Input y-values to fit baseline
17
    - half_window (int, optional): Half-window size for morphological operations
18
    - lam (float): Smoothing parameter for penalized least squares
19
    - p (float): Asymmetry parameter
20
    - diff_order (int): Order of differential matrix
21
    - tol (float, optional): Convergence tolerance (if None, uses default)
22
    - max_iter (int, optional): Maximum iterations (if None, uses default)
23
    - weights (array-like, optional): Initial weight array
24
    - x_data (array-like, optional): Input x-values
25
    
26
    Returns:
27
    tuple: (baseline, params)
28
    """
29
```
30

31
### Morphological Opening (MOR)
32

33
Basic morphological baseline using opening operation (erosion followed by dilation).
34

35
```python { .api }
36
def mor(data, half_window=None, x_data=None, window_kwargs=None, **kwargs):
37
    """
38
    Morphological baseline using opening operation.
39
    
40
    Parameters:
41
    - data (array-like): Input y-values to fit baseline
42
    - half_window (int, optional): Half-window size for structuring element
43
    - x_data (array-like, optional): Input x-values
44
    - window_kwargs (dict, optional): Window parameters for structuring element
45
    
46
    Returns:
47
    tuple: (baseline, params)
48
    """
49
```
50

51
### Improved Morphological Opening (IMOR)
52

53
Enhanced morphological baseline with iterative refinement.
54

55
```python { .api }
56
def imor(data, half_window=None, tol=1e-3, max_iter=200, x_data=None, window_kwargs=None, **kwargs):
57
    """
58
    Improved morphological baseline with iterative refinement.
59
    
60
    Parameters:
61
    - data (array-like): Input y-values to fit baseline
62
    - half_window (int, optional): Half-window size for operations
63
    - tol (float): Convergence tolerance for iterations
64
    - max_iter (int): Maximum iterations
65
    - x_data (array-like, optional): Input x-values
66
    - pad_kwargs (dict, optional): Padding parameters
67
    
68
    Returns:
69
    tuple: (baseline, params)
70
    """
71
```
72

73
### Morphological Baseline with Mollification (MorMol)
74

75
Morphological baseline with mollification for smoothness improvement.
76

77
```python { .api }
78
def mormol(data, half_window=None, tol=1e-3, max_iter=250, smooth_half_window=None, x_data=None, pad_kwargs=None):
79
    """
80
    Morphological baseline with mollification for smoothness.
81
    
82
    Parameters:
83
    - data (array-like): Input y-values to fit baseline
84
    - half_window (int, optional): Half-window size
85
    - tol (float): Convergence tolerance
86
    - max_iter (int): Maximum iterations
87
    - smooth_half_window (int, optional): Half-window for smoothing
88
    - x_data (array-like, optional): Input x-values
89
    - pad_kwargs (dict, optional): Padding parameters
90
    
91
    Returns:
92
    tuple: (baseline, params)
93
    """
94
```
95

96
### Averaging Morphological Mollification (AMorMol)
97

98
Combines averaging with morphological mollification for improved baseline estimation.
99

100
```python { .api }
101
def amormol(data, half_window=None, tol=1e-3, max_iter=200, pad_kwargs=None, x_data=None, **kwargs):
102
    """
103
    Averaging morphological baseline with mollification.
104
    
105
    Parameters:
106
    - data (array-like): Input y-values to fit baseline
107
    - half_window (int, optional): Half-window size
108
    - tol (float): Convergence tolerance
109
    - max_iter (int): Maximum iterations
110
    - pad_kwargs (dict, optional): Padding parameters
111
    - x_data (array-like, optional): Input x-values
112
    
113
    Returns:
114
    tuple: (baseline, params)
115
    """
116
```
117

118
### Rolling Ball
119

120
Rolling ball algorithm that traces the path of a ball rolling under the data curve.
121

122
```python { .api }
123
def rolling_ball(data, half_window=None, smooth_half_window=None, pad_kwargs=None, x_data=None):
124
    """
125
    Rolling ball baseline correction algorithm.
126
    
127
    Parameters:
128
    - data (array-like): Input y-values to fit baseline
129
    - half_window (int, optional): Half-window size (ball radius)
130
    - smooth_half_window (int, optional): Half-window for smoothing
131
    - pad_kwargs (dict, optional): Padding parameters
132
    - x_data (array-like, optional): Input x-values
133
    
134
    Returns:
135
    tuple: (baseline, params)
136
    """
137
```
138

139
### Moving Window Minimum Value (MWMV)
140

141
Uses moving window minimum values for baseline estimation.
142

143
```python { .api }
144
def mwmv(data, half_window=None, smooth_half_window=None, pad_kwargs=None, x_data=None):
145
    """
146
    Moving window minimum value baseline correction.
147
    
148
    Parameters:
149
    - data (array-like): Input y-values to fit baseline
150
    - half_window (int, optional): Half-window size for minimum calculation
151
    - smooth_half_window (int, optional): Half-window for smoothing
152
    - pad_kwargs (dict, optional): Padding parameters
153
    - x_data (array-like, optional): Input x-values
154
    
155
    Returns:
156
    tuple: (baseline, params)
157
    """
158
```
159

160
### Top-Hat
161

162
Top-hat morphological operation for baseline extraction.
163

164
```python { .api }
165
def tophat(data, half_window=None, x_data=None, window_kwargs=None, **kwargs):
166
    """
167
    Top-hat morphological baseline correction.
168
    
169
    Parameters:
170
    - data (array-like): Input y-values to fit baseline
171
    - half_window (int, optional): Half-window size for structuring element
172
    - x_data (array-like, optional): Input x-values
173
    - pad_kwargs (dict, optional): Padding parameters
174
    
175
    Returns:
176
    tuple: (baseline, params)
177
    """
178
```
179

180
### Morphological Penalized Spline (MPSpline)
181

182
Combines morphological operations with penalized spline fitting.
183

184
```python { .api }
185
def mpspline(data, half_window=None, lam=1e4, lam_smooth=1e-2, p=0.0, num_knots=100, spline_degree=3, diff_order=2, max_iter=50, tol=1e-3, weights=None, x_data=None):
186
    """
187
    Morphological penalized spline baseline correction.
188
    
189
    Parameters:
190
    - data (array-like): Input y-values to fit baseline
191
    - half_window (int, optional): Half-window for morphological operations
192
    - lam (float): Smoothing parameter for spline
193
    - lam_smooth (float): Smoothing parameter for morphological operations
194
    - p (float): Asymmetry parameter
195
    - num_knots (int): Number of knots for spline
196
    - spline_degree (int): Degree of spline
197
    - diff_order (int): Order of differential matrix
198
    - max_iter (int): Maximum iterations
199
    - tol (float): Convergence tolerance
200
    - weights (array-like, optional): Initial weight array
201
    - x_data (array-like, optional): Input x-values
202
    
203
    Returns:
204
    tuple: (baseline, params)
205
    """
206
```
207

208
### Jansen-Berendschot Closing with Dilation (JBCD)
209

210
Advanced morphological method with closing and dilation operations.
211

212
```python { .api }
213
def jbcd(data, half_window=None, alpha=0.1, beta=1e1, gamma=1., beta_mult=1.1, gamma_mult=0.909, tol=1e-3, max_iter=200, x_data=None):
214
    """
215
    Jansen-Berendschot Closing with Dilation baseline correction.
216
    
217
    Parameters:
218
    - data (array-like): Input y-values to fit baseline
219
    - half_window (int, optional): Half-window size
220
    - alpha (float): Asymmetry parameter
221
    - beta (float): Beta parameter for operations
222
    - gamma (float): Gamma parameter
223
    - beta_mult (float): Beta multiplication factor
224
    - gamma_mult (float): Gamma multiplication factor
225
    - tol (float): Convergence tolerance
226
    - max_iter (int): Maximum iterations
227
    - x_data (array-like, optional): Input x-values
228
    
229
    Returns:
230
    tuple: (baseline, params)
231
    """
232
```
233

234
## Usage Examples
235

236
### Basic morphological opening:
237

238
```python
239
import numpy as np
240
from pybaselines.morphological import mor
241

242
# Sample chromatographic data
243
x = np.linspace(0, 30, 3000)  # 30 minutes
244
baseline = 100 + 2 * x  # Linear drift
245
peaks = (1000 * np.exp(-((x - 5) / 0.5)**2) +   # Sharp peak
246
         800 * np.exp(-((x - 15) / 1.2)**2) +    # Medium peak  
247
         600 * np.exp(-((x - 25) / 0.8)**2))     # Another peak
248
data = baseline + peaks
249

250
# Apply morphological opening
251
baseline_est, params = mor(data, half_window=50, x_data=x)
252
corrected = data - baseline_est
253
```
254

255
### Rolling ball baseline:
256

257
```python
258
from pybaselines.morphological import rolling_ball
259

260
# Good for mass spectrometry data
261
baseline_est, params = rolling_ball(data, half_window=100, x_data=x)
262
corrected = data - baseline_est
263
```
264

265
### Iterative morphological refinement:
266

267
```python
268
from pybaselines.morphological import imor
269

270
# Iteratively refined morphological baseline
271
baseline_est, params = imor(data, half_window=75, tol=1e-4, max_iter=50, x_data=x)
272
corrected = data - baseline_est
273
```