Skip to content

Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.

feat: add clinical crosswalks module with Parquet-backed term lookup

FABIOTESS5e424ca9f88d
diff --git a/.gitignore b/.gitignore
index cc2e6ce5..0335f6ae 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,3 @@
/target
.worktrees/
+data/
diff --git a/scripts/build_crosswalks.py b/scripts/build_crosswalks.py
new file mode 100644
index 00000000..82c55d1d
--- /dev/null
+++ b/scripts/build_crosswalks.py
@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+"""Build clinical crosswalk Parquet file from open sources.
+
+Sources:
+- WHO ICD-10 codes (via open CSV mirrors)
+- SNOMED-CT to ICD-10 mapping (NHS TRUD open mapping files)
+- MeSH descriptors (NLM FTP)
+
+Output: data/crosswalks.parquet with columns:
+ source_code, source_system, target_code, target_system, relation, source_label, target_label
+
+Usage:
+ python scripts/build_crosswalks.py
+"""
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+
+# Minimal seed data for development/testing.
+# In production, fetch from WHO, NHS TRUD, NLM.
+SEED_DATA = [
+ ("I10", "ICD10", "38341003", "SNOMED", "equivalent", "Essential hypertension", "Hypertensive disorder"),
+ ("I11", "ICD10", "64715009", "SNOMED", "equivalent", "Hypertensive heart disease", "Hypertensive heart disease"),
+ ("E11", "ICD10", "44054006", "SNOMED", "equivalent", "Type 2 diabetes mellitus", "Diabetes mellitus type 2"),
+ ("J45", "ICD10", "195967001", "SNOMED", "equivalent", "Asthma", "Asthma"),
+ ("C34", "ICD10", "254637007", "SNOMED", "equivalent", "Malignant neoplasm of bronchus and lung", "Non-small cell lung cancer"),
+ ("I10", "ICD10", "D003062", "MeSH", "related", "Essential hypertension", "Hypertension"),
+ ("E11", "ICD10", "D003924", "MeSH", "related", "Type 2 diabetes mellitus", "Diabetes Mellitus, Type 2"),
+ ("38341003", "SNOMED", "D006973", "MeSH", "related", "Hypertensive disorder", "Hypertension"),
+]
+
+
+def build():
+ table = pa.table({
+ "source_code": [r[0] for r in SEED_DATA],
+ "source_system": [r[1] for r in SEED_DATA],
+ "target_code": [r[2] for r in SEED_DATA],
+ "target_system": [r[3] for r in SEED_DATA],
+ "relation": [r[4] for r in SEED_DATA],
+ "source_label": [r[5] for r in SEED_DATA],
+ "target_label": [r[6] for r in SEED_DATA],
+ })
+ pq.write_table(table, "data/crosswalks.parquet")
+ print(f"Written {len(SEED_DATA)} rows to data/crosswalks.parquet")
+
+
+if __name__ == "__main__":
+ build()
diff --git a/src/clinical.rs b/src/clinical.rs
new file mode 100644
index 00000000..9c1c24c3
--- /dev/null
+++ b/src/clinical.rs
@@ -0,0 +1,192 @@
+use crate::drift::jaro_winkler;
+use crate::graph::GraphStore;
+use std::sync::Arc;
+
+/// A single crosswalk mapping row.
+#[derive(Debug, Clone)]
+pub struct CrosswalkRow {
+ pub source_code: String,
+ pub source_system: String,
+ pub target_code: String,
+ pub target_system: String,
+ pub relation: String,
+ pub source_label: String,
+ pub target_label: String,
+}
+
+/// Clinical crosswalks backed by a Parquet file.
+pub struct ClinicalCrosswalks {
+ rows: Vec<CrosswalkRow>,
+}
+
+impl ClinicalCrosswalks {
+ /// Load crosswalk data from a Parquet file.
+ pub fn load(path: &str) -> anyhow::Result<Self> {
+ use arrow::array::StringArray;
+ use parquet::arrow::arrow_reader::ParquetRecordBatchReaderBuilder;
+ use std::fs::File;
+
+ let file = File::open(path)?;
+ let builder = ParquetRecordBatchReaderBuilder::try_new(file)?;
+ let reader = builder.build()?;
+
+ let mut rows = Vec::new();
+ for batch in reader {
+ let batch = batch?;
+ let source_code = batch.column_by_name("source_code")
+ .and_then(|c| c.as_any().downcast_ref::<StringArray>());
+ let source_system = batch.column_by_name("source_system")
+ .and_then(|c| c.as_any().downcast_ref::<StringArray>());
+ let target_code = batch.column_by_name("target_code")
+ .and_then(|c| c.as_any().downcast_ref::<StringArray>());
+ let target_system = batch.column_by_name("target_system")
+ .and_then(|c| c.as_any().downcast_ref::<StringArray>());
+ let relation = batch.column_by_name("relation")
+ .and_then(|c| c.as_any().downcast_ref::<StringArray>());
+ let source_label = batch.column_by_name("source_label")
+ .and_then(|c| c.as_any().downcast_ref::<StringArray>());
+ let target_label = batch.column_by_name("target_label")
+ .and_then(|c| c.as_any().downcast_ref::<StringArray>());
+
+ if let (Some(sc), Some(ss), Some(tc), Some(ts), Some(rel), Some(sl), Some(tl)) =
+ (source_code, source_system, target_code, target_system, relation, source_label, target_label)
+ {
+ for i in 0..batch.num_rows() {
+ rows.push(CrosswalkRow {
+ source_code: sc.value(i).to_string(),
+ source_system: ss.value(i).to_string(),
+ target_code: tc.value(i).to_string(),
+ target_system: ts.value(i).to_string(),
+ relation: rel.value(i).to_string(),
+ source_label: sl.value(i).to_string(),
+ target_label: tl.value(i).to_string(),
+ });
+ }
+ }
+ }
+
+ Ok(Self { rows })
+ }
+
+ /// Look up all mappings for a given code and system.
+ pub fn lookup(&self, code: &str, system: &str) -> Vec<&CrosswalkRow> {
+ self.rows
+ .iter()
+ .filter(|r| r.source_code == code && r.source_system == system)
+ .collect()
+ }
+
+ /// Fuzzy search across all labels using Jaro-Winkler.
+ pub fn search_label(&self, text: &str) -> Vec<serde_json::Value> {
+ let text_lower = text.to_lowercase();
+ let mut results: Vec<(f64, &CrosswalkRow)> = self
+ .rows
+ .iter()
+ .map(|r| {
+ let sl_score = jaro_winkler(&text_lower, &r.source_label.to_lowercase());
+ let tl_score = jaro_winkler(&text_lower, &r.target_label.to_lowercase());
+ (sl_score.max(tl_score), r)
+ })
+ .filter(|(score, _)| *score > 0.6)
+ .collect();
+
+ results.sort_by(|a, b| b.0.partial_cmp(&a.0).unwrap_or(std::cmp::Ordering::Equal));
+ results.truncate(20);
+
+ results
+ .iter()
+ .map(|(score, r)| {
+ serde_json::json!({
+ "source_code": r.source_code,
+ "source_system": r.source_system,
+ "target_code": r.target_code,
+ "target_system": r.target_system,
+ "source_label": r.source_label,
+ "target_label": r.target_label,
+ "similarity": score,
+ })
+ })
+ .collect()
+ }
+
+ /// Validate clinical terms in a loaded ontology against the crosswalk data.
+ pub fn validate_clinical(&self, graph: &GraphStore) -> String {
+ let label_query = "SELECT ?c ?l WHERE { \
+ ?c a <http://www.w3.org/2002/07/owl#Class> . \
+ ?c <http://www.w3.org/2000/01/rdf-schema#label> ?l \
+ }";
+
+ let mut validated = Vec::new();
+ let mut unmatched = Vec::new();
+
+ if let Ok(json) = graph.sparql_select(label_query) {
+ if let Ok(parsed) = serde_json::from_str::<serde_json::Value>(&json) {
+ if let Some(results) = parsed["results"].as_array() {
+ for row in results {
+ if let (Some(class_iri), Some(label)) = (row["c"].as_str(), row["l"].as_str()) {
+ let label_clean = label.trim_matches('"').split("^^").next().unwrap_or("").trim_matches('"');
+ let matches = self.search_label(label_clean);
+ if !matches.is_empty() {
+ validated.push(serde_json::json!({
+ "class": class_iri,
+ "label": label_clean,
+ "matches": matches.len(),
+ "best_match": matches[0],
+ }));
+ } else {
+ unmatched.push(serde_json::json!({
+ "class": class_iri,
+ "label": label_clean,
+ }));
+ }
+ }
+ }
+ }
+ }
+ }
+
+ serde_json::json!({
+ "validated": validated,
+ "unmatched": unmatched,
+ "total_classes": validated.len() + unmatched.len(),
+ })
+ .to_string()
+ }
+
+ /// Enrich an ontology class with a SKOS mapping triple.
+ pub fn enrich(&self, graph: &GraphStore, class_iri: &str, code: &str, system: &str) -> String {
+ let mappings = self.lookup(code, system);
+ if mappings.is_empty() {
+ return serde_json::json!({
+ "ok": false,
+ "message": format!("No crosswalk found for {} in {}", code, system),
+ })
+ .to_string();
+ }
+
+ let target = &mappings[0];
+ let update = format!(
+ "INSERT DATA {{ <{}> <http://www.w3.org/2004/02/skos/core#exactMatch> <urn:{}:{}> . \
+ <urn:{}:{}> <http://www.w3.org/2000/01/rdf-schema#label> \"{}\" . }}",
+ class_iri,
+ target.target_system, target.target_code,
+ target.target_system, target.target_code,
+ target.target_label,
+ );
+
+ match graph.sparql_update(&update) {
+ Ok(n) => serde_json::json!({
+ "ok": true,
+ "enriched": class_iri,
+ "mapped_to": format!("{}:{}", target.target_system, target.target_code),
+ "triples_added": n,
+ })
+ .to_string(),
+ Err(e) => serde_json::json!({
+ "ok": false,
+ "error": e.to_string(),
+ })
+ .to_string(),
+ }
+ }
+}
diff --git a/src/lib.rs b/src/lib.rs
index 6f49126f..159a9a95 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,4 +1,5 @@
pub mod config;
+pub mod clinical;
pub mod drift;
pub mod enforce;
pub mod graph;
diff --git a/tests/clinical_test.rs b/tests/clinical_test.rs
new file mode 100644
index 00000000..3e709bc3
--- /dev/null
+++ b/tests/clinical_test.rs
@@ -0,0 +1,74 @@
+use open_ontologies::graph::GraphStore;
+use std::sync::Arc;
+
+#[test]
+fn test_crosswalk_lookup() {
+ use open_ontologies::clinical::ClinicalCrosswalks;
+ let cw = ClinicalCrosswalks::load("data/crosswalks.parquet");
+ if cw.is_err() {
+ eprintln!("Skipping: crosswalks.parquet not found. Run scripts/build_crosswalks.py first.");
+ return;
+ }
+ let cw = cw.unwrap();
+
+ let results = cw.lookup("I10", "ICD10");
+ assert!(!results.is_empty());
+}
+
+#[test]
+fn test_crosswalk_search_by_label() {
+ use open_ontologies::clinical::ClinicalCrosswalks;
+ let cw = ClinicalCrosswalks::load("data/crosswalks.parquet");
+ if cw.is_err() { return; }
+ let cw = cw.unwrap();
+
+ let results = cw.search_label("hypertension");
+ assert!(!results.is_empty());
+}
+
+#[test]
+fn test_validate_clinical_terms() {
+ use open_ontologies::clinical::ClinicalCrosswalks;
+ let cw = ClinicalCrosswalks::load("data/crosswalks.parquet");
+ if cw.is_err() { return; }
+ let cw = cw.unwrap();
+
+ let graph = Arc::new(GraphStore::new());
+ graph.load_turtle(r#"
+ @prefix owl: <http://www.w3.org/2002/07/owl#> .
+ @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+ @prefix ex: <http://example.org/> .
+ ex:Hypertension a owl:Class ; rdfs:label "Hypertension" .
+ ex:FakeDisease a owl:Class ; rdfs:label "Xylophagous Syndrome" .
+ "#, None).unwrap();
+
+ let result = cw.validate_clinical(&graph);
+ assert!(result.contains("validated") || result.contains("unmatched"));
+}
+
+#[test]
+fn test_enrich_adds_skos_mapping() {
+ use open_ontologies::clinical::ClinicalCrosswalks;
+ let cw = ClinicalCrosswalks::load("data/crosswalks.parquet");
+ if cw.is_err() { return; }
+ let cw = cw.unwrap();
+
+ let graph = Arc::new(GraphStore::new());
+ graph.load_turtle(r#"
+ @prefix owl: <http://www.w3.org/2002/07/owl#> .
+ @prefix ex: <http://example.org/> .
+ ex:Hypertension a owl:Class .
+ "#, None).unwrap();
+
+ let result = cw.enrich(&graph, "http://example.org/Hypertension", "I10", "ICD10");
+ assert!(result.contains("ok") || result.contains("enriched"));
+}
+
+#[test]
+fn test_clinical_label_matching() {
+ use open_ontologies::drift::jaro_winkler;
+ let score = jaro_winkler("Hypertension", "HyperTensionSyndrome");
+ assert!(score > 0.5);
+ let score = jaro_winkler("Hypertension", "Essential hypertension");
+ assert!(score > 0.4);
+}