Observation Data API¶

`ObsMode(id, ades_mode, desc)` ¶

Bases: Enum

Observation Mode Enumeration Value format: (Internal ID, ADES MODE, Description)

`ObsType(id, label)` ¶

Bases: Enum

`ObservationData(name, optical, radar)` ¶

Single-target observation bundle with optical and radar tables.

`has_optical` `property` ¶

Return True when the bundle contains optical observations.

`has_radar` `property` ¶

Return True when the bundle contains radar observations.

`is_mixed` `property` ¶

Return True when more than one modality table is present.

`num_optical` `property` ¶

Return the number of bundled optical observations.

`num_radar` `property` ¶

Return the number of bundled radar observations.

`num_observations` `property` ¶

Return the total number of bundled observations.

`t_start` `property` ¶

Return the earliest bundled observation epoch.

`t_end` `property` ¶

Return the latest bundled observation epoch.

`select_time_bound(bound)` ¶

Select the earliest or latest epoch in the bundle.

`to_dataframe(sort_by='input')` ¶

Convert the mixed observation bundle to a pandas dataframe.

`ObservationLayout(data)` ¶

Flat residual layout for optical and radar observations.

`concat_to_flat_array(optical_array, radar_array)` ¶

Concatenate optical and radar residual arrays into one flat array.

`split_flat_array(flat_array)` ¶

Split one flat residual-like array into optical and radar blocks.

`split_array(array)` ¶

Split one observation-aligned array into optical and radar blocks.

`flat_array_to_2d_array(flat_array)` ¶

Reshape a flat optical block into (N, 2).

`split_flat_array_to_array(flat_array)` ¶

Split a flat residual-like array into shaped optical and radar blocks.

`restore_flat_array(flat_array)` ¶

Restore a flat residual-like array to original input order.

`restore_array(array)` ¶

Restore an observation-aligned array to original input order.

`ObserverType(id, label)` ¶

Bases: Enum

`OpticalObservationData(t, trk_ids, obs_type_ids, obs_mode_ids, values, uncertainties, correlations, time_uncertainties, rx_codes, program_codes, catalog_codes, note_codes, magnitudes, band_codes, sub_frames, input_indices)` ¶

Single-target optical observation table.

Parameters:

Name	Type	Description	Default
`t`	`Time`	Observation epochs. The table is one-dimensional and `t` must have shape `(N,)`.	required
`mode_ids`	`Int[ndarray, 'N']`	Internal observation-mode identifiers. These should map to optical ground-observation modes in :class:`difforb.type.ObsMode`.	required
`values`	`Float[ndarray, 'N 2']`	Angular observations in radians, ordered as right ascension and declination.	required
`uncertainties`	`Float[ndarray, 'N 2']`	Adopted angular uncertainties aligned with `values`.	required
`correlations`	`Float[ndarray, 'N']`	Correlation coefficients for the two optical tangent-plane components.	required
`time_uncertainties`	`Float[ndarray, 'N']`	Observation-time uncertainties in seconds. Missing values are stored as `NaN`.	required
`rx_codes`	`array-like of str`	Receiver observer keys. Fixed ground keys are plain observatory codes. Roving ground keys use `"code @ lon_deg, lat_deg, alt_m"`. Space keys use `"code # x_au, y_au, z_au"`.	required
`note1_codes`	`array-like of str`	Raw `Note 1` or equivalent program-code field from the source observation record.	required
`note2_codes`	`array-like of str`	Raw `Note 2` or equivalent technology-code field from the source observation record.	required
`catalog_codes`	`array-like of str`	Astrometric catalog codes. Missing values are represented by empty strings.	required
`magnitudes`	`Float[ndarray, 'N']`	Reported apparent magnitudes. Missing values are represented by `NaN`.	required
`band_codes`	`array-like of str`	Reported magnitude-band codes. Missing values are represented by empty strings.	required
`sub_frames`	`array-like of str`	ADES `subFrm` values for the originally submitted angular frame. Missing values are represented by empty strings.	required
`input_indices`	`Int[ndarray, 'N']`	Positions of the rows in the original mixed input order. If omitted, the rows are assumed to already be in their original order.	required

