Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
142 lines (112 loc) · 5.82 KB

CONTRIBUTING.md

File metadata and controls

142 lines (112 loc) · 5.82 KB
Raw

Contributing to PySDKit

Thank you for helping grow PySDKit. This page is the contributor guide for the GitHub project; the same material lives in the documentation under Development.

Why PySDKit exists

Signal decomposition treats a non-stationary recording as a sum of simpler modes (intrinsic mode functions). Those modes are a practical time-frequency / feature-engineering tool: they can be plotted, used as features, or fed to a downstream model.

Fourier analysis assumes stationarity; fixed wavelet dictionaries still impose a predefined basis. Since the Hilbert–Huang Transform (1998), a family of adaptive univariate and multivariate decompositions has grown quickly in MATLAB, but Python (the usual home of machine learning) still lacks a library comparable to PyWavelets for this class of algorithms.

PySDKit was started in April 2024 to close that gap: one package, a shared fit_transform style API, and enough visualization that decomposition can sit next to NumPy, SciPy, and neural-network stacks without a MATLAB detour.

Please cite the original paper of each algorithm you use; class and module docstrings point to those references.

Project layout: where a new algorithm belongs

Implementation lives under pysdkit/. Algorithm families use a leading underscore (pysdkit/_emd, pysdkit/_vmd, …). Shared helpers live beside them (pysdkit/data, pysdkit/plot, pysdkit/utils, pysdkit/tsa, pysdkit/entropy).

Put a new method in the family it resembles. If the principle is close to an existing package, add a module there and export it from that package’s __init__.py. If the idea is genuinely different, create a new package (for example pysdkit/_yourmethod/) rather than stretching an unrelated folder.

Package Typical contents Example gallery folder
pysdkit/_emd EMD, EEMD, CEEMDAN, REMD, SEMD, TVF-EMD, ESMD, HHT; also MEMD / APITMEMD / NSTEMD examples/emd, examples/emd_variants, examples/memd
pysdkit/_emd2d EMD2D, BMEMD examples/image
pysdkit/_ewt EWT, EWT2D, EFD examples/ewt
pysdkit/_faemd FAEMD (1-D / 2-D / 3-D) examples/faemd
pysdkit/_vmd VMD, MVMD, OVMD, STVMD, SVMD, VME examples/vmd
pysdkit/_vmd2d VMD2D, CVMD2D examples/image
pysdkit/_acmd ACMD, BA-ACMD, DD-ACMD examples/acmd
pysdkit/_vncmd VNCMD, AVNCMD, STNBMD examples/vncmd
pysdkit/_gdmd GDMD, VGNMD, IVGNMD, AGNCMD examples/gdmd
pysdkit/_tid ALIF, FMD, HVD, ITD, SSA examples/temp_iter, examples/ssa
pysdkit/_tfa SST, SET, VTFMTD examples/tfa
pysdkit/_lmd LMD, RLMD examples/lmd
pysdkit/_osd OSD, SWD examples/osd
pysdkit/_imd IMD, APMD examples/imd
pysdkit/_jmd JMD, SJMD examples/jmd
pysdkit/tsa STL, MSTL, moving-average decomposition examples/tsa
pysdkit/utils BSS, deconvolution, kurtogram examples/utils, examples/deconvolution

After the implementation:

  1. Export the public class / function from the family __init__.py.
  2. Re-export it from pysdkit/__init__.py and add the name to __all__.
  3. Add a thin autoclass / autofunction line on the matching page under docs/source/API/.
  4. Prefer pysdkit.data loaders for demo arrays; put .npy files in pysdkit/data/real_world.

Do not import the gitignored repo/ tree (local MATLAB / paper sources) from installed code or from examples.

Tests

Please add unit tests in pysdkit/tests/ so the public surface stays stable. Name the file test_<algo>.py and follow the existing unittest style (see pysdkit/tests/test_emd.py, test_vmd.py).

Aim to cover every public class and method you introduce, not only a single happy-path call. A useful minimum is:

  • construction / default parameters
  • fit_transform (shape: modes × samples, length matches the input)
  • __call__ if the class is callable
  • functional aliases (emd, vmd, …) when you export them
  • invalid inputs (ValueError / TypeError)
  • a trivial or reconstructible signal when the algorithm claims completeness

Use pysdkit.data generators (test_emd, test_univariate_signal, …) instead of huge private fixtures.

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

Examples

Please ship a gallery script that shows the algorithm on a small demo (theory plus figures). Examples are Python files, not notebooks.

  • Put the script in the matching folder under examples/ (see the table above). A new family gets a new folder and a GALLERY_HEADER.rst with a title.
  • Start with a raw title docstring (r"""..."""). Extra theory goes in # %% comment blocks (Sphinx-Gallery turns those into HTML text and into markdown cells in the generated .ipynb download).
  • Do not inject sys.path and do not use __file__. The docs build already installs the package.
  • Prefer pysdkit.data over local .mat files.
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

Look at examples/emd/emd.py or examples/vmd/ for the expected tone: motivation, a compact statement of the method, then executable plots.

The docs gallery is generated by Sphinx-Gallery at build time. Do not commit docs/source/auto_examples/. Figures are packed into a GitHub Release (gallery-cache) so Read the Docs can skip unchanged examples; see .github/docs-build.md.

Pull requests

  • Keep the change focused: one algorithm (or one tightly related family) per PR is easier to review.
  • Run the unit tests before you open the PR.
  • English for public docstrings, gallery headers, and commit messages.