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 0000000..6c65531 --- /dev/null +++ b/documentation/user-guides/design-patterns/Design Pattern 1/facility location/README.md @@ -0,0 +1,103 @@ +# 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 the location of a site and their appropriate relations with a broader area. + +Helps with creating transitive relations between sites. + +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 + AA{Individual} + BB[Class] + CC[data] + AA --> |relation| CC + end + + A ~~~ Legend + + A@{ shape: diam} + B@{ shape: diam} + C@{ shape: diam} + 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:::white + G:::white + H:::white + classDef yellow fill:#ffe680 + classDef purple fill:#dbc9ef + classDef white fill:#FFFFFF + class BB yellow + class AA purple + class CC white +``` + +# 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 0000000..f37434d --- /dev/null +++ b/documentation/user-guides/design-patterns/Design Pattern 1/facility location/mermaid/FacilityLocation.md @@ -0,0 +1,43 @@ +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 + AA{Individual} + BB[Class] + CC[data] + AA --> |relation| CC + end + + A ~~~ Legend + + A@{ shape: diam} + B@{ shape: diam} + C@{ shape: diam} + 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:::white + G:::white + H:::white + classDef yellow fill:#ffe680 + classDef purple fill:#dbc9ef + classDef white fill:#FFFFFF + class BB yellow + class AA purple + class CC white + 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 0000000..d0d8235 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 0000000..f8c8f2a --- /dev/null +++ b/documentation/user-guides/design-patterns/Design Pattern 1/facility location/sparql/CQ1.sparql @@ -0,0 +1,15 @@ +# CQ1: Where is a specific facility located? +# Returns the immediate site(s) where a given facility is located + +PREFIX : +PREFIX cco: +PREFIX obo: +PREFIX rdfs: + +SELECT ?facility ?facilityLabel ?site ?siteLabel +WHERE { + ?facility a cco:ont00000192 ; + rdfs:label ?facilityLabel ; + obo:BFO_0000171 ?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 0000000..395fdd5 --- /dev/null +++ b/documentation/user-guides/design-patterns/Design Pattern 1/facility location/sparql/CQ2.sparql @@ -0,0 +1,20 @@ +# 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 : +PREFIX cco: +PREFIX obo: +PREFIX rdfs: + +SELECT ?facility ?facilityLabel ?immediateSite ?immediateSiteLabel ?largerSite ?largerSiteLabel +WHERE { + ?facility a cco:ont00000192 ; + rdfs:label ?facilityLabel ; + obo:BFO_0000171 ?immediateSite . + ?immediateSite rdfs:label ?immediateSiteLabel ; + obo:BFO_0000171+ ?largerSite . + ?largerSite rdfs:label ?largerSiteLabel . +} +ORDER BY ?facility ?largerSite + 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 0000000..8b4a19e --- /dev/null +++ b/documentation/user-guides/design-patterns/Design Pattern 1/facility location/sparql/CQ3.sparql @@ -0,0 +1,17 @@ +# CQ3: What are all the facilities located within a particular site? +# Finds facilities directly or transitively located within a site + +PREFIX : +PREFIX cco: +PREFIX obo: +PREFIX rdfs: + +SELECT ?site ?siteLabel ?facility ?facilityLabel +WHERE { + ?site a obo:BFO_0000029 ; + rdfs:label ?siteLabel . + ?facility a cco:ont00000192 ; + rdfs:label ?facilityLabel ; + obo:BFO_0000171+ ?site . +} +ORDER BY ?site ?facility 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 0000000..10959d8 --- /dev/null +++ b/documentation/user-guides/design-patterns/Design Pattern 1/facility location/sparql/example.ttl @@ -0,0 +1,138 @@ +@prefix : . +@prefix cco: . +@prefix obo: . +@prefix owl: . +@prefix rdf: . +@prefix rdfs: . +@prefix xsd: . +@prefix skos: . +@prefix dc: . + +################################################################# +# Object Properties +################################################################# + +### http://purl.obolibrary.org/obo/BFO_0000171 +obo:BFO_0000171 rdf:type owl:ObjectProperty ; + dc:identifier "234-BFO" ; + rdfs:label "located in"@en ; + skos:definition "b located in c =Def b is an independent continuant & c is an independent & neither is a spatial region & there is some time t such that the spatial region which b occupies at t is continuant part of the spatial region which c occupies at t"@en ; + skos:scopeNote "Users that require more sophisticated representations of time are encouraged to import a temporal extension of BFO-Core provided by the BFO development team."@en . + +################################################################# +# Classes +################################################################# + +### http://purl.obolibrary.org/obo/BFO_0000029 +obo:BFO_0000029 rdf:type owl:Class ; + dc:identifier "034-BFO" ; + rdfs:label "site"@en ; + skos:definition "(Elucidation) A site is a three-dimensional immaterial entity whose boundaries either (partially or wholly) coincide with the boundaries of one or more material entities or have locations determined in relation to some material entity"@en ; + skos:example "A hole in a portion of cheese; a rabbit hole; the Grand Canyon; the Piazza San Marco; the kangaroo-joey-containing hole of a kangaroo pouch; your left nostril (a fiat part - the opening - of your left nasal cavity); the lumen of your gut; the hold of a ship; the interior of the trunk of your car; hole in an engineered floor joist"@en . + +### https://www.commoncoreontologies.org/ont00000192 +cco:ont00000192 rdf:type owl:Class ; + rdfs:label "Facility"@en ; + skos:definition "A Material Artifact that is designed as a building or campus dedicated to some specific purpose."@en ; + cco:ont00001760 "https://www.commoncoreontologies.org/ArtifactOntology"^^xsd:anyURI . + +################################################################# +# Individuals - Sites (Hierarchy) +################################################################# + +# States +:state_ny rdf:type owl:NamedIndividual , + obo:BFO_0000029 ; + rdfs:label "NY State" . + +:state_ca rdf:type owl:NamedIndividual , + obo:BFO_0000029 ; + rdfs:label "California" . + +:state_tx rdf:type owl:NamedIndividual , + obo:BFO_0000029 ; + rdfs:label "Texas" . + +# Cities +:city_nyc rdf:type owl:NamedIndividual , + obo:BFO_0000029 ; + rdfs:label "New York City" ; + obo:BFO_0000171 :state_ny . + +:city_buffalo rdf:type owl:NamedIndividual , + obo:BFO_0000029 ; + rdfs:label "Buffalo" ; + obo:BFO_0000171 :state_ny . + +:city_la rdf:type owl:NamedIndividual , + obo:BFO_0000029 ; + rdfs:label "Los Angeles" ; + obo:BFO_0000171 :state_ca . + +:city_houston rdf:type owl:NamedIndividual , + obo:BFO_0000029 ; + rdfs:label "Houston" ; + obo:BFO_0000171 :state_tx . + +# Campuses +:campus_manhattan rdf:type owl:NamedIndividual , + obo:BFO_0000029 ; + rdfs:label "Manhattan Campus" ; + obo:BFO_0000171 :city_nyc . + +:campus_downtown_la rdf:type owl:NamedIndividual , + obo:BFO_0000029 ; + rdfs:label "Downtown LA Campus" ; + obo:BFO_0000171 :city_la . + +# Buildings +:building_tower1 rdf:type owl:NamedIndividual , + obo:BFO_0000029 ; + rdfs:label "Tower 1" ; + obo:BFO_0000171 :campus_manhattan . + +:building_tower2 rdf:type owl:NamedIndividual , + obo:BFO_0000029 ; + rdfs:label "Tower 2" ; + obo:BFO_0000171 :campus_manhattan . + +################################################################# +# Individuals - Facilities +################################################################# + +:facility_warehouse_nyc rdf:type owl:NamedIndividual , + cco:ont00000192 ; + rdfs:label "NYC Main Warehouse" ; + obo:BFO_0000171 :building_tower1 . + +:facility_office_nyc rdf:type owl:NamedIndividual , + cco:ont00000192 ; + rdfs:label "NYC Corporate Office" ; + obo:BFO_0000171 :building_tower2 . + +:facility_lab_nyc rdf:type owl:NamedIndividual , + cco:ont00000192 ; + rdfs:label "NYC Research Lab" ; + obo:BFO_0000171 :campus_manhattan . + +:facility_warehouse_buffalo rdf:type owl:NamedIndividual , + cco:ont00000192 ; + rdfs:label "Buffalo Distribution Center" ; + obo:BFO_0000171 :city_buffalo . + +:facility_warehouse_la rdf:type owl:NamedIndividual , + cco:ont00000192 ; + rdfs:label "LA Warehouse" ; + obo:BFO_0000171 :campus_downtown_la . + +:facility_office_la rdf:type owl:NamedIndividual , + cco:ont00000192 ; + rdfs:label "LA Regional Office" ; + obo:BFO_0000171 :city_la . + +:facility_plant_houston rdf:type owl:NamedIndividual , + cco:ont00000192 ; + rdfs:label "Houston Manufacturing Plant" ; + obo:BFO_0000171 :city_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 42c5cf9..e1625a7 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 | +