Skip to content

redplanet.Craters.get 

get(
    crater_id: None | str | list[str] = None,
    name: None | str | list[str] = None,
    lon: None | tuple[float, float] = None,
    lat: None | tuple[float, float] = None,
    diameter: None | tuple[float, float] = None,
    has_age: None | bool = None,
    as_df: bool = False,
) -> list[dict] | pandas.core.frame.DataFrame

Filter/query a dataset of craters >50km diameter, with ages/names when available. Calling this with no arguments will return the full dataset.

We create a custom dataset (0.28 MiB) which unifies the following:

  1. Global database of Martian impact craters (Robbins & Hynek, 2012).
  2. Crater ages from both Hartmann and Neukum isochron methods (Robbins et al., 2013).
  3. IAU-approved crater nomenclature (USGS Astrogeology Science Center, 2024}).

For more information and code to reproduce the dataset, see https://github.com/Humboldt-Penguin/redplanet/tree/main/datasets/Craters -- TODO: I'll eventually have a section on my website to describe datasets and how we modified them, add a link to that here.

Parameters:

Name Type Description Default
crater_id None | str | list[str]

Unique crater identifier formatted ##-######, where the first two numbers indicate the Mars subquad and the last six number the craters in that subquad from largest to smallest diameter.

 None
name None | str | list[str]

Crater name according to official IAU nomenclature (as of 2024-11-26).

 None
lon None | tuple[float, float]

Filter craters whose center falls within this range of longitudes.

