Skip to content

Weights API

ADESWeightPolicy

Bases: UnitWeightPolicy

Use the uncertainties already reported in the observation records.

name property

Return a human-readable policy name.

source_name property

Return the source label attached to this policy.

weights(obs)

Copy the reported observation uncertainties into a weight bundle.

Parameters:

Name Type Description Default
obs ObservationData

Observation bundle whose stored uncertainties should be used directly.

 required

Returns:

Type Description
WeightResult

Weight bundle built from the modality-specific uncertainties already stored in obs.

InteractiveWeightPolicy(default_policy, additional_policies=None)

Bases: WeightPolicy

Compose a default unit policy with row-level manual and policy overrides.

The interactive policy starts from a default :class:UnitWeightPolicy result and then replaces selected rows by either manual sigmas or another registered policy. All override bookkeeping is keyed by the original mixed-input indices stored in the observation tables.

Initialize an interactive weighting controller.

Parameters:

Name Type Description Default
default_policy UnitWeightPolicy

Base policy applied to every row before interactive overrides are merged in.

 required
additional_policies list[UnitWeightPolicy]

Extra selectable policies available for row-level replacement.

 None

name property

Return a human-readable policy name.

get_all_policy_results(obs)

Evaluate every registered unit policy on one observation bundle.

Parameters:

Name Type Description Default
obs ObservationData

Observation bundle to evaluate.

 required

Returns:

Type Description
dict[WeightPolicy, WeightResult]

Mapping from registered policy object to its resolved uncertainty bundle.

select_scheme(input_indices, policy)

Assign a registered policy to specific input rows.

Parameters:

Name Type Description Default
input_indices int or iterable of int or array-like

Original mixed-input indices of the rows to override.

 required
policy UnitWeightPolicy

Registered policy whose uncertainties should replace the default result on those rows.

 required

Raises:

Type Description
ValueError

Raised when policy has not been registered in available_policies.

set_manual_optical(input_indices, ra_unc, dec_unc, correlation=0.0)

Set manual optical sigmas for specific input rows.

Parameters:

Name Type Description Default
input_indices int or iterable of int or array-like

Original mixed-input indices of the rows to override.

 required
ra_unc float

Right-ascension sigma in radians.

 required
dec_unc float

Declination sigma in radians.

 required
correlation float

Correlation coefficient for the two tangent-plane components.

 0.0

set_manual_radar(input_indices, unc)

Set manual radar sigmas for specific input rows.

Parameters:

Name Type Description Default
input_indices int or iterable of int or array-like

Original mixed-input indices of the rows to override.

 required
unc float

Radar sigma in the native unit of the stored radar measurement.

 required

restore_default_policy(input_indices=None)

Remove interactive overrides and fall back to the default policy.

Parameters:

Name Type Description Default
input_indices int or iterable of int or array-like

Original mixed-input indices to reset. When omitted, every stored override is cleared.

 None

weights(obs)

Merge the default policy with interactive row-level overrides.

Parameters:

Name Type Description Default
obs ObservationData

Observation bundle to weight.

 required

Returns:

Type Description
WeightResult

Weight bundle obtained from the default policy after manual overrides and selected policy substitutions have been applied row by row.
Notes

Manual overrides take precedence over selected alternate policies. If an alternate policy returns NaN for a row, the default-policy uncertainty is kept for that row.

UnitWeightPolicy

Bases: WeightPolicy

Base class for deterministic weighting policies with one named source.

name property

Return a human-readable policy name.

source_name abstractmethod property

Return the source label attached to uncertainties from this policy.

VFCC17WeightPolicy(filepath=DEFAULT_WEIGHT_SCHEME_FILENAME)

Bases: UnitWeightPolicy

Apply the Vereš-Farnocchia-Chesley-Chatelain 2017 optical weighting table.

The policy reads a CSV rule table and assigns one scalar optical sigma per matched observation row. The scalar sigma is then duplicated onto right ascension and declination. Radar rows are passed through unchanged from the input observation bundle.

Initialize the VFCC17 weighting policy from a CSV rule table.

Parameters:

Name Type Description Default
filepath str

Path to the weighting-rule CSV file. The file is read with "!" as the comment prefix.

 DEFAULT_WEIGHT_SCHEME_FILENAME

name property

Return a human-readable policy name.

source_name property

Return the source label attached to this policy.

uncertainties(obs)

Resolve VFCC17 optical sigmas for one observation bundle.

Parameters:

Name Type Description Default
obs ObservationData

Observation bundle whose optical rows should be matched against the loaded weighting rules.

 required

Returns:

Type Description
Float[ndarray, 'N_optical 2']

Optical sigmas in radians, stored as (sigma_ra, sigma_dec) with one row per optical observation.
Notes

The rule table stores one optical sigma value in arcseconds per matched row. This method converts that scalar to radians and applies it identically to right ascension and declination.

The over-observation scaling follows the N/4 rule from Vereš et al. (2017). Rows are counted per tracklet identifier within the unified optical table.

