mpc

Interface to the Minor Planet Center (MPC) database for asteroid and comet observations.

This module contains a wrapper for the MPC interface of the astroquery package, with additional functionality for applying observation weights and star catalog biases.

Classes

BatchMPC()

This class provides an interface between observations in the Minor Planet Centre database and Tudat.
class BatchMPC[source]

Bases: object

This class provides an interface between observations in the Minor Planet Centre database and Tudat.

Notes

Currently, transformations between reference frames are not implemented. As such observations are only returned in the J2000 Frame.

Examples

Basic sequence of usage:

Initialise and retrieve data:

>>> MPCcodes = [1, 4] # Ceres and Vesta
>>> batch = BatchMPC()
>>> batch.get_observations(MPCcodes)
>>> batch.filter(epoch_start=datetime.datetime(2016, 1, 1))

Transform to Tudat format: >>> … >>> bodies = environment_setup.create_system_of_bodies(body_settings) >>> observation_collection = batch.to_tudat(bodies=bodies, included_satellites=None)

__init__() → None[source]

Create an empty MPC batch.

copy() → BatchMPC[source]

Create a copy of the batch, equivalent to copy.copy(batchMPC())

Returns:

Copy of batch.

Return type:

BatchMPC

create_observations_from_astropy_table(table, station_body: str = 'Earth', apply_weights_VFCC17: bool = False, apply_star_catalog_debias: bool = False, debias_kwargs: dict = {}, in_degrees: bool = True) → ObservationCollection[source]

Just like to_tudat(), creates a Tudat ObservationCollection from an Astropy table or pandas DataFrame. Unlike to_tudat(), it does not require a SystemOfBodies object as input. Unlike to_tudat(), apply_weights_VFCC17 and apply_star_catalog_debias flags are set to False by default, as users might have minimal tables available, which do not necessary contain all the fields required by the batchMPC class (e.g. note1,note2, catalog, etc…)

This method is useful for creating observation collections when the environment is not defined. Note that, when performing a simulation, you must manually ensure that the ground stations (observatory codes) and bodies (MPC numbers) referenced in this collection are added to your simulation environment.

Parameters:

  • table (astropy.table.Table | pd.DataFrame) – The input table containing observations. Must include ‘number’, ‘observatory’, ‘epoch’, ‘RA’, and ‘DEC’ columns.

  • station_body (str, optional) – The name of the body to which the ground stations (observatories) are attached, by default “Earth”.

Returns:

A collection of observation sets grouped by link.

Return type:

observations.ObservationCollection

filter(bands: list[str] | None = None, catalogs: list[str] | None = None, observation_types: list[str] | None = None, observatories: list[str] | None = None, observatories_exclude: list[str] | None = None, epoch_start: float | datetime | None = None, epoch_end: float | datetime | None = None, in_place: bool = True) → None | BatchMPC[source]

Filter out observations from the batch.

Parameters:

  • bands (list[str] | None, optional) – List of observation bands to keep in the batch, by default None

  • catalogs (list[str] | None, optional) – List of star catalogs to keep in the batch. See https://www.minorplanetcenter.net/iau/info/CatalogueCodes.html for the exact encodings used by MPC, by default None

  • observation_types (list[str] | None, optional) – List of observation types to keep in the batch, e.g. CCD, Photographic etc. See the Note2 section of the MPC format description: https://minorplanetcenter.net/iau/info/OpticalObs.html for the exact encoding, by default None

  • observatories (list[str] | None, optional) – List of observatories to keep in the batch, by default None

  • observatories_exclude (list[str] | None, optional) – List of observatories to remove from the batch, by default None

  • epoch_start (float | datetime.datetime | None, optional) – Start date to include observations from, can be in python datetime in utc or the more conventional tudat seconds since j2000 in TDB if float, by default None

  • epoch_end (float | datetime.datetime | None, optional) – Final date to include observations from, can be in python datetime in utc or the more conventional tudat seconds since j2000 in TDB if float, by default None

  • in_place (bool, optional) – If true, modify the current batch object. If false returns a new object that is filtered, currect batch remains unmodified, by default True

