PySDKit

https://github.com/wwhenxuan/pysdkit
Admin
PySDKit is a Python library for signal decomposition algorithms that provides a unified interface...
Tokens:45,262
Snippets:379
Trust Score:9.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install PySDKit

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/index.rst

Use pip to install the library in your Python environment.

```bash
pip install pysdkit
```

--------------------------------

### Install PySDKit from source

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/development/index.rst

Use these commands to clone the repository and install the package in editable mode along with documentation dependencies.

```bash
git clone https://github.com/wwhenxuan/PySDKit.git
cd PySDKit
pip install -e .
pip install -r docs/requirements.txt
```

--------------------------------

### Create a gallery example script

Source: https://github.com/wwhenxuan/pysdkit/blob/main/CONTRIBUTING.md

Template for creating gallery scripts using raw docstrings and Sphinx-Gallery comment blocks.

```python
r"""
My algorithm
============

Short theory paragraph and a paper reference.
"""

# %%
# Demo
# ----

import numpy as np
from pysdkit import EMD
from pysdkit.plot import plot_IMFs
```

--------------------------------

### pysdkit.data.load_apitmemd_section_2b

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Loads the packaged hexavariate P300 example dataset.

```APIDOC
## pysdkit.data.load_apitmemd_section_2b()

### Description
Load the packaged MATLAB data_section_2b.mat hexavariate P300 example.

### Returns
- **Dict[str, ndarray | float]** - Dictionary containing 'signal', 'fs', and 't'.
```

--------------------------------

### pysdkit.data.load_set_vibdata()

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Loads the vibration record used by SET Example 4.

```APIDOC
## pysdkit.data.load_set_vibdata()

### Description
Loads the packaged vibration record used by SET Example 4 (Yu, Yu and Xu, IEEE TIE 64(10) 2017).

### Returns
- **dict** - A dictionary containing `signal`, `fs`, and `t`.
```

--------------------------------

### pysdkit.data.load_bss_beam()

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Loads the three-sensor beam record used by BSS Example 2.

```APIDOC
## pysdkit.data.load_bss_beam()

### Description
Loads the packaged three-sensor beam record used by BSS Example 2. The data is sourced from MATLAB `data_test.mat` (Yu, Shock and Vibration 2019) and includes channels `x1, x2, x3` with a sampling rate of 2560 Hz.

### Returns
- **dict** - A dictionary containing `signal`, `fs`, `t`, and `mode_shape`.
```

--------------------------------

### pysdkit.data.load_bss_yk9()

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Loads the cantilever record used by BSS Example 3.

```APIDOC
## pysdkit.data.load_bss_yk9()

### Description
Loads the packaged cantilever record used by BSS Example 3, sourced from MATLAB `yk9_mean.mat` (Yu, Shock and Vibration 2019). It contains displacement channels `d_1, d_2, d_5`.

### Returns
- **dict** - A dictionary containing `signal`, `fs`, `t`, and `mode_shape`.
```

--------------------------------

### pysdkit.data.load_set_batdata2()

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Loads the bat echolocation record used by SET Example 3.

```APIDOC
## pysdkit.data.load_set_batdata2()

### Description
Loads the packaged bat echolocation record used by SET Example 3 (Yu, Yu and Xu, IEEE TIE 64(10) 2017).

### Returns
- **dict** - A dictionary containing `signal`, `fs`, and `t`.
```

--------------------------------

### Edge-amplitude correction padding

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.utils.rst

Example of the edge-amplitude correction logic used after BSS inversion, mirroring MATLAB implementation.

```default
tau = -min([round(T/2)-1, Lh, i-1]) : min([round(T/2)-1, Lh, T-i])
pad(i) = (sum(h) / sum(h(Lh+1+tau))) ^ (1/1.6)
```

--------------------------------

### Build documentation with Sphinx

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/development/index.rst

Execute this command to generate the HTML documentation from the source files.

```bash
sphinx-build -b html docs/source docs/build/html
```

--------------------------------

### Run unit tests

Source: https://github.com/wwhenxuan/pysdkit/blob/main/CONTRIBUTING.md

Execute the test suite using the unittest discovery module.

```bash
python -m unittest discover -s pysdkit/tests -p "test_*.py" -v
```

--------------------------------

### Load packaged demo data

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/user_guide/index.rst

Accesses built-in test datasets for signal and image processing tasks.

```python
from pysdkit.data import load_bmemd_source02, load_bss_beam, test_vmd

images = load_bmemd_source02()["signal"]  # (2, 224, 224) in [0, 1]
beam = load_bss_beam()["signal"]
```

--------------------------------

### Perform signal decomposition with VMD

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/user_guide/index.rst

Demonstrates the three-step process of importing, instantiating, and fitting a VMD model to a test signal.

```python
from pysdkit import VMD
from pysdkit.data import test_vmd
from pysdkit.plot import plot_IMFs

t, signal, fs = test_vmd()
vmd = VMD(alpha=2000, K=4, tau=0.0, tol=1e-7)
IMFs = vmd.fit_transform(signal)
plot_IMFs(signal, IMFs, view="2d_freq", fs=fs, freq_max=fs / 2)
```

--------------------------------

### pysdkit.data.load_imckd_sig1()

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Loads the IMCKD demo record.