`shape` `property` ¶

Return the table shape (N,).

`obs_modes` `property` ¶

Return the resolved optical observation modes.

`is_roving` `property` ¶

Mask roving-observer optical observations.

`sort_by_date(ascending=True)` ¶

Sort the optical table by epoch.

`to_dataframe()` ¶

Convert the optical table to a pandas dataframe.

Returns:

Type	Description
`DataFrame`	Row-wise tabular view of the optical observations. The dataframe keeps one row per observation and exposes the angular values, adopted uncertainties, observer keys, catalog codes, and original input-order indices.

Notes

This method is intended for inspection, export, and debugging. It does not participate in the numerical JAX pipelines.

`RadarObservationData(t, obs_type_ids, obs_mode_ids, values, uncertainties, rx_codes, tx_codes, tx_freq, input_indices)` ¶

Single-target radar observation table.

Parameters:

Name	Type	Description	Default
`t`	`Time`	Observation epochs with shape `(N,)`.	required
`mode_ids`	`Int[ndarray, 'N']`	Internal observation-mode identifiers. These should map to radar modes in :class:`difforb.type.ObsMode`.	required
`values`	`Float[ndarray, 'N']`	Radar measurements stored as a one-dimensional series. The physical meaning is determined by `mode_ids`, for example delay/range or Doppler/range-rate.	required
`uncertainties`	`Float[ndarray, 'N']`	Adopted measurement uncertainties aligned with `values`.	required
`rx_codes`	`array-like of str`	Receiver station codes.	required
`tx_codes`	`array-like of str`	Transmitter station codes.	required
`tx_freq`	`Float[ndarray, 'N']`	Full-length transmitter frequencies in `Hz`. Missing values are initialized to `NaN`.	required
`input_indices`	`Int[ndarray, 'N']`	Positions of the rows in the original mixed input order. If omitted, the rows are assumed to already be in their original order.	required

`shape` `property` ¶

Return the table shape (N,).

`obs_modes` `property` ¶

Return the resolved radar observation modes.

`is_delay` `property` ¶

Mask radar range or delay observations.

`is_doppler` `property` ¶

Mask radar Doppler or range-rate observations.

`sort_by_date(ascending=True)` ¶

Sort the radar table by epoch.

`to_dataframe()` ¶

Convert the radar table to a pandas dataframe.

Returns:

Type	Description
`DataFrame`	Row-wise tabular view of the radar observations. The dataframe keeps one row per observation and exposes the scalar measurement, adopted uncertainty, receiver and transmitter codes, transmitter frequency, and original input-order index.

Notes

This method is intended for inspection, export, and debugging. It does not participate in the numerical JAX pipelines.

`load_local_observations(filepath)` ¶

Load local ADES observations into one ObservationData bundle.

Parameters:

Name	Type	Description	Default
`filepath`	`str`	Path to a local ADES PSV file. The filename must use the `.psv` suffix.	required

Returns:

Type	Description
`ObservationData`	Parsed single-target observation bundle.

Raises:

Type	Description
`ValueError`	Raised when `filepath` does not use `.psv` or when the file does not contain usable ADES PSV rows.

Notes

The local carrier is ADES pipe-separated values (PSV). The returned ObservationData uses DiffOrb's internal units: optical angles in radians, radar delays in microseconds, and radar frequencies in Hz.

`load_online_observations(desig, save_path=None)` ¶

Load current MPC optical observations and JPL radar observations.

Parameters:

Name	Type	Description	Default
`desig`	`str`	Permanent designation, provisional designation, or object name accepted by the MPC Observations API. The same identifier is forwarded to the JPL radar API.	required
`save_path`	`str or None`	Destination path for one ADES PSV file. The filename must use the `.psv` suffix. If `None`, no local file is written.	`None`

Returns:

Type	Description
`ObservationData`	Parsed single-target observation bundle assembled from the current MPC optical feed and the JPL radar feed.

Raises:

