API Reference

This section provides detailed documentation for the mpcq API.

Data Structures

The mpcq package uses strongly-typed tables built with Quivr and adam-core. These tables provide efficient memory usage, type safety, and fast operations through Apache Arrow.

MPCObservations

class MPCObservations(table: Table, **kwargs: int | float | str)[source]

Bases: Table

requested_provid: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

primary_designation: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

obsid: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

trksub: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

provid: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

permid: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

submission_id: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

obssubid: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

obstime

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.

ra: A column for storing 64-bit floating point numbers.

dec: A column for storing 64-bit floating point numbers.

rmsra: A column for storing 64-bit floating point numbers.

rmsdec: A column for storing 64-bit floating point numbers.

rmscorr: A column for storing 64-bit floating point numbers.

mag: A column for storing 64-bit floating point numbers.

rmsmag: A column for storing 64-bit floating point numbers.

band: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

stn: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

updated_at

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.

created_at

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.

status: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

astcat: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

mode: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

schema: ClassVar[pa.Schema] = requested_provid: large_string primary_designation: large_string obsid: large_string trksub: large_string provid: large_string permid: large_string submission_id: large_string obssubid: large_string obstime: struct<days: int64, nanos: int64> child 0, days: int64 child 1, nanos: int64 ra: double dec: double rmsra: double rmsdec: double rmscorr: double mag: double rmsmag: double band: large_string stn: large_string updated_at: struct<days: int64, nanos: int64> child 0, days: int64 child 1, nanos: int64 created_at: struct<days: int64, nanos: int64> child 0, days: int64 child 1, nanos: int64 status: large_string astcat: large_string mode: large_string

Contains observation data with columns:

obstime: Observation timestamp (Timestamp)
ra, dec: Position in degrees (Float64)
rmsra, rmsdec: Position uncertainties (Float64)
mag: Magnitude (Float64)
band: Filter band (String)
stn: Observatory code (String)
And more…

CrossMatchedMPCObservations

class CrossMatchedMPCObservations(table: Table, **kwargs: int | float | str)[source]

Bases: Table

request_id: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

mpc_observations

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.

separation_arcseconds: A column for storing 64-bit floating point numbers.

separation_seconds: A column for storing 64-bit floating point numbers.

schema: ClassVar[pa.Schema] = request_id: large_string not null mpc_observations: struct<requested_provid: large_string, primary_designation: large_string, obsid: large_string, trksub: large_string, provid: large_string, permid: large_string, submission_id: large_string, obssubid: large_string, obstime: struct<days: int64, nanos: int64>, ra: double, dec: double, rmsra: double, rmsdec: double, rmscorr: double, mag: double, rmsmag: double, band: large_string, stn: large_string, updated_at: struct<days: int64, nanos: int64>, created_at: struct<days: int64, nanos: int64>, status: large_string, astcat: large_string, mode: large_string> child 0, requested_provid: large_string child 1, primary_designation: large_string child 2, obsid: large_string child 3, trksub: large_string child 4, provid: large_string child 5, permid: large_string child 6, submission_id: large_string child 7, obssubid: large_string child 8, obstime: struct<days: int64, nanos: int64> child 0, days: int64 child 1, nanos: int64 child 9, ra: double child 10, dec: double child 11, rmsra: double child 12, rmsdec: double child 13, rmscorr: double child 14, mag: double child 15, rmsmag: double child 16, band: large_string child 17, stn: large_string child 18, updated_at: struct<days: int64, nanos: int64> child 0, days: int64 child 1, nanos: int64 child 19, created_at: struct<days: int64, nanos: int64> child 0, days: int64 child 1, nanos: int64 child 20, status: large_string child 21, astcat: large_string child 22, mode: large_string separation_arcseconds: double not null separation_seconds: double not null

Contains cross-matched observations with additional columns:

separation_arcseconds: Angular separation between matches (Float64)
separation_seconds: Time difference between matches (Float64)
mpc_observations: Nested MPCObservations table