```APIDOC
## pysdkit.data.load_imckd_sig1()

### Description
Loads the packaged IMCKD demo record (Miao et al., MSSP 2017) with a sampling rate of 20 kHz.

### Returns
- **dict** - A dictionary containing `signal`, `fs`, `t`, and `fault_hz`.
```

--------------------------------

### prepare_points

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._emd.rst

Processes extrema points to create smoother envelope spectra.

```APIDOC
### prepare_points(time: ndarray, signal: ndarray, max_pos: ndarray, max_val: ndarray, min_pos: ndarray, min_val: ndarray) -> Tuple[ndarray, ndarray]

#### Description
Processes maximum and minimum points to make the upper and lower envelope spectra smoother.

#### Parameters
- **time** (ndarray) - Required - Position or time array.
- **signal** (ndarray) - Required - Input signal.
- **max_pos** (ndarray) - Required - Position of local maxima.
- **max_val** (ndarray) - Required - Values of local maxima.
- **min_pos** (ndarray) - Required - Position of local minima.
- **min_val** (ndarray) - Required - Values of local minima.

#### Returns
- **max_extrema** (ndarray) - Processed maximum extrema.
- **min_extrema** (ndarray) - Processed minimum extrema.
```

--------------------------------

### Decompose a signal with EMD

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/index.rst

Demonstrates the standard workflow of importing, instantiating the EMD class, and applying fit_transform to a signal.

```python
import numpy as np
from pysdkit import EMD
from pysdkit.plot import plot_IMFs

t = np.linspace(0, 1, 1000)
signal = (
    np.sin(2 * np.pi * 5 * t)
    + 0.7 * np.sin(2 * np.pi * 25 * t)
    + 0.45 * np.sin(2 * np.pi * 80 * t)
)

emd = EMD()
IMFs = emd.fit_transform(signal, max_imfs=3)
plot_IMFs(signal, IMFs, view="2d_freq", fs=1000, freq_max=150)
```

--------------------------------

### Importing decomposition algorithms

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.rst

Import the primary decomposition classes directly from the package root.

```python
from pysdkit import EMD, VMD, BMEMD
```

--------------------------------

### append(samples)

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._emd.rst

Appends samples to the fastest-IMF buffer.

```APIDOC
## append(samples: ndarray)

### Description
Append samples to the fastest-IMF buffer.

### Parameters
- **samples** (ndarray) - Required - Real 1-D chunk of samples.
```

--------------------------------

### pysdkit.data.load_wind_demo

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Loads a wind-demo CSV/TXT file.

```APIDOC
## pysdkit.data.load_wind_demo(path: str)

### Description
Load a wind-demo CSV/TXT file where the first column is the wind series.

### Parameters
- **path** (str) - Required - Path to a comma-separated file.
```

--------------------------------

### init_hammersley

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._emd.rst

Builds the Hammersley point set.

```APIDOC
## init_hammersley(n_dim: int)

### Description
Constructs the Hammersley point set used for direction vectors.

### Parameters
- **n_dim** (int) - Required - Number of channels / embedding dimension (3 <= n_dim <= 16).

### Returns
- **seq** (ndarray) - Low-discrepancy samples in [0, 1].
```

--------------------------------

### pysdkit.data.load_acycbd_sig2

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Loads the packaged ACYCBD demo record.

```APIDOC
## pysdkit.data.load_acycbd_sig2()

### Description
Load the packaged ACYCBD demo record (Zhang, Miao, Lin, Yi, MSSP 2021).

### Returns
- **Dict[str, ndarray | float]** - Dictionary containing 'signal', 'fs', 't', and 'bpfi'.
```

--------------------------------

### Mirror signal expansion

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.utils.rst

Demonstrates how to mirror elements at the beginning and end of an array using fmirror.

```pycon
>>> array = np.array([1, 2, 3, 4, 5])
>>> fmirror(array, 2)

> array([2, 1, 1, 2, 3, 4, 5, 5, 4])
```

--------------------------------

### pysdkit.data.load_fast_kurtogram_x()

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Loads the Fast Kurtogram demo record.

```APIDOC
## pysdkit.data.load_fast_kurtogram_x()

### Description
Loads the packaged Fast Kurtogram demo record (Antoni, MSSP 2007) containing weak repetitive transients hidden in stationary noise.

### Returns
- **dict** - A dictionary containing `signal`, `fs`, and `t`.
```

--------------------------------

### update(samples)

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._emd.rst

Appends a chunk and iterates.

```APIDOC
## update(samples: ndarray)

### Description
Append a chunk and iterate (one streaming step).

### Parameters
- **samples** (ndarray) - Required - New univariate samples.

### Returns
- **ndarray** - Current IMF matrix.
```

--------------------------------

### Perform Empirical Mode Decomposition (EMD)

Source: https://github.com/wwhenxuan/pysdkit/blob/main/README.md

Demonstrates basic signal decomposition using the EMD algorithm and visualizing the resulting IMFs.

```python
import numpy as np
from pysdkit import EMD
from pysdkit.plot import plot_IMFs

t = np.linspace(0, 1, 1000)
signal = np.sin(2 * np.pi * 5 * t) + 0.7 * np.sin(2 * np.pi * 25 * t) + 0.45 * np.sin(2 * np.pi * 80 * t)

emd = EMD()
IMFs = emd.fit_transform(signal, max_imfs=3)
plot_IMFs(signal, IMFs, view="2d_freq", fs=1000, freq_max=150)
```

