Skip to content

Asteroid Masses

SBN Archive asteroid masses download, parsing, and loading.

See the Asteroid Masses User Guide for concepts and usage.

Download

Download the SBN Archive asteroid masses compilation dataset.

Provides a helper to fetch the compil.ast.masses.zip file from the SBN Archive. Network errors are propagated to the caller so that higher-level code (e.g. :func:load_asteroid_masses) can decide on fallback behaviour.

ASTMASS_URL = 'https://sbnarchive.psi.edu/pds4/non_mission/compil.ast.masses.zip' module-attribute

Default URL for the SBN Archive asteroid masses compilation (ZIP).

download_astmass_file(filepath, *, url=ASTMASS_URL, timeout=_DEFAULT_TIMEOUT)

Download the SBN Archive asteroid masses 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:ASTMASS_URL.

 ASTMASS_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 SBN Archive asteroid masses dataset.

Extracts the fixed-width astmass12.tab table from the downloaded ZIP archive and converts it into a Polars DataFrame with typed columns for mass, density, shape, and reference information.

load_astmass_tab_to_dataframe(filepath)

Load the asteroid masses .tab file from a ZIP into a Polars DataFrame.

Opens the ZIP at filepath, searches for an entry whose name ends with astmass12.tab (to handle subdirectory paths inside the archive), and parses each line of the fixed-width table by byte-offset slicing.

Parameters:

Name Type Description Default
filepath str | Path

Path to the compil.ast.masses.zip file.

 required

Returns:

Type Description
DataFrame

Polars DataFrame with 15 typed columns.

Raises:

Type Description
FileNotFoundError

If filepath does not exist.
ValueError

If the ZIP does not contain a astmass12.tab entry.

Providers

Factory functions for loading the SBN Archive asteroid masses dataset.

Provides convenience functions for loading the asteroid masses compilation as a Polars DataFrame:

  • :func:load_asteroid_masses: Load from cache, downloading fresh data when stale.
  • :func:load_astmass_from_file: Load from an arbitrary file path.

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

Load asteroid masses 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 of compil.ast.masses.zip is downloaded from the SBN Archive.

Parameters:

Name Type Description Default
filepath str | Path | None

Path to the cached ZIP file. When None (the default), uses <cache_dir>/datasets/astmass/compil.ast.masses.zip.

 None
max_age_days float

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

 _DEFAULT_MAX_AGE_DAYS

Returns:

Type Description
DataFrame

Polars DataFrame with asteroid mass, density, and shape data.

Raises:

Type Description
RuntimeError

If the download fails and no cached file exists.

Examples:

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

load_astmass_from_file(filepath)

Load asteroid masses data from a local file.

Parameters:

Name Type Description Default
filepath str | Path

Path to a compil.ast.masses.zip file.

 required

Returns:

Type Description
DataFrame

Polars DataFrame with asteroid mass, density, and shape data.

Raises:

Type Description
FileNotFoundError

If the file does not exist.
ValueError

If the ZIP does not contain astmass12.tab.

Examples:

from astrojax.datasets import load_astmass_from_file
df = load_astmass_from_file("/path/to/compil.ast.masses.zip")
print(df.shape)