Metadata-Version: 2.5
Name: ost_photometry
Version: 0.6.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: pillow>=10.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: regions>=0.11
Requires-Dist: reproject<0.22,>=0.19
Requires-Dist: requests>=2.31
Requires-Dist: scikit-image>=0.25
Requires-Dist: scikit-learn>=1.6
Requires-Dist: scipy>=1.15
Requires-Dist: tifffile>=2023.1
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.
Frame quality (FWHM, roundness, star count, sky) is measured per frame; frames
can be rejected by threshold or "best X %" (`frame_selection`), the sharpest
frame is the alignment reference, and stacks can be FWHM-, star-count- or
noise-weighted (`stack_weighting`). The archive pipeline (`ost_photometry.archive`,
`reduce.grouping`) fetches an object or observation run from the OST data
archive, groups calibration frames by mount session (camera orientation from
plate solving) with flat probabilities, reduces per group and stacks every
target (see [docs/ARCHIVE_PIPELINE.md](docs/ARCHIVE_PIPELINE.md)) . Colour images
(RGB, LRGB, SHO, HOO, custom mixes) from the stacks: `ost_photometry.imaging`
(see [docs/COLOR_COMPOSITE.md](docs/COLOR_COMPOSITE.md)).

**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)                               |
| Colour images from the stacks                   | [docs/COLOR_COMPOSITE.md](docs/COLOR_COMPOSITE.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).
