Metadata-Version: 2.4
Name: ftmwpipeline
Version: 0.1.0b1
Summary: A Python package for FTMW spectroscopy signal processing and peak fitting
Author-email: "Kyle N. Crabtree" <kncrabtree@ucdavis.edu>
Maintainer-email: "Kyle N. Crabtree" <kncrabtree@ucdavis.edu>
License-Expression: MIT
Project-URL: Homepage, https://github.com/kncrabtree/ftmwpipeline
Project-URL: Documentation, https://ftmwpipeline.readthedocs.io/
Project-URL: Repository, https://github.com/kncrabtree/ftmwpipeline.git
Project-URL: Bug Tracker, https://github.com/kncrabtree/ftmwpipeline/issues
Keywords: spectroscopy,FTMW,signal-processing,peak-fitting,scientific-computing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: h5py>=3.1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: tqdm>=4.60.0
Requires-Dist: threadpoolctl>=3.0.0
Requires-Dist: blackchirp>=0.1.0rc2
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: Flake8-pyproject>=1.2.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=2.15.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Provides-Extra: notebook
Requires-Dist: jupyter>=1.0.0; extra == "notebook"
Requires-Dist: ipywidgets>=7.6.0; extra == "notebook"
Requires-Dist: ipykernel>=6.0.0; extra == "notebook"
Dynamic: license-file

# ftmwpipeline

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](pyproject.toml)

A Python package for FTMW (Fourier Transform Microwave) spectroscopy signal
processing and peak fitting — from a raw free-induction decay to a fitted line
list with honest uncertainties.

The design goal is a **statistically faithful** measurement, not just a
plausible-looking spectrum:

- **Unbiased spectrum.** The canonical Fourier transform is computed with no
  apodization, time-domain windowing, or zero-padding. Those operations trade
  frequency resolution, bias the line shape, and interpolate bins so the noise
  and χ² statistics no longer mean what they should. Keeping the transform
  native-length preserves resolution and the line shape, and keeps the per-bin
  statistics valid for everything downstream.
- **Rigorous from noise to fit.** A region-aware, per-bin noise estimate sets
  detection thresholds; lines are fit in the time domain over finite-duration
  windows; and fitted parameters carry uncertainties propagated **with their
  correlations**, not as independent error bars. A reported precision reflects
  what the data actually constrains.
- **Reproducible and portable.** Each experiment is one self-contained `.ftmw`
  file. Given the file and a compatible package version, the analysis
  reproduces the same result on any machine — no external preset or side
  artifact can silently change it.
- **One analysis, three interfaces.** A command-line interface, an
  object-oriented `Pipeline` class, and a stateless functional API are thin
  wrappers over one implementation and produce numerically identical results;
  use whichever fits your workflow.

## Installation

`ftmwpipeline` is currently in open beta. To install,

```bash
pip install --pre ftmwpipeline
```

This pulls in the scientific Python stack (NumPy, SciPy, Matplotlib, pandas,
h5py) and the `blackchirp` loader dependency. Testing and documentation tooling
are available as extras (`[dev]`, `[docs]`).

To work from a clone, install in editable mode — directly with pip, or via the
provided conda environment files:

```bash
pip install -e ".[dev]"
# or
conda env create -f environment-dev.yml && conda activate ftmwpipeline-dev
```

## Quick start

Process a raw experiment end to end in one command:

```bash
ftmwpipeline run path/to/experiment/ --output exp.ftmw --trim 26500:40000
```

`--trim` selects the active spectral band (MHz). The same build from Python,
through the class API:

```python
from ftmwpipeline import Pipeline

result = Pipeline.build("path/to/experiment/", trim=(26500, 40000), output="exp.ftmw")
pipe = Pipeline.open(result["pipeline_file"])
print(pipe.info())   # provenance, completed stages, next available stages
```

or driven stage by stage, with the same calls available on the functional API
(`import ftmwpipeline.api as ftmw`):

```python
pipe = Pipeline.create("exp.ftmw", source="path/to/experiment/")
pipe.compute_ft(trim=(26500, 40000))
pipe.estimate_noise()
pipe.calibrate_tau()
pipe.detect_peaks()
pipe.assign_windows()
pipe.fit_peaks()
```

At the command line each stage runs with the object-verb grammar
(`<stage> run` / `<stage> show`):

```bash
ftmwpipeline data import  exp.ftmw path/to/experiment/
ftmwpipeline ft run       exp.ftmw --trim 26500:40000
ftmwpipeline noise run    exp.ftmw
ftmwpipeline tau run      exp.ftmw
ftmwpipeline peaks run    exp.ftmw
ftmwpipeline windows run  exp.ftmw
ftmwpipeline fit run      exp.ftmw
ftmwpipeline report run   exp.ftmw --output-dir report
```

## Documentation

Full documentation — installation, a worked quickstart on bundled example data,
a guide to each pipeline stage, and the CLI/API reference — is at
[ftmwpipeline.readthedocs.io](https://ftmwpipeline.readthedocs.io/).

## License

MIT — see [LICENSE](LICENSE).
