Dev environmental exposure

Agents/FenlandTrajectoryAgent/.gitignore

@@ -5,6 +5,7 @@ build/
 dist/
 *~*
 .idea/
+!.vscode/
 py4jps/
 coverage.xml
 .coverage

Agents/FenlandTrajectoryAgent/.vscode/launch.json

@@ -0,0 +1,68 @@
+{
+
+    "version": "0.2.0",
+    "configurations": [
+      {
+        "type": "python",
+        "name": "Build and Debug (Flask)",
+        "request": "attach",
+        "host": "localhost",
+        "port": "${input:debug.port}",
+        "preLaunchTask": "compose-build-deploy",
+        "pathMappings": [
+          {
+            "localRoot": "${workspaceFolder}/agent",
+            "remoteRoot": "/app/agent"
+          }
+        ]
+      },
+      {
+        "type": "python",
+        "name": "Debug (Flask)",
+        "request": "attach",
+        "host": "localhost",
+        "port": "${input:debug.port}",
+        "preLaunchTask": "compose-deploy",
+        "pathMappings": [
+          {
+            "localRoot": "${workspaceFolder}/agent",
+            "remoteRoot": "/app/agent"
+          }
+        ]
+      },
+
+      {
+        "type": "python",
+        "name": "Reattach and Debug (Flask)",
+        "request": "attach",
+        "host": "localhost",
+        "port": "${input:debug.port.read}",
+        "pathMappings": [
+          {
+            "localRoot": "${workspaceFolder}/agent",
+            "remoteRoot": "/app/agent"
+          }
+        ]
+      }
+    ],
+    "inputs": [
+      {
+        "id": "debug.port",
+        "type": "command",
+        "command": "shellCommand.execute",
+        "args": {
+          "command": "bash ./stack.sh ports write",
+          "useFirstResult": true
+        }
+      },
+      {
+        "id": "debug.port.read",
+        "type": "command",
+        "command": "shellCommand.execute",
+        "args": {
+          "command": "bash ./stack.sh ports read",
+          "useFirstResult": true
+        }
+      }
+    ]
+  }

Agents/FenlandTrajectoryAgent/.vscode/tasks.json

@@ -0,0 +1,76 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+      {
+        "type": "shell",
+        "label": "compose-build",
+        "command": "./stack.sh",
+        "args": ["build", "--debug-port", "${input:debug.port}"],
+        "group": {
+          "kind": "build",
+          "isDefault": true
+        },
+        "windows": {
+          "options": {
+            "shell": {
+              "executable": "bash"
+            }
+          }
+        }
+      },
+      {
+        "type": "shell",
+        "label": "compose-deploy-internal",
+        "command": "./stack.sh",
+        "args": [
+          "start",
+          "${input:stackName}",
+          "--debug-port",
+          "${input:debug.port}"
+        ],
+        "windows": {
+          "options": {
+            "shell": {
+              "executable": "bash"
+            }
+          }
+        }
+      },
+      {
+        "type": "shell",
+        "label": "compose-deploy",
+        "command": "sleep 1",
+        "dependsOn": ["compose-deploy-internal"],
+        "windows": {
+          "options": {
+            "shell": {
+              "executable": "powershell"
+            }
+          }
+        }
+      },
+      {
+        "type": "shell",
+        "label": "compose-build-deploy",
+        "dependsOn": ["compose-build", "compose-deploy"],
+        "dependsOrder": "sequence"
+      }
+    ],
+    "inputs": [
+      {
+        "id": "stackName",
+        "type": "promptString",
+        "description": "Name your stack.",
+        "default": "CEW-DT"
+      },
+      {
+        "id": "debug.port",
+        "type": "command",
+        "command": "shellCommand.execute",
+        "args": {
+          "command": "bash ./stack.sh ports read",
+          "useFirstResult": true
+        }
+      }
+    ]
+  }

Agents/FenlandTrajectoryAgent/README.md

@@ -1,9 +1,8 @@
 # 1. Description
 
-The `Fenland Trajectory Agent` is a specialized tool for batch instantiation of structured time-series GPS trajectory data. This agent is capable of receiving HTTP POST requests or CURL commands to load GPS trajectory files, which it subsequently instantiates into triples before uploading them into the knowledge graph.
-
-Presently, the agent focuses on data from the Fenland Study to analyze the interaction between GPS trajectories and environmental features within the context of a digital twin. Example data can be found at Dropbox/CoMo_shared/_Projects/c4e-AI-for-public-health/sample_gps_data.csv. By default, the data instantiated from the Fenland Study using this agent encompasses Speed, Height, Distance, Heading, Latitude, and Longitude. This method is also applicable to other categories of time-series structured data in Fenland Study by replacing or adding the relevant column names. The information instantiated into the knowledge graph adheres to the Ontology of Devices [OntoDevice] in [TheWorldAvatar] project. The instantiation process is executed based on the [TimeSeriesClient]. This agent is implemented as a Docker container, designed for deployment within a stack managed by the [Stack Manager]
+The `Fenland Trajectory Agent` is a specialised tool designed to both instantiate structured time-series GPS trajectory data into a knowledge graph and perform quantitative exposure calculations between these trajectories and environmental features. This agent is implemented as a Docker container, designed for deployment within a stack managed by the [Stack Manager]. The agent receives [HTTP POST] requests or Client URL ([CURL]) commands to perform specified tasks. These include loading GPS trajectory files, mapping them into RDF triples, and uploading them to the stack. Additionally, for an exposure radius of interest, the agent can interpret environmental features and perform corresponding exposure calculations automatically. Examples of these calculations include determining the number of food retail locations or greenspace objects within the defined radius.
 