--------------------------------

### pysdkit.data.load_apitmemd_section_3b

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Loads the packaged single-shot P300 trials dataset.

```APIDOC
## pysdkit.data.load_apitmemd_section_3b()

### Description
Load the packaged MATLAB data_section_3b.mat single-shot P300 trials.

### Returns
- **Dict[str, ndarray | float]** - Dictionary containing 'signal', 'fs', and 't'.
```

--------------------------------

### pysdkit.data.load_smhd_sig3

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Loads the packaged SMHD demo record (Miao et al., 2016).

```APIDOC
## pysdkit.data.load_smhd_sig3()

### Description
Load the packaged SMHD demo record (Miao et al., Meas. Sci. Technol. 2016). Returns a dictionary containing the signal, sampling frequency (fs), time axis (t), and BPFI.

### Returns
- **dict** - Contains 'signal', 'fs', 't', 'bpfi'
```

--------------------------------

### pysdkit.data.test_vmd

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Loads the packaged VMD demo signal.

```APIDOC
## pysdkit.data.test_vmd()

### Description
Load the packaged VMD demo signal (vmd_example.npy). This is the multi-component example previously stored as examples/example.npy (length 1024).

### Returns
- **Tuple[ndarray, ndarray, float]** - (t, x, fs) time axis, signal, and sampling frequency.
```

--------------------------------

### pysdkit.data.test_fmd

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Loads the official MATLAB FMD demo signal.

```APIDOC
## pysdkit.data.test_fmd()

### Description
Load the official MATLAB FMD demo signal shipped with PySDKit.

### Returns
- **tuple** - (t, x, fs) containing time axis, signal, and sampling frequency.
```

--------------------------------

### reconstruct(imfs=None)

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._emd.rst

Sum IMFs to reconstruct the original channel(s).

```APIDOC
## reconstruct(imfs: ndarray | None = None) -> ndarray

### Description
Sum IMFs to reconstruct the original channel(s).

### Parameters
- **imfs** (ndarray | None) - Optional - IMF tensor; defaults to the last fit_transform result.

### Returns
- **ndarray** - Reconstructed signal with shape (seq_len,) or (n_channels, seq_len)
```

--------------------------------

### pysdkit.data.load_vme_ecg_055m

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Loads the packaged MIMIC record 055m.

```APIDOC
## pysdkit.data.load_vme_ecg_055m()

### Description
Load the packaged MIMIC record 055m shipped with MATLAB VME.

### Returns
- **dict** - Contains 'val', 'ecg', 'respiration', 'fs', 't'
```

--------------------------------

### pysdkit.data.test_grayscale

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Loads a sample 2D grayscale image.

```APIDOC
## pysdkit.data.test_grayscale()

### Description
Load a sample 2D grayscale image for testing, size [256, 256].
```

--------------------------------

### pysdkit.OnlineEMD

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._emd.rst

Constructor for the OnlineEMD class.

```APIDOC
## class pysdkit.OnlineEMD(n_extrema=10, max_imfs=-1, emd_algo=2, bound=3.0)

### Description
Initializes the Online Empirical Mode Decomposition (Online EMD) object.

### Parameters
- **n_extrema** (int) - Optional - Extrema per sliding window. Must be >= 4.
- **max_imfs** (int) - Optional - Maximum IMFs (-1 for unlimited).
- **emd_algo** (int or str) - Optional - EMD algorithm selection (0/'rilling', 1/'fixe', 2/'fix_h').
- **bound** (float) - Optional - Gaussian truncation value.
```

--------------------------------

### pysdkit.data.load_bmemd_source02

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Loads the packaged BMEMD multi-focus pair source02.

```APIDOC
## pysdkit.data.load_bmemd_source02()

### Description
Load the packaged BMEMD multi-focus pair source02_1 / source02_2.

### Returns
- **Dict[str, ndarray | Tuple[str, str]]** - Dictionary containing 'signal' and 'names'.
```

--------------------------------

### pysdkit.utils.imckd

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.utils.rst

Performs Improved MCKD with on-the-fly period estimation.

```APIDOC
## pysdkit.utils.imckd(signal: ndarray, fs: float, filter_size: int = 100, term_iter: int = 30, period: int | None = None, shift_order: int = 3) -> Tuple[ndarray, ndarray, Dict[str, int | float | ndarray]]

### Description
An improved MCKD implementation with on-the-fly period estimation, acting as a faithful port of the MATLAB `imckd.m` function.

### Parameters
- **signal** (ndarray) - Required - 1-D record `x`.
- **fs** (float) - Required - Sampling frequency in hertz.
- **filter_size** (int) - Optional - Inverse FIR length `L` (default 100).
- **term_iter** (int) - Optional - Number of iterations (default 30).
- **period** (int) - Optional - Prior period in samples; estimated from raw envelope if omitted.
- **shift_order** (int) - Optional - CK shift order `M` (default 3).

### Returns
- **Tuple** - Returns `(y, fir, info)` containing the filtered signal, unit-norm FIR, and a dictionary of iteration history.
```

--------------------------------

### pysdkit.data.load_apitmemd_section_3a

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Loads a snippet of the cooperative SSVEP dataset.

