Contour tool

Introduced 0.13.0

The ContourTool, which an agent sees as FindConcentrations, answers where is it worst — where activity clusters, where density peaks, where the busiest area is.

It returns nested regions, each enclosing a share of the total, rather than a single bounding box. That distinction matters: concentration is rarely one blob. A hull tells you the extent of your data; a contour tells you the shape of its concentration, and those are different questions.

The tool is a wrapper over the contour aggregation, so it inherits that aggregation's behavior exactly.

Parameters

Parameter	Required	Description
index	Yes	The index to measure.
field	No	The geometry field to measure. If omitted, the tool discovers a geometry field in the index and uses it.
query	No	A query string that restricts the documents measured. Omit it to measure everything.
weight_field	No	A numeric field whose value weights each document. Use it when documents are not equal — a field of vessel tonnage, incident severity, or transaction value.
percent	No	The contour levels to return, as a comma-separated list. Default is 50,75,90.
precision	No	The grid precision to accumulate density at. Higher precision means finer boundaries and more cells.

Both geo_point and Cartesian point fields are supported.

Register a flow agent that runs the ContourTool

POST /_plugins/_agent/agents/_register
{
  "name": "Concentration_Agent",
  "type": "flow",
  "description": "finds where activity is concentrated",
  "tools": [
    {
      "type": "ContourTool",
      "name": "DemoContourTool",
      "parameters": {
        "index": "vessel_positions",
        "percent": "50,75,90"
      }
    }
  ]
}

Run it:

POST /_plugins/_agent/agents/<agent_id>/_execute
{
  "parameters": { "question": "where is traffic heaviest?" }
}

What the answer tells you

The tool states what is trustworthy before it lists any numbers, so that a model which stops reading early still has the caveat. Every answer says both of the following, because stating only the first would understate a merge that is genuinely exact:

• The measurement is exact across shards. Merging tallies involves no interpolation — density is accumulated per grid cell and cells add up. The count inside a region is a real count.
• Region boundaries are quantised to the grid. They are accurate to a cell, not to a point. The answer names the precision it used.

When nothing reaches a threshold, the answer says that no region reached one — it does not return an empty result and let you infer it. When the index has no geometry field, it says there is nothing in the index whose density can be measured, rather than reporting zero concentrations.

note

FindConcentrations is for where things pile up. To list the individual features themselves, use FindFeatures (GeoLayerTool). To trace a route over time, use FindTracks.

Choosing levels

percent values are shares of the concentration, not shares of the area. 50 encloses the densest regions accounting for half the weight; 90 is a wider envelope accounting for nearly all of it. Asking for several levels costs almost nothing — every requested level is derived from a single pass over the accumulated grid, so 50,75,90 is no more expensive than 90 alone.

In movement ecology these are called percent-volume contours, or isopleths; the terms describe the same thing.