+Presently, the agent focuses on data from the Fenland Study to analyze the interaction between GPS trajectories and environmental features within the context of a digital twin. Example gps data can be found at Dropbox/CoMo_shared/_Projects/c4e-AI-for-public-health/sample_gps_data.csv. By default, the data instantiated from the Fenland Study using this agent encompasses Speed, Height, Distance, Heading, Latitude, and Longitude. This method is also applicable to other categories of time-series structured data in Fenland Study by replacing or adding the relevant column names. The information instantiated into the knowledge graph adheres to the Ontology of Devices [OntoDevice] in [TheWorldAvatar] project. The instantiation process is executed based on the [TimeSeriesClient]. In terms of environmental features from the Fenland Study, the raw data is stored in Dropbox/CoMo_shared/_Projects/c4e-AI-for-public-health/Data/Raw data/. Uploading and instantiating environmental data requires the [Stack-data-uploader] tool, and configuration files can be found in the [AI-for-Public-Health] folder. 
 
 # 2. Agent Setup
 
@@ -81,9 +80,11 @@ To spin up the stack, create `postgis_password` and `geoserver_password` files i
 
 # 4. Using the Agent
 
-The agent will automatically register a task upon startup to assimilate the data from the target GPS folder into the Knowledge Graph (KG). This background task can be triggered via an HTTP request after the agent has started, accessible at http://localhost:{Port}/fenland-trajectory-agent. Please replace {Port} with the numerical value of the port on which your stack is running.
+## 4.1 Data Ingestion
+
+The agent will automatically register a task upon startup to assimilate the data from the target GPS folder into the Knowledge Graph (KG). This background task can be triggered via an HTTP request after the agent has started, accessible at http://localhost:{Port}/fenland-trajectory-agent. Please replace {Port} with the numerical value of the port on which your stack is running. 
 
-## Functionality Description
+### Functionality Description
 
 The operation of this agent is streamlined into two key steps: **Preprocess** and **Instantiate**. Here is a brief description of each:
 
@@ -95,15 +96,41 @@ Importantly, the preprocessing step must be completed before moving on to the in
 
 In addition to the core functionality, this agent offers a route task called layer_generator that creates GeoServer layers from PostGIS tables for visualisation. Given a table name (formed by UUID) and latitude/longitude column names, the agent deploys the [SQL commands for virtual-table generation], creates vector objects, and communicates with the GeoServer REST API to publish the layer. Please note that this functionality is specialized and typically requires manual examination of SQL commands and layer metadata (such as EPSG) to ensure compatibility with specific requirements. This functionality will be further updated and refined after the AI for Public Health (Fenland) project's visualisation is switched to [TWA-VF] 5.4.0.
 
-## Example HTTP Requests
-Example HTTP requests for preprocessing and instantiating data are available in detailed HTTP files. You can access these examples at the [preprocess] file, the [instantiate] file, and the [layer_generator] file. 
+### Example HTTP Requests
+Example requests for preprocessing and instantiating data are available in detailed HTTP files. You can access these examples at the [preprocess] file, the [instantiate] file, and the [layer_generator] file. 
+
+Additionally, services above can be triggered using CURL from a bash terminal. An example CURL command used to load the GPS trajectory files is displayed in [CURL commands folder]. 
+
+## 4.2 Count-Based Exposure Calculation
+
+The agent is configured to calculate exposure by listening to trajectory IRIs and environmental feature IRIs along with a specified exposure radius. 
+The calculation can be triggered via an HTTP request after the agent has started, accessible at http://localhost:{Port}/fenland-trajectory-agent. 
+
+### Functionality Description
+
+The workflow begins by generating a buffer zone around the trajectory geometry, with the buffer extending outward from the trajectory line by a specified exposure radius. Environmental features, such as food retail locations or greenspaces, are then identified and counted based on their intersections with this buffer zone, providing a quantitative measure of exposure. To accommodate different data storage scenarios, the agent provides two routes for exposure calculations:
+
+- **Exposure_count**:  
+This route is used when the environmental data and the Fenland Trajectory Agent are deployed in different stacks. In this case, you need to update the [config.properties] file with the following parameters:
+
+```
+ENV_DATA_ENDPOINT_URL (a SPARQL endpoint)
+TRAJECTORY_DB_HOST
+```
+
+For example, when using an Ontop SPARQL endpoint as `ENV_DATA_ENDPOINT_URL` with data such as Food Retail and Greenspace, the matching [OBDA mappings] should be configured in advance by [Stack-data-uploader]. Once these settings are complete, the agent will fetch the geometry data for both environmental features and trajectories from the specified endpoint and database, temporarily store the data in a dataframe, and perform the calculations within the agent.
+
+A typical example involves using an Ontop SPARQL endpoint as `ENV_DATA_ENDPOINT_URL`, where this Ontop endpoint can originate from any other stack created by the [Stack Manager]. Food Retail and Greenspace datasets can be used as demonstration cases. When uploading these structured datasets to the stack, the [Stack-data-uploader] should be preconfigured with particular [OBDA mapping] files containing key metadata, such as FeatureType and SourceTableName. These mappings are essential, as the exposure calculation relies on this metadata to trigger the appropriate computation methods.
 