```APIDOC
## pysdkit.data.load_apitmemd_section_3a()

### Description
Load a short packaged snippet of MATLAB data_section_3a.mat.

### Returns
- **Dict[str, ndarray | float]** - Dictionary containing 'signal', 'fs', and 't'.
```

--------------------------------

### pysdkit.SST

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._tfa.rst

The SST class provides methods for performing Synchrosqueezing Transforms, denoising, and modal decomposition.

```APIDOC
## class pysdkit.SST(n_voices=32, wavelet='bump', n_levels=5, n_window=32, denoise_gain=0.2)

### Description
Synchrosqueezing Transform for time-frequency analysis and mode recovery.

### Parameters
- **n_voices** (int) - Optional - Voices per octave (default 32).
- **wavelet** (int | str) - Optional - 'bump' or 'morlet' (default 'bump').
- **n_levels** (int) - Optional - Depth of the bandwidth quadtree (default 5).
- **n_window** (int) - Optional - Selective-SST averaging window (default 32).
- **denoise_gain** (float) - Optional - 'c' in the modified universal threshold (default 0.2).

### Methods
- **denoise(signal)**: Performs multivariate or univariate SST thresholding.
- **fit_transform(signal, return_tfr=False)**: Inverts SST over adaptive bands to recover AM–FM modes.
- **instantaneous_frequency()**: Returns joint IF trajectories or SST-bin IF.
- **selective_transform(signal)**: Performs selective synchrosqueezing by zeroing coefficients that fail the windowed RCM threshold.
- **transform(signal)**: Computes the time-frequency representation.
```

--------------------------------

### pysdkit.sst

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._tfa.rst

Functional interface for modal decomposition.

```APIDOC
## pysdkit.sst(signal, **kwargs)

### Description
Functional modal-decomposition interface equivalent to calling SST(...)(signal).

### Parameters
- **signal** (ndarray) - Required - Input signal array of shape (T,) or (C, T).
- **kwargs** (dict) - Optional - Configuration parameters for the SST class.
```

--------------------------------

### pysdkit.data.load_bmemd_source09

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Loads the packaged BMEMD pair source09.

```APIDOC
## pysdkit.data.load_bmemd_source09()

### Description
Load the packaged BMEMD pair source09_1 / source09_2.

### Returns
- **Dict[str, ndarray | Tuple[str, str]]** - Dictionary containing 'signal' and 'names'.
```

--------------------------------

### pysdkit.imd

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._imd.rst

Functional wrapper for the IMD decomposition.

```APIDOC
## function pysdkit.imd(signal, fs, n_particles=45, max_iter=20, threshold=1.6, min_band=0.0, max_modes=4, seg_num=10, seed=None, return_all=False)

### Description
Functional wrapper to perform Impulsive Mode Decomposition.

### Parameters
- **signal** (ndarray) - Required - 1-D real signal.
- **fs** (float) - Required - Sampling frequency.
- **n_particles** (int) - Optional - Number of particles.
- **max_iter** (int) - Optional - Maximum iterations.
- **threshold** (float) - Optional - Sparsity threshold.
- **min_band** (float) - Optional - Minimum frequency band.
- **max_modes** (int) - Optional - Maximum number of modes.
- **seg_num** (int) - Optional - Number of segments.
- **seed** (int) - Optional - Random seed.
- **return_all** (bool) - Optional - If True, returns additional diagnostic data.
```

--------------------------------

### pysdkit.BMEMD

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._emd2d.rst

Initializes the BMEMD object for multi-channel image decomposition.

```APIDOC
## class pysdkit.BMEMD(n_dir=8, max_imfs=4, stop_crit='stop', stop_vec=None, stop_cnt=2, max_iter=1000, max_sift=50)

### Description
Initializes a Bidimensional Multivariate Empirical Mode Decomposition (BMEMD) instance. This class projects multi-channel images onto direction vectors to perform multi-scale image fusion.

### Parameters
- **n_dir** (int) - Optional - Number of projection directions (>= 6).
- **max_imfs** (int) - Optional - Maximum number of oscillatory BIMFs before the residue.
- **stop_crit** (str) - Optional - Stopping criterion, either 'stop' or 'fix_h'.
- **stop_vec** (Sequence[float]) - Optional - Parameters [sd, sd2, tol] for 'stop' criterion.
- **stop_cnt** (int) - Optional - Consecutive siftings for 'fix_h'.
- **max_iter** (int) - Optional - Outer-iteration cap.
- **max_sift** (int) - Optional - Inner sifting cap per BIMF.
```

--------------------------------

### pysdkit.EEMD

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._emd.rst

Constructor for the EEMD class, initializing the decomposition parameters.

```APIDOC
## class pysdkit.EEMD(ext_EMD=None, trials=100, noise_width=0.05, parallel=False, separate_trends=False, noise_kind='normal', processes=None, max_imfs=-1, max_iter=1000, random_seed=42)

### Description
Initializes the Ensemble Empirical Mode Decomposition (EEMD) object with specified configuration parameters.

### Parameters
- **trials** (int) - Number of trials for the ensemble.
- **noise_width** (float) - Standard deviation of the added noise.
- **parallel** (bool) - Whether to use parallel processing.
- **separate_trends** (bool) - Whether to separate trends.
- **noise_kind** (str) - Type of noise ('normal' or 'uniform').
- **processes** (int) - Number of processes for parallel execution.
- **max_imfs** (int) - Maximum number of IMFs to decompose.
- **max_iter** (int) - Maximum number of iterations.
- **random_seed** (int) - Seed for random number generation.
```

