Area Aggregation Model¶

The area aggregation model ("area_aggregation") aggregates attribute values from source entities (points, lines, or polygons) to target polygon areas.

Use cases include:

Aggregating traffic flows from road segments to municipality boundaries
Computing maximum emissions within administrative areas
Calculating cumulative metrics over time within geographic regions

To set up this model properly, you must first determine a target entity group in a dataset. This entity group must have a polygon geometry defined. You can then define one or more aggregations that map attributes from source entity groups onto this target entity group, based on overlap. A source entity is mapped to a target entity if it at least partially overlaps (intersects). This means that an entity may be counted towards multiple target polygons. The source_attribute attribute on the mapped source entities are then aggregrated using to given aggregation function and the result is written to the target_attribute attribute of the target entity.

Aggregation Functions¶

The model supports the following aggregation functions:

Instantaneous functions

min - Minimum value of source entities within each target area
max - Maximum value of source entities within each target area
average - Weighted average of source values (weights based on entity overlap)
sum - Weighted sum of source values

Time-integral functions

integral / integral_seconds - Cumulative sum over time (in seconds)
integral_minutes - Cumulative sum over time (in minutes)
integral_hours - Cumulative sum over time (in hours)
integral_days - Cumulative sum over time (in days)

when using a time integral function, it is important to choose the right aggregation function based on the time-unit of the source attribute. If the unit of the source attribute is in “per second”, then use the integral or integral_seonds function. If time source attribute is in “per minutes”, then use the integral_minutes attribute, etc. The chosen integral function has no effect on the interval between updates from this model. When choosing a time-integral function, you should also specify the "output_interval" configuration option.

Source Geometries¶

The model determines which source entities fall within each target polygon based on the source_geometry setting:

point - Point entities are matched if they fall within the target polygon
line - Line entities are matched if they intersect the target polygon
polygon - Polygon entities are matched if they intersect the target polygon

When a source entity overlaps multiple target polygons its contribution is divided over every matching polygon equally. The (relative) overlap over all matched areas is not factored in.

Configuration Options¶

Option	Type	Description
target_entity_group	array	`[dataset_name, entity_group_name]` for target polygons (required)
aggregations	array	List of aggregation configurations (required)
output_interval	number	Interval in seconds between outputs (optional)

Aggregation Configuration¶

Each aggregation in the aggregations array has the following options:

Option	Type	Description
source_entity_group	array	`[dataset_name, entity_group_name]` for the entity that should be aggregated
source_geometry	string	Source geometry type: `"point"`, `"line"`, or `"polygon"`
source_attribute	string	Attribute to aggregate from `source_entity_group`
target_attribute	string	Attribute to store aggregated values
function	string	Aggregation function (see above)

Example Configurations¶

Aggregating traffic flows to municipalities:

{
    "name": "railway_municipalities_aggregation",
    "type": "area_aggregation",
    "target_entity_group": ["municipalities_area_set", "area_entities"],
    "aggregations": [
        {
            "source_entity_group": ["railway_network", "track_segment_entities"],
            "source_geometry": "line",
            "source_attribute": "transport.cargo_flow",
            "target_attribute": "transport.cargo_flow.railways"
            "function": "max",
        },
        {
            "source_entity_group": ["railway_network", "track_segment_entities"],
            "source_geometry": "line",
            "source_attribute": "transport.energy_consumption.hours",
            "target_attribute": "transport.cumulative_energy",
            "function": "integral_hours"
        }
    ]
}

Multiple source datasets to single target:

{
    "name": "road_aggregation",
    "type": "area_aggregation",
    "target_entity_group": ["municipalities_area_set", "area_entities"],
    "aggregations": [
        {
            "source_entity_group": ["road_network", "road_segment_entities"],
            "source_geometry": "line"
            "source_attribute": "transport.passenger_vehicle_flow",
            "target_attribute": "transport.passenger_vehicle_flow",
            "function": "max",
        },
        {
            "source_entity_group": ["road_network", "road_segment_entities"],
            "source_geometry": "line"
            "source_attribute": "transport.cargo_vehicle_flow",
            "target_attribute": "transport.cargo_vehicle_flow",
            "function": "max",
        }
    ]
}

Notes¶

When a source entity overlaps multiple target polygons, its contribution is split equally between the overlapping targets.
Time-integral functions accumulate values over the simulation duration. The target attribute is initialized to zero and updated incrementally.
The output_interval option can be used to control how frequently the model produces outputs. It must be set when using any of the integral

Config Schema Reference¶

AreaAggregationConfig¶

type: object

properties:: target_entity_group: AreaAggregationEntityGroup (required)

aggregations: Aggregations (required)

output_interval: number Interval in seconds between outputs

AreaAggregationEntityGroup¶

type: array

A tuple of two strings: [dataset_name, entity_group_name]

Aggregations¶

type: array
items: Aggregation
minItems: 1

Aggregation¶

type: object

properties:: source_entity_group: AreaAggregationEntityGroup (required)

source_attribute: string Attribute to aggregate from source entities (required)

target_attribute: string Attribute to store aggregated values (required)

function: string Aggregation function: "min", "max", "average", "sum", "integral", "integral_seconds", "integral_minutes", "integral_hours", or "integral_days" (required)

source_geometry: string Source geometry type: "point", "line", or "polygon" (required)