adam_core.photometry.rotation.core module

class adam_core.photometry.rotation.core.RotationPeriodObservations(table: Table, **kwargs: int | float | str)[source]

Bases: Table

time

A column which represents an embedded quivr table.

Parameters:

  • table_type – The type of the table to embed.

  • nullable – Whether the column can contain null values.

  • metadata – A dictionary of metadata to attach to the column.

mag

A column for storing 64-bit floating point numbers.

mag_sigma

A column for storing 64-bit floating point numbers.

filter

A column for storing large strings (over 231 bytes long). Large string data is stored in variable-length chunks.

session_id

A column for storing large strings (over 231 bytes long). Large string data is stored in variable-length chunks.

r_au

A column for storing 64-bit floating point numbers.

delta_au

A column for storing 64-bit floating point numbers.

phase_angle_deg

A column for storing 64-bit floating point numbers.

classmethod from_point_source_observations(detections: PointSourceDetections, exposures: Exposures, object_coords: CartesianCoordinates) → RotationPeriodObservations[source]

Build observations from adam_core point-source detections + exposures.

Links this table to the core adam_core observation primitives: one row per PointSourceDetections entry, with filter and the per-exposure observing geometry (heliocentric distance r_au, observer distance delta_au, and solar phase_angle_deg) derived from the aligned Exposures and the object’s heliocentric CartesianCoordinates.

object_coords must be heliocentric (origin=SUN) and the same length and order as detections; detections.exposure_id is used to align each detection to its exposure. mag / r_au / delta_au / phase_angle_deg must be finite (and the distances positive) or a ValueError is raised.

schema: ClassVar[pa.Schema] = time: struct<days: int64, nanos: int64>   child 0, days: int64   child 1, nanos: int64 mag: double not null mag_sigma: double filter: large_string session_id: large_string r_au: double not null delta_au: double not null phase_angle_deg: double not null
table: pa.Table
class adam_core.photometry.rotation.core.RotationPeriodResult(table: Table, **kwargs: int | float | str)[source]

Bases: Table

period_days

A column for storing 64-bit floating point numbers.

period_hours

A column for storing 64-bit floating point numbers.

frequency_cycles_per_day

A column for storing 64-bit floating point numbers.

profile

A column for storing large strings (over 231 bytes long). Large string data is stored in variable-length chunks.

period_verdict

A column for storing large strings (over 231 bytes long). Large string data is stored in variable-length chunks.

reliability_code

A column for storing large strings (over 231 bytes long). Large string data is stored in variable-length chunks.

confidence_flags

A column for storing large lists of values (over 231 objects).

Unless you need to represent data with more than 2**31 elements, prefer ListColumn.

The values in the list can be of any type.

Note that all quivr Tables are storing lists of values, so this column type is only useful for storing lists of lists.

Parameters:

  • value_type – The type of the values in the list.

  • nullable – Whether the list can contain null values.

  • metadata – A dictionary of metadata to attach to the column.

  • validator – A validator to run against the column’s values.

insufficiency_reasons

A column for storing large lists of values (over 231 objects).

Unless you need to represent data with more than 2**31 elements, prefer ListColumn.

The values in the list can be of any type.

Note that all quivr Tables are storing lists of values, so this column type is only useful for storing lists of lists.

Parameters:

  • value_type – The type of the values in the list.

  • nullable – Whether the list can contain null values.

  • metadata – A dictionary of metadata to attach to the column.

  • validator – A validator to run against the column’s values.

is_valid

A column for storing booleans.

is_reliable

A column for storing booleans.

period_lower_days

A column for storing 64-bit floating point numbers.

period_upper_days

A column for storing 64-bit floating point numbers.

relative_period_uncertainty

A column for storing 64-bit floating point numbers.

alternate_period_days

A column for storing large lists of values (over 231 objects).

Unless you need to represent data with more than 2**31 elements, prefer ListColumn.

The values in the list can be of any type.

Note that all quivr Tables are storing lists of values, so this column type is only useful for storing lists of lists.

Parameters:

  • value_type – The type of the values in the list.

  • nullable – Whether the list can contain null values.

  • metadata – A dictionary of metadata to attach to the column.

  • validator – A validator to run against the column’s values.

fourier_period_days

A column for storing 64-bit floating point numbers.