--------------------------------

### pysdkit.EMD2D

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._emd2d.rst

Constructor for the EMD2D class to initialize decomposition parameters.

```APIDOC
## class pysdkit.EMD2D(max_imfs=None, mse_thr=0.01, mean_thr=0.01, max_iter=1000)

### Description
Initializes the Empirical Mode Decomposition 2D object for a single grayscale image.

### Parameters
- **max_imfs** (int | None) - Optional - Maximum number of IMFs to extract.
- **mse_thr** (float | None) - Optional - Threshold for mean square error check.
- **mean_thr** (float | None) - Optional - Threshold for mean value check.
- **max_iter** (int | None) - Optional - Maximum number of iterations for sifting.
```

--------------------------------

### pysdkit.data.load_oemd_ecg()

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Loads the MIT-BIH Normal Sinus Rhythm ECG record.

```APIDOC
## pysdkit.data.load_oemd_ecg()

### Description
Loads the packaged MIT-BIH Normal Sinus Rhythm ECG used by Online EMD (Fontugne, Borgnat and Flandrin, ICASSP 2017).

### Returns
- **dict** - A dictionary containing `signal`, `fs`, and `t`.
```

--------------------------------

### pysdkit.swd

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._osd.rst

Functional interface to the Swarm Decomposition (SWD) model.

```APIDOC
## pysdkit.swd(signal, P_th=0.05, StD_th=0.05, return_all=False, **kwargs)

### Description
Functional interface to perform Swarm Decomposition on a signal.

### Parameters
- **signal** (ndarray) - Required - The input signal array.
- **P_th** (float) - Optional - Relative spectral-peak threshold.
- **StD_th** (float) - Optional - Iterative-SwF convergence threshold.
- **return_all** (bool) - Optional - If True, returns components, residue, and omegas.
```

--------------------------------

### pysdkit.data.test_univariate_nonlinear_chip

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Selects and generates a test case for a one-dimensional nonlinear chip univariate signal.

```APIDOC
## pysdkit.data.test_univariate_nonlinear_chip(case: int = 1, duration: float = 1.0, sampling_rate: int = 1000, noise_level: float = 0.1, random_state: int = 42)

### Description
Selects a test case for a one-dimensional nonlinear chip univariate signal based on the input case.

### Parameters
- **case** (int) - Optional - The test number in [1, 2].
- **duration** (float) - Optional - Length of the signal in seconds.
- **sampling_rate** (int) - Optional - Number of samples per second.
- **noise_level** (float) - Optional - Standard deviation of the Gaussian noise.
- **random_state** (int) - Optional - Random seed for the noise generation.

### Returns
- **Tuple[array, array]** - The generated non-linear chip signal.
```

--------------------------------

### pysdkit.SWD

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._osd.rst

Swarm Decomposition (SWD) class for signal decomposition.

```APIDOC
## class pysdkit.SWD(P_th=0.05, StD_th=0.05, spectrum='welch', sg_order=2, sg_window=15, welch_window=None, welch_noverlap=None, welch_nfft=None, max_components=15, max_sift=15, min_omega_hat=0.05, freq_merge_tol=0.03, refine=True)

### Description
Initializes the Swarm Decomposition model.
```

--------------------------------

### pysdkit.VMD

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._vmd.rst

Constructor for the VMD class to initialize the decomposition parameters.

```APIDOC
## class pysdkit.VMD(alpha, K, tau, init='uniform', DC=False, max_iter=500, tol=1e-06, store_history=True)

### Description
Initializes the VMD object with specific hyperparameters for the decomposition process.

### Parameters
- **alpha** (int) - Required - The balancing parameter of the data-fidelity constraint.
- **K** (int) - Required - The number of modes to be recovered.
- **tau** (float) - Required - Time-step of the dual ascent.
- **init** (str) - Optional - Initialization method for center frequencies ('uniform').
- **DC** (bool) - Optional - Whether the first mode is DC.
- **max_iter** (int) - Optional - Maximum number of iterations.
- **tol** (float) - Optional - Tolerance for convergence.
- **store_history** (bool) - Optional - Whether to store the history of the decomposition.
```

--------------------------------

### fit_transform(signal, max_imfs=None)

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._emd.rst

Decompose uni-/multi-channel signals with Serial-EMD.

```APIDOC
## fit_transform(signal: ndarray, max_imfs: int | None = None) -> ndarray

### Description
Decompose uni-/multi-channel signals with Serial-EMD.

### Parameters
- **signal** (ndarray) - Required - Input signal with shape (seq_len,) or (n_channels, seq_len)
- **max_imfs** (int | None) - Optional - Override for the maximum number of IMFs

### Returns
- **ndarray** - IMFs with shape (K, seq_len) or (K, seq_len, n_channels)
```

--------------------------------

### pysdkit.SET

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._tfa.rst

The SET class provides methods for Synchroextracting Transform for time-frequency analysis and modes.