MPCOrbits

class MPCOrbits(table: Table, **kwargs: int | float | str)[source]

Bases: Table

requested_provid: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

primary_designation: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

id: A column for storing 64-bit integers.

provid: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

epoch

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.

q: A column for storing 64-bit floating point numbers.

e: A column for storing 64-bit floating point numbers.

i: A column for storing 64-bit floating point numbers.

node: A column for storing 64-bit floating point numbers.

argperi: A column for storing 64-bit floating point numbers.

peri_time: A column for storing 64-bit floating point numbers.

q_unc: A column for storing 64-bit floating point numbers.

e_unc: A column for storing 64-bit floating point numbers.

i_unc: A column for storing 64-bit floating point numbers.

node_unc: A column for storing 64-bit floating point numbers.

argperi_unc: A column for storing 64-bit floating point numbers.

peri_time_unc: A column for storing 64-bit floating point numbers.

a1: A column for storing 64-bit floating point numbers.

a2: A column for storing 64-bit floating point numbers.

a3: A column for storing 64-bit floating point numbers.

h: A column for storing 64-bit floating point numbers.

g: A column for storing 64-bit floating point numbers.

created_at

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.

updated_at

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.

orbits() → Orbits[source]

Return the orbits as an adam_core Orbits object.

Returns:: orbits – The orbits and associated data for the given provisional designations.
Return type:: Orbits

schema: ClassVar[pa.Schema] = requested_provid: large_string not null primary_designation: large_string id: int64 provid: large_string epoch: struct<days: int64, nanos: int64> child 0, days: int64 child 1, nanos: int64 q: double e: double i: double node: double argperi: double peri_time: double q_unc: double e_unc: double i_unc: double node_unc: double argperi_unc: double peri_time_unc: double a1: double a2: double a3: double h: double g: double created_at: struct<days: int64, nanos: int64> child 0, days: int64 child 1, nanos: int64 updated_at: struct<days: int64, nanos: int64> child 0, days: int64 child 1, nanos: int64

Contains orbital elements with columns:

epoch: Epoch of orbital elements (Timestamp)
a: Semi-major axis in AU (Float64)
e: Eccentricity (Float64)
i: Inclination in degrees (Float64)
om: Longitude of ascending node in degrees (Float64)
w: Argument of perihelion in degrees (Float64)
ma: Mean anomaly in degrees (Float64)

MPCPrimaryObjects

class MPCPrimaryObjects(table: Table, **kwargs: int | float | str)[source]

Bases: Table

requested_provid: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

primary_designation: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

provid: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

created_at

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.

updated_at

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] = requested_provid: large_string not null primary_designation: large_string provid: large_string created_at: struct<days: int64, nanos: int64> child 0, days: int64 child 1, nanos: int64 updated_at: struct<days: int64, nanos: int64> child 0, days: int64 child 1, nanos: int64

Contains object identification data with columns:

primary_designation: Primary designation (String)
provid: Provisional designation (String)
permid: Permanent identifier (String)
created_at, updated_at: Timestamps for record updates

Client Classes

BigQueryMPCClient

class BigQueryMPCClient(dataset_id: str, views_dataset_id: str, **kwargs: Any)[source]

Bases: MPCClient

query_observations(provids: List[str]) → MPCObservations[source]

Query the MPC database for the observations and associated data for the given provisional designations.

Parameters:: provids (List[str]) – List of provisional designations to query.
Returns:: observations – The observations and associated data for the given provisional designations.
Return type:: MPCObservations

all_orbits() → MPCOrbits[source]

Query the MPC database for all orbits and associated data.

Returns:: orbits – The orbits and associated data for all objects in the MPC database.
Return type:: MPCOrbits

query_orbits(provids: List[str]) → MPCOrbits[source]

Query the MPC database for the orbits and associated data for the given provisional designations.

