diff --git a/documentation/user-guides/design-patterns/Design Pattern 1/facility location/README.md b/documentation/user-guides/design-patterns/Design Pattern 1/facility location/README.md new file mode 100644 index 00000000..1ab32893 --- /dev/null +++ b/documentation/user-guides/design-patterns/Design Pattern 1/facility location/README.md @@ -0,0 +1,110 @@ +# Pattern Name +Facility Location + +# Intent + +To represent location relationships where material entities (e.g., facilities, equipment, infrastructure) are situated within progressively larger geographic regions or sites (e.g., building → campus → city → state → country), enabling multi-level location queries and reasoning. The specific entity types and site hierarchies shown are examples. This pattern generalizes to any material entity that can be located at sites, and any hierarchical organization of sites. + +# Competency Questions + +1. Where is a specific facility located? +2. What bigger site is this facility located in, and are there smaller sites that the facility is located in that are also located in the bigger site? +3. What are all the facilities located within a particular site? + +# Structure + +Represents locations as sites and use of the located_in relation. + +Helps with show how non-transitive relation can be used to do a query that acts transitively. + +Visual model through mermaid and png. + +*Note: Entity types and location hierarchies shown are illustrative examples. This pattern applies to any material entities and site taxonomies relevant to your domain.* +```mermaid +flowchart BT + A@{ label: "Facility 1" } -- LocatedIn
BFO_0000171 --> B@{ label: "City 1" } + B -- LocatedIn
BFO_0000171 --> C@{ label: "State 1" } + A -- rdf:type --> D@{ label: "Facility
ont00000192
" } + B -- rdf:type --> E@{ label: "Site
BFO_0000029
" } + C -- rdf:type --> E + A -. rdfs:label .-> F[""Building 1""] + B -. rdfs:label .-> G[""NY City""] + C -. rdfs:label .-> H[""NY State""] + + subgraph Legend[" "] + direction LR + LL[ ] --> |relation| LL2[ ] + LD[ ] -.-> |data property| LD2[ ] + AA["Individual"] + BB["Class"] + CC[""literal""] + end + + A ~~~ Legend + + A@{ shape: rect} + B@{ shape: rect} + C@{ shape: rect} + D@{ shape: rect} + E@{ shape: rect} + F@{ shape: rect} + G@{ shape: rect} + H@{ shape: rect} + A:::purple + B:::purple + C:::purple + D:::yellow + E:::yellow + F:::literal + G:::literal + H:::literal + AA:::purple + BB:::yellow + CC:::literal + LL:::invisible + LL2:::invisible + LD:::invisible + LD2:::invisible + classDef yellow fill:#ffe680,color:#7a6000,stroke:#c8a800 + classDef purple fill:#dbc9ef,color:#000000,stroke:#9b7fc7 + classDef literal fill:none,stroke:none,color:#555555,font-style:italic + classDef invisible fill:none,stroke:none,color:none,width:0px + +``` + +# File Structure +``` +facility-location/ +├── README.md +├── mermaid/ +│ ├── FacilityLocation.md # Mermaid source file +│ └── FacilityLocation.png # Exported PNG diagram +└── sparql/ + ├── CQ1.sparql # Where is a specific facility located? + ├── CQ2.sparql # What larger/smaller sites contain this facility? + ├── CQ3.sparql # What facilities are within a particular site? + └── example.ttl # Test data for SPARQL queries +``` + +## File Descriptions + +### mermaid/ +| File | Description | +|------|-------------| +| `FacilityLocation.md` | Mermaid diagram source showing the pattern structure | +| `FacilityLocation.png` | PNG export of the diagram for documentation | + +### sparql/ +| File | Competency Question | +|------|---------------------| +| `CQ1.sparql` | Where is a specific facility located? | +| `CQ2.sparql` | What bigger site is this facility located in, and are there smaller sites that the facility is located in that are also located in the bigger site? | +| `CQ3.sparql` | What are all the facilities located within a particular site? | +| `example.ttl` | Turtle file with test instances (states, cities, campuses, buildings, facilities) | + +# Additional Notes + +- Related pattern: Geospatial Coordinate Pattern +- Key classes: `obo:BFO_0000029` (Site), `cco:ont00000192` (Facility) +- Key property: `obo:BFO_0000171` (located in) + diff --git a/documentation/user-guides/design-patterns/Design Pattern 1/facility location/mermaid/FacilityLocation.md b/documentation/user-guides/design-patterns/Design Pattern 1/facility location/mermaid/FacilityLocation.md new file mode 100644 index 00000000..9985318b --- /dev/null +++ b/documentation/user-guides/design-patterns/Design Pattern 1/facility location/mermaid/FacilityLocation.md @@ -0,0 +1,49 @@ +flowchart BT + A@{ label: "Facility 1" } -- LocatedIn
BFO_0000171 --> B@{ label: "City 1" } + B -- LocatedIn
BFO_0000171 --> C@{ label: "State 1" } + A -- rdf:type --> D@{ label: "Facility
ont00000192
" } + B -- rdf:type --> E@{ label: "Site
BFO_0000029
" } + C -- rdf:type --> E + A -. rdfs:label .-> F[""Building 1""] + B -. rdfs:label .-> G[""NY City""] + C -. rdfs:label .-> H[""NY State""] + + subgraph Legend[" "] + direction LR + LL[ ] --> |relation| LL2[ ] + LD[ ] -.-> |data property| LD2[ ] + AA["Individual"] + BB["Class"] + CC[""literal""] + end + + A ~~~ Legend + + A@{ shape: rect} + B@{ shape: rect} + C@{ shape: rect} + D@{ shape: rect} + E@{ shape: rect} + F@{ shape: rect} + G@{ shape: rect} + H@{ shape: rect} + A:::purple + B:::purple + C:::purple + D:::yellow + E:::yellow + F:::literal + G:::literal + H:::literal + AA:::purple + BB:::yellow + CC:::literal + LL:::invisible + LL2:::invisible + LD:::invisible + LD2:::invisible + classDef yellow fill:#ffe680,color:#7a6000,stroke:#c8a800 + classDef purple fill:#dbc9ef,color:#000000,stroke:#9b7fc7 + classDef literal fill:none,stroke:none,color:#555555,font-style:italic + classDef invisible fill:none,stroke:none,color:none,width:0px + \ No newline at end of file diff --git a/documentation/user-guides/design-patterns/Design Pattern 1/facility location/mermaid/FacilityLocation.png b/documentation/user-guides/design-patterns/Design Pattern 1/facility location/mermaid/FacilityLocation.png new file mode 100644 index 00000000..72c7509b Binary files /dev/null and b/documentation/user-guides/design-patterns/Design Pattern 1/facility location/mermaid/FacilityLocation.png differ diff --git a/documentation/user-guides/design-patterns/Design Pattern 1/facility location/sparql/CQ1.sparql b/documentation/user-guides/design-patterns/Design Pattern 1/facility location/sparql/CQ1.sparql new file mode 100644 index 00000000..31940e6e --- /dev/null +++ b/documentation/user-guides/design-patterns/Design Pattern 1/facility location/sparql/CQ1.sparql @@ -0,0 +1,22 @@ +# CQ1: Where is a facility located? +# Returns the immediate site(s) where a given facility is located + +PREFIX rdfs: +PREFIX cco: +PREFIX obo: +PREFIX facility: +PREFIX located_in: + +SELECT ?facility ?facilityLabel ?site ?siteLabel +WHERE { + + # ── Parameter: bind the facility IRI you want to query ────────────────── + #BIND( AS ?facility) + + BIND( AS ?facility) + + ?facility a facility: ; + rdfs:label ?facilityLabel ; + located_in: ?site . + ?site rdfs:label ?siteLabel . +} diff --git a/documentation/user-guides/design-patterns/Design Pattern 1/facility location/sparql/CQ2.sparql b/documentation/user-guides/design-patterns/Design Pattern 1/facility location/sparql/CQ2.sparql new file mode 100644 index 00000000..83f3c475 --- /dev/null +++ b/documentation/user-guides/design-patterns/Design Pattern 1/facility location/sparql/CQ2.sparql @@ -0,0 +1,33 @@ +# CQ2: What bigger site is this facility located in, and are there smaller sites +# that the facility is also located in that are within the bigger site? +# Uses property paths to find the full location hierarchy + +PREFIX rdfs: +PREFIX cco: +PREFIX obo: +PREFIX facility: +PREFIX located_in: + +SELECT ?site ?siteLabel ?parentSite ?parentSiteLabel + (COUNT(?intermediate) AS ?depth) +WHERE { + + # ── Parameter: bind the facility IRI you want to query ────────────────── + #BIND( AS ?facility) + + BIND( AS ?facility) + + ?facility located_in: ?site . + + ?site located_in: ?parentSite . + ?site rdfs:label ?siteLabel . + ?parentSite rdfs:label ?parentSiteLabel . + + OPTIONAL { + ?site located_in:+ ?intermediate . + ?intermediate located_in:+ ?parentSite . + } + +} +GROUP BY ?site ?siteLabel ?parentSite ?parentSiteLabel +ORDER BY ASC(?depth) ASC(?siteLabel) diff --git a/documentation/user-guides/design-patterns/Design Pattern 1/facility location/sparql/CQ3.sparql b/documentation/user-guides/design-patterns/Design Pattern 1/facility location/sparql/CQ3.sparql new file mode 100644 index 00000000..9884e223 --- /dev/null +++ b/documentation/user-guides/design-patterns/Design Pattern 1/facility location/sparql/CQ3.sparql @@ -0,0 +1,27 @@ +# CQ3: What are all the facilities located within a site? +# Finds facilities directly or transitively located within a site + +PREFIX rdfs: +PREFIX cco: +PREFIX obo: +PREFIX site: +PREFIX facility: +PREFIX located_in: + +SELECT ?targetSite ?targetSiteLabel ?facility ?facilityLabel +WHERE { + + # ── Parameter: bind the site IRI you want to query ────────────────────── + #BIND( AS ?targetSite) + + BIND( AS ?targetSite) + + ?targetSite rdfs:label ?targetSiteLabel . + + ?facility a facility: ; + rdfs:label ?facilityLabel ; + located_in:+ ?targetSite . + +} +ORDER BY ASC(?facilityLabel) + diff --git a/documentation/user-guides/design-patterns/Design Pattern 1/facility location/sparql/example.ttl b/documentation/user-guides/design-patterns/Design Pattern 1/facility location/sparql/example.ttl new file mode 100644 index 00000000..05855da1 --- /dev/null +++ b/documentation/user-guides/design-patterns/Design Pattern 1/facility location/sparql/example.ttl @@ -0,0 +1,101 @@ +# Test data for CQ1–CQ3 +# Imports CCO (which in turn imports BFO), so no need to restate definitions here. +# For reference, the key classes and properties used are: +# - obo:BFO_0000029 (site) — a three-dimensional immaterial entity +# - cco:ont00000192 (Facility) — a Material Artifact dedicated to a specific purpose +# - obo:BFO_0000171 (located in) — occupies a spatial region that is part of another's region +# Full definitions are in the imported ontologies. + +@prefix : . +@prefix cco: . +@prefix obo: . +@prefix owl: . +@prefix rdf: . +@prefix rdfs: . +@prefix xsd: . + + + rdf:type owl:Ontology ; + owl:imports . + +################################################################# +# Sites — location hierarchy (largest → smallest) +# +# NY State +# └── New York City (located_in NY State) +# │ └── Manhattan Campus (located_in NYC) +# │ ├── Tower 1 (located_in Manhattan Campus) +# │ └── Tower 2 (located_in Manhattan Campus) +# └── Buffalo (located_in NY State) +# California +# └── Los Angeles (located_in California) +# └── Downtown LA Campus (located_in LA) +# Texas +# └── Houston (located_in Texas) +################################################################# + +# States +:state_ny rdf:type obo:BFO_0000029 ; rdfs:label "NY State" . +:state_ca rdf:type obo:BFO_0000029 ; rdfs:label "California" . +:state_tx rdf:type obo:BFO_0000029 ; rdfs:label "Texas" . + +# Cities +:city_nyc rdf:type obo:BFO_0000029 ; rdfs:label "New York City" ; + obo:BFO_0000171 :state_ny . # NYC located_in NY State + +:city_buffalo rdf:type obo:BFO_0000029 ; rdfs:label "Buffalo" ; + obo:BFO_0000171 :state_ny . # Buffalo located_in NY State + +:city_la rdf:type obo:BFO_0000029 ; rdfs:label "Los Angeles" ; + obo:BFO_0000171 :state_ca . # LA located_in California + +:city_houston rdf:type obo:BFO_0000029 ; rdfs:label "Houston" ; + obo:BFO_0000171 :state_tx . # Houston located_in Texas + +# Campuses +:campus_manhattan rdf:type obo:BFO_0000029 ; rdfs:label "Manhattan Campus" ; + obo:BFO_0000171 :city_nyc . # Manhattan Campus located_in NYC + +:campus_downtown_la rdf:type obo:BFO_0000029 ; rdfs:label "Downtown LA Campus" ; + obo:BFO_0000171 :city_la . # Downtown LA Campus located_in LA + +# Buildings +:building_tower1 rdf:type obo:BFO_0000029 ; rdfs:label "Tower 1" ; + obo:BFO_0000171 :campus_manhattan . # Tower 1 located_in Manhattan Campus + +:building_tower2 rdf:type obo:BFO_0000029 ; rdfs:label "Tower 2" ; + obo:BFO_0000171 :campus_manhattan . # Tower 2 located_in Manhattan Campus + +################################################################# +# Facilities +# +# NYC Main Warehouse located_in Tower 1 +# NYC Corporate Office located_in Tower 2 +# NYC Research Lab located_in Manhattan Campus +# Buffalo Distribution Ctr located_in Buffalo +# LA Warehouse located_in Downtown LA Campus +# LA Regional Office located_in Los Angeles +# Houston Manufacturing located_in Houston +################################################################# + +:facility_warehouse_nyc rdf:type cco:ont00000192 ; rdfs:label "NYC Main Warehouse" ; + obo:BFO_0000171 :building_tower1 . # NYC Main Warehouse located_in Tower 1 + +:facility_office_nyc rdf:type cco:ont00000192 ; rdfs:label "NYC Corporate Office" ; + obo:BFO_0000171 :building_tower2 . # NYC Corporate Office located_in Tower 2 + +:facility_lab_nyc rdf:type cco:ont00000192 ; rdfs:label "NYC Research Lab" ; + obo:BFO_0000171 :campus_manhattan . # NYC Research Lab located_in Manhattan Campus + +:facility_warehouse_buffalo rdf:type cco:ont00000192 ; rdfs:label "Buffalo Distribution Center" ; + obo:BFO_0000171 :city_buffalo . # Buffalo Distribution Center located_in Buffalo + +:facility_warehouse_la rdf:type cco:ont00000192 ; rdfs:label "LA Warehouse" ; + obo:BFO_0000171 :campus_downtown_la . # LA Warehouse located_in Downtown LA Campus + +:facility_office_la rdf:type cco:ont00000192 ; rdfs:label "LA Regional Office" ; + obo:BFO_0000171 :city_la . # LA Regional Office located_in Los Angeles + +:facility_plant_houston rdf:type cco:ont00000192 ; rdfs:label "Houston Manufacturing Plant" ; + obo:BFO_0000171 :city_houston . # Houston Manufacturing Plant located_in Houston + \ No newline at end of file diff --git a/documentation/user-guides/design-patterns/README.md b/documentation/user-guides/design-patterns/README.md index 42c5cf94..e1625a76 100644 --- a/documentation/user-guides/design-patterns/README.md +++ b/documentation/user-guides/design-patterns/README.md @@ -3,3 +3,10 @@ This folder contains common CCO design patterns. Each entry includes a mermaid graph, a visualization of that graph, a description of competency questions answered, and a sparql query to support the competency questions. Users are encouraged to reuse these design patterns in their knowledge graphs to speed up data mapping and querying while ensuring greater consistency and interoperability across knowledge graphs. + +## Folder Directory + +| Folder Name | Description | +|------------------|--------------------------------------------| +| Design Pattern 1 | facility location | +