```APIDOC
## class pysdkit.SET(hlength=None, fs=1.0, amp_thresh=0.8, if_tol=0.5, n_imfs=1, ridge_lambda=1.0, clear_win=5)

### Description
Initializes the Synchroextracting Transform (SET) analyzer.

### Parameters
- **hlength** (int | None) - Optional - Gaussian window length (odd). Defaults to round(N/8).
- **fs** (float) - Optional - Sampling frequency. Defaults to 1.0.
- **amp_thresh** (float) - Optional - STFT amplitude gate. Defaults to 0.8.
- **if_tol** (float) - Optional - Extracting half-width in bins. Defaults to 0.5.
- **n_imfs** (int) - Optional - Number of oscillatory modes. Defaults to 1.
- **ridge_lambda** (float) - Optional - Smoothness of brevridge. Defaults to 1.0.
- **clear_win** (int) - Optional - Frequency clearing window between successive ridges. Defaults to 5.

## method SET.fit_transform(signal, n_imfs=None)

### Description
Performs ridge-based modal decomposition of the SET map.

### Parameters
- **signal** (ndarray) - Required - Real 1-D record.
- **n_imfs** (int | None) - Optional - Number of ridges to extract.

### Returns
- **ndarray** - IMF array of shape (n_imfs + 1, T), where the last row is the residual.

## method SET.transform(signal)

### Description
Computes the SET time-frequency map.

### Parameters
- **signal** (ndarray) - Required - Real 1-D record.

### Returns
- **Tuple[ndarray, ndarray]** - Returns (te, freq) where te has shape (n_freq, T).
```

--------------------------------

### pysdkit.agncmd / pysdkit.agdmd

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._gdmd.rst

Functional wrappers for performing Adaptive Generalized Dispersive Mode Decomposition.

```APIDOC
## pysdkit.agncmd(signal, fs, beta=1e-07, max_modes=3, tol=1e-08, max_iter=300, return_all=False)
## pysdkit.agdmd(signal, fs, beta=1e-07, max_modes=3, tol=1e-08, max_iter=300, return_all=False)

### Description
Functional wrappers that execute the AGNCMD decomposition process on a given signal.

### Parameters
- **signal** (ndarray) - Required - 1-D real time series.
- **fs** (float) - Required - Sampling frequency (Hz).
- **beta** (float) - Optional - Regularization parameter.
- **max_modes** (int) - Optional - Maximum number of modes.
- **tol** (float) - Optional - Convergence tolerance.
- **max_iter** (int) - Optional - Maximum iterations.
- **return_all** (bool) - Optional - If True, returns extended diagnostic tuple.
```

--------------------------------

### stop(signal: ndarray, time: ndarray, seq: ndarray, seq_len: int, n_dim: int) → Tuple[bool, ndarray]

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._emd.rst

Implements the Rilling sifting stop test using NS-TEMD envelopes.

```APIDOC
### stop(signal: ndarray, time: ndarray, seq: ndarray, seq_len: int, n_dim: int) → Tuple[bool, ndarray]

Rilling sifting stop test.

#### Parameters
- **signal** (ndarray) - Current proto-IMF of shape (n_samples, n_channels).
- **time** (ndarray) - Sample indices.
- **seq** (ndarray) - Hammersley samples.
- **seq_len** (int) - Number of time samples.
- **n_dim** (int) - Number of channels.

#### Returns
- **stop_flag** (bool) - True if sifting should stop.
- **env_mean** (ndarray) - Local-mean estimate.
```

--------------------------------

### pysdkit.vgnmd

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._gdmd.rst

Functional wrapper for the VGNMD class.

```APIDOC
## pysdkit.vgnmd(signal, fs, alpha=0.0001, beta=1e-07, tol=1e-08, max_iter=300, return_all=False)

### Description
Functional interface to perform VGNMD decomposition.
```

--------------------------------

### pysdkit.data.load_sst_doppler

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Loads the packaged bivariate Doppler-radar record.

```APIDOC
## pysdkit.data.load_sst_doppler()

### Description
Load the packaged bivariate Doppler-radar record used by multivariate SST.

### Returns
- **dict** - Contains 'signal'
```

--------------------------------

### pysdkit.data.test_univariate_cube

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Generates 3D cube data for testing 3D univariate signal decomposition.

```APIDOC
## pysdkit.data.test_univariate_cube(case: int = 1, low: int | ndarray = 0, high: int | ndarray = 10, sampling_rate: int = 30) -> ndarray

### Description
Generates a 3D cube data structure for testing 3D univariate signal decomposition algorithms.

### Parameters
- **case** (int) - Optional - Test case, range in [1, 2, 3, 4, 5, 6]. Default: 1.
- **low** (int | ndarray) - Optional - Minimum value of grid matrix. Default: 0.
- **high** (int | ndarray) - Optional - Maximum value of grid matrix. Default: 10.
- **sampling_rate** (int) - Optional - Number of points in the matrix. Default: 30.

### Returns
- **ndarray** - 3D cube data of a specified range.
```

--------------------------------

### ESMD.fit_transform(signal, dt=1.0, return_all=False, compute_di=True)

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._emd.rst

Decompose a 1-D real signal using Extreme-Point Symmetric Mode Decomposition.

```APIDOC
## ESMD.fit_transform(signal: ndarray, dt: float = 1.0, return_all: bool = False, compute_di: bool = True) -> ndarray | Tuple[ndarray, ...]

### Description
Decompose a 1-D real signal.

### Parameters
- **signal** (ndarray) - Required - Input series Y
- **dt** (float) - Optional - Sampling period
- **return_all** (bool) - Optional - Also return residual, amplitudes, frequencies, energy
- **compute_di** (bool) - Optional - Compute DI instantaneous amp / freq / energy

### Returns
- **ndarray | Tuple[ndarray, ...]** - IMFs stacked with residual as last row (n_imf+1, N), or extended tuple when return_all is True
```

