Skip to content

api.md

Latest commit

 

History

History
134 lines (106 loc) · 3.88 KB

api.md

File metadata and controls

134 lines (106 loc) · 3.88 KB
Raw

API reference

Grouped by what a run does in order: get the data, cut it, transform it, fit it, write it out.

If you are writing a package on top of SpecMod, start with specmod.api instead. It is a small, frozen subset of what follows, and the only part that carries a compatibility promise — the rest of this page documents internals that move between 0.x releases. See CONTRIBUTING.md for the exact scope of that promise.

The stable surface

.. automodule:: specmod.api
   :exclude-members: AmplitudeKind, Config, InternalError, InvalidInputError,
                     MissingBackendError, Motion, ResolvedConfig, SpecModError,
                     Spectrum, SpectrumPair, config_hash, load_config,
                     make_window, window_correction
.. automodule:: specmod.exceptions

The names excluded above are re-exports, documented once under the section that owns them — Spectrum and SpectrumPair under Spectra, Config and load_config under Configuration, and make_window and window_correction under Transforms. Documenting them twice gives every cross-reference to them two targets and makes all of them ambiguous, which is the same trap described below. specmod.api.__all__ is the authoritative list, and tests/test_api_surface.py asserts it.

Packages are documented at the path you import from — specmod.picks.PickSet, not specmod.picks.base.PickSet. Documenting both the package and its submodules gave every re-exported name two targets and made every cross-reference to it ambiguous.

Getting data

.. automodule:: specmod.datasets
.. automodule:: specmod.acquire

Picks

.. automodule:: specmod.picks
   :imported-members:

Preparing waveforms

.. automodule:: specmod.preprocess

Spectra

.. automodule:: specmod.pipeline
.. automodule:: specmod.core.spectrum
.. automodule:: specmod.core.collection
.. automodule:: specmod.core.noise
.. automodule:: specmod.core.bandwidth
.. automodule:: specmod.core.units
.. automodule:: specmod.core.scalogram

Transforms and smoothing

.. automodule:: specmod.transforms
   :imported-members:
.. automodule:: specmod.smoothing
   :imported-members:

Source models

.. automodule:: specmod.sources
   :imported-members:

Fitting

.. automodule:: specmod.fitting
   :imported-members:
.. automodule:: specmod.staged

Magnitude

.. automodule:: specmod.magnitude
.. automodule:: specmod.spreading
   :exclude-members: HOLT_2019_UTAH

HOLT_2019_UTAH is the piecewise model fitted in Holt (2019), pre-built: Piecewise(segments=((0.90, 43.0), (2.57, 76.0), (0.44, 136.0), (1.54, 400.0))). It is excluded above because autodoc cannot format a signature for a callable dataclass instance documented as module data — inspect.signature handles it fine, autodoc's own formatter raises. Excluding one constant is cheaper than working around that.

Output

.. automodule:: specmod.io
   :imported-members:
.. autodata:: specmod.io.FORMAT_VERSION
   :annotation: = 1
.. automodule:: specmod.tables
.. automodule:: specmod.plotting
   :imported-members:

FORMAT_VERSION is named explicitly because :imported-members: does not reach it. Autodoc reads a constant's documentation from the #: comment above its assignment, and the assignment is in specmod.io.layout, which is where the format is defined — importing the name into the package carries the value but not the comment. Documenting io.layout as well would give every re-exported name in it two targets, which is the trap described at the top of this page.

Configuration

.. automodule:: specmod.config
.. automodule:: specmod.utils