Introduce PlotsAnalysisPlatformClient

This is a wrapper around Picterra's PlotsAnalysis platform public api.

Author: stephanerestani-picterra

docs/api.rst

@@ -9,6 +9,14 @@ DetectorPlatformClient
 .. autoclass:: picterra.APIClient
     :members:
 
+
+PlotsAnalysisPlatformClient
+---------------------------
+
+.. autoclass:: picterra.PlotsAnalysisPlatformClient
+    :members:
+
+
 Pagination
 ----------
 

examples/data/plots_analysis/example_plots.geojson

@@ -0,0 +1,67 @@
+{
+  "type": "FeatureCollection",
+  "features": [
+    {
+      "type": "Feature",
+      "properties": { "id": "PLOT-1"},
+      "geometry": {
+        "coordinates": [
+          [
+            [
+              -49.27362953726589,
+              -2.616445544400051
+            ],
+            [
+              -49.28121040069351,
+              -2.6284004278355297
+            ],
+            [
+              -49.271919906343896,
+              -2.627524039887618
+            ],
+            [
+              -49.26726341159804,
+              -2.6196814639718013
+            ],
+            [
+              -49.27362953726589,
+              -2.616445544400051
+            ]
+          ]
+        ],
+        "type": "Polygon"
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": { "id": "PLOT-2"},
+      "geometry": {
+        "coordinates": [
+          [
+            [
+              -49.26680302670468,
+              -2.620018411983054
+            ],
+            [
+              -49.26898505564435,
+              -2.6240857701543234
+            ],
+            [
+              -49.26509339578354,
+              -2.625613834998731
+            ],
+            [
+              -49.26291136684472,
+              -2.6214565953891764
+            ],
+            [
+              -49.26680302670468,
+              -2.620018411983054
+            ]
+          ]
+        ],
+        "type": "Polygon"
+      }
+    }
+  ]
+}

examples/plots_analysis.py

@@ -0,0 +1,25 @@
+import datetime
+import json
+
+from picterra import PlotsAnalysisPlatformClient
+
+# Replace this with the path to a GeoJSON file containing plot geometries
+# as a GeoJSON FeatureCollection of Polygons. In particular, each Feature
+# should have a unique "id" property.
+plots_feature_collection_filename = "data/plots_analysis/example_plots.geojson"
+
+client = PlotsAnalysisPlatformClient()
+
+# This will run the "EUDR Cocoa" deforestation risk analysis, discarding any
+# deforestation alerts happening after 2022-01-01.
+print("Starting analysis...")
+results = client.batch_analyze_plots(
+    plots_feature_collection_filename,
+    "eudr_cocoa",
+    datetime.datetime.fromisoformat("2022-01-01")
+)
+
+# The output of the analysis is a JSON file containing the input plots and their
+# associated deforestation risk.
+print("Analysis completed:")
+print(json.dumps(results, indent=2))

src/picterra/__init__.py

@@ -6,5 +6,6 @@
 from .detector_platform_client import DetectorPlatformClient as APIClient
 from .detector_platform_client import DetectorPlatformClient
 from .nongeo import nongeo_result_to_pixel
+from .plots_analysis_platform_client import PlotsAnalysisPlatformClient
 
-__all__ = ["APIClient", "DetectorPlatformClient", "nongeo_result_to_pixel", "APIError", "ResultsPage"]
+__all__ = ["APIClient", "DetectorPlatformClient", "PlotsAnalysisPlatformClient", "nongeo_result_to_pixel", "APIError", "ResultsPage"]

src/picterra/plots_analysis_platform_client.py

@@ -0,0 +1,78 @@
+"""
+Handles interfacing with the plots analysis api v1 documented at:
+https://app.picterra.ch/public/apidocs/plots_analysis/v1/
+
+Note that that Plots Analysis Platform is a separate product from the Detector platform and so
+an API key which is valid for one may encounter permissions issues if used with the other
+"""
+import datetime
+from typing import Literal
+
+import requests
+from requests.exceptions import RequestException
+
+from picterra.base_client import APIError, BaseAPIClient
+
+AnalysisMethodology = Literal["eudr_cocoa", "eudr_soy"]
+
+
+class PlotsAnalysisPlatformClient(BaseAPIClient):
+    def __init__(self, **kwargs):
+        super().__init__("public/api/plots_analysis/v1/", **kwargs)
+
+    def batch_analyze_plots(self, plots_geometries_filename: str, methodology: AnalysisMethodology, assessment_date: datetime.datetime):
+        """
+        Runs the specified methodology against the plot geometries stored in the provided file and
+        returns the analysis results.
+
+        Args:
+        - plots_geometries_filename: Path to a file containing the geometries of the plots to run the
+        analysis against.
+        - methodology: which analysis to run.
+        - assessment_date: the point in time at which the analysis should be evaluated.
+
+        Returns: the analysis results as a dict.
+        """
+        # Get an upload URL and analysis ID
+        resp = self.sess.post(self._full_url("batch_analysis/upload/"))
+        try:
+            resp.raise_for_status()
+        except RequestException as err:
+            raise APIError(
+                f"Failure obtaining an upload url and plots analysis ID: {err}"
+            )
+
+        analysis_id = resp.json()["analysis_id"]
+        upload_url = resp.json()["upload_url"]
+
+        # Upload the provided file
+        with open(plots_geometries_filename, "rb") as fh:
+            resp = requests.put(upload_url, data=fh.read())
+            try:
+                resp.raise_for_status()
+            except RequestException as err:
+                raise APIError(f"Failure uploading plots file for analysis: {err}")
+
+        # Start the analysis
+        data = {"methodology": methodology, "assessment_date": assessment_date.isoformat()}
+        resp = self.sess.post(
+            self._full_url(f"batch_analysis/start/{analysis_id}/"), data=data
+        )
+        try:
+            resp.raise_for_status()
+        except RequestException as err:
+            raise APIError(f"Couldn't start analysis for id: {analysis_id}: {err}")
+
+        # Wait for the operation to succeed
+        op_result = self._wait_until_operation_completes(resp.json())
+        download_url = op_result["results"]["download_url"]
+        resp = requests.get(download_url)
+        try:
+            resp.raise_for_status()
+        except RequestException as err:
+            raise APIError(
+                f"Failure to download results file from operation id {op_result['id']}: {err}"
+            )
+        results = resp.json()
+
+        return results

tests/test_plots_analysis_client.py

@@ -0,0 +1,64 @@
+import datetime
+import json
+import tempfile
+
+import responses
+
+from picterra import PlotsAnalysisPlatformClient
+from tests.utils import (
+    OP_RESP,
+    OPERATION_ID,
+    _add_api_response,
+    _client,
+    plots_analysis_api_url,
+)
+
+
+def test_plots_analysis_platform_client_base_url(monkeypatch):
+    """
+    Sanity-check that the client defaults to the correct base url
+    """
+    monkeypatch.setenv("PICTERRA_API_KEY", "1234")
+    client = PlotsAnalysisPlatformClient()
+    assert client.base_url == "https://app.picterra.ch/public/api/plots_analysis/v1/"
+
+
+@responses.activate
+def test_analyse_plots(monkeypatch):
+    # Setup the fake api responses
+    fake_analysis_id = "1234-4321-5678"
+    fake_analysis_results = { "foo": "bar" }
+    _add_api_response(
+        plots_analysis_api_url("batch_analysis/upload/"),
+        responses.POST,
+        {
+            "analysis_id": fake_analysis_id,
+            "upload_url": "https://example.com/upload/to/blobstore?key=123567",
+        },
+    )
+
+    responses.put("https://example.com/upload/to/blobstore?key=123567")
+
+    _add_api_response(plots_analysis_api_url(f"batch_analysis/start/{fake_analysis_id}/"), responses.POST, OP_RESP)
+    _add_api_response(plots_analysis_api_url(f"operations/{OPERATION_ID}/"), responses.GET, {
+        "status": "success",
+        "results": {
+            "download_url": "https://example.com/blobstore/results",
+            "expiration": "2022-12-31",
+        }
+    })
+    responses.get(
+        "https://example.com/blobstore/results",
+        json.dumps(fake_analysis_results)
+    )
+
+    client: PlotsAnalysisPlatformClient = _client(monkeypatch, platform="plots_analysis")
+    with tempfile.NamedTemporaryFile() as tmp:
+        with open(tmp.name, "w") as f:
+            json.dump({"foo": "bar"}, f)
+        results = client.batch_analyze_plots(
+            tmp.name,
+            methodology="eudr_cocoa",
+            assessment_date=datetime.datetime.fromisoformat("2020-01-01"),
+        )
+    assert results == fake_analysis_results

tests/utils.py

@@ -2,7 +2,7 @@
 
 import responses
 
-from picterra.detector_platform_client import DetectorPlatformClient
+from picterra import DetectorPlatformClient, PlotsAnalysisPlatformClient
 
 
 def _add_api_response(
@@ -37,6 +37,8 @@ def _client(monkeypatch, platform="detector", max_retries=0, timeout=1, **kwargs
     monkeypatch.setenv("PICTERRA_API_KEY", "1234")
     if platform == "detector":
         client = DetectorPlatformClient(timeout=timeout, max_retries=max_retries, **kwargs)
+    elif platform == "plots_analysis":
+        client = PlotsAnalysisPlatformClient(timeout=timeout, max_retries=max_retries, **kwargs)
     else:
         raise NotImplementedError(f"Unrecognised API platform {platform}")
     return client
@@ -46,6 +48,10 @@ def detector_api_url(path):
     return urljoin(TEST_API_URL, urljoin("public/api/v2/", path))
 
 
+def plots_analysis_api_url(path):
+    return urljoin(TEST_API_URL, urljoin("public/api/plots_analysis/v1/", path))
+
+
 TEST_API_URL = "http://example.com/"
 TEST_POLL_INTERVAL = 0.1
 OPERATION_ID = 21