--------------------------------

### fit_transform

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._emd2d.rst

Decomposes a multi-channel image stack into aligned BIMFs and a residue.

```APIDOC
## fit_transform(images, max_imfs=None)

### Description
Decomposes a multi-channel image stack into aligned BIMFs plus residue. All channels share the same BIMF count.

### Parameters
- **images** (ndarray) - Required - Stack of shape (n_channels, H, W) with 2 <= n_channels <= 16.
- **max_imfs** (int) - Optional - Maximum number of oscillatory BIMFs.

### Returns
- **imfs** (ndarray) - Array of shape (K, n_channels, H, W) where the last slice is the residue.
```

--------------------------------

### pysdkit.MEMD

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._emd.rst

Constructor for the Multivariate Empirical Mode Decomposition class.

```APIDOC
## class pysdkit.MEMD(stop_crit='stop', max_iter=1000, n_dir=64, stop_vec=None, stop_cnt=2)

### Description
Initializes the MEMD object to perform multivariate signal decomposition.

### Parameters
- **stop_crit** (str) - Optional - Stopping criterion: 'stop' (Rilling et al.) or 'fix_h' (Huang et al.).
- **max_iter** (int) - Optional - Maximum sifting iterations per IMF.
- **n_dir** (int) - Optional - Number of projection directions.
- **stop_vec** (Sequence[float]) - Optional - [sd, sd2, tol] parameters for 'stop' criterion.
- **stop_cnt** (int) - Optional - Consecutive siftings required for 'fix_h' criterion.
```

--------------------------------

### pysdkit.data.test_hht

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Generates data for Hilbert-Huang transform testing.

```APIDOC
## pysdkit.data.test_hht(duration: float = 2.0, sampling_rate: int = 1000)

### Description
Generate data generation function to verify Hilbert-Huang transform.

### Parameters
- **duration** (float) - Optional - Length of the signal in seconds.
- **sampling_rate** (int) - Optional - Number of samples per second.
```

--------------------------------

### get_imfs_and_trend

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._emd.rst

Retrieves the IMFs and the main trend from the most recently analyzed signal.

```APIDOC
### get_imfs_and_trend() -> Tuple[ndarray, ndarray]

#### Description
Provides access to separated IMFs and the main trend. Note that the trend may differ from the residue.

#### Returns
- **imfs** (ndarray) - Obtained IMFs.
- **trend** (ndarray) - Obtained main trend.
```

--------------------------------

### pysdkit.gdmd

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._gdmd.rst

Functional wrapper for the GDMD class.

```APIDOC
## pysdkit.gdmd(signal, fs=None, init_gd=None, alpha=0.001, beta=1e-07, tol=1e-08, max_iter=300, K=None, return_all=False)

### Description
Functional interface to perform GDMD decomposition on a signal.
```

--------------------------------

### pysdkit.data.test_univariate_cubic_quad

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Generates a signal with quadratic and cubic coupling.

```APIDOC
## pysdkit.data.test_univariate_cubic_quad(duration: float = 6.0, sampling_rate: int = 128, noise_level: float = 0.0, random_state: int = 42) -> Tuple[ndarray, ndarray]

### Description
Generates a signal defined by s(t) = 2 * sin(2π*3*t) + 0.8 * sin(2π*5*t)^2 + 0.5 * sin(2π*7*t)^3.

### Parameters
- **duration** (float) - Optional - Length of signal in seconds. Default: 6.0.
- **sampling_rate** (int) - Optional - Samples per second. Default: 128.
- **noise_level** (float) - Optional - Standard deviation of Gaussian noise. Default: 0.0.
- **random_state** (int) - Optional - Random seed. Default: 42.

### Returns
- **Tuple[ndarray, ndarray]** - Tuple containing (t, noisy_signal).
```

--------------------------------

### pysdkit.utils.acycbd

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.utils.rst

Performs Adaptive CYCBD with EHPS cyclic-frequency estimation.

```APIDOC
## pysdkit.utils.acycbd(signal, fs, filter_size=40, relative_error=0.001, max_iter=50, order=2, n_harmonics=10)

### Description
Adaptive CYCBD with EHPS cyclic-frequency estimation. Returns the FIR filter, signal, and info dictionary.

### Parameters
- **signal** (ndarray) - Required - 1-D record x.
- **fs** (float) - Required - Sampling frequency in hertz.
- **filter_size** (int) - Optional - Inverse FIR length N (default 40).
- **relative_error** (float) - Optional - MATLAB param.RE (default 1e-3).
- **max_iter** (int) - Optional - MATLAB param.iter (default 50).
- **order** (int) - Optional - Cyclostationarity order p (default 2).
- **n_harmonics** (int) - Optional - EHPS product order K (default 10).
```

--------------------------------

### pysdkit.data.test_univariate_gaussamp_quadfm

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Generates a Gaussian–modulated quadratic chirp signal.