Raises:

  • ValueError – Is raised if bands, observatories, or observatories_exclude are not list or None.

  • ValueError – Is raised if both observations_exclude and observatories are not None.

Returns:

Returns a new instance of BatchMPC that is filtered.

Return type:

None or BatchMPC

from_astropy(table: QTable | Table, in_degrees: bool = True, frame: str = 'J2000', custom_name: str | None = None) → None[source]

Loads observations from an Astropy Table into the BatchMPC object.

This method provides a convenient way to import observation data that has been processed or filtered and is stored in an Astropy Table or QTable. It serves as a wrapper that validates the input before converting it to a pandas DataFrame for internal processing.

Parameters:

  • table (astropy.table.Table) – The Astropy Table or QTable containing the observation data. It must include the following columns: ‘number’, ‘epoch’, ‘RA’, ‘DEC’, ‘band’, ‘observatory’.

  • in_degrees (bool, optional) – If True, ‘RA’ and ‘DEC’ columns are assumed to be in degrees. If False, they are assumed to be in radians. Defaults to True.

  • frame (str, optional) – The reference frame of the observations. Currently, only “J2000” is supported. Defaults to “J2000”.

Raises:

  • ValueError – If the input table is not an Astropy Table/QTable or if it is missing any of the required columns.

  • NotImplementedError – If a frame other than ‘J2000’ is provided.

from_file(filename: str, in_degrees: bool = False, frame: str = 'J2000', custom_name: str | None = None) → None[source]

Loads observations from a local MPC 80-column text file.

This method serves as a high-level convenience function that orchestrates the parsing of a raw 80-column file and loading the data into the batch. It uses the tudatpy.data.mpc.parser_80col.parse_80cols_file function internally.

The parser returns an Astropy Table with RA/DEC values in radians, so this method subsequently calls from_astropy to ingest the data. The in_degrees parameter should therefore be False (the default).

Note

If you wish to perform intermediate operations on the parsed data using pandas, you can call the parser directly and then use the from_pandas method:

from tudatpy.data.mpc.parser_80col import parse_80cols_file

# 1. Parse the file to an Astropy Table
astropy_table = parse_80cols_file("my_obs.txt")

# 2. Convert to a pandas DataFrame for manipulation
pandas_df = astropy_table.to_pandas()
# ... perform custom pandas operations on pandas_df ...

# 3. Load the processed DataFrame into the batch
batch = BatchMPC()
batch.from_pandas(pandas_df, in_degrees=False)
Parameters:

  • filename (str) – The path to the MPC 80-column formatted text file.

  • in_degrees (bool, optional) – Specifies the unit of RA/DEC in the file. Since the internal parser handles the conversion to radians, this should be left as False. Defaults to False.

  • frame (str, optional) – The reference frame of the observations. Currently, only “J2000” is supported. Defaults to “J2000”.

from_pandas(table: DataFrame, in_degrees: bool = True, frame: str = 'J2000', custom_name: str | None = None) → None[source]

Loads observations from a pandas DataFrame into the BatchMPC object.

The DataFrame must contain the following columns: - ‘number’: The MPC object code (e.g., ‘433’ for Eros). - ‘epoch’: The observation epoch in Julian Day format. - ‘RA’: Right Ascension. - ‘DEC’: Declination. - ‘band’: The observation band. - ‘observatory’: The MPC observatory code.

Parameters:

  • table (pd.DataFrame) – The pandas DataFrame containing the observation data.

  • in_degrees (bool, optional) – If True, RA and DEC columns in the DataFrame are assumed to be in degrees. If False, they are assumed to be in radians. Defaults to True.

  • frame (str, optional) – The reference frame of the observations. Currently, only “J2000” is supported. Defaults to “J2000”.

get_observations(MPCcodes: list[str | int], id_types: list[str | None] | None = None, drop_misc_observations: bool = True, custom_name: str | None = None) → None[source]

Retrieve all observations for a set of MPC listed objects. This method uses astroquery to retrieve the observations from the MPC. An internet connection is required, observations are cached for faster subsequent retrieval. Removes duplicate and irrelevant observation data by default (see drop_misc_observations).

