p4tools 0.13.3
Tools for working with data from the Planet Four Zooniverse project.
License: MIT License
Requires Python: >=3.10
Keywords: zooniverse citizen_science panoptes

# p4tools


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

[![PyPI
version](https://img.shields.io/pypi/v/p4tools.svg)](https://pypi.python.org/pypi/p4tools)

## Installation

``` bash
pip install p4tools
```

## Features

- Provide easy access to the Planet Four catalog data.
  - Data will be automatically downloaded and cached by the `pooch`
    library.
  - The first time it will take a few seconds to download the data, the
    next time it will be using the cache.
- Provide automatic downloading of the png tiles of the catalog.
- Provide plotting tools

> Note: The original data for input to the Planet Four projects were
> these `_COLOR` products like this one:
> https://hirise-pds.lpl.arizona.edu/PDS/EXTRAS/RDR/ESP/ORB_011400_011499/ESP_011486_0980/ESP_011486_0980_IRB.NOMAP.browse.jpg
> (not the browse product though, but the full size of course)

## Paper

The underlying paper for this work is:

> Aye, K.-M., Schwamb, M.E., Portyankina, G., Hansen, C.J., McMaster,
> A., Miller, G.R.M., Carstensen, B., Snyder, C., Parrish, M., Lynn, S.,
> Mai, C., Miller, D., Simpson, R.J., Smith, A.M., 2019. Planet Four:
> Probing springtime winds on Mars by mapping the southern polar CO2 jet
> deposits. Icarus 319, 558–598.
> https://doi.org/10.1016/j.icarus.2018.08.018

``` python
from p4tools import io
```

``` python
# get the catalogs
fans = io.get_fan_catalog()
blotches = io.get_blotch_catalog()
fans.head()
```

<div>
<style scoped>
    .dataframe tbody tr th:only-of-type {
        vertical-align: middle;
    }
&#10;    .dataframe tbody tr th {
        vertical-align: top;
    }
&#10;    .dataframe thead th {
        text-align: right;
    }
</style>

|  | marking_id | angle | distance | tile_id | image_x | image_y | n_votes | obsid | spread | version | ... | y_angle | l_s | map_scale | north_azimuth | BodyFixedCoordinateX | BodyFixedCoordinateY | BodyFixedCoordinateZ | PlanetocentricLatitude | PlanetographicLatitude | Longitude |
|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|
| 0 | F000000 | 205.56 | 179.71 | APF0000ci9 | 2270.76 | 24336.16 | 35 | ESP_012079_0945 | 88.03 | 1 | ... | -0.43 | 214.785 | 0.25 | 126.856883 | -65.804336 | 261.407884 | -3370.504345 | -85.427383 | -85.480829 | 104.129523 |
| 1 | F000001 | 185.39 | 179.62 | APF0000cia | 3391.21 | 5640.60 | 15 | ESP_012079_0945 | 21.35 | 1 | ... | -0.09 | 214.785 | 0.25 | 126.856883 | -67.219114 | 257.011589 | -3370.631413 | -85.493546 | -85.546226 | 104.656897 |
| 2 | F000002 | 184.98 | 500.27 | APF0000cia | 3509.96 | 5876.70 | 10 | ESP_012079_0945 | 18.91 | 1 | ... | -0.09 | 214.785 | 0.25 | 126.856883 | -67.170611 | 257.055226 | -3370.630794 | -85.493039 | -85.545725 | 104.644396 |
| 3 | F000004 | 184.29 | 105.43 | APF0000cia | 3716.27 | 5824.50 | 6 | ESP_012079_0945 | 26.41 | 1 | ... | -0.07 | 214.785 | 0.25 | 126.856883 | -67.127761 | 257.024926 | -3370.635002 | -85.493723 | -85.546401 | 104.637107 |
| 4 | F000005 | 189.42 | 109.50 | APF0000cia | 3452.17 | 6033.00 | 3 | ESP_012079_0945 | 22.58 | 1 | ... | -0.16 | 214.785 | 0.25 | 126.856883 | -67.169940 | 257.096267 | -3370.628302 | -85.492368 | -85.545061 | 104.642019 |

<p>5 rows × 24 columns</p>
</div>

``` python
# get fans for a given tile_id
fans_for_tile = io.get_fans_for_tile("APF0000cro")
fans_for_tile.head()
```