fourier_order

A column for storing 64-bit integers.

fourier_sigma_threshold

A column for storing 64-bit floating point numbers.

fourier_phase_c1

A column for storing 64-bit floating point numbers.

fourier_phase_c2

A column for storing 64-bit floating point numbers.

residual_sigma_mag

A column for storing 64-bit floating point numbers.

fourier_is_valid

A column for storing booleans.

fourier_is_reliable

A column for storing booleans.

fourier_alternate_period_days

A column for storing large lists of values (over 231 objects).

Unless you need to represent data with more than 2**31 elements, prefer ListColumn.

The values in the list can be of any type.

Note that all quivr Tables are storing lists of values, so this column type is only useful for storing lists of lists.

Parameters:

  • value_type – The type of the values in the list.

  • nullable – Whether the list can contain null values.

  • metadata – A dictionary of metadata to attach to the column.

  • validator – A validator to run against the column’s values.

phase_coverage_fraction

A column for storing 64-bit floating point numbers.

n_rotations_spanned

A column for storing 64-bit floating point numbers.

amplitude_snr

A column for storing 64-bit floating point numbers.

n_significant_aliases

A column for storing 64-bit integers.

n_observations

A column for storing 64-bit integers.

n_fit_observations

A column for storing 64-bit integers.

n_clipped

A column for storing 64-bit integers.

n_filters

A column for storing 64-bit integers.

n_sessions

A column for storing 64-bit integers.

used_session_offsets

A column for storing booleans.

is_period_doubled

A column for storing booleans.

classmethod single_insufficient(*, reasons: list[str], confidence_flags: list[str] | None = None, n_observations: int = 0, n_filters: int = 0, n_sessions: int = 0, profile: str = 'default') → RotationPeriodResult[source]

One-row insufficient_data result: NaN period, every nullable diagnostic None.

The canonical builder for the insufficient verdict. Used both by the solver’s early-exit path and by the detection wrappers when an object cannot be solved, so a grouped solve returns one row per object id rather than silently dropping failures. period_verdict/reliability_code are the contract constants ("insufficient_data" / "1").

schema: ClassVar[pa.Schema] = period_days: double not null period_hours: double not null frequency_cycles_per_day: double not null profile: large_string not null period_verdict: large_string not null reliability_code: large_string not null confidence_flags: large_list<item: large_string>   child 0, item: large_string insufficiency_reasons: large_list<item: large_string>   child 0, item: large_string is_valid: bool not null is_reliable: bool not null period_lower_days: double period_upper_days: double relative_period_uncertainty: double alternate_period_days: large_list<item: double>   child 0, item: double fourier_period_days: double fourier_order: int64 fourier_sigma_threshold: double fourier_phase_c1: double fourier_phase_c2: double residual_sigma_mag: double fourier_is_valid: bool fourier_is_reliable: bool fourier_alternate_period_days: large_list<item: double>   child 0, item: double phase_coverage_fraction: double n_rotations_spanned: double amplitude_snr: double n_significant_aliases: int64 n_observations: int64 not null n_fit_observations: int64 not null n_clipped: int64 not null n_filters: int64 not null n_sessions: int64 not null used_session_offsets: bool not null is_period_doubled: bool not null
table: pa.Table
class adam_core.photometry.rotation.core.GroupedRotationPeriodResults(table: Table, **kwargs: int | float | str)[source]

Bases: Table

object_id

A column for storing large strings (over 231 bytes long). Large string data is stored in variable-length chunks.

result

A column which represents an embedded quivr table.

Parameters:

  • table_type – The type of the table to embed.

  • nullable – Whether the column can contain null values.

  • metadata – A dictionary of metadata to attach to the column.

