Metadata-Version: 2.5
Name: ost_photometry
Version: 0.5.0
Summary: Photometry reduction and analysis package for the OST observatory
Project-URL: Homepage, https://github.com/OST-Observatory/ost_photometry_package
Project-URL: Bug Tracker, https://github.com/OST-Observatory/ost_photometry_package/issues
Author-email: Rainer Hainich <rhainich@astro.physik.uni-potsdam.de>, OST Observatory <rhainich@astro.physik.uni-potsdam.de>
License-File: LICENSE
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <4,>=3.11
Requires-Dist: astroalign>=2.6
Requires-Dist: astropy<8,>=7.2
Requires-Dist: astroquery>=0.4.11
Requires-Dist: bottleneck>=1.6
Requires-Dist: ccdproc>=2.5
Requires-Dist: matplotlib>=3.10
Requires-Dist: numpy<3,>=2.2
Requires-Dist: pandas>=2.2
Requires-Dist: path>=17.1
Requires-Dist: photutils>=3.0.0
Requires-Dist: regions>=0.11
Requires-Dist: reproject<0.22,>=0.19
Requires-Dist: scikit-image>=0.25
Requires-Dist: scikit-learn>=1.6
Requires-Dist: scipy>=1.15
Requires-Dist: tqdm>=4.67
Requires-Dist: twirl>=0.5
Provides-Extra: dev
Requires-Dist: mypy>=1.18; extra == 'dev'
Requires-Dist: pre-commit>=4.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.16; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# OST Photometry Package

Photometry reduction and analysis package for the
[OST Observatory](https://polaris.astro.physik.uni-potsdam.de/) of
the University of Potsdam.

The package provides data reduction and analysis for photometric observations
from the observatory's telescopes. It is used in astrophysics laboratory courses
and for on-the-fly reduction in the observatory archive, but the APIs are
intended for general differential photometry workflows as well.

## Package structure

The installable package lives under `src/ost_photometry/` and splits into two
main layers:

| Module | Role |
|--------|------|
| **`ost_photometry.reduce`** | CCD preprocessing: bias/dark/flat correction, registration, masking, instrument helpers |
| **`ost_photometry.analyze`** | Science analysis: WCS, extraction, correlation, calibration, post-processing, light curves |

Supporting code includes `terminal_output` and `style` (console output),
`checks`, `calibration_parameters` (catalogs, filters, chips, extinction curves),
and `core` (shared utilities such as parallel execution).

Typical workflow: reduce raw FITS with **`reduce`**, then run **`analyze`** on
the calibrated image series via an `Observation` object and `run_pipeline()`.

## Capabilities

**Reduction (`reduce`)** — CCD stack building, image alignment, cosmic-ray
handling, and WCS helpers. Default alignment is star-triangle (`shift_method="aa_true"`);
`shift_method="wcs"` reprojects onto the reference celestial WCS (large dithers /
sparse fields). Camera gain, read noise, and dark current are interpolated from
the bundled `data/cameras.json` catalog. Worker pools default to half the CPUs.

**Analysis pipeline (`analyze.pipeline`)** — configurable step sequence driven by
[`PipelineConfig`](src/ost_photometry/analyze/pipeline/config.py):

1. WCS determination (`astrometry`, `astap`, `twirl`)
2. PSF or aperture photometry extraction
3. Intra- and inter-filter source correlation
4. Optional extinction coefficient fit
5. Differential calibration (median ZP or linear T/ZP; epoch-native tables)
6. Post-processing (region selection, cluster/Gaia matching, magnitude conversion)
7. Optional light-curve plots and HiPS reference subtraction

**Calibration** — catalog cross-match (APASS, VizieR, custom tables), extinction
correction, `PhotometryCalibrator` / `CalibrationEngine`, and named presets
(`linear_fit_per_image`, `linear_fit_per_night`, …).

**Libraries usable outside the pipeline** — `main_extract`, `PhotometryCalibrator`,
`ExtinctionCorrector`, correlation helpers, plotting, image subtraction, and
calibration-source fetch/crossmatch APIs.

Entry point for scripted runs:

```python
from ost_photometry.analyze import Observation, PipelineConfig

observation = Observation.from_config(...)
config = PipelineConfig.from_preset("linear_fit_per_night")
observation.run_pipeline(filter_list, image_paths=..., output_dir=..., config=config)
```

## Requirements

Core Python dependencies:

* [ccdproc](https://github.com/astropy/ccdproc)
* [photutils](https://github.com/astropy/photutils)
* [astropy](https://github.com/astropy/astropy)
* [astroquery](https://github.com/astropy/astroquery)
* [numpy](https://github.com/numpy/numpy)
* [scipy](https://github.com/scipy/scipy)
* [matplotlib](https://github.com/matplotlib/matplotlib)

For the default WCS method (`astap`), the
[ASTAP](https://www.hnsky.org/astap.htm) binary must be on `PATH`.
The alternative `astrometry` method needs a local
[astrometry.net](https://nova.astrometry.net/) installation.

## Documentation

| Topic | Document |
|-------|----------|
| Pipeline options and decision tables | [docs/PIPELINE_CONFIG.md](docs/PIPELINE_CONFIG.md) |
| Diagnostic plot layout | [docs/DIAGNOSTICS.md](docs/DIAGNOSTICS.md) |
| Site extinction table and observation campaigns | [docs/EXTINCTION_COEFFICIENTS.md](docs/EXTINCTION_COEFFICIENTS.md) |
| Breaking changes and architecture (archive) | [docs/ARCHITECTURE_AND_MIGRATION.md](docs/ARCHITECTURE_AND_MIGRATION.md) |
| Script compatibility matrix | [docs/COMPATIBILITY_REPORT.md](docs/COMPATIBILITY_REPORT.md) |
| Changelog | [CHANGELOG.md](CHANGELOG.md) |
| How `main` is tagged / GitHub Releases | [docs/RELEASING.md](docs/RELEASING.md) |
| Known follow-ups | [docs/TODO.md](docs/TODO.md) |

Config defaults and all pipeline fields:
[`src/ost_photometry/analyze/pipeline/config.py`](src/ost_photometry/analyze/pipeline/config.py).

## Development

Install the package with lint/test tools, then enable the git hook so
[Ruff](https://docs.astral.sh/ruff/) runs (and auto-fixes) before each commit —
the same check as CI (`ruff check src tests`):

```bash
python -m pip install -e ".[dev]"
pre-commit install
```

Run the linter on demand with `ruff check src tests` (add `--fix` to apply
safe fixes). Tests: `pytest tests -m "not slow"`. CI runs that suite on
Python 3.11, 3.12, and 3.13.

Releases are annotated tags `vX.Y.Z` on `main`; see
[docs/RELEASING.md](docs/RELEASING.md) and [CHANGELOG.md](CHANGELOG.md).
