Metadata-Version: 2.4
Name: toa_sp
Version: 0.2.0
Summary: Multi-strategy single-pulse TOA extraction from PSRFITS search-mode data
Author-email: Songbo Zhang <sbzhang@pmo.ac.cn>, Xuan Yang <yangxuan@pmo.ac.cn>
License: MIT
Project-URL: Homepage, https://github.com/songqiii/toa_sp
Project-URL: Repository, https://github.com/songqiii/toa_sp
Project-URL: Issues, https://github.com/songqiii/toa_sp/issues
Keywords: pulsar,timing,TOA,single-pulse,radio-astronomy,PSRFITS,FRB,RRAT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Requires-Dist: scipy>=1.7
Requires-Dist: astropy>=4.3
Requires-Dist: matplotlib>=3.5
Provides-Extra: mcmc
Requires-Dist: emcee>=3.0; extra == "mcmc"
Provides-Extra: corner
Requires-Dist: corner>=2.0; extra == "corner"
Provides-Extra: all
Requires-Dist: emcee>=3.0; extra == "all"
Requires-Dist: corner>=2.0; extra == "all"
Dynamic: license-file

# toa_sp — Multi-Strategy Single-Pulse TOA Extraction

[![Python](https://img.shields.io/badge/python-3.7%2B-blue)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.XXXXXXX-blue)](https://doi.org/10.5281/zenodo.XXXXXXX)

**toa_sp** extracts times of arrival (TOAs) directly from PSRFITS search-mode data, bypassing the folding step required by conventional pulsar timing pipelines. It implements nine complementary TOA estimation strategies — parametric (Gaussian, EMG, Voigt) and non-parametric (leading edge, centre of mass, peak, shapelet) — together with MCMC uncertainty estimation, automatic time-resolution optimisation, and sub-band cross-validation.

Designed for highly variable radio sources (RRATs, FRBs, mode-changing pulsars) where the integrated profile assumption breaks down.

## Installation

```bash
pip install toa_sp
```

For MCMC support (optional):

```bash
pip install toa_sp[all]
```

## Quick Start

```bash
toa_sp -f FRB20220529_tracking-M01_0158.fits \
    -dm 255.0 -s 1.1 -w 0.06 -bs 8 -bf 16 \
    --auto_res --compare --tim --tim_strategy best \
    -o timing_result
```

Or run as a script:

```bash
python toa_sp.py -f data.fits -dm 175.25 -s 2.5 -w 0.05 -bs 4 -bf 16
```

## TOA Strategies

| Strategy | Type | Description |
|---|---|---|
| `single` | Parametric | Single-component fit; TOA = μ₁ |
| `highest` | Parametric | Brightest fitted component |
| `error_weighted` | Parametric | Inverse-variance weighted average |
| `first_peak` | Parametric | Earliest significant (S/N > 5) component |
| `weighted` | Parametric | Amplitude-weighted average *(deprecated)* |
| `leading_edge` | Non-parametric | Half-max crossing + rise-time correction |
| `center_of_mass` | Non-parametric | Flux-weighted centroid (S > 3σ_off) |
| `peak` | Non-parametric | Profile maximum, quadratic sub-bin interpolation |
| `shapelet` | Non-parametric | Hermite–Gaussian decomposition, AICc order selection |

## Profile Models

- **Gaussian** (default) — symmetric, N-component
- **EMG** — exponentially modified Gaussian for scattering tails
- **Voigt** — combined Gaussian + Lorentzian broadening
- **Shapelet** — flexible basis expansion, automatically regularised

## Key Features

- **Auto resolution optimisation** (`--auto_res`) — maximises peak S/N via dyadic rebinning
- **Sub-band cross-validation** (`--sub_band_fit`) — tests TOA consistency across frequency
- **AICc model selection** (`--auto_n`) — data-driven choice of component number
- **MCMC uncertainty** (`--mcmc`) — robust posterior sampling via `emcee`
- **TEMPO2 output** (`--tim`) — writes `.tim` files for downstream timing analysis
- **Convergence diagnostic** — Δ_conv metric identifies unstable decompositions

## Requirements

- Python ≥ 3.7
- numpy, scipy, astropy, matplotlib
- Optional: emcee, corner

## License

MIT — see [LICENSE](LICENSE) for details.

## Repository Structure

```
toa_sp/
├── toa_sp.py          # Main pipeline
├── pyproject.toml      # Package metadata
├── tools/
│   ├── plot_pipeline.py       # Pipeline schematic
│   └── plot_rrat_residuals.py # Residual plot generation
└── README.md
```