schema: ClassVar[pa.Schema] = object_id: large_string not null result: struct<period_days: double, period_hours: double, frequency_cycles_per_day: double, profile: large_s (... 893 chars omitted)   child 0, period_days: double   child 1, period_hours: double   child 2, frequency_cycles_per_day: double   child 3, profile: large_string   child 4, period_verdict: large_string   child 5, reliability_code: large_string   child 6, confidence_flags: large_list<item: large_string>       child 0, item: large_string   child 7, insufficiency_reasons: large_list<item: large_string>       child 0, item: large_string   child 8, is_valid: bool   child 9, is_reliable: bool   child 10, period_lower_days: double   child 11, period_upper_days: double   child 12, relative_period_uncertainty: double   child 13, alternate_period_days: large_list<item: double>       child 0, item: double   child 14, fourier_period_days: double   child 15, fourier_order: int64   child 16, fourier_sigma_threshold: double   child 17, fourier_phase_c1: double   child 18, fourier_phase_c2: double   child 19, residual_sigma_mag: double   child 20, fourier_is_valid: bool   child 21, fourier_is_reliable: bool   child 22, fourier_alternate_period_days: large_list<item: double>       child 0, item: double   child 23, phase_coverage_fraction: double   child 24, n_rotations_spanned: double   child 25, amplitude_snr: double   child 26, n_significant_aliases: int64   child 27, n_observations: int64   child 28, n_fit_observations: int64   child 29, n_clipped: int64   child 30, n_filters: int64   child 31, n_sessions: int64   child 32, used_session_offsets: bool   child 33, is_period_doubled: bool
table: pa.Table
adam_core.photometry.rotation.core.HARMONIC_FACTORS: list[float] = [0.25, 0.3333333333333333, 0.5, 0.6666666666666666, 0.75, 1.0, 1.3333333333333333, 1.5, 2.0, 3.0, 4.0]

Harmonic factors applied to the recovered period when diagnosing aliases.

adam_core.photometry.rotation.core.relative_error_pct(p_rec: float, p_true: float) → float[source]

Strict relative error of a recovered period, in percent.

Parameters:

  • p_rec (float) – Recovered period (hours).

  • p_true (float) – True (LCDB) period (hours); must be positive.

Returns:

100 * |p_rec - p_true| / p_true.

Return type:

float

adam_core.photometry.rotation.core.harmonic_adjusted_error_pct(p_rec: float, p_true: float) → tuple[float, float][source]

Harmonic-tolerant relative error and the best-fitting harmonic factor.

Minimises |p_rec * f - p_true| / p_true over HARMONIC_FACTORS.

Parameters:

  • p_rec (float) – Recovered period (hours).

  • p_true (float) – True (LCDB) period (hours); must be positive.

Returns:

The minimum harmonic-adjusted error in percent, and the factor f that achieves it.

Return type:

tuple of (float, float)

adam_core.photometry.rotation.core.alias_bucket(best_factor: float) → str[source]

Label the harmonic-alias bucket for the best-fitting factor.

Parameters:

best_factor (float) – The harmonic factor returned by harmonic_adjusted_error_pct().

Returns:

One of "1x", "1/4x", "1/3x", "1/2x", "2/3x", "3/4x", "4/3x", "3/2x", "2x", "3x", "4x", or "other" if no factor is within 5% of best_factor.

Return type:

str

adam_core.photometry.rotation.core.within_tolerance(p_rec: float, p_true: float, tolerance_fraction: float) → bool[source]

Whether the raw relative error is within the fixture’s tolerance.

Uses the strict relative_error_pct() (no harmonic adjustment) compared against the per-fixture tolerance_fraction from the npz.

Parameters:

  • p_rec (float) – Recovered period (hours).

  • p_true (float) – True (LCDB) period (hours); must be positive.

  • tolerance_fraction (float) – Allowed fractional error (e.g. 0.01 for a tight U=3 fixture).

Returns:

True if relative_error_pct(p_rec, p_true) <= tolerance_fraction * 100.

Return type:

bool

adam_core.photometry.rotation.core.near_day_alias(p_rec_hours: float, p_true_hours: float, tolerance_fraction: float = 0.02) → bool[source]

Whether the recovered frequency is a diurnal-cadence alias of the truth.

Flags lock-on to a day-aliased frequency (cycles per day): the recovered frequency sits within tolerance_fraction of f_true +/- n for n in {1, 2} cycles/day, i.e. |f_rec - (f_true +/- n)| / f_true <= tol.

Parameters:

  • p_rec_hours (float) – Recovered period (hours); must be positive.

  • p_true_hours (float) – True (LCDB) period (hours); must be positive.

  • tolerance_fraction (float, optional) – Fractional tolerance on the day-aliased frequency match (default 0.02).

Returns:

True if a day-alias relationship holds.

Return type:

bool