Skip to content

Commit 2aeee12

Browse files
emmanuelmathotemmanuelmathot
committed
Add correlation examples and migration guide for dynamic STAC correlation
- Introduced a comprehensive document detailing correlation algorithm examples, including real-world scenarios and Python code snippets for event, hazard, and impact analysis. - Added a migration guide to assist users in transitioning from static correlation identifiers to dynamic STAC-based queries, outlining benefits, migration phases, and practical examples.
1 parent 950389a commit 2aeee12

File tree

8 files changed

+2573
-16
lines changed

8 files changed

+2573
-16
lines changed

‎docs/model/README.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -175,7 +175,14 @@ The event class has the following attributes:
175175
- **hazard_codes**: The hazard codes of the hazards affecting the event.
176176
The hazard codes are based on the **[2025 UNDRR-ISC Hazard Information Profiles](./taxonomy.md#2025-update)** (reference classification system).
177177
For interoperability, codes from [other classification systems](./taxonomy.md#hazards) are **recommended** to also be included.
178-
- **correlation_id**: The unique identifier assigned by the Monty system to the reference event. It is used to "pair" all the instances of the event. More information about the correlation identifier can be found [here](./correlation_identifier.md).
178+
- **correlation_id**: The unique identifier assigned by the Monty system to the reference event. It is used to "pair" all the instances of the event.
179+
180+
> [!TIP]
181+
> **Dynamic Correlation Available**: While static correlation IDs remain supported, the Monty system now offers **dynamic STAC-based correlation** using CQL2 filters. This provides greater flexibility for multi-hazard events and cross-classification queries. See:
182+
> - [STAC-Based Correlation Algorithms](./stac-api/correlation_algorithms.md) - Dynamic correlation specifications
183+
> - [Correlation Examples](./stac-api/correlation_examples.md) - Real-world examples with Python code
184+
> - [Migration Guide](./stac-api/migration_guide.md) - Transitioning from static to dynamic correlation
185+
> - [Legacy Correlation Identifier](./correlation_identifier.md) - Static ID algorithm (still supported)
179186
- **keywords**: A list of keywords that describe the event. This list includes the human-readable names of
180187
- the countries affected by the event
181188
- the hazard types affecting the event

‎docs/model/correlation_identifier.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,15 @@
11
# Correlation Identifier
22

3-
This page describes the algorithm used to generate the correlation identifier for the items for the Monty system.
3+
> **Note**: This document describes the **legacy static correlation identifier** system. For the **new dynamic STAC-based correlation approach**, see:
4+
> - [STAC-Based Correlation Algorithms](./stac-api/correlation_algorithms.md) - Main algorithm documentation
5+
> - [Correlation Examples](./stac-api/correlation_examples.md) - Practical examples with code
6+
> - [Migration Guide](./stac-api/migration_guide.md) - How to transition from static to dynamic correlation
7+
>
8+
> The static correlation identifier described below is still generated and remains available for backward compatibility, but the new dynamic approach offers greater flexibility and better support for multi-hazard events.
9+
10+
---
11+
12+
This page describes the **legacy algorithm** used to generate the static correlation identifier for items in the Monty system.
413

514
## Context
615

‎docs/model/stac-api/README.md‎

Lines changed: 355 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,355 @@
1+
# STAC API Documentation
2+
3+
This directory contains documentation for querying and correlating disaster data using the Montandon STAC API.
4+
5+
## Overview
6+
7+
The Montandon system uses STAC (SpatioTemporal Asset Catalog) API with the Filter extension (CQL2) to provide powerful querying capabilities for disaster events, hazards, and impacts data.
8+
9+
**STAC API Endpoint**: `https://montandon-eoapi-stage.ifrc.org/stac`
10+
11+
> [!Note]
12+
> This is a staging endpoint. Production endpoint will be provided upon release.
13+
14+
## Documentation Files
15+
16+
### [correlation_algorithms.md](./correlation_algorithms.md)
17+
**Main algorithm specification document**
18+
19+
Describes the dynamic correlation algorithms for linking events, hazards, and impacts using STAC API queries.
20+
21+
**Contents**:
22+
- Overview of dynamic vs. static correlation
23+
- Core correlation algorithms (Event-to-Event, Event-to-Hazard, Event-to-Impact, Hazard-to-Impact)
24+
- Array operators explained (`a_contains`, `a_overlaps`, etc.)
25+
- Advanced patterns (temporal tolerance, hazard hierarchy, spatial correlation)
26+
- Performance considerations
27+
28+
**Audience**: Developers implementing correlation logic, data analysts designing queries
29+
30+
---
31+
32+
### [correlation_examples.md](./correlation_examples.md)
33+
**Practical examples with complete code**
34+
35+
Real-world correlation examples with working Python code using pystac-client.
36+
37+
**Contents**:
38+
- Spain October 2024 floods (complete workflow)
39+
- Multi-hazard cascading events (earthquake → tsunami)
40+
- Regional multi-country events (Southeast Asia floods)
41+
- Complete correlation workflow with helper classes
42+
- Impact aggregation and analysis
43+
44+
**Audience**: Developers integrating with Montandon API, data scientists analyzing disaster data
45+
46+
---
47+
48+
### [migration_guide.md](./migration_guide.md)
49+
**Transition guide from static to dynamic correlation**
50+
51+
Helps users migrate from the legacy static correlation identifier system to the new dynamic approach.
52+
53+
**Contents**:
54+
- Migration path and phases
55+
- When to use each approach
56+
- Practical migration examples
57+
- Performance comparisons
58+
- Testing and validation
59+
- Common issues and solutions
60+
61+
**Audience**: Existing Montandon users, system integrators, project managers
62+
63+
---
64+
65+
### [queryables.md](./queryables.md)
66+
**Queryable properties reference**
67+
68+
Lists all queryable properties available in the Montandon STAC API and how to use them.
69+
70+
**Contents**: *(To be created)*
71+
- Standard STAC properties
72+
- Montandon extension properties
73+
- Property types and schemas
74+
- Usage examples
75+
76+
---
77+
78+
## Quick Start
79+
80+
### 1. Install Dependencies
81+
82+
```bash
83+
pip install pystac-client
84+
```
85+
86+
### 2. Connect to API
87+
88+
```python
89+
from pystac_client import Client
90+
91+
client = Client.open("https://montandon-eoapi-stage.ifrc.org/stac")
92+
```
93+
94+
### 3. Find Events for a Country and Hazard
95+
96+
```python
97+
# Find flood events in Spain during October 2024
98+
search = client.search(
99+
collections=["glide-events", "gdacs-events"],
100+
filter={
101+
"op": "and",
102+
"args": [
103+
{
104+
"op": "a_contains",
105+
"args": [{"property": "monty:country_codes"}, "ESP"]
106+
},
107+
{
108+
"op": "a_contains",
109+
"args": [{"property": "monty:hazard_codes"}, "MH0600"]
110+
},
111+
{
112+
"op": "t_during",
113+
"args": [
114+
{"property": "datetime"},
115+
{"interval": ["2024-10-01T00:00:00Z", "2024-10-31T23:59:59Z"]}
116+
]
117+
}
118+
]
119+
},
120+
filter_lang="cql2-json",
121+
limit=100
122+
)
123+
124+
for item in search.items():
125+
print(f"{item.id}: {item.properties.get('title')}")
126+
```
127+
128+
### 4. Find Related Hazards and Impacts
129+
130+
```python
131+
# Get correlation ID from an event
132+
corr_id = item.properties.get("monty:corr_id")
133+
134+
# Find all related hazards
135+
hazards = client.search(
136+
filter={
137+
"op": "and",
138+
"args": [
139+
{"op": "=", "args": [{"property": "monty:corr_id"}, corr_id]},
140+
{"op": "in", "args": ["hazard", {"property": "roles"}]}
141+
]
142+
},
143+
filter_lang="cql2-json"
144+
)
145+
146+
# Find all related impacts
147+
impacts = client.search(
148+
filter={
149+
"op": "and",
150+
"args": [
151+
{"op": "=", "args": [{"property": "monty:corr_id"}, corr_id]},
152+
{"op": "in", "args": ["impact", {"property": "roles"}]}
153+
]
154+
},
155+
filter_lang="cql2-json"
156+
)
157+
```
158+
159+
For complete examples, see [correlation_examples.md](./correlation_examples.md).
160+
161+
---
162+
163+
## Key Concepts
164+
165+
### Array Operators
166+
167+
The STAC Filter extension provides specialized operators for array fields like `monty:hazard_codes` and `monty:country_codes`:
168+
169+
| Operator | Description | Example |
170+
|----------|-------------|---------|
171+
| `a_contains` | Array contains element | `["MH0600", "FL"]` contains `"MH0600"` ✅ |
172+
| `a_overlaps` | Arrays share at least one element | `["MH0600"]` overlaps `["MH0600", "MH0603"]` ✅ |
173+
| `a_equals` | Arrays are exactly equal | `["ESP"]` equals `["ESP"]` ✅, not `["ESP", "FRA"]` ❌ |
174+
| `a_containedBy` | All elements are in the other array | `["FL"]` contained by `["FL", "MH0600"]` ✅ |
175+
176+
**Important**: Use array operators for array fields. Regular `=` operator only works for exact array matching.
177+
178+
### Temporal Operators
179+
180+
| Operator | Description |
181+
|----------|-------------|
182+
| `t_intersects` | Time ranges overlap |
183+
| `t_during` | Item time is within period |
184+
| `t_after` | Item time is after point |
185+
| `t_before` | Item time is before point |
186+
187+
### Spatial Operators
188+
189+
| Operator | Description |
190+
|----------|-------------|
191+
| `s_intersects` | Geometries intersect |
192+
| `s_contains` | Geometry contains another |
193+
| `s_within` | Geometry is within another |
194+
195+
---
196+
197+
## Common Patterns
198+
199+
### Pattern 1: Find Events by Location and Hazard Type
200+
201+
```python
202+
search = client.search(
203+
filter={
204+
"op": "and",
205+
"args": [
206+
{"op": "a_contains", "args": [{"property": "monty:country_codes"}, "ESP"]},
207+
{"op": "a_contains", "args": [{"property": "monty:hazard_codes"}, "MH0600"]},
208+
{"op": "in", "args": ["event", {"property": "roles"}]}
209+
]
210+
},
211+
filter_lang="cql2-json"
212+
)
213+
```
214+
215+
### Pattern 2: Find All Data for a Correlation ID
216+
217+
```python
218+
search = client.search(
219+
filter={
220+
"op": "=",
221+
"args": [{"property": "monty:corr_id"}, "20241027-ESP-FL-2-GCDB"]
222+
},
223+
filter_lang="cql2-json"
224+
)
225+
```
226+
227+
### Pattern 3: Multi-Hazard Query
228+
229+
```python
230+
# Find events with either flooding or landslides
231+
search = client.search(
232+
filter={
233+
"op": "and",
234+
"args": [
235+
{
236+
"op": "a_overlaps",
237+
"args": [
238+
{"property": "monty:hazard_codes"},
239+
["MH0600", "GH0300", "nat-hyd-flo-flo", "nat-geo-mmd-lan"]
240+
]
241+
},
242+
{"op": "in", "args": ["event", {"property": "roles"}]}
243+
]
244+
},
245+
filter_lang="cql2-json"
246+
)
247+
```
248+
249+
### Pattern 4: Regional Analysis
250+
251+
```python
252+
# Find disasters affecting multiple countries
253+
search = client.search(
254+
filter={
255+
"op": "and",
256+
"args": [
257+
{
258+
"op": "a_overlaps",
259+
"args": [
260+
{"property": "monty:country_codes"},
261+
["THA", "VNM", "KHM", "LAO"]
262+
]
263+
},
264+
{
265+
"op": "t_during",
266+
"args": [
267+
{"property": "datetime"},
268+
{"interval": ["2024-06-01T00:00:00Z", "2024-09-30T23:59:59Z"]}
269+
]
270+
}
271+
]
272+
},
273+
filter_lang="cql2-json"
274+
)
275+
```
276+
277+
---
278+
279+
## Collections
280+
281+
The Montandon STAC API organizes data into collections by source and data type:
282+
283+
### Event Collections
284+
- `glide-events` - GLIDE source events
285+
- `gdacs-events` - GDACS source events
286+
- `emdat-events` - EM-DAT source events
287+
- `usgs-events` - USGS earthquake events
288+
- `ibtracs-events` - IBTrACS tropical cyclone events
289+
- `idmc-gidd-events` - IDMC GIDD displacement events
290+
- `idmc-idu-events` - IDMC IDU displacement events
291+
- `ifrcevent-events` - IFRC events
292+
- `reference-events` - Reference correlation events
293+
294+
### Hazard Collections
295+
- `glide-hazards` - GLIDE hazard assessments
296+
- `gdacs-hazards` - GDACS hazard assessments
297+
- `usgs-hazards` - USGS earthquake hazards (shakemaps)
298+
- `ibtracs-hazards` - IBTrACS cyclone hazards
299+
- `ifrcevent-hazards` - IFRC hazard data
300+
301+
### Impact Collections
302+
- `gdacs-impacts` - GDACS impact estimates
303+
- `emdat-impacts` - EM-DAT impact data
304+
- `idmc-gidd-impacts` - IDMC GIDD displacement impacts
305+
- `idmc-idu-impacts` - IDMC IDU displacement impacts
306+
- `usgs-impacts` - USGS earthquake impacts
307+
- `desinventar-impacts` - DesInventar impact data
308+
- `ifrcevent-impacts` - IFRC impact data
309+
310+
---
311+
312+
## Resources
313+
314+
### External Documentation
315+
- [STAC Specification](https://stacspec.org/)
316+
- [STAC Filter Extension](https://github.com/stac-api-extensions/filter)
317+
- [CQL2 Specification](https://docs.ogc.org/DRAFTS/21-065.html)
318+
- [pystac-client Documentation](https://pystac-client.readthedocs.io/)
319+
320+
### Montandon Documentation
321+
- [Data Model](../README.md)
322+
- [Taxonomy](../taxonomy.md)
323+
- [Legacy Correlation Identifier](../correlation_identifier.md)
324+
325+
### Support
326+
- GitHub: [IFRCGo/monty-stac-extension](https://github.com/IFRCGo/monty-stac-extension)
327+
- IFRC GO: [go.ifrc.org](https://go.ifrc.org)
328+
329+
---
330+
331+
## Examples by Use Case
332+
333+
| Use Case | Document | Section |
334+
|----------|----------|---------|
335+
| Find all data for a disaster | [correlation_examples.md](./correlation_examples.md) | Example 1: Spain October 2024 Floods |
336+
| Track cascading hazards | [correlation_examples.md](./correlation_examples.md) | Example 2: Multi-Hazard Event |
337+
| Regional disaster analysis | [correlation_examples.md](./correlation_examples.md) | Example 3: Regional Multi-Country Event |
338+
| Migrate from old system | [migration_guide.md](./migration_guide.md) | Migration Path |
339+
| Build custom correlation | [correlation_algorithms.md](./correlation_algorithms.md) | Advanced Patterns |
340+
| Optimize query performance | [migration_guide.md](./migration_guide.md) | Performance Considerations |
341+
342+
---
343+
344+
## Contributing
345+
346+
To contribute to this documentation:
347+
348+
1. Review existing algorithms and examples
349+
2. Test queries against the staging API
350+
3. Submit pull requests with improvements
351+
4. Report issues or request features
352+
353+
---
354+
355+
Last Updated: November 2025

0 commit comments

Comments
 (0)