<div>
<style scoped>
    .dataframe tbody tr th:only-of-type {
        vertical-align: middle;
    }
&#10;    .dataframe tbody tr th {
        vertical-align: top;
    }
&#10;    .dataframe thead th {
        text-align: right;
    }
</style>

|  | marking_id | angle | distance | tile_id | image_x | image_y | n_votes | obsid | spread | version | ... | y_angle | l_s | map_scale | north_azimuth | BodyFixedCoordinateX | BodyFixedCoordinateY | BodyFixedCoordinateZ | PlanetocentricLatitude | PlanetographicLatitude | Longitude |
|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|
| 639 | F00028e | 176.82 | 357.51 | APF0000cro | 1904.17 | 469.07 | 30 | ESP_012079_0945 | 29.52 | 1 | ... | 0.06 | 214.785 | 0.25 | 126.856883 | -68.025795 | 255.956937 | -3370.658673 | -85.507336 | -85.559856 | 104.883467 |
| 640 | F00028f | 177.09 | 122.21 | APF0000cro | 1948.37 | 602.24 | 25 | ESP_012079_0945 | 22.86 | 1 | ... | 0.05 | 214.785 | 0.25 | 126.856883 | -68.003644 | 255.983513 | -3370.657733 | -85.506997 | -85.559521 | 104.877359 |
| 641 | F000290 | 177.02 | 137.73 | APF0000cro | 1666.29 | 290.83 | 24 | ESP_012079_0945 | 19.18 | 1 | ... | 0.05 | 214.785 | 0.25 | 126.856883 | -68.096623 | 255.937481 | -3370.658914 | -85.507347 | -85.559867 | 104.899357 |
| 642 | F000291 | 178.83 | 97.55 | APF0000cro | 1875.95 | 400.38 | 16 | ESP_012079_0945 | 35.51 | 1 | ... | 0.02 | 214.785 | 0.25 | 126.856883 | -68.038458 | 255.943748 | -3370.659367 | -85.507498 | -85.560016 | 104.886848 |
| 643 | F000292 | 178.56 | 108.57 | APF0000cro | 2316.12 | 491.00 | 4 | ESP_012079_0945 | 52.76 | 1 | ... | 0.03 | 214.785 | 0.25 | 126.856883 | -67.928961 | 255.925385 | -3370.666710 | -85.508282 | -85.560791 | 104.864970 |

<p>5 rows × 24 columns</p>
</div>

### Metadata

Metadata for the HiRISE observions that were used for the input data to
the project:

``` python
# get the metadata of the HiRISE images
metadata = io.get_meta_data()
```

``` python
metadata.head()
```

<div>
<style scoped>
    .dataframe tbody tr th:only-of-type {
        vertical-align: middle;
    }
&#10;    .dataframe tbody tr th {
        vertical-align: top;
    }
&#10;    .dataframe thead th {
        text-align: right;
    }
</style>

|  | OBSERVATION_ID | IMAGE_CENTER_LATITUDE | IMAGE_CENTER_LONGITUDE | SOLAR_LONGITUDE | START_TIME | map_scale | north_azimuth | \# of tiles |
|----|----|----|----|----|----|----|----|----|
| 0 | ESP_011296_0975 | -82.1965 | 225.2530 | 178.833 | 2008-12-23 16:15:26 | 1.0 | 110.600107 | 91 |
| 1 | ESP_011341_0980 | -81.7969 | 76.1304 | 180.809 | 2008-12-27 04:25:02 | 0.5 | 110.208923 | 126 |
| 2 | ESP_011348_0950 | -85.0427 | 259.0940 | 181.117 | 2008-12-27 17:29:17 | 1.0 | 123.624057 | 91 |
| 3 | ESP_011350_0945 | -85.2160 | 181.4150 | 181.205 | 2008-12-27 21:14:01 | 0.5 | 99.672793 | 126 |
| 4 | ESP_011351_0945 | -85.2157 | 181.5480 | 181.249 | 2008-12-27 23:05:54 | 1.0 | 127.960688 | 91 |

</div>

``` python
# get the lat/lon or BodyFixedcoordinates of the tiles
coords = io.get_tile_coords()
coords.head()
```

<div>
<style scoped>
    .dataframe tbody tr th:only-of-type {
        vertical-align: middle;
    }
&#10;    .dataframe tbody tr th {
        vertical-align: top;
    }