Parameters:

  • MPCcodes (list[str | int]) – List of integer or str MPC object codes for minor planets or comets.

  • id_types (list[str | None] | None, default None) – A list of identification types (‘asteroid_number’, ‘comet_number’, ‘comet_designation’) corresponding to each MPCcode. If an element is None, the type is considered unknown. If the entire list is None, all types are considered unknown.

  • drop_misc_observations (bool, default True) – Drops observations made by method: radar and offset (natural satellites). Drops observations made by roaming observers. Drops duplicate listings to denote first observation.

observatories_table(only_in_batch: bool = True, only_space_telescopes: bool = False, exclude_space_telescopes: bool = False, include_positions: bool = False) → DataFrame[source]

Returns a pandas DataFrame with information about all MPC observatories, Carthesian positions are only available after running the to_tudat() method.

Parameters:

  • only_in_batch (bool, optional) – Filter out observatories that are not in the batch, by default True

  • only_space_telescopes (bool, optional) – Filter out all observatories except space telescopes, by default False

  • only_space_telescopes – Filter out all space telescopes, by default False

  • include_positions (bool, optional) – Include cartesian positions of the terrestrial telescopes only available after running to_tudat(), by default False

Returns:

Dataframe with information about the observatories.

Return type:

pd.DataFrame

plot_observations_sky(objects: list[str] | None = None, projection: str | None = None, figsize: tuple[float] = (14.0, 7.0))[source]

Generates a matplotlib figure with the observations’ right ascension and declination over time.

NOTE: Only plots observations between 1970 and 3000 to ensure safe datetime conversion across platforms.

plot_observations_temporal(objects: list[str] | None = None, figsize: tuple[float] = (9.0, 6.0))[source]

Generates a matplotlib figure with the declination and right ascension over time.

Parameters:

  • objects (list[str] | None, optional) – List of specific MPC objects in batch to plot, None to plot all , by default None

  • projection (str, optional) – projection of the figure options are: ‘aitoff’, ‘hammer’, ‘lambert’ and ‘mollweide’, by default “aitoff”

  • figsize (tuple[float], optional) – size of the matplotlib figure, by default (15, 7)

Returns:

Matplotlib figure with the observations

Return type:

Matplotlib figure

set_weights(weights: list | ndarray | Series)[source]

Manually set weights per observation. Weights are passed to observation collection when .to_tudat() is called. Set the apply_weights_VFCC17 parameter in .to_tudat() to False to avoid overwriting. The order of the weights should match the order found in the .table parameter.

Parameters:

weights (list | np.ndarray | pd.Series) – Iterable with weights per observation.

Raises:

ValueError – If the size of weights does not match the number of observations in the batch table.

summary()[source]

Produce a quick summary of the content of the batch.

to_tudat(bodies: SystemOfBodies, included_satellites: dict[str, str] | None, station_body: str = 'Earth', add_sbdb_gravity_model: bool = False, apply_weights_VFCC17: bool = True, apply_star_catalog_debias: bool = True, debias_kwargs: dict = {}) → ObservationCollection[source]
Converts the observations in the batch into a Tudat compatible format and

sets up the relevant Tudat infrastructure to support estimation.

This method does the following:

1. (By Default) Applies star catalog debiasing and estimation weight calculation.2. Creates an empty body for each minor planet with their MPC code as a name.3. Adds this body to the system of bodies inputted to the method.4. Retrieves the global position of the terrestrial observatories in the batch and adds these stations to the Tudat environment.5. Creates link definitions between each unique terrestrial observatory/ minor planet combination in the batch.6. (Optionally) creates a link definition between each space telescope / minor planet combination in the batch. This requires an addional input.7. Creates a SingleObservationSet object for each unique link that includes all observations for that link.8. (By Default) Add the relevant weights to the SingleObservationSet per observation.8. Returns the observations

