specmod 0.2.0__py3-none-any.whl

specmod-0.2.0.dist-info/METADATA

@@ -0,0 +1,294 @@
+Metadata-Version: 2.5
+Name: specmod
+Version: 0.2.0
+Summary: A Python toolbox for processing and modelling seismic spectra
+Project-URL: Homepage, https://github.com/sgjholt/SpecMod
+Project-URL: Repository, https://github.com/sgjholt/SpecMod
+Project-URL: Issues, https://github.com/sgjholt/SpecMod/issues
+Author: James Holt
+License-Expression: MIT
+License-File: LICENSE
+Keywords: moment magnitude,seismology,source parameters,spectra
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: lmfit>=1.3
+Requires-Dist: matplotlib>=3.9
+Requires-Dist: numpy>=2.0
+Requires-Dist: obspy>=1.5
+Requires-Dist: pandas>=2.2.2
+Requires-Dist: pooch>=1.8
+Requires-Dist: scipy>=1.15
+Provides-Extra: dev
+Requires-Dist: h5py>=3.11; extra == 'dev'
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pyarrow>=16.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: myst-nb>=1.1; extra == 'docs'
+Requires-Dist: myst-parser>=3.0; extra == 'docs'
+Requires-Dist: pydata-sphinx-theme>=0.15; extra == 'docs'
+Requires-Dist: sphinx>=7.3; extra == 'docs'
+Provides-Extra: io
+Requires-Dist: h5py>=3.11; extra == 'io'
+Requires-Dist: pyarrow>=16.0; extra == 'io'
+Provides-Extra: mcmc
+Requires-Dist: emcee>=3.1; extra == 'mcmc'
+Provides-Extra: multitaper
+Requires-Dist: multitaper>=1.2; extra == 'multitaper'
+Provides-Extra: tutorial
+Requires-Dist: ipykernel>=7.0; extra == 'tutorial'
+Requires-Dist: nbclient>=0.10; extra == 'tutorial'
+Requires-Dist: nbformat>=5.10; extra == 'tutorial'
+Provides-Extra: wavelet
+Requires-Dist: pywavelets>=1.5; extra == 'wavelet'
+Description-Content-Type: text/markdown
+
+# SpecMod
+
+A Python toolbox for processing and modelling seismic spectra, following the
+method of Edwards *et al.* (2010).
+
+SpecMod estimates source parameters — long-period spectral level Ω, corner
+frequency `f_c`, and the attenuation operator `t*` — by fitting a Brune-type
+source model to direct-phase spectra.
+
+> **Status: alpha, and under active reconstruction.**
+> The package is pre-1.0 and mid-refactor. The modern layers
+> (`specmod.config`, `specmod.core`, `specmod.transforms`, `specmod.picks`,
+> `specmod.fitting`) are built and tested; the older pipeline modules still
+> carry pre-refactor behaviour and are being replaced stage by stage. Expect
+> breaking changes at every `0.x` release until the API settles at 1.0 — they
+> land in minor bumps by design, with no deprecation cycle. Pin an exact
+> version for anything you intend to publish.
+> [`docs/roadmap.md`](docs/roadmap.md) says which stages are done and what 1.0
+> will mean; [`docs/REFACTOR_PLAN.md`](docs/REFACTOR_PLAN.md) is the working
+> document behind it.
+
+## Installation
+
+Requires Python 3.11 or newer.
+
+```sh
+pip install -e ".[dev]"
+```
+
+Optional extras:
+
+| Extra | Adds |
+|---|---|
+| `multitaper` | Prieto's `multitaper` package — jackknife confidence intervals, F-test for spectral lines |
+| `wavelet` | PyWavelets, for wavelet families beyond the built-in Morlet |
+| `mcmc` | `emcee`, for Markov-chain Monte Carlo parameter search |
+
+No Fortran compiler is needed. Multitaper estimation is implemented natively on
+SciPy's DPSS tapers, so the historical `mtspec` dependency — Fortran source with
+no wheels and no release since 2016 — is no longer required.
+
+## Estimating a spectrum
+
+Every estimator returns a `Spectrum` that knows its own units:
+
+```python
+import numpy as np
+from specmod.transforms import FFTEstimator, MultitaperEstimator
+
+dt = 0.01
+trace = np.random.default_rng(0).normal(0, 1e-6, 2000)
+
+spectrum = MultitaperEstimator(time_bandwidth=3.0, n_tapers=5).estimate(
+    trace, dt, motion="velocity"
+)
+
+spectrum.unit           # 'm/s*s' — a Fourier amplitude spectrum
+spectrum.duration       # 20.0 s, the physical record length
+spectrum.energy()       # recovers sum(x**2) * dt
+```
+
+Conversions return new objects and are unit-aware:
+
+```python
+spectrum.to_motion("displacement")   # divides by 2*pi*f
+spectrum.to_kind("psd")              # A**2 / (2T)
+spectrum.band(0.5, 25.0)
+```
+
+The wavelet estimator additionally exposes the full time-frequency surface,
+which is what to look at when a fit comes out wrong:
+
+```python
+from specmod.transforms import CWTEstimator
+
+scalogram = CWTEstimator().scalogram(trace, dt)
+scalogram.time_average()     # an ordinary Spectrum, fits like any other
+scalogram.coi_coverage()     # how much of the window each frequency resolves
+scalogram.qc()               # concentration, coda balance, resolved bandwidth
+```
+
+Which estimator to use, and what each one does to your data — including
+measured position-dependence and the variance-normalisation convention `mtspec`
+used — is set out in
+[`docs/choosing-a-transform.md`](docs/choosing-a-transform.md), with a
+worked walkthrough in
+[`docs/notebooks/choosing-a-transform.ipynb`](docs/notebooks/choosing-a-transform.ipynb).
+
+### Why the units are typed
+
+A spectrum carries its ground-motion domain and amplitude convention as
+attributes rather than in module-level globals. The alternative is keeping those
+globals in sync by hand with however many times `.inte()` or `.diff()` has been
+called, where getting it wrong returns a wrong seismic moment with no error
+anywhere. Here it is a type error.
+
+Amplitude normalisation is keyed off the physical record duration, never off the
+length of the frequency axis, so zero-padding refines the frequency grid and
+changes nothing else.
+
+## Reading picks
+
+Arrivals are attached to traces by `set_picks`, which detects the format from
+the file rather than from its name:
+
+```python
+import specmod.preprocess as pre
+
+pre.set_picks(stream, "event.xml")
+```
+
+Everything `obspy.read_events` parses is read through one delegate — QuakeML,
+SEISAN Nordic, HypoDD, NonLinLoc, IMS/GSE bulletins — plus Snuffler marker
+files, plus delimited tables whose columns you name. A format registered with
+ObsPy's own plugin system is read here with no SpecMod-side registration at
+all.
+
+Most formats supply less than a full sensor identity — a bare station code is
+common — so a pick matches a trace on the fields it *states*. A pick that fits
+several sensors is an error rather than a broadcast: a station's surface and
+borehole instruments differ only by location code and do not see the same
+arrival.
+
+Adding a format, the column mapping for a picker's CSV, and the policies for
+duplicate picks and multi-event files are in
+[`docs/pick-formats.md`](docs/pick-formats.md).
+
+## Configuration
+
+Settings are grouped by pipeline stage and resolved through five layers —
+package defaults, a committed `specmod.toml`, a gitignored
+`specmod.local.toml`, `SPECMOD_*` environment variables, then explicit
+arguments:
+
+```sh
+specmod config show      # resolved values, and which layer set each one
+specmod config freeze    # emit TOML to commit alongside a result
+```
+
+Package defaults reproduce the behaviour that shipped before the refactor, so
+upgrading does not silently move anyone's numbers. A study pins its own values
+in a committed file — see [`studies/magna_2020_paper.toml`](studies/magna_2020_paper.toml),
+which transcribes the workflow of the Magna paper below.
+
+Every output records the configuration that produced it, a hash of it, and the
+SpecMod version, so a locally-overridden run is still reproducible from its
+outputs.
+
+## Documentation
+
+The full documentation — the pipeline with its equations, the estimator
+comparison, pick formats, and an API reference — builds with Sphinx:
+
+```bash
+uv pip install -e '.[docs]'
+sphinx-build -b html docs docs/_build/html
+```
+
+`docs/REFACTOR_PLAN.md` is excluded from the built site on purpose: it is a
+working document that records decisions and the measurements behind them, not
+documentation for using the package.
+
+## Development
+
+```sh
+uv venv && uv pip install -e ".[dev]"
+pre-commit install                 # both hook types; not optional
+pytest                             # test suite
+pytest --without-optional-extras   # as a default install and CI see it
+ruff check src/ tests/ tools/      # lint
+ruff format src/ tests/ tools/
+mypy                               # strict on the rewritten modules
+```
+
+[`docs/development.md`](docs/development.md) is the full guide — the repository
+mapped, every tool and CI check, the branch and commit conventions, and where
+development stops and releasing begins. [`AGENTS.md`](AGENTS.md) is the short
+version that binds AI coding sessions.
+
+Run `--without-optional-extras` before pushing. A development environment
+with `specmod[multitaper]` installed will pass tests that a default install
+fails, and CI installs only `[dev]`.
+
+The `mypy` override list in `pyproject.toml` is the migration backlog: modules
+leave it as they are rewritten, and the target is an empty list.
+
+Command-line entry points are built on [`click`](https://click.palletsprojects.com),
+including internal tooling — one convention across the whole surface.
+
+### Measured numbers in the docs
+
+The documentation quotes a lot of measurements, and stale numbers are worse
+than no numbers. Every table that came out of a measurement is generated:
+
+```sh
+python tools/measure_docs.py show     # print the tables
+python tools/measure_docs.py write    # refresh the docs in place
+python tools/measure_docs.py check    # fail if any table is stale
+```
+
+`tests/test_docs_are_current.py` runs `check`, so a change that moves a
+published number fails the suite rather than quietly leaving the prose wrong.
+Measurements that read `tutorial/data/events/` are slower and opt-in via `--field`;
+refresh those by hand after changing an estimator.
+
+### Releasing
+
+Commit messages follow [Conventional Commits](https://www.conventionalcommits.org),
+which is what makes the changelog and the version automatic: `release-please`
+opens a standing release pull request, and merging it creates the tag, the
+GitHub Release, the PyPI upload and the Zenodo DOI. Nothing is released until
+that merge. See [`docs/releasing.md`](docs/releasing.md), which also lists the
+repository settings that have to be turned on once.
+
+## References
+
+Edwards, B., Allmann, B., Fäh, D., Clinton, J. (2010). Automatic computation of
+moment magnitudes for small earthquakes and the scaling of local to moment
+magnitude. *Geophysical Journal International* 183(1), 407–420.
+<https://doi.org/10.1111/j.1365-246X.2010.04743.x>
+
+Holt, J., Whidden, K.M., Koper, K.D., Pankow, K.L., Mayeda, K., Pechmann, J.C.,
+Edwards, B., Gök, R., Walter, W.R. Towards robust and routine determination of
+Mw for small earthquakes: application to the 2020 Mw 5.7 Magna, Utah, seismic
+sequence. *Seismological Research Letters*.
+
+Thomson, D.J. (1982). Spectrum estimation and harmonic analysis.
+*Proceedings of the IEEE* 70(9), 1055–1096.
+
+## Contributing
+
+Issues and pull requests are welcome. Commits follow
+[Conventional Commits](https://www.conventionalcommits.org), which drives the
+changelog and version bumps.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

specmod-0.2.0.dist-info/RECORD

@@ -0,0 +1,62 @@
+specmod/__init__.py,sha256=jUpGxd9YwXnWe_lV5bbcmFiIxmzJuR6a3kIV8bw6tTs,511
+specmod/acquire.py,sha256=xUkm22b9nXTK1eYpy3grSWzTgHzPf2a1y-dEZFNbk7M,13313
+specmod/api.py,sha256=JP3f_EMjfTEqUSCEDJ0YBZ6ss5lnLWinYM94Syvk53Q,17836
+specmod/cli.py,sha256=m-Rr5ZSbvCmxOL-mqnnR7TEjPtzIdaiwKRQv0YG9YSU,4061
+specmod/datasets.py,sha256=IrOK6x58AuvmucPMmhkduP-kSOdXqfYFiJWkXLg5p0E,11126
+specmod/distance.py,sha256=YZEeATI9Gv3Nbbfa5OAy26sOcxYczEC8ANat0REEq-A,6859
+specmod/exceptions.py,sha256=ygDyk_KOLxifUh_AfChrkM-vShydbEXk8-qxw1Kxnrg,2044
+specmod/io.py,sha256=6tCgN6K23XdnX20BptkFq96asfnEKPoJ5OUoGJJyvVk,10210
+specmod/magnitude.py,sha256=sP9h9etg3Xi9E9lzkgIe0-ZJKscSCbNK-AdrKY-doTM,11168
+specmod/pipeline.py,sha256=BXZdUs126nKEQ19MywNZG8XHowRwKCb1NLt9H_-9QpA,11784
+specmod/plotting.py,sha256=bCWdUrw2wboQORo9aDSHGd53zzFkgpfNuNUrGxqcyYg,7223
+specmod/preprocess.py,sha256=vZDSlmz0rLAbwLJwxYYSEIFDIGYXidRVNJTaekBegGA,18813
+specmod/spreading.py,sha256=SAKOb6nbPt0uiKn_4XQ4KWGdkLTXbgi45pAjluvcMyA,7458
+specmod/staged.py,sha256=5DCOlmMTt38Gi3xSiZTqG0aN5Yle382G3s2CDvStd6M,21512
+specmod/tables.py,sha256=ttduUrv3Nw9XC2B6OuvWa-fOKXVCilMVxbSfDVnPVR4,3999
+specmod/utils.py,sha256=R6ybnJr59LXH5KnCQB5c-AJ3CJK3FSQOrRoWu8_qhQE,11829
+specmod/_vendor/__init__.py,sha256=UV0Dc5ppqpen7PGL8M4Xgq8cC9TofgX8aDf5oWwR7F8,991
+specmod/_vendor/qiinv.py,sha256=l3yntXtiY88jZ2u68ZgXQFtbe9mC-l_pI6MqOiFWhs4,10061
+specmod/config/__init__.py,sha256=mdOZx-8bKOtNSZ76wlh4NUzf7J6Emgm-tMI69pAvEBg,1035
+specmod/config/layers.py,sha256=IlYlMXTtTIOhEPgnBJlyUTn7srADokycaNdH6Ok7fCk,5640
+specmod/config/provenance.py,sha256=4i7QowIVuydld87N3XAfHLAZ7ANe78533Fchrkn8F6s,2439
+specmod/config/sections.py,sha256=rerpE4ygXB2RR1_IjgNsS31VumjcNPg1XOIhw-mYjmc,15866
+specmod/config/serialize.py,sha256=jbmG2WM2LLkvCT_Y0zhfrn1nFXHDx7dL-mZtqRq57us,2067
+specmod/core/__init__.py,sha256=a_ym0xWj_1DQYfHSM4NlerGhU9HTpZPpe8ZmaVcyzRE,882
+specmod/core/bandwidth.py,sha256=OkpALARc3QNpFSw9Tlcqw0kye7FDizgX2C0-gKgvKj8,6293
+specmod/core/collection.py,sha256=JxhpUyiHrySYYpGKkeRUZGC2l1eoA3NDGWy1FLvsg0Y,22004
+specmod/core/noise.py,sha256=pzkgFNu_glG2xtLHPJhkvZNrhWeXPCxxXBg0NmtbNjE,18301
+specmod/core/scalogram.py,sha256=DG4kuiVAVtJoUjnGrEy2jbHf1wNoScKTfNgu7xkgsYc,9499
+specmod/core/spectrum.py,sha256=Xa-fXJW7IrJLoYHwN_-ydSiizNSgwpWf30xuTe5Vj14,13844
+specmod/core/units.py,sha256=XXX0dV8k5loX2vs3Vi1b3xDXQKi9eeb0lLX3OHQtxBw,4857
+specmod/fitting/__init__.py,sha256=QQ1ivYxN5S14r4e2ynYZls9AYNH1GQMLF4PVHfC_i0w,1946
+specmod/fitting/base.py,sha256=4C_FeCPwyaA5x1a0WkqLHOf9MeUpPnBHhP9nVdTaFPw,1941
+specmod/fitting/event.py,sha256=zQwK_5zWFo4NXLqeL_l1c6EdzbPiSO3wcSolfRN-_FY,11663
+specmod/fitting/guess.py,sha256=gXEH435gpw8lPfD0r1aKeGgLOWQ3teoC4NAg4t2xnJc,6906
+specmod/fitting/spectrum.py,sha256=0gSvzxIDdWstK-tPKeR-njiKlP62pw0Sfmcow__jiro,13507
+specmod/picks/__init__.py,sha256=v9llkfvBm5MU4COf1H03oDxMLd1pKMhnR7qek-X3EYQ,6033
+specmod/picks/base.py,sha256=xJq7thhuqJ3xgAyM4qQHXK5etrXoVcWsgsQrN8xVK1o,8452
+specmod/picks/delimited.py,sha256=qEECceD91Z6fUPkSa8auUALoNmfXowtW775FdUsNwq0,7690
+specmod/picks/events.py,sha256=9Mrw5p4AiVV_CTRaZFeAcKB80g_0IknovhHBSAqqeqQ,5542
+specmod/picks/resolution.py,sha256=sYYDOs_qnR3SqKKPzQhvK6hOx8djW1KwtKoFJ0P44Hg,5098
+specmod/picks/snuffler.py,sha256=bbTv-RI0OomGDA_XceCrnSrLaiLxfrfS_e8rjVefsQQ,2795
+specmod/smoothing/__init__.py,sha256=NmUQIKd6z6ECa5hdTMLDS7V-09Yg6O9H6PtVy_oqfhg,1307
+specmod/smoothing/base.py,sha256=GKPi1Fc_DDt8ZtzFLf7u3Uy4qau-OsZiy9Q3Y0FyFrU,1966
+specmod/smoothing/konno_ohmachi.py,sha256=vmzLasw5U947VzYek_6lYjy1fk_I0i2cPoZy5zSddBU,2891
+specmod/smoothing/log_bins.py,sha256=PqQ-43yr1jXreKgKc4si6o3xeTepR4FweZshAqEQDsc,6876
+specmod/sources/__init__.py,sha256=E-g9swZtszfo-K6EY1PpnrKg7B-hcDqnIInhZW_C1Z4,2170
+specmod/sources/attenuation.py,sha256=kpQLP0Br9n6o0pMoxPyjWdymPc7NQR9bF8NzGHzhKHY,2952
+specmod/sources/composite.py,sha256=3dmpwBdBXj8HlKiCNkED03pkCb0YYpw_24HmxXW37hQ,5004
+specmod/sources/motion.py,sha256=l2piORA6AodI2nBMxA8m7Qq_G1SH1BOVpAMGmmwZo0k,1380
+specmod/sources/source.py,sha256=fzw-hLSpIsO2ioqPEM5wkaFrjNlDCd4Nk886fLn33OM,4606
+specmod/transforms/__init__.py,sha256=VQ7qIzhoAJnMXiEO-fkNqBb4MG7VV6vYMY-T3ZJJ3gM,1419
+specmod/transforms/base.py,sha256=RN8ympxUDyFvZYvZoEInju4uI-FdybsaOVhF6-gR0uY,8551
+specmod/transforms/cwt.py,sha256=vaw0XI-ftDQRNEo7mUm4AgpWF22_64v3Ds21QXOV9XA,8905
+specmod/transforms/fft.py,sha256=39ORckHm8Gbp23WQ3dF4fN8V1YGdr-GFuPQk31KD6QI,5219
+specmod/transforms/multitaper.py,sha256=5-5Yed_eGSdyIG3xPLDDh2NxPSs3_VlC4_JT6aIMN8I,15980
+specmod/transforms/prieto.py,sha256=r79Vz5UlZATorlVijhpBLoi7OwOriaifO50AbABwsjM,10757
+specmod/transforms/quadratic.py,sha256=AY40WQRyphewoz3NdKtYj1BtpcFY3O6McMp-TS-RUgU,9500
+specmod-0.2.0.dist-info/METADATA,sha256=J5DmsuFO51LsRUzNA5UNf6dp-OCE3hTpz7AlfjGaERE,11473
+specmod-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+specmod-0.2.0.dist-info/entry_points.txt,sha256=BMsuH-YPrljyx9ocZsJQNaG4GPRJxNrbETSIwKGSvyQ,45
+specmod-0.2.0.dist-info/licenses/LICENSE,sha256=Ny0RvbbbP7aV2yCme28RCYJmCljjA5JPINvl2QYyBQg,1067
+specmod-0.2.0.dist-info/RECORD,,

specmod-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

specmod-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+specmod = specmod.cli:main

specmod-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 James Holt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.