Type	Description
`ValueError`	Raised when neither remote service returns any observation rows.
`HTTPError`	Raised when one of the remote services returns an unsuccessful status.

Notes

Optical observations are requested as ADES_DF rows from the MPC Observations API. Radar observations are requested from the JPL small-body radar API and converted into the shared ADES-compatible row schema before the final :class:ObservationData bundle is built.

If save_path is provided, the function writes the fetched observations to ADES PSV before converting the same rows to ObservationData. Radar delay rows fetched from JPL are converted from the JPL table units to ADES PSV units during the write step.

References

https://docs.minorplanetcenter.net/mpc-ops-docs/apis/get-obs/
https://ssd-api.jpl.nasa.gov/doc/sb_radar.html

Observation Data API¶

ObsMode(id, ades_mode, desc) ¶

ObsType(id, label) ¶

ObservationData(name, optical, radar) ¶

has_optical property ¶

has_radar property ¶

is_mixed property ¶

num_optical property ¶

num_radar property ¶

num_observations property ¶

t_start property ¶

t_end property ¶

select_time_bound(bound) ¶

to_dataframe(sort_by='input') ¶

ObservationLayout(data) ¶

concat_to_flat_array(optical_array, radar_array) ¶

split_flat_array(flat_array) ¶

split_array(array) ¶

flat_array_to_2d_array(flat_array) ¶

split_flat_array_to_array(flat_array) ¶

restore_flat_array(flat_array) ¶

restore_array(array) ¶

ObserverType(id, label) ¶

OpticalObservationData(t, trk_ids, obs_type_ids, obs_mode_ids, values, uncertainties, correlations, time_uncertainties, rx_codes, program_codes, catalog_codes, note_codes, magnitudes, band_codes, sub_frames, input_indices) ¶

shape property ¶

obs_modes property ¶

is_roving property ¶

sort_by_date(ascending=True) ¶

to_dataframe() ¶

RadarObservationData(t, obs_type_ids, obs_mode_ids, values, uncertainties, rx_codes, tx_codes, tx_freq, input_indices) ¶

shape property ¶

obs_modes property ¶

is_delay property ¶

is_doppler property ¶

sort_by_date(ascending=True) ¶

to_dataframe() ¶

load_local_observations(filepath) ¶

load_online_observations(desig, save_path=None) ¶

`ObsMode(id, ades_mode, desc)` ¶

`ObsType(id, label)` ¶

`ObservationData(name, optical, radar)` ¶

`has_optical` `property` ¶

`has_radar` `property` ¶

`is_mixed` `property` ¶

`num_optical` `property` ¶

`num_radar` `property` ¶

`num_observations` `property` ¶

`t_start` `property` ¶

`t_end` `property` ¶

`select_time_bound(bound)` ¶

`to_dataframe(sort_by='input')` ¶

`ObservationLayout(data)` ¶

`concat_to_flat_array(optical_array, radar_array)` ¶

`split_flat_array(flat_array)` ¶

`split_array(array)` ¶

`flat_array_to_2d_array(flat_array)` ¶

`split_flat_array_to_array(flat_array)` ¶

`restore_flat_array(flat_array)` ¶

`restore_array(array)` ¶

`ObserverType(id, label)` ¶

`OpticalObservationData(t, trk_ids, obs_type_ids, obs_mode_ids, values, uncertainties, correlations, time_uncertainties, rx_codes, program_codes, catalog_codes, note_codes, magnitudes, band_codes, sub_frames, input_indices)` ¶

`shape` `property` ¶

`obs_modes` `property` ¶

`is_roving` `property` ¶

`sort_by_date(ascending=True)` ¶

`to_dataframe()` ¶

`RadarObservationData(t, obs_type_ids, obs_mode_ids, values, uncertainties, rx_codes, tx_codes, tx_freq, input_indices)` ¶

`shape` `property` ¶

`obs_modes` `property` ¶

`is_delay` `property` ¶

`is_doppler` `property` ¶

`sort_by_date(ascending=True)` ¶

`to_dataframe()` ¶

`load_local_observations(filepath)` ¶

`load_online_observations(desig, save_path=None)` ¶