Skip to content

Contributing

The whole point of spectro-kernel is that a spectroscopy operation is implemented once. If you catch yourself re-coding FITS parsing, continuum normalisation, an SNR or a line fit somewhere else - stop, and add it here instead.

The golden rule

Before writing an algorithm, decide its provenance:

  • Does a canonical implementation exist in astropy, specutils, scipy or astroquery? → Wrap it. Set backend accordingly and cite it in references.
  • Is it a published method not in those libraries (like DER_SNR)? → Implement it, set backend = "numpy"/"scipy", and cite the paper.
  • Is it glue or a project convention? → Implement it, no reference needed.

This is the we-don't-reinvent principle, and it is enforced socially in review.

Adding an algorithm

One Python file under algorithms/<category>/, one test under tests/unit/. The full walkthrough is the tutorial Add an algorithm. The checklist:

  • [ ] @register_algorithm(name, category=…, version=…) on a BaseAlgorithm subclass.
  • [ ] run(self, ctx, params) reads from ctx, writes to ctx, returns AlgorithmOutput.
  • [ ] default_params, required_params, param_descriptions declared.
  • [ ] input_requirements / output_produces declared.
  • [ ] backend set; references cite the literature where applicable.
  • [ ] A test with a synthetic input and a known expected answer.
  • [ ] An optional dependency, if any, imported lazily and registered conditionally.

Conventions

  • Naming: snake_case, verb-first (fit_gaussian_line). An explicit suffix when variants coexist (normalize_polynomial / normalize_percentile).
  • Signature: always run(self, ctx: WorkContext, params: dict) -> AlgorithmOutput.
  • Determinism: no eval/exec, no hidden state; seed RNGs from params.
  • Units: wavelengths in Ångström; a documented flux_unit on Spectrum1D.
  • Versioning: bump the algorithm version on any behaviour change.
  • Core dependencies are only astropy, numpy, scipy, pyyaml. Anything else goes behind an extra.

Running the checks locally

uv pip install -e ".[dev,mcp,viz]"
ruff check src tests
pytest

CI runs the same checks on every pull request; keep main green.

Building the documentation

uv pip install -e ".[docs,all]"
python tools/docs/generate.py && zensical serve   # live preview at http://127.0.0.1:8000
python tools/docs/build.py                        # what CI runs: generators + strict build into site/

The algorithm catalogue page is generated from the registry at build time - you never edit it by hand. Add a docstring and metadata to your algorithm and the catalogue page documents it automatically.