&#10;    .dataframe thead th {
        text-align: right;
    }
</style>

|  | x_tile | y_tile | x_hirise | y_hirise | PlanetocentricLatitude | PlanetographicLatitude | PositiveEast360Longitude | BodyFixedCoordinateX | BodyFixedCoordinateY | BodyFixedCoordinateZ | tile_id | obsid |
|----|----|----|----|----|----|----|----|----|----|----|----|----|
| 0 | 1 | 1 | 420.0 | 324.0 | -85.504144 | -85.556701 | 104.952104 | -68.380674 | 256.056147 | -3370.636698 | APF0000cwz | ESP_012079_0945 |
| 1 | 1 | 2 | 420.0 | 872.0 | -85.502300 | -85.554878 | 104.934805 | -68.331337 | 256.181661 | -3370.628630 | APF0000ck9 | ESP_012079_0945 |
| 2 | 1 | 3 | 420.0 | 1420.0 | -85.500454 | -85.553054 | 104.917486 | -68.281853 | 256.307249 | -3370.620295 | APF0000cty | ESP_012079_0945 |
| 3 | 1 | 4 | 420.0 | 1968.0 | -85.498607 | -85.551228 | 104.900198 | -68.232522 | 256.433112 | -3370.615690 | APF0000ciy | ESP_012079_0945 |
| 4 | 1 | 5 | 420.0 | 2516.0 | -85.496762 | -85.549404 | 104.882968 | -68.183281 | 256.558509 | -3370.606455 | APF0000cwp | ESP_012079_0945 |

</div>

### Image tiles

The png tiles of the HiRISE images are automatically downloaded and
cached by the `pooch` library.

``` python
# get the urls of the tiles
tile_urls = io.get_tile_urls()
tile_urls.head()
```

<div>
<style scoped>
    .dataframe tbody tr th:only-of-type {
        vertical-align: middle;
    }
&#10;    .dataframe tbody tr th {
        vertical-align: top;
    }
&#10;    .dataframe thead th {
        text-align: right;
    }
</style>

|     | tile_id    | tile_url                                          |
|-----|------------|---------------------------------------------------|
| 0   | APF0000coq | http://www.planetfour.org/subjects/standard/50... |
| 1   | APF0000cro | http://www.planetfour.org/subjects/standard/50... |
| 2   | APF0000cs6 | http://www.planetfour.org/subjects/standard/50... |
| 3   | APF0000co1 | http://www.planetfour.org/subjects/standard/50... |
| 4   | APF0000cpd | http://www.planetfour.org/subjects/standard/50... |

</div>

``` python
# or get the url for a tile id
io.get_url_for_tile("APF0000cro")
```

    'http://www.planetfour.org/subjects/standard/50e742bf5e2ed212400040a4.jpg'

``` python
# get the png as numpy array:
img = io.get_subframe_for_tile("APF0000cro")
img
```

    array([[[146,   1,   8],
            [146,   1,   6],
            [145,   0,   5],
            ...,
            [116,   3,   0],
            [115,   1,   0],
            [115,   3,   1]],

           [[147,   2,   7],
            [146,   1,   6],
            [145,   0,   2],
            ...,
            [119,   1,   0],
            [119,   1,   0],
            [117,   2,   0]],

           [[145,   3,   2],
            [145,   1,   1],
            [147,   0,   0],
            ...,
            [125,   0,   0],
            [124,   0,   0],
            [125,   0,   0]],

           ...,

           [[121,  96,  76],
            [126,  99,  80],
            [127,  99,  78],
            ...,
            [125,  93,  72],
            [124,  92,  71],
            [130,  98,  77]],

           [[118,  91,  70],
            [124,  97,  76],
            [123,  95,  74],
            ...,
            [130,  98,  77],
            [125,  93,  72],
            [130,  98,  75]],

           [[111,  84,  63],
            [116,  89,  68],
            [114,  83,  63],
            ...,
            [132, 100,  79],
            [127,  95,  72],
            [133, 101,  78]]], dtype=uint8)

``` python
io.get_hirise_id_for_tile("APF0000cro")
```

    'ESP_012079_0945'

## License

MIT license

## Credits

### Developer and Maintainer

- K.-Michael Aye <kmichael.aye@gmail.com>

### Contributors

- Some ideas and concepts came from Meg Schwamb