The given range must be a subset of either [-180,180] or [0,360] -- e.g. lon=[-170,350] is not allowed (it doesn't make sense).

 None
lat None | tuple[float, float]

Filter craters whose center falls within this range of latitudes.

 None
diameter None | tuple[float, float]

Filter craters whose diameter falls within this range, in kilometers.

 None
has_age None | bool

If True, only return craters with both Hartmann/Neukum isochron ages available. Default is False.

 None
as_df bool

If True, return a pandas DataFrame. Default is False, which returns a list of dictionaries.

 False

Returns:

Type Description
list[dict] | pd.DataFrame

Filtered list of craters with keys/columns:

  • id : str
    • Unique crater identifier formatted ##-######, where the first two numbers indicate the Mars subquad and the last six number the craters in that subquad from largest to smallest diameter.
  • name : str
    • Crater name according to official IAU nomenclature (as of 2024-11-26).
  • lat : float
    • Latitude of the crater center.
  • lon : float
    • Longitude of the crater center, in range [-180,180].
  • 'plon' : float
    • Longitude of the crater center, in range [0,360].
  • diam : float
    • Diameter of the crater, in km.
  • ['diam_sd', 'diam_elli_major', 'diam_elli_minor', 'diam_elli_angle', 'diam_elli_major_sd', 'diam_elli_minor_sd'] : float
    • For more info, see Appendix A of Robbins and Hynek (2012).
  • ['N_H(10)', 'N_N(10)', 'N_H(25)', 'N_N(25)', 'N_H(50)', 'N_N(50)', 'Hartmann Isochron Age', 'Neukum Isochron Age', 'Hartmann Turn-Off Diameter', 'Neukum Turn-Off Diameter'] : None | list[float, float, float]
    • When available, the ages are given in a list where the first value is the estimated age and second/third are uncertainties (they will always be negative/positive respectively). All values are in billions of years (aka "giga-annums"/"Ga").
    • For more info, see Supplementary Table 3 of Robbins et al. (2013).
References
  1. Robbins, S. J., & Hynek, B. M. (2012). A new global database of Mars impact craters ≥1 km: 1. Database creation, properties, and parameters. Journal of Geophysical Research: Planets, 117(E5). https://doi.org/10.1029/2011JE003966 [Database available at https://craters.sjrdesign.net/]
  2. Robbins, S. J., Hynek, B. M., Lillis, R. J., & Bottke, W. F. (2013). Large impact crater histories of Mars: The effect of different model crater age techniques. Icarus, 225(1), 173-184. https://doi.org/10.1016/j.icarus.2013.03.019 [For age data, see Supplementary Table 3]
  3. USGS Astrogeology Science Center (2024). Gazetteer of Planetary Nomenclature: Craters on Mars [Dataset]. U.S. Geological Survey. https://planetarynames.wr.usgs.gov/SearchResults?Target=20_Mars&Feature%20Type=9_Crater,%20craters [Accessed 2024-11-26]
Source code in src/redplanet/Craters/getter.py 
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
@substitute_docstrings
def get(
    crater_id : None | str | list[str]     = None,
    name      : None | str | list[str]     = None,
    lon       : None | tuple[float, float] = None,
    lat       : None | tuple[float, float] = None,
    diameter  : None | tuple[float, float] = None,
    has_age   : None | bool                = None,
    as_df     : bool                       = False,
) -> list[dict] | pd.DataFrame:
    """
    Filter/query a dataset of craters >50km diameter, with ages/names when available. Calling this with no arguments will return the full dataset.

    We create a custom dataset (0.28 MiB) which unifies the following:

    1. Global database of Martian impact craters ({@Robbins2012_crater_db.p}).
    2. Crater ages from both Hartmann and Neukum isochron methods ({@Robbins2013_crater_ages.p}).
    3. IAU-approved crater nomenclature ({@IAU_crater_names.p}}).

    For more information and code to reproduce the dataset, see <https://github.com/Humboldt-Penguin/redplanet/tree/main/datasets/Craters>{target="_blank"} -- TODO: I'll eventually have a section on my website to describe datasets and how we modified them, add a link to that here.

    Parameters
    ----------
    crater_id : None | str | list[str], optional
        Unique crater identifier formatted ##-######, where the first two numbers indicate the Mars subquad and the last six number the craters in that subquad from largest to smallest diameter.
    name : None | str | list[str], optional
        Crater name according to official IAU nomenclature (as of 2024-11-26).
    lon : None | tuple[float, float], optional
        Filter craters whose center falls within this range of longitudes.

        The given range must be a subset of either [-180,180] or [0,360] -- e.g. `lon=[-170,350]` is not allowed (it doesn't make sense).
    lat : None | tuple[float, float], optional
        Filter craters whose center falls within this range of latitudes.
    diameter : None | tuple[float, float], optional
        Filter craters whose diameter falls within this range, in kilometers.
    has_age : None | bool, optional
        If True, only return craters with both Hartmann/Neukum isochron ages available. Default is False.
    as_df : bool, optional
        If True, return a pandas DataFrame. Default is False, which returns a list of dictionaries.

    Returns
    -------
    list[dict] | pd.DataFrame
        Filtered list of craters with keys/columns:

        - `id` : str
            - Unique crater identifier formatted ##-######, where the first two numbers indicate the Mars subquad and the last six number the craters in that subquad from largest to smallest diameter.
        - `name` : str
            - Crater name according to official IAU nomenclature (as of 2024-11-26).
        - `lat` : float
            - Latitude of the crater center.
        - `lon` : float
            - Longitude of the crater center, in range [-180,180].
        - 'plon' : float
            - Longitude of the crater center, in range [0,360].
        - `diam` : float
            - Diameter of the crater, in km.
        - `['diam_sd', 'diam_elli_major', 'diam_elli_minor', 'diam_elli_angle', 'diam_elli_major_sd', 'diam_elli_minor_sd']` : float
            - For more info, see Appendix A of {@Robbins2012_crater_db.n}.
        - `['N_H(10)', 'N_N(10)', 'N_H(25)', 'N_N(25)', 'N_H(50)', 'N_N(50)', 'Hartmann Isochron Age', 'Neukum Isochron Age', 'Hartmann Turn-Off Diameter', 'Neukum Turn-Off Diameter']` : None | list[float, float, float]
            - When available, the ages are given in a list where the first value is the estimated age and second/third are uncertainties (they will always be negative/positive respectively). All values are in billions of years (aka "giga-annums"/"Ga").
            - For more info, see Supplementary Table 3 of {@Robbins2013_crater_ages.n}.
    """

    df = _get_dataset()

    if crater_id:
        if isinstance(crater_id, str):
            crater_id = [crater_id]
        df = df[ df['id'].isin(crater_id) ]

    if name:
        if isinstance(name, str):
            name = [name]
        df = df[ df['name'].isin(name) ]
        ## TODO: make names insensitive to case and special characters like apostrophes, e.g. "kovalsky" == "Koval'sky"


    if lon:
        _verify_coords(lon, 0)
        # lon = _plon2slon(lon)    ## this introduces unexpected/annoying behavior, TODO figure it out eventually lol (or add a plon col to df, and if any input lons are >180 then query that column instead lol)
        if lon[0] > 180 or lon[1] > 180:
            df = df[ df['plon'].between(lon[0], lon[1]) ]
        else:
            df = df[ df['lon'].between(lon[0], lon[1]) ]

    if lat:
        _verify_coords(0, lat)
        df = df[ df['lat'].between(lat[0], lat[1]) ]


    if diameter:
        df = df[ df['diam'].between(diameter[0], diameter[1]) ]

    if has_age:
        df = df[
            pd.notna(df['Hartmann Isochron Age']) &
            pd.notna(df['Neukum Isochron Age'])
        ]

    if not as_df:
        df = df.to_dict(orient='records')

    return df