```APIDOC
## pysdkit.data.test_univariate_gaussamp_quadfm(duration: float = 6.0, sampling_rate: int = 128, noise_level: float = 0.0, random_state: int = 42) -> Tuple[ndarray, ndarray]

### Description
Generates a Gaussian–modulated quadratic chirp: s(t) = 4 * exp(-((t-3)/1.5)**2) * sin(2π*(10*t + 3*t**2)).

### Parameters
- **duration** (float) - Optional - Length of signal in seconds. Default: 6.0.
- **sampling_rate** (int) - Optional - Samples per second. Default: 128.
- **noise_level** (float) - Optional - Standard deviation of Gaussian noise. Default: 0.0.
- **random_state** (int) - Optional - Random seed. Default: 42.

### Returns
- **Tuple[ndarray, ndarray]** - Tuple containing (t, noisy_signal).
```

--------------------------------

### Perform Variational Mode Decomposition (VMD)

Source: https://github.com/wwhenxuan/pysdkit/blob/main/README.md

Applies VMD to a test signal with specific hyperparameters for decomposition.

```python
from pysdkit import VMD
from pysdkit.data import test_vmd
from pysdkit.plot import plot_IMFs

t, signal, fs = test_vmd()

vmd = VMD(alpha=2000, K=4, tau=0.0, tol=1e-7)
IMFs = vmd.fit_transform(signal)
plot_IMFs(signal, IMFs, view="2d_freq", fs=fs, freq_max=fs / 2)
```

--------------------------------

### pysdkit.models.PCA

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.models.rst

An object-oriented interface for performing Principal Component Analysis.

```APIDOC
## class pysdkit.models.PCA(n_components=2, norm='centralize')

### Description
Provides an object-oriented interface for dimensionality reduction using PCA.

### Methods
- **fit_transform(X: ndarray) -> ndarray**: Executes the PCA algorithm on input data X.
- **data_processing(X: ndarray) -> ndarray**: Preprocesses the input data.
- **reset() -> None**: Clears stored results from the algorithm.

### Properties
- **components_**: Returns the top N principal components.
- **explained_variance_ratio_**: Returns the explained variance ratio.
- **mean_**: Returns the mean vector of the input data.
- **variance_**: Returns the variance vector of the input data.
```

--------------------------------

### pysdkit.SSA.fit_transform

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._tid.rst

Executes the Singular Spectral Analysis (SSA) algorithm to perform signal decomposition.

```APIDOC
### Method
`fit_transform(signal: ndarray) -> ndarray`

### Description
Executes the Singular Spectral Analysis (SSA) algorithm to perform signal decomposition on a 1D input signal.

### Parameters
- **signal** (ndarray) - Required - Input signal of 1D ndarray.

### Returns
- **ndarray** - The decomposed results of IMFs.
```

--------------------------------

### pysdkit.data.load_sst_float

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit.data.rst

Loads the packaged float-drift record.

```APIDOC
## pysdkit.data.load_sst_float()

### Description
Load the packaged float-drift record used by multivariate SST.

### Returns
- **dict** - Contains 'signal'
```

--------------------------------

### fit_transform(signal, max_imfs)

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._emd.rst

Decomposes a whole record.

```APIDOC
## fit_transform(signal: ndarray, max_imfs: int = None)

### Description
Decompose a whole record (dump-then-iterate).

### Parameters
- **signal** (ndarray) - Required - Univariate 1-D signal.
- **max_imfs** (int) - Optional - Override the constructor cap for this call.

### Returns
- **ndarray** - Array of shape (n_imfs, n_samples).
```

--------------------------------

### pysdkit.IMD

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._imd.rst

Impulsive Mode Decomposition class for extracting impulsive modes using particle-swarm optimization.

```APIDOC
## class pysdkit.IMD(n_particles=45, max_iter=20, threshold=1.6, min_band=0.0, max_modes=4, seg_num=10, fs=None, seed=None)

### Description
Initializes the IMD decomposition framework.

### Parameters
- **n_particles** (int) - Optional - Number of particles for optimization.
- **max_iter** (int) - Optional - Maximum iterations.
- **threshold** (float) - Optional - Sparsity threshold.
- **min_band** (float) - Optional - Minimum frequency band.
- **max_modes** (int) - Optional - Maximum number of modes.
- **seg_num** (int) - Optional - Number of segments.
- **fs** (float) - Optional - Sampling frequency.
- **seed** (int) - Optional - Random seed.

## method fit_transform(signal, fs=None, return_all=False)

### Description
Decomposes a signal into impulsive modes.

### Parameters
- **signal** (ndarray) - Required - 1-D real signal.
- **fs** (float) - Optional - Sampling frequency.
- **return_all** (bool) - Optional - If True, returns bands, residual, and fitness histories.
```

--------------------------------

### pysdkit.SJMD

Source: https://github.com/wwhenxuan/pysdkit/blob/main/docs/source/API/pysdkit._jmd.rst

Class for Successive Jump and Mode Decomposition (SJMD/SMJMD) without a predefined mode count.

```APIDOC
## class pysdkit.SJMD(max_alpha=80000.0, tau=50.0, beta=0.5, b_bar=0.9, stopc=4, tol=1e-05, kdm=None, max_inner=100, min_alpha=10.0)

### Description
Initializes the SJMD model for successive extraction of modes and jump components.

### Method: fit_transform(signal, return_all=False)
- **signal** (ndarray) - Required - Univariate or multivariate signal.
- **return_all** (bool) - Optional - If True, returns (modes, jump).
```
Tokens:
Raw