planetarypy 0.32.1
Python Tools for Planetary Science
License: MIT License
Requires Python: >=3.9
Keywords: planetary science, data analysis

PlanetaryPy
================

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

# PlanetaryPy

> Beta release: This will become (part of) the core package of the
> [PlanetaryPy](https://planetarypy.org/) organisation.

Potential logo:![image.png](images/plp_logo_candidate.png)

## Install

``` bash
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](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_parquet.html)
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`](https://michaelaye.github.io/planetarypy/api/utils.html#url_retrieve),
among other stuff.

## Experiment/Instrument Specific

So far, `planetarypy` supports CTX EDR and HiRISE RGB.NOMAP data. Look
at the
[`CTX`](https://michaelaye.github.io/planetarypy/api/ctx.html#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](api/02c_pds.apps.ipynb) for more details.

``` python
from planetarypy.pds.apps import get_index
```

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

<div>
<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>
<table border="1" class="dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>VOLUME_ID</th>
      <th>FILE_SPECIFICATION_NAME</th>
      <th>ORIGINAL_PRODUCT_ID</th>
      <th>PRODUCT_ID</th>
      <th>IMAGE_TIME</th>
      <th>INSTRUMENT_ID</th>
      <th>INSTRUMENT_MODE_ID</th>
      <th>LINE_SAMPLES</th>
      <th>LINES</th>
      <th>SPATIAL_SUMMING</th>
      <th>...</th>
      <th>SUB_SOLAR_LATITUDE</th>
      <th>SUB_SPACECRAFT_LONGITUDE</th>
      <th>SUB_SPACECRAFT_LATITUDE</th>
      <th>SOLAR_DISTANCE</th>
      <th>SOLAR_LONGITUDE</th>
      <th>LOCAL_TIME</th>
      <th>IMAGE_SKEW_ANGLE</th>
      <th>RATIONALE_DESC</th>
      <th>DATA_QUALITY_DESC</th>
      <th>ORBIT_NUMBER</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>86101</th>
      <td>MROX_2757</td>
      <td>DATA/J07_047671_1256_XN_54S338W.IMG</td>
      <td>4A_04_10F0036A00</td>
      <td>J07_047671_1256_XN_54S338W</td>
      <td>2016-09-27 00:24:54.682</td>
      <td>CTX</td>
      <td>NIFL</td>
      <td>2528</td>
      <td>8192</td>
      <td>1</td>
      <td>...</td>
      <td>-19.41</td>
      <td>338.09</td>
      <td>-54.43</td>
      <td>207762612.4</td>
      <td>230.58</td>
      <td>15.48</td>
      <td>90.1</td>
      <td>Crater in Noachis Terra</td>
      <td>OK</td>
      <td>47671</td>
    </tr>
    <tr>
      <th>54420</th>
      <td>MROX_1819</td>
      <td>DATA/D10_031170_1808_XN_00N221W.IMG</td>
      <td>4A_04_109C017D00</td>
      <td>D10_031170_1808_XN_00N221W</td>
      <td>2013-03-21 06:58:09.892</td>
      <td>CTX</td>
      <td>NIFL</td>
      <td>5056</td>
      <td>7168</td>
      <td>1</td>
      <td>...</td>
      <td>-24.39</td>
      <td>221.52</td>
      <td>0.88</td>
      <td>209925149.5</td>
      <td>286.15</td>
      <td>14.49</td>
      <td>90.1</td>
      <td>Ride-along with HiRISE</td>
      <td>OK</td>
      <td>31170</td>
    </tr>
    <tr>
      <th>71053</th>
      <td>MROX_2331</td>
      <td>DATA/F10_039530_1470_XI_33S203W.IMG</td>
      <td>4A_04_10C9000F00</td>
      <td>F10_039530_1470_XI_33S203W</td>
      <td>2015-01-01 16:20:01.840</td>
      <td>CTX</td>
      <td>ITL</td>
      <td>5056</td>
      <td>52224</td>
      <td>1</td>
      <td>...</td>
      <td>-25.3</td>
      <td>203.96</td>
      <td>-33.12</td>
      <td>207070298.2</td>
      <td>263.93</td>
      <td>15.2</td>
      <td>90.4</td>
      <td>Terrain in Terra Cimmeria</td>
      <td>OK</td>
      <td>39530</td>
    </tr>
    <tr>
      <th>51385</th>
      <td>MROX_1742</td>
      <td>DATA/D04_028919_2026_XN_22N327W.IMG</td>
      <td>4A_04_109002A800</td>
      <td>D04_028919_2026_XN_22N327W</td>
      <td>2012-09-26 21:17:00.483</td>
      <td>CTX</td>
      <td>NIFL</td>
      <td>5056</td>
      <td>6144</td>
      <td>1</td>
      <td>...</td>
      <td>0.67</td>
      <td>327.06</td>
      <td>22.78</td>
      <td>219814412.3</td>
      <td>178.44</td>
      <td>15.53</td>
      <td>90.1</td>
      <td>Ride-along with HiRISE</td>
      <td>OK</td>
      <td>28919</td>
    </tr>
    <tr>
      <th>51923</th>
      <td>MROX_1757</td>
      <td>DATA/D05_029283_1524_XN_27S180W.IMG</td>
      <td>4A_04_1092020B00</td>
      <td>D05_029283_1524_XN_27S180W</td>
      <td>2012-10-25 05:44:21.786</td>
      <td>CTX</td>
      <td>NIFL</td>
      <td>5056</td>
      <td>9216</td>
      <td>1</td>
      <td>...</td>
      <td>-6.28</td>
      <td>178.36</td>
      <td>-27.56</td>
      <td>214830233.7</td>
      <td>194.72</td>
      <td>15.57</td>
      <td>90.1</td>
      <td>Ride-along with HiRISE</td>
      <td>OK</td>
      <td>29283</td>
    </tr>
  </tbody>
</table>
<p>5 rows × 51 columns</p>
</div>

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

<div>
<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>
<table border="1" class="dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>VOLUME_ID</th>
      <th>FILE_NAME_SPECIFICATION</th>
      <th>INSTRUMENT_HOST_ID</th>
      <th>INSTRUMENT_ID</th>
      <th>OBSERVATION_ID</th>
      <th>PRODUCT_ID</th>
      <th>PRODUCT_VERSION_ID</th>
      <th>TARGET_NAME</th>
      <th>ORBIT_NUMBER</th>
      <th>MISSION_PHASE_NAME</th>
      <th>...</th>
      <th>LINE_PROJECTION_OFFSET</th>
      <th>SAMPLE_PROJECTION_OFFSET</th>
      <th>CORNER1_LATITUDE</th>
      <th>CORNER1_LONGITUDE</th>
      <th>CORNER2_LATITUDE</th>
      <th>CORNER2_LONGITUDE</th>
      <th>CORNER3_LATITUDE</th>
      <th>CORNER3_LONGITUDE</th>
      <th>CORNER4_LATITUDE</th>
      <th>CORNER4_LONGITUDE</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>144822</th>
      <td>MROHR_0001</td>
      <td>RDR/ESP/ORB_074100_074199/ESP_074107_1410/ESP_...</td>
      <td>MRO</td>
      <td>HIRISE</td>
      <td>ESP_074107_1410</td>
      <td>ESP_074107_1410_COLOR</td>
      <td>1</td>
      <td>MARS</td>
      <td>74107</td>
      <td>Extended Science Phase</td>
      <td>...</td>
      <td>-4568562.5</td>
      <td>2009279.5</td>
      <td>-38.7446</td>
      <td>159.311</td>
      <td>-38.7465</td>
      <td>159.287</td>
      <td>-38.614</td>
      <td>159.269</td>
      <td>-38.6121</td>
      <td>159.293</td>
    </tr>
    <tr>
      <th>22518</th>
      <td>MROHR_0001</td>
      <td>RDR/ESP/ORB_014000_014099/ESP_014080_1040/ESP_...</td>
      <td>MRO</td>
      <td>HIRISE</td>
      <td>ESP_014080_1040</td>
      <td>ESP_014080_1040_RED</td>
      <td>1</td>
      <td>MARS</td>
      <td>14080</td>
      <td>Extended Science Phase</td>
      <td>...</td>
      <td>-3193960.0</td>
      <td>-845180.0</td>
      <td>-76.0185</td>
      <td>165.215</td>
      <td>-76.0315</td>
      <td>164.858</td>
      <td>-75.6958</td>
      <td>164.658</td>
      <td>-75.6831</td>
      <td>165.005</td>
    </tr>
    <tr>
      <th>86634</th>
      <td>MROHR_0001</td>
      <td>RDR/ESP/ORB_046300_046399/ESP_046395_1730/ESP_...</td>
      <td>MRO</td>
      <td>HIRISE</td>
      <td>ESP_046395_1730</td>
      <td>ESP_046395_1730_COLOR</td>
      <td>1</td>
      <td>MARS</td>
      <td>46395</td>
      <td>Extended Science Phase</td>
      <td>...</td>
      <td>-1584330.0</td>
      <td>-26573400.0</td>
      <td>-6.9957</td>
      <td>292.569</td>
      <td>-6.9979</td>
      <td>292.551</td>
      <td>-6.6838</td>
      <td>292.51</td>
      <td>-6.6815</td>
      <td>292.529</td>
    </tr>
    <tr>
      <th>138163</th>
      <td>MROHR_0001</td>
      <td>RDR/ESP/ORB_069100_069199/ESP_069178_2345/ESP_...</td>
      <td>MRO</td>
      <td>HIRISE</td>
      <td>ESP_069178_2345</td>
      <td>ESP_069178_2345_RED</td>
      <td>1</td>
      <td>MARS</td>
      <td>69178</td>
      <td>Extended Science Phase</td>
      <td>...</td>
      <td>12762196.0</td>
      <td>15708938.0</td>
      <td>53.8598</td>
      <td>76.7591</td>
      <td>53.8474</td>
      <td>76.602</td>
      <td>54.0013</td>
      <td>76.5672</td>
      <td>54.0137</td>
      <td>76.7249</td>
    </tr>
    <tr>
      <th>125490</th>
      <td>MROHR_0001</td>
      <td>RDR/ESP/ORB_063500_063599/ESP_063504_1995/ESP_...</td>
      <td>MRO</td>
      <td>HIRISE</td>
      <td>ESP_063504_1995</td>
      <td>ESP_063504_1995_COLOR</td>
      <td>1</td>
      <td>MARS</td>
      <td>63504</td>
      <td>Extended Science Phase</td>
      <td>...</td>
      <td>4638178.5</td>
      <td>12794202.0</td>
      <td>19.4523</td>
      <td>124.149</td>
      <td>19.45</td>
      <td>124.128</td>
      <td>19.5686</td>
      <td>124.113</td>
      <td>19.5709</td>
      <td>124.133</td>
    </tr>
  </tbody>
</table>
<p>5 rows × 54 columns</p>
</div>

## Instrument tools

### CTX

``` python
from planetarypy.ctx import CTX
```

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

    'J07_047671_1256_XN_54S338W'

``` python
ctx = CTX(pid)
ctx
```

    PRODUCT_ID: J07_047671_1256_XN_54S338W
    URL: https://pds-imaging.jpl.nasa.gov/data/mro/mars_reconnaissance_orbiter/ctx/mrox_2757/data/J07_047671_1256_XN_54S338W.IMG
    source_path: /remote/trove/geo/planet/Mars/CTX/pds/mrox_2757/J07_047671_1256_XN_54S338W.IMG
    Shape: (8192, 2528)

``` python
ctx.source_path
```

    Path('/remote/trove/geo/planet/Mars/CTX/pds/mrox_2757/J07_047671_1256_XN_54S338W.IMG')

``` python
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).

<div id="refs" class="references csl-bib-body hanging-indent">

<div id="ref-laura_jason_2022_7443567" class="csl-entry">

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>.

</div>

</div>