Metadata-Version: 2.4
Name: LogPSplinePSD
Version: 0.2.0
Summary: LogPsplines in JAX
Author-email: Avi Vajpeyi <avi.vajpeyi@gmail.com>
Project-URL: Homepage, https://nz-gravity.github.io/LogPSplinePSD/
Project-URL: Bug Reports, https://github.com/nz-gravity/LogPSplinePSD/issues
Project-URL: Source, https://github.com/nz-gravity/LogPSplinePSD/
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: jax
Requires-Dist: jaxtyping>=0.3.9
Requires-Dist: optax
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: tqdm
Requires-Dist: numpyro
Requires-Dist: h5py
Requires-Dist: arviz-base[netcdf4,zarr]
Requires-Dist: arviz-stats
Requires-Dist: arviz-plots[matplotlib]
Requires-Dist: xarray[accel,io]
Requires-Dist: click
Requires-Dist: ipywidgets
Requires-Dist: plotly
Requires-Dist: loguru
Requires-Dist: scikit-fda
Requires-Dist: multimethod<2,>=1.12
Provides-Extra: wdm
Requires-Dist: wdm-transform>=0.5.0; extra == "wdm"
Provides-Extra: typecheck
Requires-Dist: beartype>=0.22.9; extra == "typecheck"
Provides-Extra: dev
Requires-Dist: LogPSplinePSD[typecheck]; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-memray; extra == "dev"
Requires-Dist: pytest-durations; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: jupyter-book<2.0; extra == "dev"
Requires-Dist: ipykernel; extra == "dev"
Requires-Dist: prek; extra == "dev"
Requires-Dist: GitPython; extra == "dev"
Requires-Dist: vulture; extra == "dev"
Dynamic: license-file

LogPSplinePSD
=============

``LogPSplinePSD`` estimates power spectral densities (PSDs) with Bayesian
log-P-splines. It supports univariate and multivariate time series, fits smooth
spectral matrices with NumPyro/JAX, and returns ``PSDResult`` outputs with
ArviZ-compatible ``xarray.DataTree`` posteriors.

Highlights
----------

- Log-domain P-spline models for positive PSDs.
- Multivariate Wishart likelihoods for spectral matrices.
- VI warm starts and factorised multivariate NUTS.
- Optional frequency-domain coarse graining.
- Scalar time-varying fits from WDM and moving-periodogram powers.
- Posterior PSD quantiles, coherence summaries, and diagnostic plots.

Install
-------

For development, use the repository virtual environment:

.. code-block:: bash

   source .venv/bin/activate
   python -m pip install -e '.[dev]'

For package use:

.. code-block:: bash

   python -m pip install LogPSplinePSD

Five-Minute Example
-------------------

.. code-block:: python

   from log_psplines import StationaryConfig, fit
   from log_psplines.example_datasets import VARMAData

   data = VARMAData.ar(order=4, n_samples=8192, fs=64.0, seed=7)

   result = fit(
       data.ts,
       StationaryConfig(
           n_knots=16,
           knot_kwargs={"method": "density"},
           vi_steps=200,
           n_warmup=100,
           n_samples=200,
           rng_key=7,
           true_psd=data.get_true_psd(),
       ),
   )

   frequency = result.frequency
   psd_draws = result.psd

Next Steps
----------

- Follow the `univariate example <docs/examples/univar-example.ipynb>`_.
- Explore the `multivariate example <docs/examples/multivariate-example.ipynb>`_.
- Try the `time-varying example <docs/examples/timevarying-example.ipynb>`_.
- Read the `spectral conventions <docs/conventions.rst>`_.

Architecture
------------

See the `development notes <CONTRIBUTING.md>`_ for the shared scalar/matrix
model and time-frequency evaluation. Scalar time-varying power inference is
available through ``fit()``. Multivariate time-varying inference is not yet
implemented.

Documentation
-------------

Build the docs locally with:

.. code-block:: bash

   source .venv/bin/activate
   .venv/bin/jupyter-book build docs

The public docs focus on package usage, configuration, outputs, API reference,
and implementation notes. Domain-specific examples are intentionally kept out of
the main docs for now and can be added later as separate studies.

References
----------

Eilers, P. H. C., & Marx, B. D. (1996). *Flexible smoothing with B-splines and
penalties*. Statistical Science, 11(2), 89-121.

Maturana-Russel, J., & Meyer, R. (2021). *P-spline spectral density estimation
with a discrete penalty*. arXiv:1905.01832.

Vajpeyi, A., Meyer, R., Maturana-Russel, P., & Liu, J. (2026).
*Multivariate Bayesian P-spline estimation of spectral density matrices,
with application to LISA TDI noise*.
`arXiv:2607.04833 <https://arxiv.org/abs/2607.04833>`_.
`DOI:10.48550/arXiv.2607.04833 <https://doi.org/10.48550/arXiv.2607.04833>`_.
