Aggregate network objects

CHANGELOG.md

@@ -5,6 +5,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 ### Added
+- [#601] Implemented new flowclient API entrypoint, aggregate_network_objects(), to access (with simplified parameters) equivalent flowmachine query
+
 - [#581] Implemented new flowclient API entrypoint, total_network_objects(), to access (with simplified parameters) equivalent flowmachine query
 
 - [#577] Implemented new flowclient API entrypoint, location_introversion(), to access (with simplified parameters) equivalent flowmachine query

docs/notebook_preamble.py

@@ -89,6 +89,10 @@ def format_dict(x):
         "permissions": {"run": True, "poll": True, "get_result": True},
         "spatial_aggregation": ["admin3", "admin2", "admin1"],
     },
+    "aggregate_network_objects": {
+        "permissions": {"run": True, "poll": True, "get_result": True},
+        "spatial_aggregation": ["admin3", "admin2", "admin1"],
+    },
 }
 
 TOKEN = make_token(

docs/source/4-developer.md

@@ -90,6 +90,10 @@ The API exposes four routes:
 
 At present, the following query types are accessible through FlowAPI:
 
+- `aggregate_network_objects`
+
+    Statistics about unique cells/sites aggregated to a period.
+
 - `daily_location`
 
     A statistic representing where subscribers are on a given day, aggregated to a spatial unit.

flowauth/backend/flowauth/models.py

@@ -523,6 +523,7 @@ def make_demodata():  # pragma: no cover
         "unique_subscriber_counts",
         "location_introversion",
         "total_network_objects",
+        "aggregate_network_objects",
     ):
         c = Capability(name=c)
         db.session.add(c)

flowclient/flowclient/__init__.py

@@ -31,6 +31,7 @@
     unique_subscriber_counts,
     location_introversion,
     total_network_objects,
+    aggregate_network_objects,
 )
 
 __all__ = [
@@ -54,4 +55,5 @@
     "unique_subscriber_counts",
     "location_introversion",
     "total_network_objects",
+    "aggregate_network_objects",
 ]

flowclient/flowclient/client.py

@@ -1022,3 +1022,31 @@ def total_network_objects(
         "end_date": end_date,
         "aggregation_unit": aggregation_unit,
     }
+
+
+def aggregate_network_objects(
+    start_date: str, end_date: str, aggregation_unit: str
+) -> dict:
+    """
+    Return query spec for aggregate network objects
+
+    Parameters
+    ----------
+    start_date : str
+        ISO format date of the first day of the count, e.g. "2016-01-01"
+    end_date : str
+        ISO format date of the day _after_ the final date of the count, e.g. "2016-01-08"
+    aggregation_unit : str
+        Unit of aggregation, e.g. "admin3"
+
+    Returns
+    -------
+    dict
+        Dict which functions as the query specification
+    """
+    return {
+        "query_kind": "aggregate_network_objects",
+        "start_date": start_date,
+        "end_date": end_date,
+        "aggregation_unit": aggregation_unit,
+    }

flowmachine/flowmachine/core/server/query_schemas/aggregate_network_objects.py

@@ -0,0 +1,45 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+from marshmallow import Schema, fields, post_load
+from marshmallow.validate import OneOf, Length
+
+from flowmachine.features import AggregateNetworkObjects
+from .base_exposed_query import BaseExposedQuery
+from .custom_fields import AggregationUnit
+
+__all__ = ["AggregateNetworkObjectsSchema", "AggregateNetworkObjectsExposed"]
+
+
+class AggregateNetworkObjectsSchema(Schema):
+
+    start_date = fields.Date(required=True)
+    end_date = fields.Date(required=True)
+    aggregation_unit = AggregationUnit()
+
+    @post_load
+    def make_query_object(self, params):
+        return AggregateNetworkObjectsExposed(**params)
+
+
+class AggregateNetworkObjectsExposed(BaseExposedQuery):
+    def __init__(self, *, start_date, end_date, aggregation_unit):
+        # Note: all input parameters need to be defined as attributes on `self`
+        # so that marshmallow can serialise the object correctly.
+        self.start_date = start_date
+        self.end_date = end_date
+        self.aggregation_unit = aggregation_unit
+
+    @property
+    def _flowmachine_query_obj(self):
+        """
+        Return the underlying flowmachine aggregate_network_objects object.
+
+        Returns
+        -------
+        Query
+        """
+        return AggregateNetworkObjects(
+            start=self.start_date, stop=self.end_date, level=self.aggregation_unit
+        )