Parameters:

  • bodies (environment.SystemOfBodies) – SystemOfBodies containing at least the earth to allow for the placement of terrestrial telescopes

  • included_satellites (dict[str, str] | None, optional) – A dictionary that links the name of a space telescope used by the user with the observatory code in MPC. Used when utilising observations from space telescopes like TESS and WISE. The keys should be the MPC observatory codes. The values should be the bodies’ in the user’s code. The relevant observatory code can be retrieved using the .observatories_table() method, by default None

  • station_body (bool, optional) – Body to attach ground stations to. Does not need to be changed unless the Earth body has been renamed, by default “Earth”

  • station_body – Adds a central_sbdb gravity model to the object, generated using JPL’s small body database. This option is only available for a limited number of bodies and raises an error if unavailable. See tudatpy.dynamics.environment_setup.gravity_field.central_sbdb for more info. Enabled if True, by default False

  • apply_weights_VFCC17 (bool, optional) – Applies the weighting scheme as described in: “Statistical analysis of astrometric errors for the most productive asteroid surveys” by Veres et al. (2017). Overwrites custom weights set through the .set_weights() method if True, by default True

  • apply_star_catalog_debias (bool, optional) – Applies star catalog debiasing as described in: “Star catalog position and proper motion corrections in asteroid astrometry II: The Gaia era” by Eggl et al. (2018), by default True

  • debias_kwargs (dict, optional) – Additional options when applying star catalog debiasing. A different debias file can be set here. Options are set as kwargs using a dictionary, see data._biases.get_biases_EFCC18() for more info, by default dict()

Returns:

ObservationCollection with the observations found in the batch

Return type:

observations.ObservationCollection

Examples

Using Space Telescopes

Create dictionary to link name in tudat with mpc code in batch:

>> sats_dict = {“C57”:”TESS”} >> obs = batch1.to_tudat(bodies, included_satellites=sats_dict)

property MPC_objects: list[str]

List of MPC objects.

property bands: list[str]

List of bands in batch.

property bodies_created: dict

Dictionary with the bodies created by to_tudat and details.

property epoch_end: float

Epoch of latest observation in batch in seconds since J2000 TDB.

property epoch_start: float

Epoch of oldest observation in batch in seconds since J2000 TDB.

property observatories: list[str]

List of observatories in batch.

property size: int

Number of observations in batch.

property space_telescopes: list[str]

List of satellite_observatories in batch.

property table: DataFrame

Pandas dataframe with observation data.

Functions

load_bias_file(filepath[, Nside, catalog_flags])

Loads a healpix star catalog debias file and processes it into a dataframe.

get_biases_EFCC18(RA, DEC, ...[, bias_file, ...])

Calculate and return star catalog bias values as described in: "Star catalog position and proper motion corrections in asteroid astrometry II: The Gaia era" by Eggl et al. (2018).

get_weights_VFCC17([MPC_codes, epoch, ...])

Retrieves observation weights using the weighting scheme presented in "Statistical analysis of astrometric errors for the most productive asteroid surveys" by Veres et al. (2017).
load_bias_file(filepath: str, Nside: int | None = None, catalog_flags: list = ['a', 'b', 'c', 'd', 'e', 'g', 'i', 'j', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 't', 'u', 'v', 'w', 'L', 'N', 'Q', 'R', 'S', 'U', 'Y']) → tuple[DataFrame, int][source]

Loads a healpix star catalog debias file and processes it into a dataframe. Automatically retrieves NSIDE parameter.

Parameters:

  • filepath (str) – Filepath of debias file.

  • Nside (int | None, optional) – NSIDE value, to be left None in most cases as this is retrieved automatically by the function, by default None

  • catalog_flags (list | None, optional) – list of catalog flags, should be left default in most cases, by default None

Returns:

Dataframe with biases in multiindex format ((Npix x Ncat) x Nvals), the numpix value

Return type:

tuple[pd.DataFrame, int]

Raises:

ValueError – If NSIDE cannot be retrieved automatically.

