Exposure feature info agent

The purpose of this agent is to display results generated by the exposure calculation agent. The advantage of this over the standard Feature-Info-Agent is that this agent groups the exposure results in a format that is more suited for the calculation results, e.g.

{
    "Count": {"400 m": 10, "800 m": 50},
    "Area": {"400 m": 100, "800 m": 5000}
}

which is not possible with the standard feature info agent.

This agent is designed to be deployed on https://github.com/TheWorldAvatar/hd4-stack.

Routes

1. /feature-info-agent/get

   Mandatory parameter: iri

   Example request (handled by visualisation framework):

   curl http://localhost:3838/exposure-feature-info-agent/feature-info-agent/get?iri=http://subject

   This is for non-trajectory calculations where results are instantiated as triples.

2. /sql/feature-info-agent/get

   Alternative for /feature-info-agent/get which queries results using SQL instead of SPARQL.

3. /trajectory/feature-info-agent/get

   Parameters:

   • iri (mandatory): IRI of the trajectory (the instance that contains point time series)
   • trip (optional, mandatory IF trajectory contains trip information): trip index

   Example request (handled by visualisation framework):

   curl http://localhost:3838/exposure-feature-info-agent/trajectory/feature-info-agent/get?iri=http://subject&trip=1

   This is for trajectory based calculations where results are instantiated as time series.

4. /timeline

   Optional parameters:

   • lowerbound
   • upperbound
   • If neither is supplied, the complete trajectory is queried.

   Required header: Authorization: Bearer <ACCESS_TOKEN>.

   Supplied bounds are inclusive. Like the trip-agent, each bound is interpreted as a number when possible; otherwise it is parsed using the Java class declared by timeseries:hasTimeClass.

   Mandatory environment variables to configure:

   • KEYCLOAK_SERVER
   • KEYCLOAK_REALM

   curl --get 'http://localhost:3838/exposure-feature-info-agent/timeline' -H "Authorization: Bearer ${ACCESS_TOKEN}" --data-urlencode 'lowerbound=1700000000' --data-urlencode 'upperbound=1700086400'

   For a time series using java.time.Instant, ISO-8601 timestamps can be supplied instead:

   curl --get 'http://localhost:3838/exposure-feature-info-agent/timeline' -H "Authorization: Bearer ${ACCESS_TOKEN}" --data-urlencode 'lowerbound=2025-03-08T15:13:42.805Z' --data-urlencode 'upperbound=2025-03-08T17:30:19.359Z'

   Example response (illustrative values, with timestamp-based stay bounds):

   [
       {
           "key": "stay-1",
           "trip": 0,
           "lowerbound": "2025-03-08T15:13:42.805Z",
           "upperbound": "2025-03-08T15:30:00Z",
           "results": {
               "Green space": {
                   "collapse": true,
                   "Area": {
                       "collapse": true,
                       "400 m": "1200 m²",
                       "800 m": "5000 m²",
                       "display_order": ["400 m", "800 m"]
                   }
               }
           }
       },
       {
           "key": "trip-1",
           "trip": 1,
           "results": {
               "Green space": {
                   "collapse": true,
                   "Area": {
                       "collapse": true,
                       "400 m": "1800 m²",
                       "800 m": "6500 m²",
                       "display_order": ["400 m", "800 m"]
                   }
               }
           }
       },
       {
           "key": "stay-2",
           "trip": 0,
           "lowerbound": "2025-03-08T17:00:00Z",
           "upperbound": "2025-03-08T17:30:19.359Z",
           "results": {
               "Green space": {
                   "collapse": true,
                   "Area": {
                       "collapse": true,
                       "400 m": "2200 m²",
                       "800 m": "7000 m²",
                       "display_order": ["400 m", "800 m"]
                   }
               }
           }
       }
   ]

5. /timeline/getDatasets

   Required header: Authorization: Bearer <ACCESS_TOKEN>

   Mandatory environment variables to configure:

   • KEYCLOAK_SERVER
   • KEYCLOAK_REALM

   Datasets are assumed to be uploaded using the stack-data-uploader.

   Optional parameter: rdf_type, defaulting to http://www.w3.org/ns/dcat#Dataset. The submitted query is in the following form, where the class of ?dataset_iri will be substituted if the rdf_type parameter is provided.

   PREFIX dcat: <http://www.w3.org/ns/dcat#>
   PREFIX dcterms: <http://purl.org/dc/terms/>
   PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
   
   SELECT ?dataset_iri
       (COALESCE(MIN(STR(?label)), MIN(STR(?title))) AS ?name)
   WHERE {
       ?catalog a dcat:Catalog ;
               dcat:dataset ?dataset_iri .
   
       ?dataset_iri a <http://www.w3.org/ns/dcat#Dataset> ;
                   dcterms:title ?title .
   
       OPTIONAL {
           ?dataset_iri rdfs:label ?label .
       }
   }
   GROUP BY ?dataset_iri
   ORDER BY ?name ?dataset_iri

   Names in the result use rdfs:label or, if absent, dcterms:title (table name).

   curl --get 'http://localhost:3838/exposure-feature-info-agent/timeline/getDatasets' -H "Authorization: Bearer ${ACCESS_TOKEN}" --data-urlencode 'rdf_type=http://www.w3.org/ns/dcat#Dataset'

   Example response:

   [{"iri": "http://dataset", "name": "Heat dataset"}]

Build

Populate docker\credentials with repo_password.txt and repo_username.txt.

Then run the following to build the Docker image:

docker compose build

To push the image to the repository, run the following

docker compose push

Debugging

A debugging config is provided - https://github.com/TheWorldAvatar/hd4-stack/blob/main/stack-manager/inputs/config/services/exposure-feature-info-agent-debug.json, with an extra JAVA_OPTS environment variable and the debugging port is set to 5005.

To attach using VS code, the following config can be applied in launch.json:

{
    "type": "java",
    "name": "Reattach and Debug",
    "request": "attach",
    "hostName": "localhost",
    "port": "5005"
}

Note that some debugging features may not work if this repo folder is not named ExposureFeatureInfoAgent (e.g. being able to watch parameters).