# IES Ecosystem Demo

The [Information Exchange Standard (IES)](https://github.com/IES-Org) is a layered ontology framework used by the UK National Digital Twin Programme (NDTP). Open Ontologies supports the full IES stack through its marketplace.

## The IES Layers

IES is split into three tiers, each building on the last:

```
ies-top     (ToLO)    ~22 classes    BORO foundations, 4D extensionalism
    |
ies-core              ~131 classes   Persons, states, events, identifiers
    |
ies-common            ~513 classes   Full ontology — everything above + domain patterns
```

## Quick Start: Load the Full Stack

```text
# Load all three layers individually
onto_marketplace install ies-top
onto_stats
onto_clear

onto_marketplace install ies-core
onto_stats
onto_clear

# Or load the full IES Common (includes everything)
onto_marketplace install ies
onto_stats
```

## Full Pipeline Demo

### Step 1: Load and Validate

```text
onto_marketplace install ies
onto_stats
onto_lint
```

Expected output:
- 513 classes, 206 object properties, 4,040 triples
- 0 lint issues (IES v5 is well-formed)

### Step 2: Reason

```text
onto_reason --profile rdfs
onto_stats
```

RDFS materialises **+3,094 inferred triples** (77% growth) — transitive subclass chains across 241 State subclasses, 117 ClassOfEntity subclasses, and 102 Event subclasses.

### Step 3: Ingest Real EPC Data

The repo includes a sample of 10 real UK Energy Performance Certificates from the Open Data Communities register ([benchmark/epc/epc-sample.csv](../benchmark/epc/epc-sample.csv)) with a pre-built mapping config ([benchmark/epc/epc-ies-mapping.json](../benchmark/epc/epc-ies-mapping.json)).

```text
# Load IES Building Extension as the target ontology
onto_validate benchmark/generated/ies-building-extension.ttl
onto_load benchmark/generated/ies-building-extension.ttl

# Generate or review the mapping (CSV columns → IES predicates)
onto_map benchmark/epc/epc-sample.csv

# Ingest the CSV data using the mapping
onto_ingest benchmark/epc/epc-sample.csv --mapping benchmark/epc/epc-ies-mapping.json

# Check what was created
onto_stats

# Reason to materialise inferred triples
onto_reason --profile rdfs

# Query: which dwellings have poor energy ratings?
onto_query "SELECT ?dwelling ?rating WHERE {
  ?dwelling a <http://example.org/ontology/ies-building#Dwelling> .
  ?dwelling <http://example.org/ontology/ies-building#energyRatingBand> ?rating .
  FILTER(?rating IN (
    <http://example.org/ontology/ies-building#BandE>,
    <http://example.org/ontology/ies-building#BandF>,
    <http://example.org/ontology/ies-building#BandG>
  ))
}"
```

The mapping config maps CSV columns to IES Building predicates:

| CSV Column | IES Predicate | Type |
| --- | --- | --- |
| `postcode` | `bldg:hasPostalCode` | string |
| `propertytype` | `ies:similarEntity` → ClassOfBuilding | lookup (D→Detached, S→Semi, T→Terraced, F→Flat) |
| `CURRENT_ENERGY_RATING` | `bldg:energyRatingBand` | lookup (A-G → BandA-BandG) |
| `CURRENT_ENERGY_EFFICIENCY` | `bldg:energyScore` | integer |
| `MAIN_FUEL` | `bldg:usesFuel` → FuelType | lookup (mains gas→MainsGas, etc.) |
| `MAINHEAT_DESCRIPTION` | `bldg:heatingDescription` | string |
| `WALLS_DESCRIPTION` | `bldg:wallsDescription` | string |
| `inspectiondate` | `bldg:inspectionDate` | date |
| `CO2_EMISSIONS_CURRENT` | `bldg:co2Emissions` | decimal |

This mirrors NDTP's actual pipeline: take tabular EPC data, map it to IES-shaped RDF, validate, reason, and query.

### Step 4: Explore with SPARQL

See [ies-examples.md](ies-examples.md) for 5 ready-to-use queries. Quick taste:

```text
# Count State subclasses (the 4D temporal pattern)
onto_query "SELECT (COUNT(DISTINCT ?c) AS ?count) WHERE {
  ?c rdfs:subClassOf* <http://informationexchangestandard.org/ont/ies/common/State> .
  FILTER(?c != <http://informationexchangestandard.org/ont/ies/common/State>)
}"
# Result: 241
```

### Step 5: Load Example Data

IES has ~42 example Turtle files across its repos. Pull them directly:

```text
# Event participation patterns
onto_pull https://raw.githubusercontent.com/IES-Org/ont-ies/main/docs/examples/sample-data/event-participation.ttl

# Hospital scenario
onto_pull https://raw.githubusercontent.com/IES-Org/ont-ies/main/docs/examples/sample-data/hospital.ttl

# Movement tracking
onto_pull https://raw.githubusercontent.com/IES-Org/ont-ies/main/docs/examples/sample-data/movement.ttl

# GeoSPARQL integration
onto_pull https://raw.githubusercontent.com/IES-Org/ont-ies/main/docs/examples/sample-data/geosparql.ttl
```

Additional examples from telicent-oss:

```text
# Ship movement (4D spatiotemporal)
onto_pull https://raw.githubusercontent.com/telicent-oss/ies-examples/main/additional_examples/ship_movement.ttl

# Aircraft observation
onto_pull https://raw.githubusercontent.com/telicent-oss/ies-examples/main/additional_examples/observing_moving_aircraft.ttl

# Countries reference data
onto_pull https://raw.githubusercontent.com/telicent-oss/ies-examples/main/regions_of_the_world/countries.ttl
```

### Step 6: SHACL Validation

IES provides SHACL shapes for data validation:

```text
# Validate against IES Common shapes
onto_pull https://raw.githubusercontent.com/IES-Org/ont-ies/main/docs/specification/ies-common.shacl
onto_shacl
```

Core-level shapes for specific patterns:

```text
# Person state validation
onto_pull https://raw.githubusercontent.com/IES-Org/ies-core/main/spec/validation_artefacts/PersonState.shacl.ttl

# Birth/death state validation
onto_pull https://raw.githubusercontent.com/IES-Org/ies-core/main/spec/validation_artefacts/BirthStateShape.shacl.ttl
onto_pull https://raw.githubusercontent.com/IES-Org/ies-core/main/spec/validation_artefacts/DeathStateShape.shacl.ttl
```

### Step 7: Alignment

Map IES to other domain ontologies:

```text
# Save IES, load target, align
onto_save /tmp/ies.ttl
onto_clear
onto_marketplace install schema-org
onto_save /tmp/schema-org.ttl
onto_clear
onto_align --source /tmp/ies.ttl --target /tmp/schema-org.ttl
```

See [ies-alignment.md](ies-alignment.md) for the full IES:Building alignment walkthrough.

## IES Ecosystem Map

| Resource | Repo | What's There |
| --- | --- | --- |
| **IES Top (ToLO)** | `IES-Org/ies-top` | Foundational ontology + 2 SHACL shapes |
| **IES Core** | `IES-Org/ies-core` | Core patterns + 6 SHACL shapes + 7 test data files |
| **IES Common** | `IES-Org/ont-ies` | Full ontology (4 formats) + SHACL shapes + 15 examples + user guides + 70 diagrams |
| **IES Examples** | `telicent-oss/ies-examples` | 28 Turtle example files + regions reference data |
| **IES Tool** | `telicent-oss/ies-tool` | Python library + bundled v4.3 ontology + SHACL shapes |
| **RDF Transform** | `telicent-oss/telicent-rdf-transform` | IES4 to IES-Next migration mappings |
| **NDTP AI Extension** | `National-Digital-Twin/ndtp-ai-ontology-extension` | LLM-driven ontology extension tooling |
| **IES4 (archived, last MIT release v4.3.1)** | `dstl/IES4` | Legacy mirror; archived 4 Mar 2025 when custodianship moved from Dstl to DBT. Last public release 4.3.1 (3 Mar 2025) under MIT — pinnable as a reproducible compliance baseline. 4.3.2+ work continues in a private working group. Canonical successor is `IES-Org/ont-ies` (above), portal at [informationexchangestandard.org](https://informationexchangestandard.org/). |

## Benchmark Results

| Layer | Classes | Properties | Triples | + RDFS | Fetch | RDFS |
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
| IES Top (ToLO) | ~22 | TBD | TBD | TBD | TBD | TBD |
| IES Core | ~131 | TBD | TBD | TBD | TBD | TBD |
| **IES Common** | **513** | **206** | **4,040** | **+3,094** | **911ms** | **63ms** |

IES Common is the second-largest ontology in the marketplace by class count (after Schema.org's 1,009). RDFS reasoning adds 77% more triples — the richest inference gain of any non-general ontology, driven by the deep 4D State/Event/ClassOfEntity hierarchies.