-Additionally, services above can be triggered using Client URL (CURL) from a bash terminal. An example CURL command used to load the GPS trajectory files is displayed in [CURL commands folder]. 
+- **Exposure_count_single_stack**: If the environmental data and the Fenland Trajectory Agent are deployed in the same stack.
+This route is used when the environmental data and the Fenland Trajectory Agent are deployed in the same stack. In this case, the agent will query the Ontop SPARQL endpoint deployed within the same stack to fetch the datasource table name corresponding to the trajectory IRI. The agent will then populate an query and execute the calculation internally within the stack.
 
+### Example HTTP Requests
+Example requests are available in detailed HTTP files. You can access these examples at the [exposure_count] file and the [exposure_count_single_stack] file. Services can also be triggered using CURL from a bash terminal. Examples are displayed in [CURL commands folder]. 
 
  
 # Authors
-Jiying Chen ([email protected]), May 2024
+Jiying Chen ([email protected]), Jan 2025
 
 
 <!-- Links -->
@@ -140,6 +167,10 @@ Jiying Chen ([email protected]), May 2024
 [ISO 8601]: https://www.iso.org/iso-8601-date-and-time-format.html
 [knowledge graph operations guidance]: https://cambridge-cares.github.io/TheWorldAvatar/examples/sparql/
 [TWA-VF]: https://github.com/cambridge-cares/TheWorldAvatar/tree/main/web/twa-vis-framework
+[Stack-data-uploader]: https://github.com/cambridge-cares/TheWorldAvatar/tree/main/Deploy/stacks/dynamic/stack-data-uploader
+[AI-for-Public-Health]: https://github.com/cambridge-cares/TheWorldAvatar/tree/main/Deploy/stacks/AI4PublicHealth
+[HTTP POST]: https://www.w3schools.com/tags/ref_httpmethods.asp
+[CURL]: https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-web-client-urls
 
 <!-- files -->
 [Dockerfile]: ./Dockerfile
@@ -157,3 +188,7 @@ Jiying Chen ([email protected]), May 2024
 [layer_generator]: ./example-requests/SendHTTP/layer_generator.http
 [KGClient]: ./agent/kgutils/kgclient.py
 [SQL commands for virtual-table generation]: ./agent/layergenerator/virtual_table.sql
+[config.properties]:./agent/flaskapp/exposure/config.properties
+[exposure_count]: ./example-requests/SendHTTP/exposure_count.http
+[exposure_count_single_stack]: ./example-requests/SendHTTP/exposure_count_single_stack.http
+[OBDA mapping]: ./resources/ontop.obda

Agents/FenlandTrajectoryAgent/agent/buffer_creator/buffer.py

@@ -0,0 +1,70 @@
+import psycopg2
+import logging
+from typing import Optional, Any
+
+def connect_to_database(
+    host: str, port: int, user: str, password: str, database: str
+) -> psycopg2.extensions.connection:
+    """
+    Establish a connection to the PostgreSQL database.
+    Raises an exception if the connection fails.
+    """
+    try:
+        logging.info("Starting database connection...")
+        connection = psycopg2.connect(
+            host=host,
+            port=port,
+            user=user,
+            password=password,
+            database=database,
+            connect_timeout=10
+        )
+        logging.info("Connected to the database.")
+        return connection
+    except psycopg2.Error as e:
+        logging.error(f"Error connecting to the database: {e}")
+        raise e
+
+
+def execute_query(connection: psycopg2.extensions.connection, query: str, params: Optional[tuple] = None) -> Any:
+    """
+    Execute a query on the database and fetch results.
+    Returns the results of the query.
+    """
+    try:
+        with connection.cursor() as cursor:
+            logging.info(f"Executing query: {query}")
+            cursor.execute(query, params)
+            results = cursor.fetchall()
+            if results:
+                logging.info(f"Query returned {len(results)} rows.")
+            else:
+                logging.info("Query returned no results.")
+            return results
+    except psycopg2.Error as e:
+        logging.error(f"Error executing query: {e}")
+        raise e
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+
+    # Connection details
+    host = "localhost"
+    port = 5432
+    user = "postgres"
+    password = "1111"
+    database = "postgres"
+
+    # SQL Query
+    query = 'SELECT "Council" FROM "fr_cambridge";'
+
+    try:
+        # Connect to database
+        with connect_to_database(host, port, user, password, database) as conn:
+            results = execute_query(conn, query)
+            if results:
+                for row in results:
+                    print(row[0])
+    except Exception as e:
+        logging.error(f"An error occurred: {e}")