planetarypy 0.26.7

Python Tools for Planetary Science

PlanetaryPy

Potential logo:

Install

pip install planetarypy

This will pull in these other dependencies and their dependencies:

tomlkit pandas pvl numpy python-dateutil tqdm lxml yarl hirise-tools kalasiris

Suggested standard abbreviations:

• Inside these docs the package will be called PLPY for brevity.
• A standard Python import could be: plp or plpy
  • because the last p in plp can be pronounced out, we consider these equivalent for human conversation and pronounce these “plippy”.

General scope

First and foremost this package should provide support in working with planetary science data.

With working we mean:

• locating
• retrieving
• reading
• further processing

of data.

Locating

This library manages, via its PDS tools, multiple PDS3 index files per instrument that can be used for identifying data of interest. These index files are automatically downloaded and converted to the very performant (and cloud-ready) parquet file format. > Parquet is able to store advanced datatypes like nan-capable integer and full datetime objects, as opposed to HDF5.

Retrieving

The interface to getting data is via a path-retrieving function based on a PDS product-id. If that product-id is available locally, the path will be returned. If it is not, it will previously be downloaded, stored in a systematic fashion organized by mission and instrument, and then the local path will be returned.

Reading

For now, the library only returns the path to the object and the user needs to sort out the reading process. A recently funded NASA project Planetary Data Reader will be integrated here, so that basic reading into memory can be provided.

As such, we anticipate two classes of reading support: 1. basic reading into numpy and/or xarray 1. added reader functionality like basic plots and basic geospatial processing, as supported by interested parties

There will exist larger other packages that focus on working with a given instrument’s data, in which case that package could become an affiliated package with the planetarypy GitHub organization, if so desired.

Further processing

In the future, additional frequently used procedures will be added to this library, e.g. * frequently used GDAL/rasterio procedures * frequently used SPICE operations * like surface illumination on a given body

PDS tools

Look at the Apps docs to see what pds.apps exist for easily getting PDS indexes. The find_index app is specifically useful when you don’t know what index files exist.

So far, the following indexes are supported (but not necessarily all tested within PLPY):

• Cassini
  • ISS (all)
  • UVIS (all)
• MRO
  • CTX EDR
  • HiRISE
    • EDR, RDR, DTM
      • EDR index has a bug (as delivered by the team, reported), where I need to activate an existing fix for it.
• LRO
  • Diviner (DLRE)
    • EDR, RDR
  • LOLA
    • EDR, RDR

More indexes

More indexes of other instruments can be easily added by following the existing structure of what has been copied into your config at ~/.planetarypy_config.toml.

Please consider submitting a pull request for adding further PDS index files into the config file at its source: https://github.com/michaelaye/nbplanetary/blob/master/planetarypy/data/planetarypy_config.toml

Utils

Find something in Utils for working with NASA timestamps and a well working URL download function url_retrieve, among other stuff.

Experiment/Instrument Specific

So far, planetarypy supports CTX EDR and HiRISE RGB.NOMAP data. Look at the CTX and HiRISE pages for descriptions of classes for working with these data.

Bug reports

Please submit bug reports at https://github.com/michaelaye/nbplanetary/issues

How to use

Indexes

See PDS apps for more details.

from planetarypy.pds.apps import get_index

ctrindex = get_index("mro.ctx", "edr")
ctrindex.sample(5, random_state=42)  # setting random_state to always get same files for docs

<style scoped> .dataframe tbody tr th:only-of-type { vertical-align: middle; }

.dataframe tbody tr th {
    vertical-align: top;
}

.dataframe thead th {
    text-align: right;
}

</style>

	VOLUME_ID	FILE_SPECIFICATION_NAME	ORIGINAL_PRODUCT_ID	PRODUCT_ID	IMAGE_TIME	INSTRUMENT_ID	INSTRUMENT_MODE_ID	LINE_SAMPLES	LINES	SPATIAL_SUMMING	...	SUB_SOLAR_LATITUDE	SUB_SPACECRAFT_LONGITUDE	SUB_SPACECRAFT_LATITUDE	SOLAR_DISTANCE	SOLAR_LONGITUDE	LOCAL_TIME	IMAGE_SKEW_ANGLE	RATIONALE_DESC	DATA_QUALITY_DESC	ORBIT_NUMBER
102927	MROX_3290	DATA/K09_056855_1472_XN_32S152W.IMG	4A_04_112001B600	K09_056855_1472_XN_32S152W	2018-09-12 15:27:23.819	CTX	NIFL	5056	7168	1	...	-23.61	152.16	-32.84	206674590.7	248.70	15.12	90.1	Ride-along with HiRISE	OK	56855
116952	MROX_3714	DATA/N08_065442_0965_XN_83S191W.IMG	4A_04_114C019800	N08_065442_0965_XN_83S191W	2020-07-12 17:31:23.962	CTX	NIFL	5056	33792	1	...	-21.24	190.23	-83.51	207154930.4	237.37	17.12	91.4	Planum Australe	OK	65442
16386	MROX_0690	DATA/B01_010083_2567_XI_76N181W.IMG	4A_04_103101E100	B01_010083_2567_XI_76N181W	2008-09-20 04:33:05.584	CTX	ITL	5056	52224	1	...	19.30	180.80	76.84	237461101.1	129.80	14.76	89.7	North polar outlier	OK	10083
107515	MROX_3450	DATA/K15_059059_1434_XN_36S196W.IMG	4A_04_112C004300	K15_059059_1434_XN_36S196W	2019-03-03 08:44:14.027	CTX	NIFL	2528	9216	1	...	-4.38	196.66	-36.69	229158765.3	349.79	14.21	90.1	Craters in Terra Cimmeria	OK	59059
57288	MROX_1890	DATA/D16_033513_1653_XI_14S108W.IMG	4A_04_10A9016F00	D16_033513_1653_XI_14S108W	2013-09-19 20:45:34.363	CTX	ITL	5056	15360	1	...	10.17	108.53	-14.83	241359283.4	24.21	14.66	90.2	Syria/Claritas dust-raising event monitoring site	OK	33513