Parameters:: provids (List[str]) – List of provisional designations to query.
Returns:: orbits – The orbits and associated data for the given provisional designations.
Return type:: MPCOrbits

query_submission_info(submission_ids: List[str]) → MPCSubmissionResults[source]

Query for observation status and mapping (observation ID to trksub, provid, etc.) for a given list of submission IDs.

Parameters:: submission_ids (List[str]) – List of submission IDs to query.
Returns:: submission_info – The observation status and mapping for the given submission IDs.
Return type:: MPCSubmissionResults

query_submission_history(provids: List[str]) → MPCSubmissionHistory[source]

Query for submission history for a given list of provisional designations.

Parameters:: provids (List[str]) – List of provisional designations to query.
Returns:: submission_history – The submission history for the given provisional designations.
Return type:: MPCSubmissionHistory

query_primary_objects(provids: List[str]) → MPCPrimaryObjects[source]

Query the MPC database for the primary objects and associated data for the given provisional designations.

Parameters:: provids (List[str]) – List of provisional designations to query.
Returns:: primary_objects – The primary objects and associated data for the given provisional designations.
Return type:: MPCPrimaryObjects

cross_match_observations(ades_observations: ADESObservations, obstime_tolerance_seconds: int = 30, arcseconds_tolerance: float = 2.0) → CrossMatchedMPCObservations[source]

Cross-match the given ADES observations with the MPC observations.

Parameters:

ades_observations (ADESObservations) – The ADES observations to cross-match.
obstime_tolerance_seconds (float, optional) – Time tolerance in seconds for matching observations.
arcseconds_tolerance (float, optional) – Angular separation tolerance in arcseconds.

Returns:

cross_matched_mpc_observations – The MPC observations that match the given ADES observations.

Return type:

CrossMatchedMPCObservations

find_duplicates(provid: str, obstime_tolerance_seconds: int = 30, arcseconds_tolerance: float = 2.0) → CrossMatchedMPCObservations[source]

Find duplicates in the MPC observations for a given object by comparing observations against each other using time and position tolerances.

Parameters:

provid (str) – The provisional designation to check for duplicates.
obstime_tolerance_seconds (int, optional) – Time tolerance in seconds for matching observations.
arcseconds_tolerance (float, optional) – Angular separation tolerance in arcseconds.

Returns:

cross_matched_mpc_observations – The MPC observations that are potential duplicates, with separation information included.

Return type:

CrossMatchedMPCObservations

The main client for interacting with the MPC BigQuery dataset. All query methods return strongly-typed Quivr tables.

Submission Classes

MPCSubmissionResults

class MPCSubmissionResults(table: Table, **kwargs: int | float | str)[source]

Bases: Table

requested_submission_id: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

obsid: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

obssubid: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

trksub: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

primary_designation: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

permid: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

provid: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

submission_id: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

status: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

schema: ClassVar[pa.Schema] = requested_submission_id: large_string not null obsid: large_string obssubid: large_string trksub: large_string primary_designation: large_string permid: large_string provid: large_string submission_id: large_string status: large_string

MPCSubmissionHistory

class MPCSubmissionHistory(table: Table, **kwargs: int | float | str)[source]

Bases: Table

requested_provid: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

primary_designation: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

submission_id: A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

submission_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.

first_submission: A column for storing booleans.

last_submission: A column for storing booleans.

num_obs: A column for storing 64-bit integers.

first_obs_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.

last_obs_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.

arc_length: A column for storing 64-bit floating point numbers.

schema: ClassVar[pa.Schema] = requested_provid: large_string not null primary_designation: large_string submission_id: large_string submission_time: struct<days: int64, nanos: int64> child 0, days: int64 child 1, nanos: int64 first_submission: bool last_submission: bool num_obs: int64 first_obs_time: struct<days: int64, nanos: int64> child 0, days: int64 child 1, nanos: int64 last_obs_time: struct<days: int64, nanos: int64> child 0, days: int64 child 1, nanos: int64 arc_length: double