mpcq 0.4.0

Client library for interacting with an MPC observations database

mpcq

A Python package by the Asteroid Institute, a program of the B612 Foundation

mpcq is a powerful Python client library for querying and analyzing Minor Planet Center (MPC) data through Google BigQuery. This package provides efficient access to a BigQuery instance of the Small Bodies Node (SBN) replica of the MPC's Small Bodies Node database, maintained by the Asteroid Institute.

Features

• BigQuery Integration: Direct access to a complete replica of the MPC database through Google BigQuery
• Efficient Queries: Optimized query patterns for common asteroid data access patterns
• Rich Data Access: Query observations, orbits, submission history, and more
• Cross-Matching: Tools for matching observations and finding duplicates
• ADES Support: Integration with ADES format for modern asteroid data exchange

BigQuery Dataset Access

The Asteroid Institute maintains a BigQuery replica of the Minor Planet Center's Small Bodies Node database. The dataset is available through Google Cloud's Analytics Hub and requires subscription to two listings:

1. Main MPC Dataset
2. Clustered Views Dataset

To access the dataset, you'll need:

1. A Google Cloud Platform account
2. BigQuery API access enabled
3. Subscription to both Analytics Hub listings
4. Google Cloud credentials configured

Queries will be billed according to your Google Cloud Platform account's BigQuery pricing.

Installation

pip install mpcq

Quick Start

from mpcq.client import BigQueryMPCClient

# Initialize client with your subscribed dataset IDs
client = BigQueryMPCClient(
    dataset_id="your_subscribed_main_dataset_id",
    views_dataset_id="your_subscribed_views_dataset_id"
)

# Query observations for a specific object
observations = client.query_observations(["2013 RR165"])

# Convert to pandas DataFrame for analysis
from mpcq.utils import observations_to_dataframe
df = observations_to_dataframe(observations)
print(df.head())

Advanced Usage

Query Submission History

# Get submission history for an object
submissions = client.query_submission_history(["2013 RR165"])

Cross-Match Observations

# Cross-match ADES observations with MPC database
matched = client.cross_match_observations(
    ades_observations,
    obstime_tolerance_seconds=30,
    arcseconds_tolerance=2.0
)

Find Duplicates

# Find potential duplicate observations
duplicates = client.find_duplicates(
    "2013 RR165",
    obstime_tolerance_seconds=30,
    arcseconds_tolerance=2.0
)

Documentation

For complete documentation, including detailed API reference and examples, visit our ReadTheDocs page.

BigQuery Dataset Schema

The dataset (moeyens-thor-dev.mpc_sbn_aurora) contains several key tables:

• public_obs_sbn: Primary observations table
• public_current_identifications: Current object identifications
• public_numbered_identifications: Numbered asteroid identifications
• public_orbits: Orbital elements

You can explore these tables and their schemas directly in the BigQuery Console.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Acknowledgments

The Asteroid Institute acknowledges the Minor Planet Center and the Small Bodies Node for their invaluable work in maintaining the authoritative small bodies database.