Feature/issue 196 Add new feature type to query the API for lake data

nikki-t commented 3 months ago

Github Issue: #196

Description

Add new option for the "feature" request parameter for prior lakes. Allows querying of lake data through the API.

Overview of work done

Added new feature type of PriorLake.
Added new fields for lake data. See hydrocron.utils.constants.PRIOR_LAKE_ALL_COLUMNS.
Added new function call to retrieve lake data: get_prior_lake_series_by_feature_id.
Update existing documentation to include lake fields and example to retrieve lake data.

Overview of verification done

Added new test of lake data retrieval.
Added new test of lake data conversion to GeoPandas GeoDataFrame.

New and existing unit tests pass.

Overview of integration done

Deployed to SIT environment and ran the following queries.

Lake GeoJSON:

curl --location 'https://soto.podaac.sit.earthdatacloud.nasa.gov/hydrocron/v1/timeseries?feature=PriorLake&feature_id=6350036102&start_time=2024-07-20T00:00:00Z&end_time=2024-07-26T00:00:00Z&fields=lake_id,time_str,wse,area_total,quality_f,collection_shortname,crid,PLD_version,range_start_time&output=geojson'

Response

{
    "status": "200 OK",
    "time": 517.39,
    "hits": 1,
    "results": {
        "csv": "",
        "geojson": {
            "type": "FeatureCollection",
            "features": [
                {
                    "id": "0",
                    "type": "Feature",
                    "properties": {
                        "lake_id": "6350036102",
                        "time_str": "2024-07-25T22:48:23Z",
                        "wse": "260.802",
                        "area_total": "0.553409",
                        "quality_f": "1",
                        "collection_shortname": "SWOT_L2_HR_LakeSP_2.0",
                        "crid": "PIC0",
                        "PLD_version": "105",
                        "range_start_time": "2024-07-25T22:47:27Z",
                        "wse_units": "m",
                        "area_total_units": "km^2"
                    },
                    "geometry": {
                        "type": "Point",
                        "coordinates": [
                            -42.590727027987064,
                            -19.822613018107482
                        ]
                    }
                }
            ]
        }
    }
}

Lake CSV:

curl --location 'https://soto.podaac.sit.earthdatacloud.nasa.gov/hydrocron/v1/timeseries?feature=PriorLake&feature_id=6350036102&start_time=2024-07-20T00:00:00Z&end_time=2024-07-26T00:00:00Z&fields=lake_id,time_str,wse,area_total,quality_f,collection_shortname,crid,PLD_version,range_start_time&output=csv'

Response

{
    "status": "200 OK",
    "time": 335.996,
    "hits": 1,
    "results": {
        "csv": "lake_id,time_str,wse,area_total,quality_f,collection_shortname,crid,PLD_version,range_start_time,wse_units,area_total_units\n6350036102,2024-07-25T22:48:23Z,260.802,0.553409,1,SWOT_L2_HR_LakeSP_2.0,PIC0,105,2024-07-25T22:47:27Z,m,km^2\n",
        "geojson": {}
    }
}

Lake compact GeoJSON:

curl --location 'https://soto.podaac.sit.earthdatacloud.nasa.gov/hydrocron/v1/timeseries?feature=PriorLake&feature_id=6350036102&start_time=2024-07-20T00:00:00Z&end_time=2024-07-26T00:00:00Z&fields=lake_id,time_str,wse,area_total,quality_f,collection_shortname,crid,PLD_version,range_start_time&output=geojson&compact=true'

Response

{
    "status": "200 OK",
    "time": 363.813,
    "hits": 1,
    "results": {
        "csv": "",
        "geojson": {
            "type": "FeatureCollection",
            "features": [
                {
                    "id": "0",
                    "type": "Feature",
                    "properties": {
                        "lake_id": [
                            "6350036102"
                        ],
                        "time_str": [
                            "2024-07-25T22:48:23Z"
                        ],
                        "wse": [
                            "260.802"
                        ],
                        "area_total": [
                            "0.553409"
                        ],
                        "quality_f": [
                            "1"
                        ],
                        "collection_shortname": [
                            "SWOT_L2_HR_LakeSP_2.0"
                        ],
                        "crid": [
                            "PIC0"
                        ],
                        "PLD_version": [
                            "105"
                        ],
                        "range_start_time": [
                            "2024-07-25T22:47:27Z"
                        ],
                        "wse_units": [
                            "m"
                        ],
                        "area_total_units": [
                            "km^2"
                        ]
                    },
                    "geometry": {
                        "type": "Point",
                        "coordinates": [
                            -42.590727027987064,
                            -19.822613018107482
                        ]
                    }
                }
            ]
        }
    }
}

*Note: Only one time step

Lake compact CSV:

curl --header "Accept: text/csv" --location 'https://soto.podaac.sit.earthdatacloud.nasa.gov/hydrocron/v1/timeseries?feature=PriorLake&feature_id=6350036102&start_time=2024-07-20T00:00:00Z&end_time=2024-07-26T00:00:00Z&fields=lake_id,time_str,wse,area_total,quality_f,collection_shortname,crid,PLD_version,range_start_time'

Response

"lake_id,time_str,wse,area_total,quality_f,collection_shortname,crid,PLD_version,range_start_time,wse_units,area_total_units\n6350036102,2024-07-25T22:48:23Z,260.802,0.553409,1,SWOT_L2_HR_LakeSP_2.0,PIC0,105,2024-07-25T22:47:27Z,m,km^2\n"

PR checklist:

[X] Linted
[X] Updated unit tests
[X] Updated changelog
[X] Integration testing

See Pull Request Review Checklist for pointers on reviewing this pull request

nikki-t commented 3 months ago

Unit tests show this warning:

tests/test_api.py::test_timeseries_lambda_handler_json_lake
  /Users/tebaldi/Documents/workspace/hydrocron/workspace/hydrocron/hydrocron/db/io/swot_shp.py:135: UserWarning: Geometry is in a geographic CRS. Results from 'centroid' are likely incorrect. Use 'GeoSeries.to_crs()' to re-project geometries to a projected CRS before this operation.

    geodf_centerpoint['geometry'] = geodf_polygon['geometry'].centroid

@torimcd - Have you seen this before? Do you think this is an issue?

frankinspace commented 3 months ago

Was curious and found this explanation of the warning: https://gis.stackexchange.com/q/372564

I don't think the accuracy of the centroid we use is particularly important for our use case so I think what is here is ok but open to other opinions

torimcd commented 3 months ago

Agreed, I don't think the accuracy is important here. I've been ignoring that warning since we aren't using the centroid to do anything more than facilitate returning valid geojson. We can open a new issue to fix it if the warning is annoying, but should probably add a note to the documentation in the meantime.

podaac / hydrocron