PhoPS

Photometric Pipeline for Surveys

PhoPS is a Python package for point-source photometry and astrometry on FITS images. The repository is now structured as an installable package with a shared service layer, a CLI, and a desktop UI adapter layer that can support a future Qt frontend.

• Astrometric solving through astrometry.net
• Gaia-based reference patch creation
• Field-star photometric calibration
• Target photometry for asteroid or fixed-star mode
• Optional automatic RANSAC threshold selection and bootstrap zero-point uncertainty
• CSV outputs and diagnostic plots
• Publication-style scientific light-curve plots from photometry.csv
• Shared core usable from terminal or desktop UI

PhoPS depends on Python packages and a few system tools:

• Python 3.10+
• solve-field
• hpsplit
• build-astrometry-index
• Internet access for Gaia and ephemeris queries during runtime

Those three binaries come from astrometry.net and must be available on PATH.

python -m pip install -e .

For development:

python -m pip install -e ".[dev]"

Create a config file:

phops init-config config.yaml

Validate it:

phops validate-config -c config.yaml

Run the full pipeline:

phops run -c config.yaml

If PhoPS detects an earlier interrupted or completed run in the same output folder, it asks whether you want to resume, restart, or cancel. By default, the terminal runner first shows a compact run summary with the key input and output paths, then starts a two-layer live progress view with the current frame, stage, percentage, running counts, current action, and last warning. Use -v if you want plain detailed logs instead.

Regenerate the photometry light-curve plot from an existing CSV:

phops plot-photometry -c config.yaml

Launch the current desktop runner:

phops gui -c config.yaml

• Put your FITS files into the folder defined by paths.input_dir.
• Set photometry.mode to asteroid or star.
• In asteroid mode, set photometry.target_id.
• In asteroid mode, set photometry.ephemeris_provider to jpl or miriade; the default is jpl.
• In star mode, set photometry.coords and declare photometry.coords_unit.
• photometry.coords_unit: deg means both values are degrees.
• photometry.coords_unit: hourangle_deg means RA is hour angle and Dec is degrees.
• Use astrometry.solve_mode: existing_wcs only when the FITS files already contain a full celestial WCS.
• For occultation datasets, photometry.mode: star is usually the correct choice because exposure time is set for the target star and the asteroid is often too faint for reliable frame-by-frame photometry.
• Outputs are written under paths.solve_dir, with plots and cutouts in subdirectories.
• Resume mode keeps a small checkpoint file inside paths.solve_dir so already measured frames can be skipped cleanly after an interruption.

PhoPS can use either a fixed RANSAC threshold or an automatic threshold for the radial zero-point model. In automatic mode, the threshold is selected once from the first valid image by finding the knee of the monotonised inlier-count curve, then reused for the rest of the sequence. After the final RANSAC fit for each image, PhoPS bootstraps the final inlier reference-star sample to estimate the zero-point uncertainty at each measured source radius.

The target and optional reference-star tables report the total photometric uncertainty in mag_err:

mag_err = sqrt(sigma_formal^2 + sigma_ZP_boot^2)

The formal aperture-photometry uncertainty is still computed internally, and snr is unchanged. The separate sigma_total column is not written to final photometry tables. zp_scatter is retained as a diagnostic quality metric for the zero-point fit and is not added directly to the formal uncertainty budget. When enabled, phops_analysis_summary.yaml records the input path, output path, runtime, threshold choice, inlier/outlier counts, zero-point fit diagnostics, bootstrap settings, and per-image uncertainty summaries.

• phops run -c config.yaml Runs the full astrometry + photometry pipeline.
• phops run -c config.yaml --resume Resumes from existing outputs without reprocessing frames already measured.
• phops run -c config.yaml --restart Clears the current run outputs and starts from scratch without prompting.
• phops validate-config -c config.yaml Parses and validates the YAML config without processing data.
• phops init-config path/to/config.yaml Writes a ready-to-edit example config.
• phops gui -c config.yaml Opens the current reference desktop runner. The service layer is kept separate so this can be replaced by a Qt frontend later.
• phops plot-photometry -c config.yaml Renders light_curve.png and, if enabled, light_curve.pdf from the current photometry table.

src/phops/           installable package
tests/               automated tests
docs/                project documentation
examples/            example config
config.yaml          editable local config

• photometry.csv: calibrated target photometry
• reference_star_timeseries.csv: optional calibrated reference-star time series
• phops_analysis_summary.yaml: optional calibration and uncertainty summary
• astrometry.csv: matched-source residuals
• output/plots/: zeropoint and astrometry plots
• output/plots/light_curve.png: calibrated light curve
• output/plots/light_curve.pdf: optional publication-ready vector export
• output/cutouts/: measured target cutouts
• output/.phops-run-state.json: hidden resume checkpoint used by the CLI

See docs/configuration.md, docs/outputs.md, and docs/architecture.md for details.

PhoPS is licensed under GNU GPL v3. See LICENSE.