flowmachine/flowmachine/core/server/query_schemas/flowmachine_query.py

@@ -27,6 +27,10 @@
     LocationIntroversionExposed,
 )
 from .total_network_objects import TotalNetworkObjectsSchema, TotalNetworkObjectsExposed
+from .aggregate_network_objects import (
+    AggregateNetworkObjectsSchema,
+    AggregateNetworkObjectsExposed,
+)
 from .dfs_metric_total_amount import (
     DFSTotalMetricAmountSchema,
     DFSTotalMetricAmountExposed,
@@ -48,6 +52,7 @@ class FlowmachineQuerySchema(OneOfSchema):
         "unique_subscriber_counts": UniqueSubscriberCountsSchema,
         "location_introversion": LocationIntroversionSchema,
         "total_network_objects": TotalNetworkObjectsSchema,
+        "aggregate_network_objects": AggregateNetworkObjectsSchema,
         "dfs_metric_total_amount": DFSTotalMetricAmountSchema,
     }
 
@@ -76,6 +81,8 @@ def get_obj_type(self, obj):
             return "location_introversion"
         elif isinstance(obj, TotalNetworkObjectsExposed):
             return "total_network_objects"
+        elif isinstance(obj, AggregateNetworkObjectsExposed):
+            return "aggregate_network_objects"
         elif isinstance(obj, DFSTotalMetricAmountExposed):
             return "dfs_metric_total_amount"
         else:

flowmachine/flowmachine/features/network/total_network_objects.py

@@ -203,7 +203,7 @@ def aggregate(self, by=None, statistic="avg"):
         )
 
 
-class AggregateNetworkObjects(GeoDataMixin, Query):
+class AggregateNetworkObjects(TotalNetworkObjects, Query):
     """
     Class for calculating statistics about unique cells/sites
     and aggregate it by period.

integration_tests/tests/flowmachine_server_tests/test_server.py

@@ -55,6 +55,7 @@ def test_get_available_queries(send_zmq_message_and_receive_reply):
                 "unique_subscriber_counts",
                 "location_introversion",
                 "total_network_objects",
+                "aggregate_network_objects",
                 "dfs_metric_total_amount",
             ]
         },

integration_tests/tests/flowmachine_server_tests/test_server.test_api_spec_of_flowmachine_query_schemas.approved.txt

@@ -87,6 +87,7 @@
   "FlowmachineQuerySchema": {
     "discriminator": {
       "mapping": {
+        "aggregate_network_objects": "#/components/schemas/AggregateNetworkObjects",
         "daily_location": "#/components/schemas/DailyLocation",
         "dfs_metric_total_amount": "#/components/schemas/DFSTotalMetricAmount",
         "dummy_query": "#/components/schemas/DummyQuery",
@@ -104,6 +105,9 @@
       "propertyName": "query_kind"
     },
     "oneOf": [
+      {
+        "$ref": "#/components/schemas/AggregateNetworkObjects"
+      },
       {
         "$ref": "#/components/schemas/DFSTotalMetricAmount"
       },
@@ -145,6 +149,33 @@
       }
     ]
   },
+  "AggregateNetworkObjects": {
+    "properties": {
+      "aggregation_unit": {
+        "enum": [
+          "admin0",
+          "admin1",
+          "admin2",
+          "admin3"
+        ],
+        "type": "string"
+      },
+      "end_date": {
+        "format": "date",
+        "type": "string"
+      },
+      "start_date": {
+        "format": "date",
+        "type": "string"
+      }
+    },
+    "required": [
+      "aggregation_unit",
+      "end_date",
+      "start_date"
+    ],
+    "type": "object"
+  },
   "Flows": {
     "properties": {
       "aggregation_unit": {

integration_tests/tests/test_queries.py

@@ -59,6 +59,14 @@
                 "direction": "in",
             },
         ),
+        (
+            "aggregate_network_objects",
+            {
+                "start_date": "2016-01-01",
+                "end_date": "2016-01-02",
+                "aggregation_unit": "admin3",
+            },
+        ),
         # (
         #     # TODO: currently flowclient.modal_location() doesn't accept a 'locations'
         #     # argument but rather expects a list of location objects. We can't test this