Skip to content

SBDB Asteroids

JPL Small Body Database (SBDB) asteroid data download, parsing, lookup, and loading.

See the SBDB Asteroids User Guide for concepts and usage.

Download

Download the JPL Small Body Database (SBDB) asteroid dataset.

Provides a helper to fetch the SBDB asteroid data CSV file from a GitHub LFS repository. Network errors are propagated to the caller so that higher-level code (e.g. :func:load_sbdb_asteroids) can decide on fallback behaviour.

SBDB_URL = 'https://github.com/duncaneddy/lfs/raw/main/asteroid_data/sbdb_asteroid_data_2026_02_15.csv' module-attribute

Default URL for the JPL SBDB asteroid data CSV (GitHub LFS snapshot).

download_sbdb_file(filepath, *, url=SBDB_URL, timeout=_DEFAULT_TIMEOUT)

Download the JPL SBDB asteroid dataset to filepath.

Creates parent directories if they do not exist. On success the downloaded binary data is written to filepath and the resolved path is returned.

Parameters:

Name Type Description Default
filepath str | Path

Destination path for the downloaded file.

 required
url str

URL to fetch. Defaults to :data:SBDB_URL.

 SBDB_URL
timeout float

HTTP timeout in seconds. Defaults to 120.

 _DEFAULT_TIMEOUT

Returns:

Name Type Description
Resolved Path

class:~pathlib.Path to the written file.

Raises:

Type Description
HTTPStatusError

If the server returns a non-2xx status.
TransportError

On network-level failures (DNS, timeout, etc.).

Parsers

Parsing utilities for the JPL Small Body Database (SBDB) asteroid dataset.

Reads the SBDB CSV file and converts it into a Polars DataFrame with column names matching the MPC convention for downstream compatibility with :func:~astrojax.datasets.asteroid_state_ecliptic.

load_sbdb_csv_to_dataframe(filepath)

Load the SBDB CSV file into a Polars DataFrame.

Reads the CSV at filepath, renames orbital-element columns to match the MPC naming convention (om -> node, w -> peri, ma -> M, epoch -> epoch_jd, pdes -> number), and casts the number column to Utf8 for parity with the MPC DataFrame.

Parameters:

Name Type Description Default
filepath str | Path

Path to the sbdb_asteroid_data.csv file.

 required

Returns:

Type Description
DataFrame

Polars DataFrame with 21 columns including orbital elements,
DataFrame

physical properties (diameter, GM), and epoch metadata.

Raises:

Type Description
FileNotFoundError

If filepath does not exist.

Providers

Factory functions for loading the JPL SBDB asteroid dataset.

Provides convenience functions for loading the SBDB asteroid data as a Polars DataFrame:

  • :func:load_sbdb_asteroids: Load from cache, downloading fresh data when stale.
  • :func:load_sbdb_from_file: Load from an arbitrary file path.
  • :func:get_sbdb_asteroid_ephemeris: Look up a single asteroid's orbital elements and physical properties.

get_sbdb_asteroid_ephemeris(df, identifier)

Look up an asteroid's orbital elements from the SBDB DataFrame.

Searches by number (if identifier is an int or numeric string) or by name (if identifier is a non-numeric string).

The returned dictionary is compatible with :func:~astrojax.datasets.asteroid_state_ecliptic:

.. code-block:: python

eph = get_sbdb_asteroid_ephemeris(df, 1)
oe = jnp.array([eph["a"], eph["e"], eph["i"],
                 eph["node"], eph["peri"], eph["M"]])
state = asteroid_state_ecliptic(eph["epoch_jd"], oe, target_jd)

Parameters:

Name Type Description Default
df DataFrame

Polars DataFrame as returned by :func:load_sbdb_asteroids.

 required
identifier int | str

Asteroid number (int or numeric str) or name (str).

 required

Returns:

Type Description
dict

Dictionary with keys: name, full_name, number,
dict

epoch_jd, a, e, i, node, peri, M,
dict

n, diameter, GM.

Raises:

Type Description
KeyError

If the asteroid is not found.

Examples:

from astrojax.datasets import load_sbdb_asteroids, get_sbdb_asteroid_ephemeris
df = load_sbdb_asteroids()
ceres = get_sbdb_asteroid_ephemeris(df, 1)
print(ceres["name"])  # "Ceres"

load_sbdb_asteroids(filepath=None, *, max_age_days=_DEFAULT_MAX_AGE_DAYS)

Load SBDB asteroid data from a local cache, downloading when stale.

Checks whether the cached file at filepath exists and is younger than max_age_days. If the file is missing or stale, a fresh copy is downloaded from GitHub LFS.

Parameters:

Name Type Description Default
filepath str | Path | None

Path to the cached CSV file. When None (the default), uses <cache_dir>/datasets/sbdb/sbdb_asteroid_data.csv.

 None
max_age_days float

Maximum acceptable age of the cached file in days. Defaults to 365.

 _DEFAULT_MAX_AGE_DAYS

Returns:

Type Description
DataFrame

Polars DataFrame with SBDB asteroid orbital elements and
DataFrame

physical properties.

Raises:

Type Description
RuntimeError

If the download fails and no cached file exists.

Examples:

from astrojax.datasets import load_sbdb_asteroids
df = load_sbdb_asteroids()
print(df.shape)
print(df.head())

load_sbdb_from_file(filepath)

Load SBDB asteroid data from a local file.

Parameters:

Name Type Description Default
filepath str | Path

Path to a sbdb_asteroid_data.csv file.

 required

Returns:

Type Description
DataFrame

Polars DataFrame with SBDB asteroid orbital elements and
DataFrame

physical properties.

Raises:

Type Description
FileNotFoundError

If the file does not exist.

Examples:

from astrojax.datasets import load_sbdb_from_file
df = load_sbdb_from_file("/path/to/sbdb_asteroid_data.csv")
print(df.shape)