11User guide
22==========
33
4- Three-step API
5- --------------
4+ What PySDKit is
5+ ---------------
6+
7+ **Signal decomposition ** is a post-wavelet time-frequency tool: a
8+ complex **non-stationary, nonlinear ** recording is assumed to be a sum
9+ of simpler sub-signals (intrinsic mode functions). Analysing those
10+ modes recovers time-frequency structure that a single Fourier transform
11+ cannot, and that a fixed wavelet dictionary often cannot either.
12+
13+ Since the Hilbert–Huang Transform (1998), a family of univariate and
14+ multivariate decompositions has grown quickly in MATLAB. Python is the
15+ usual home of machine learning, yet it still lacked a library comparable
16+ to `PyWavelets <https://pywavelets.readthedocs.io/ >`_ for this class of
17+ algorithms.
18+
19+ PySDKit was started in April 2024 to close that gap: one package, a
20+ shared ``fit_transform `` API, and matching plots so decomposition can
21+ be used as **feature engineering ** next to NumPy, SciPy, and neural
22+ networks. Families already in the tree include EMD, EWT, VMD / OVMD,
23+ VNCMD, ALIF, APMD, and related 2-D methods.
24+
25+ Please cite the **original paper ** of each algorithm you use; class and
26+ module docstrings point to those references.
27+
28+ Install
29+ -------
30+
31+ From PyPI:
32+
33+ .. code-block :: bash
34+
35+ pip install pysdkit
36+
37+
38+
39+ From a clone (editable, for development):
40+
41+ .. code-block :: bash
42+
43+ git clone https://github.com/wwhenxuan/PySDKit.git
44+ cd PySDKit
45+ pip install -e .
46+
47+
48+ :mod: `pysdkit.data ` (for example ``test_vmd ``) over local MATLAB files.
49+ ``.npy `` data live under ``pysdkit/data/real_world ``. The gitignored
50+ ``repo/ `` tree is not installed and must not be imported at runtime.
51+
52+ Unified interface
53+ -----------------
654
755Decomposition classes share a scikit-learn-style interface:
856
9571. Import the algorithm from :mod: `pysdkit `.
10582. Create an instance (optional parameters set the rank, filter length, …).
11593. Call ``fit_transform `` on a 1-D array, a channel stack, or an image.
60+ 4. Inspect the original recording and the IMFs with
61+ :func: `~pysdkit.plot.plot_IMFs `.
1262
1363.. code-block :: python
1464
@@ -21,8 +71,7 @@ Decomposition classes share a scikit-learn-style interface:
2171 IMFs = vmd.fit_transform(signal)
2272 plot_IMFs(signal, IMFs, view = " 2d_freq" fs = fs, freq_max = fs / 2 )
2373
24-
25- --------------------
74+
2675
2776.. list-table ::
2877 :header-rows: 1
@@ -49,25 +98,94 @@ Which family to pick
4998
5099A full name list is on :doc: `/API/modules `.
51100
52- Packaged data
53- -------------
101+ Worked examples
102+ ---------------
103+
104+ The snippets below are the three README-style demos from
105+ ``examples/demo.py ``. Run that script for CEEMDAN and 2-D VMD as well.
106+
107+ EMD — three-tone mixture
108+ ~~~~~~~~~~~~~~~~~~~~~~~~
109+
110+ A sum of cosines at 5 / 25 / 80 Hz. EMD sifts recursively by scale.
111+
112+ .. code-block :: python
113+
114+ import numpy as np
115+ from pysdkit import EMD
116+ from pysdkit.plot import plot_IMFs
117+
118+ t = np.linspace(0 , 1 , 1000 )
119+ signal = (
120+ np.sin(2 * np.pi * 5 * t)
121+ + 0.7 * np.sin(2 * np.pi * 25 * t)
122+ + 0.45 * np.sin(2 * np.pi * 80 * t)
123+ )
124+
125+ emd = EMD()
126+ IMFs = emd.fit_transform(signal, max_imfs = 3 )
127+ plot_IMFs(signal, IMFs, view = " 2d_freq" fs = 1000 , freq_max = 150 )
128+
129+ image :: ../auto_examples/images/sphx_glr_demo_001.png
130+ :width: 95%
131+ :alt: EMD — three-tone mixture (time and frequency)
54132
55- Demo arrays install with the package. Prefer the loaders in
56- :mod: `pysdkit.data ` over any local MATLAB dump:
133+ VMD — packaged multicomponent signal
134+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
135+
136+ Non-recursive VMD estimates several band-limited modes jointly in the
137+ Fourier domain. Data come from ``test_vmd() ``.
57138
58139.. code-block :: python
59140
60- from pysdkit.data import load_bmemd_source02, load_bss_beam, test_vmd
141+ from pysdkit import VMD
142+ from pysdkit.data import test_vmd
143+ from pysdkit.plot import plot_IMFs
144+
145+ t, signal, fs = test_vmd()
146+ vmd = VMD(alpha = 2000 , K = 4 , tau = 0.0 , tol = 1e-7 )
147+ IMFs = vmd.fit_transform(signal)
148+ plot_IMFs(signal, IMFs, view = " 2d_freq" fs = fs, freq_max = fs / 2 )
149+
150+ image :: ../auto_examples/images/sphx_glr_demo_002.png
151+ :width: 95%
152+ :alt: VMD — packaged multi-component example (time and frequency)
153+
154+ MVMD — aligned multichannel modes
155+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
156+
157+ Three channels share a 36 Hz oscillation; each also carries a distinct
158+ tone. MVMD keeps mode index :math: `k` aligned across channels.
159+
160+ .. code-block :: python
161+
162+ import numpy as np
163+ from pysdkit import MVMD
164+ from pysdkit.plot import plot_IMFs
165+
166+ t = np.arange(0 , 1 , 0.001 )
167+ signal = np.vstack(
168+ [
169+ np.cos(2 * np.pi * 2 * t) + np.cos(2 * np.pi * 36 * t),
170+ np.cos(2 * np.pi * 24 * t) + np.cos(2 * np.pi * 36 * t),
171+ np.cos(2 * np.pi * 80 * t) + np.cos(2 * np.pi * 36 * t),
172+ ]
173+ )
174+
175+ mvmd = MVMD(alpha = 2000 , K = 4 , tau = 0.0 , init = " uniform"
176+ IMFs = mvmd.fit_transform(signal) # (K, T, C)
177+ plot_IMFs(signal, IMFs)
61178
62- images = load_bmemd_source02()[" signal" # (2, 224, 224) in [0, 1]
63- beam = load_bss_beam()[" signal"
179+ image :: ../auto_examples/images/sphx_glr_demo_003.png
180+ :width: 95%
181+ :alt: MVMD — mode-aligned multichannel decomposition
64182
65- .npy `` files live under ``pysdkit/data/real_world ``; callers still pass
66- a bare file name to the loader. The gitignored ``repo/ `` directory is
67- not part of the install and must not be used at runtime.
183+ Examples gallery
184+ ----------------
68185
69- Next steps
70- ----------
186+ The full executed gallery (theory, figures, Python and notebook
187+ downloads) is :doc: ` /auto_examples/index `.
71188
72- - Example gallery: :doc: `/auto_examples/index `
73- - Public classes: :doc: `/API/modules `
189+ ``examples/demo.py `` is the overview script used above. Each algorithm
190+ family has its own folder under ``examples/ `` (for example
191+ ``examples/emd/ ``, ``examples/vmd/ ``).
0 commit comments