adam_core.photometry.rotation.wrappers module

adam_core.photometry.rotation.wrappers.build_rotation_period_observations_from_detections(detections: PointSourceDetections, exposures: Exposures, object_coords: CartesianCoordinates) → RotationPeriodObservations

adam_core.photometry.rotation.wrappers.estimate_rotation_period_best_apparition(observations: RotationPeriodObservations, *, apparition_gap_days: float = 120.0, **solver_kwargs: Any) → RotationPeriodResult

Solve each apparition separately and keep the highest-confidence result.

Ground-based lightcurves of the same asteroid from different apparitions differ in viewing aspect (and therefore amplitude), photometric noise, and nightly cadence, so the diurnal-alias structure of each apparition differs too. An apparition that happens to sample the rotation cleanly can yield a confident, correct period where the densest apparition – or all apparitions pooled – locks onto a sampling alias or hedges. This helper partitions the observations into apparitions (separated by more than apparition_gap_days), runs estimate_rotation_period() on each independently, and returns the result of the most confident apparition.

The selection rule uses no knowledge of any reference answer: rank the verdicts single_period > period_family > insufficient_data, tie-break on higher amplitude_snr, then on more observations, then on the earlier apparition. Measured on the 118-object LCDB standard-candle calibration set, this policy raised confident (single_period) claims from 35 to 43 while the strict precision of those claims improved (0.800 -> 0.837) and the wrong-family count was unchanged – selection shopping did not introduce false confidence on that set, but the guarantee is empirical, not structural.

The chosen row is returned with a apparition_selected_<k>_of_<n> confidence flag appended (1-based, chronological). An apparition whose solve fails with an expected ValueError participates as an insufficient_data candidate flagged solve_error; an unexpected error is re-raised with the apparition attached. Apparitions solve serially; for large batches, parallelize per apparition yourself.

adam_core.photometry.rotation.wrappers.estimate_rotation_period_from_detections(detections: PointSourceDetections, exposures: Exposures, object_coords: CartesianCoordinates, **search_kwargs: Any) → RotationPeriodResult

adam_core.photometry.rotation.wrappers.estimate_rotation_period_from_detections_grouped(detections: PointSourceDetections, exposures: Exposures, object_coords: CartesianCoordinates, object_ids: Array | ChunkedArray | Sequence[str | None], **search_kwargs: Any) → GroupedRotationPeriodResults