References
  1. Vereš, P., Farnocchia, D., Chesley, S. R., & Chamberlin, A. B. (2017). Statistical analysis of astrometric errors for the most productive asteroid surveys. Icarus, 296, 139-144.

time_uncertainties(obs)

Resolve VFCC17 optical time uncertainties in seconds.

Missing ordinary optical times receive the GRSS/VFCC17 default of 1.0 second. Gaia, occultation, and space-observer rows are left as NaN so downstream covariance inflation skips them.

weights(obs)

Build a full weight bundle from the VFCC17 optical sigmas.

Parameters:

Name Type Description Default
obs ObservationData

Observation bundle to weight.

 required

Returns:

Type Description
WeightResult

Weight bundle with VFCC17 optical uncertainties and reported radar uncertainties.

WeightPolicy

Bases: ABC

Abstract interface for mapping observations to weighting results.

weights(obs) abstractmethod

Build modality-specific uncertainties for one observation bundle.

Parameters:

Name Type Description Default
obs ObservationData

Single-target observation bundle containing optical and radar modality tables.

 required

Returns:

Type Description
WeightResult

Resolved uncertainties and derived source labels for the available observation rows.

WeightResult(optical_uncertainties, radar_uncertainties, optical_sources, radar_sources, optical_correlations, optical_time_uncertainties)

Resolved uncertainties, correlations, and derived weight matrices.

Initialize a weight-result bundle.

optical_weights property

Return the marginal optical inverse-variance weights.

optical_covariances property

Return per-row optical covariance blocks.

optical_weight_matrices property

Return per-row optical weight matrices.

radar_weights property

Return radar inverse-variance weights.

flat_weights property

Return the marginal inverse-variance view in optical-then-radar order.

optical_covariances_with_time(optical_rates)

Return optical covariance blocks inflated by time uncertainty.

Parameters:

Name Type Description Default
optical_rates (ndarray, shape(N_optical, 2))

Tangent-plane angular rates in radians per day, ordered as (ra_dot_cos_dec, dec_dot). The rates must use the same angular units as optical_uncertainties.

 required

Returns:

Type Description
(ndarray, shape(N_optical, 2, 2))

Optical covariance matrices after adding rate rate^T * (sigma_time / 86400)^2 for finite, non-zero time uncertainties.

with_optical_time_rates(optical_rates)

Return a weight result whose optical covariances include time uncertainty.

Parameters:

Name Type Description Default
optical_rates (ndarray, shape(N_optical, 2))

Tangent-plane angular rates in radians per day, ordered as (ra_dot_cos_dec, dec_dot).

 required

Returns:

Type Description
WeightResult

New bundle with effective optical sigmas and correlations derived from the time-inflated covariance matrices. The returned optical_time_uncertainties are zeroed because their contribution has already been folded into the covariance.

optical_weight_matrices_with_time(optical_rates)

Return optical inverse-covariance blocks inflated by time uncertainty.

WeightRule(obs_type, obs_mode, observer_type, obs_note_code, site_code, program_code, catalog_code, sub_frame, date_min, date_max, sigma, comment)

Single rule row in a tabular astrometric weighting scheme.

The rule stores categorical selectors and optional time bounds for one uncertainty assignment. String fields use "*" as a wildcard and "|" as an OR separator for multi-valued selectors.

Initialize a weighting-rule row.

Parameters:

Name Type Description Default
obs_type str

Observation-type selector keyed by :class:difforb.astrometry.data.ObsType, or "*" for all types.

 required
obs_mode str

Observation-mode selector keyed by :class:difforb.astrometry.data.ObsMode. Multiple values may be joined with "|".

 required
observer_type str

Observer-type selector keyed by :class:difforb.astrometry.data.ObserverType. Multiple values may be joined with "|".

 required
obs_note_code str

Required substring in the optical note-code field, or "*" for no filter.

 required
site_code str

Required receiver or site code, or "*" for no filter.

 required
program_code str

Allowed ADES prog codes. Multiple two-character values may be joined with "|".

 required
catalog_code str

Allowed catalog codes. Multiple values may be joined with "|".

 required
sub_frame str

ADES subFrm selector for the originally submitted angular frame. Multiple values may be joined with "|".

 required
date_min Time or None

Inclusive lower time bound in UTC for rule validity.

 required
date_max Time or None

Exclusive upper time bound in UTC for rule validity.

 required
sigma float

Scalar one-axis optical uncertainty in arcseconds before conversion to radians by the policy.

 required
comment str

Human-readable rule annotation carried from the source table.

 required

match_mask(obs)

Return the rows matched by this rule.

Parameters:

Name Type Description Default
obs OpticalObservationData

Optical observation table to test. Matching uses observation type, observation mode, observer type, note code, receiver code, program code, catalog code, submitted frame, and optional time bounds.

 required

Returns:

Type Description
Bool[ndarray, N]

Boolean mask with one entry per input row. True marks rows that satisfy every active selector in the rule.
Notes

Time comparisons are performed against the observation epochs stored in obs.t. date_min is inclusive and date_max is exclusive.