get_biases_EFCC18(RA: float | ndarray | list, DEC: float | ndarray | list, epoch_seconds_TDB: float | ndarray | list, catalog: str | ndarray | list, bias_file: str | None = '/home/docs/.tudat/resource/star_catalog_biases/debias_2018/bias.dat', Nside: int | None = None, catalog_flags: list[str] = ['a', 'b', 'c', 'd', 'e', 'g', 'i', 'j', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 't', 'u', 'v', 'w', 'L', 'N', 'Q', 'R', 'S', 'U', 'Y']) → tuple[ndarray, ndarray][source]

Calculate and return star catalog bias values as described in: “Star catalog position and proper motion corrections in asteroid astrometry II: The Gaia era” by Eggl et al. (2018). Uses the regular bias set by default. A high res version of the bias map can be retrieved from the paper. This can then be selected using the bias_file paramater.

Parameters:

  • RA (float | np.ndarray | list) – Right Ascension value in radians

  • DEC (float | np.ndarray | list) – Declination value in radians

  • epoch_seconds_TDB (float | np.ndarray | list) – Time in seconds since J2000 TDB.

  • catalog (str | np.ndarray | list) – Star Catalog code as described by MPC: https://www.minorplanetcenter.net/iau/info/CatalogueCodes.html

  • bias_file (str | None, optional) – Optional bias file location, used to load in alternative debias coefficients. By default coefficients are retrieved from Tudat resources, by default None

  • Nside (int | None, optional) – Optional Nside value, should be left None in most cases, by default None

  • catalog_flags (list[str] | None, optional) – List of catalog values to use, should be left None in most cases, by default None

Returns:

Right Ascencion Corrections, Declination corrections

Return type:

tuple[np.ndarray, np.ndarray]

Raises:

ValueError – If all mandatory inputs are not matching in size.

get_weights_VFCC17(MPC_codes: Series | list | ndarray | None = None, epoch: Series | list | ndarray | None = None, observation_type: Series | list | ndarray | None = None, observatory: Series | list | ndarray | None = None, star_catalog: Series | list | ndarray | None = None, mpc_table: DataFrame | None = None, return_full_table=False) → ndarray | DataFrame[source]

Retrieves observation weights using the weighting scheme presented in “Statistical analysis of astrometric errors for the most productive asteroid surveys” by Veres et al. (2017). Input may be provided using either a full MPC table (e.g. from BatchMPC) or using the individual variables.

Observation types: “x”, “X”, “V”, “v”, “W”, “w”, “R”, “r”, “Q”, “q”, “O”, are not described by the paper and receive a placeholder weight of 1/100 if provided.

Parameters:

  • MPC_codes (pd.Series | list | np.ndarray | None, optional) – Iterable with the MPC target codes, e.g. 433 for Eros. Size must match other iterables, by default None

  • epoch (pd.Series | list | np.ndarray | None, optional) – Epoch expressed as Julian Days. Size must match other iterables, by default None

  • observation_type (pd.Series | list | np.ndarray | None, optional) – Iterable with the observation types in MPC format. See the NOTE2 section of the MPC format description for the exact encoding: https://minorplanetcenter.net/iau/info/OpticalObs.html. Size must match other iterables, by default None

  • observatory (pd.Series | list | np.ndarray | None, optional) – Iterable with the MPC target codes, e.g. 433 for Eros. Size must match other iterables, by default None

  • star_catalog (pd.Series | list | np.ndarray | None, optional) – Iterable with the star catalog codes. See the MPC catalog codes page for the exact encoding: https://www.minorplanetcenter.net/iau/info/CatalogueCodes.html. Size must match other iterables, by default None

  • mpc_table (pd.DataFrame | None, optional) – Table retrieved by calling the mpc.BatchMPC.table property. Set None when using iterable input. Set others None when using table, by default None

  • return_full_table (bool, optional) – Return the table with all intermediate calculations if True, return a numpy array if False, by default False

Returns:

  • np.ndarray – If return_full_table is False, numpy array with weights with same size as input.

  • pd.DataFrame – If return_full_table is True, pandas table with all intermediate calculations.

Raises:

ValueError – MPC_codes, epoch, observation_type, observatory and star_catalog must all be not None and the same size. mpc_table must be None. If table input is used, the remaining input parameters must be done.