5 rows × 51 columns

hirise_rdr = get_index("mro.hirise", "rdr")
hirise_rdr.sample(5, random_state=42)

<style scoped> .dataframe tbody tr th:only-of-type { vertical-align: middle; }

.dataframe tbody tr th {
    vertical-align: top;
}

.dataframe thead th {
    text-align: right;
}

</style>

	VOLUME_ID	FILE_NAME_SPECIFICATION	INSTRUMENT_HOST_ID	INSTRUMENT_ID	OBSERVATION_ID	PRODUCT_ID	PRODUCT_VERSION_ID	TARGET_NAME	ORBIT_NUMBER	MISSION_PHASE_NAME	...	LINE_PROJECTION_OFFSET	SAMPLE_PROJECTION_OFFSET	CORNER1_LATITUDE	CORNER1_LONGITUDE	CORNER2_LATITUDE	CORNER2_LONGITUDE	CORNER3_LATITUDE	CORNER3_LONGITUDE	CORNER4_LATITUDE	CORNER4_LONGITUDE
95782	MROHR_0001	RDR/ESP/ORB_049400_049499/ESP_049456_0945/ESP_...	MRO	HIRISE	ESP_049456_0945	ESP_049456_0945_COLOR	1	MARS	49456	Extended Science Phase	...	289555.5	1014477.5	-85.6701	286.4690	-85.6815	286.3020	-85.5562	284.8560	-85.5452	285.0210
142902	MROHR_0001	RDR/ESP/ORB_072700_072799/ESP_072755_2030/ESP_...	MRO	HIRISE	ESP_072755_2030	ESP_072755_2030_RED	1	MARS	72755	Extended Science Phase	...	5448057.5	-36148404.0	22.8511	342.4710	22.8408	342.3770	22.9836	342.3590	22.9940	342.4520
114241	MROHR_0001	RDR/ESP/ORB_057400_057499/ESP_057400_1150/ESP_...	MRO	HIRISE	ESP_057400_1150	ESP_057400_1150_RED	1	MARS	57400	Extended Science Phase	...	-15324106.0	9551808.0	-65.0631	99.2951	-65.0739	99.1184	-64.9297	99.0696	-64.9190	99.2454
260	MROHR_0001	RDR/PSP/ORB_001300_001399/PSP_001390_2290/PSP_...	MRO	HIRISE	PSP_001390_2290	PSP_001390_2290_RED	2	MARS	1390	Primary Science Phase	...	11574100.0	-17349000.0	48.8086	283.9690	48.7969	283.8150	48.9486	283.7880	48.9603	283.9430
148555	MROHR_0001	RDR/ESP/ORB_075600_075699/ESP_075617_0955/ESP_...	MRO	HIRISE	ESP_075617_0955	ESP_075617_0955_RED	1	MARS	75617	Extended Science Phase	...	1299053.5	-203581.5	-84.5200	10.3353	-84.5620	9.6666	-84.4557	8.9553	-84.4145	9.6167

5 rows × 54 columns

Instrument tools

CTX

from planetarypy.ctx import CTX

Unable to display output for mime type(s): application/javascript, application/vnd.holoviews_load.v0+json

Unable to display output for mime type(s): application/javascript, application/vnd.holoviews_load.v0+json

<style>.bk-root, .bk-root .bk:before, .bk-root .bk:after { font-family: var(--jp-ui-font-size1); font-size: var(--jp-ui-font-size1); color: var(--jp-ui-font-color1); } </style>

pid = ctrindex.sample(random_state=42).squeeze().PRODUCT_ID
pid

'K09_056855_1472_XN_32S152W'

ctx = CTX(pid)
ctx

PRODUCT_ID: K09_056855_1472_XN_32S152W
URL: https://pds-imaging.jpl.nasa.gov/data/mro/mars_reconnaissance_orbiter/ctx/mrox_3290/data/K09_056855_1472_XN_32S152W.IMG
source_path: /home/ayek72/mnt/troveplanets/pds/mrox_3290/K09_056855_1472_XN_32S152W.IMG
Shape: (7168, 5056)

ctx.source_path

Path('/home/ayek72/mnt/troveplanets/pds/mrox_3290/K09_056855_1472_XN_32S152W.IMG')

ctx.download()

File exists. Use `overwrite=True` to download fresh.

Acknowledgements

The creation of this library was in part supported by:

• NASA Cassini UVIS mission
• NASA SSW grant NNX15AH36G
• NASA PDART grant 80NSSC20K0875
• NASA SSW grant 80NSSC20K0748
• German Space Agency (DLR Bonn), grant 50 OO 2204, on behalf of the German Federal Ministry for Economic Affairs and Climate Action.
• This research has made use of the USGS Integrated Software for Imagers and Spectrometers (ISIS)(Laura et al. 2022).

Laura, Jason, Alex Acosta, Travis Addair, Lauren Adoram-Kershner, James Alexander, Oleg Alexandrov, Stacey Alley, et al. 2022. Integrated Software for Imagers and Spectrometers (version 7.2.0_RC1). Zenodo. https://doi.org/10.5281/zenodo.7443567.