adam_core.photometry.rotation.estimator module

adam_core.photometry.rotation.estimator.estimate_rotation_period(observations: RotationPeriodObservations, *, profile: str = 'default', search_fidelity: str | None = None, fourier_orders: tuple[int, ...] | None = None, clip_sigma: float = 3.0, min_rotations_in_span: float = 2.0, max_frequency_cycles_per_day: float = 1000.0, frequency_grid_scale: float = 30.0, max_search_period_hours: float | None = None, early_exit_on_insufficient: bool = True, exact_evaluation_backend: str = 'numpy', session_mode: str = 'auto', auto_session_min_observations_per_group: int = 6, auto_session_bic_improvement: float = 10.0) → RotationPeriodResult[source]

Estimate an asteroid rotation period with a measured confidence verdict.

Fits the distance-reduced, light-time-corrected photometry with a truncated-harmonic Fourier model, searches a frequency grid, clusters harmonic aliases, and classifies the outcome against the confidence contract rather than emitting a bare point estimate.

Parameters:

  • observations (RotationPeriodObservations) – One row per photometric measurement: time, magnitude, optional uncertainty, filter, optional session id, and observing geometry (r_au / delta_au / phase_angle_deg).

  • profile (str, default "default") – Solver configuration profile (Fourier orders, F-test/cluster confidences, reliability window). Only "default" is shipped.

  • search_fidelity ({"validated_staged", "exact_grid"}, optional) – Frequency-search strategy; defaults to "validated_staged" (coarse pass refined with exact evaluations). "exact_grid" evaluates every grid frequency.

  • session_mode ({"ignore", "use", "auto"}, default "auto") – Per-session magnitude-offset handling. "auto" adopts offsets only when a BIC test clears auto_session_bic_improvement.

  • exact_evaluation_backend ({"numpy", "jax"}, default "numpy") – Backend for exact frequency fits; "jax" is faster on large grids and gives identical results (imported lazily, so "numpy" needs no JAX).

  • early_exit_on_insufficient (bool, default True) – When True (default), screen obviously under-determined inputs before building the grid and return a structured insufficient_data result instead of raising. Set False (validation/calibration) to force every object through the full solve so a recovered period is always reported.

  • min_rotations_in_span (float) – Frequency-grid and fit knobs: lower frequency bound (rotations spanned), upper bound, grid oversampling, optional period ceiling, and the sigma-clipping threshold.

  • max_frequency_cycles_per_day (float) – Frequency-grid and fit knobs: lower frequency bound (rotations spanned), upper bound, grid oversampling, optional period ceiling, and the sigma-clipping threshold.

  • frequency_grid_scale (float) – Frequency-grid and fit knobs: lower frequency bound (rotations spanned), upper bound, grid oversampling, optional period ceiling, and the sigma-clipping threshold.

  • max_search_period_hours (float) – Frequency-grid and fit knobs: lower frequency bound (rotations spanned), upper bound, grid oversampling, optional period ceiling, and the sigma-clipping threshold.

  • clip_sigma (float) – Frequency-grid and fit knobs: lower frequency bound (rotations spanned), upper bound, grid oversampling, optional period ceiling, and the sigma-clipping threshold.

Returns:

A one-row table. Headline fields: period_verdict (single_period / period_family / insufficient_data), reliability_code ("3" / "2" / "1", mapping to the LCDB U code), confidence_flags and insufficiency_reasons – plus the recovered period_hours / period_days, the Fourier diagnostic block, and the verdict diagnostics.

Return type:

RotationPeriodResult

Raises:

ValueError – If session_mode / exact_evaluation_backend is invalid or a numeric knob is non-positive.

Notes

The confidence verdict is measured, not guaranteed. The solver is designed to downgrade harmonic and sampling aliases to period_family instead of asserting a confident single_period, but this is calibrated behaviour with a known, nonzero residual false-confidence risk: a single_period result can occasionally be a harmonic or sampling alias of the true period. Measured strict single_period precision on the LCDB/DAMIT standard-candle set is ~0.88, and one tracked case (1627 Ivar, a ~5/3 diurnal-sampling alias) is still reported confidently at the wrong period. When a period that is wrong by an integer factor would be costly, cross-check a single_period result against alternate_period_days and reliability_code rather than treating the verdict as infallible.