|
| 1 | +#' FHIR-to-OMOP Concept Resolver |
| 2 | +#' |
| 3 | +#' @description |
| 4 | +#' R6 class providing access to the FHIR-to-OMOP Concept Resolver endpoints. |
| 5 | +#' Translates FHIR coded values (system URI + code) into OMOP standard |
| 6 | +#' concepts, CDM target tables, and optional Phoebe recommendations. |
| 7 | +#' |
| 8 | +#' @details |
| 9 | +#' Access via the `fhir` active binding on an `OMOPHubClient`: |
| 10 | +#' ```r |
| 11 | +#' client <- OMOPHubClient$new(api_key = "oh_xxx") |
| 12 | +#' result <- client$fhir$resolve( |
| 13 | +#' system = "http://snomed.info/sct", |
| 14 | +#' code = "44054006", |
| 15 | +#' resource_type = "Condition" |
| 16 | +#' ) |
| 17 | +#' result$data$resolution$target_table |
| 18 | +#' # "condition_occurrence" |
| 19 | +#' ``` |
| 20 | +#' |
| 21 | +#' @keywords internal |
| 22 | +FhirResource <- R6::R6Class( |
| 23 | + "FhirResource", |
| 24 | + public = list( |
| 25 | + #' @description |
| 26 | + #' Create a new FhirResource. |
| 27 | + #' @param base_req Base httr2 request object. |
| 28 | + initialize = function(base_req) { |
| 29 | + private$.base_req <- base_req |
| 30 | + }, |
| 31 | + |
| 32 | + #' @description |
| 33 | + #' Resolve a single FHIR Coding to an OMOP standard concept. |
| 34 | + #' |
| 35 | + #' Provide at least one of (`system` + `code`), (`vocabulary_id` + `code`), |
| 36 | + #' or `display`. |
| 37 | + #' |
| 38 | + #' @param system FHIR code system URI (e.g. `"http://snomed.info/sct"`). |
| 39 | + #' @param code Code value from the FHIR Coding. |
| 40 | + #' @param display Human-readable text (semantic search fallback). |
| 41 | + #' @param vocabulary_id Direct OMOP vocabulary_id, bypasses URI resolution. |
| 42 | + #' @param resource_type FHIR resource type (e.g. `"Condition"`, `"Observation"`). |
| 43 | + #' @param include_recommendations Logical. Include Phoebe recommendations. Default `FALSE`. |
| 44 | + #' @param recommendations_limit Integer. Max recommendations (1-20). Default `5L`. |
| 45 | + #' @param include_quality Logical. Include mapping quality signal. Default `FALSE`. |
| 46 | + #' |
| 47 | + #' @returns A list with `input` and `resolution` containing source/standard |
| 48 | + #' concepts, target CDM table, and optional enrichments. |
| 49 | + resolve = function(system = NULL, |
| 50 | + code = NULL, |
| 51 | + display = NULL, |
| 52 | + vocabulary_id = NULL, |
| 53 | + resource_type = NULL, |
| 54 | + include_recommendations = FALSE, |
| 55 | + recommendations_limit = 5L, |
| 56 | + include_quality = FALSE) { |
| 57 | + body <- compact_list( |
| 58 | + system = system, |
| 59 | + code = code, |
| 60 | + display = display, |
| 61 | + vocabulary_id = vocabulary_id, |
| 62 | + resource_type = resource_type |
| 63 | + ) |
| 64 | + if (isTRUE(include_recommendations)) { |
| 65 | + body$include_recommendations <- TRUE |
| 66 | + body$recommendations_limit <- as.integer(recommendations_limit) |
| 67 | + } |
| 68 | + if (isTRUE(include_quality)) { |
| 69 | + body$include_quality <- TRUE |
| 70 | + } |
| 71 | + |
| 72 | + perform_post(private$.base_req, "fhir/resolve", body = body) |
| 73 | + }, |
| 74 | + |
| 75 | + #' @description |
| 76 | + #' Batch-resolve up to 100 FHIR Codings. |
| 77 | + #' |
| 78 | + #' Failed items are reported inline without failing the batch. |
| 79 | + #' |
| 80 | + #' @param codings A list of coding lists, each with optional elements |
| 81 | + #' `system`, `code`, `display`, `vocabulary_id`. |
| 82 | + #' @param resource_type FHIR resource type applied to all codings. |
| 83 | + #' @param include_recommendations Logical. Default `FALSE`. |
| 84 | + #' @param recommendations_limit Integer. Default `5L`. |
| 85 | + #' @param include_quality Logical. Default `FALSE`. |
| 86 | + #' |
| 87 | + #' @returns A list with `results` (per-item) and `summary` |
| 88 | + #' (total/resolved/failed). |
| 89 | + resolve_batch = function(codings, |
| 90 | + resource_type = NULL, |
| 91 | + include_recommendations = FALSE, |
| 92 | + recommendations_limit = 5L, |
| 93 | + include_quality = FALSE) { |
| 94 | + stopifnot(is.list(codings), length(codings) >= 1, length(codings) <= 100) |
| 95 | + if (!all(vapply(codings, is.list, logical(1)))) { |
| 96 | + cli::cli_abort(c( |
| 97 | + "{.arg codings} must be a list of coding lists.", |
| 98 | + "i" = "Each element should be a list with {.field system}, {.field code}, etc.", |
| 99 | + "i" = "Example: {.code list(list(system = \"http://snomed.info/sct\", code = \"44054006\"))}" |
| 100 | + )) |
| 101 | + } |
| 102 | + |
| 103 | + body <- list(codings = codings) |
| 104 | + if (!is.null(resource_type)) body$resource_type <- resource_type |
| 105 | + if (isTRUE(include_recommendations)) { |
| 106 | + body$include_recommendations <- TRUE |
| 107 | + body$recommendations_limit <- as.integer(recommendations_limit) |
| 108 | + } |
| 109 | + if (isTRUE(include_quality)) body$include_quality <- TRUE |
| 110 | + |
| 111 | + perform_post(private$.base_req, "fhir/resolve/batch", body = body) |
| 112 | + }, |
| 113 | + |
| 114 | + #' @description |
| 115 | + #' Resolve a FHIR CodeableConcept with vocabulary preference. |
| 116 | + #' |
| 117 | + #' Picks the best match per OHDSI preference order |
| 118 | + #' (SNOMED > RxNorm > LOINC > CVX > ICD-10). Falls back to `text` |
| 119 | + #' via semantic search if no coding resolves. |
| 120 | + #' |
| 121 | + #' @param coding A list of coding lists, each with `system`, `code`, |
| 122 | + #' and optional `display`. |
| 123 | + #' @param text Optional CodeableConcept.text for semantic fallback. |
| 124 | + #' @param resource_type FHIR resource type. |
| 125 | + #' @param include_recommendations Logical. Default `FALSE`. |
| 126 | + #' @param recommendations_limit Integer. Default `5L`. |
| 127 | + #' @param include_quality Logical. Default `FALSE`. |
| 128 | + #' |
| 129 | + #' @returns A list with `best_match`, `alternatives`, and `unresolved`. |
| 130 | + resolve_codeable_concept = function(coding, |
| 131 | + text = NULL, |
| 132 | + resource_type = NULL, |
| 133 | + include_recommendations = FALSE, |
| 134 | + recommendations_limit = 5L, |
| 135 | + include_quality = FALSE) { |
| 136 | + stopifnot(is.list(coding), length(coding) >= 1, length(coding) <= 20) |
| 137 | + if (!all(vapply(coding, is.list, logical(1)))) { |
| 138 | + cli::cli_abort(c( |
| 139 | + "{.arg coding} must be a list of coding lists.", |
| 140 | + "i" = "Each element should be a list with {.field system} and {.field code}.", |
| 141 | + "i" = "Example: {.code list(list(system = \"http://snomed.info/sct\", code = \"44054006\"))}" |
| 142 | + )) |
| 143 | + } |
| 144 | + |
| 145 | + body <- list(coding = coding) |
| 146 | + if (!is.null(text)) body$text <- text |
| 147 | + if (!is.null(resource_type)) body$resource_type <- resource_type |
| 148 | + if (isTRUE(include_recommendations)) { |
| 149 | + body$include_recommendations <- TRUE |
| 150 | + body$recommendations_limit <- as.integer(recommendations_limit) |
| 151 | + } |
| 152 | + if (isTRUE(include_quality)) body$include_quality <- TRUE |
| 153 | + |
| 154 | + perform_post(private$.base_req, "fhir/resolve/codeable-concept", body = body) |
| 155 | + } |
| 156 | + ), |
| 157 | + private = list( |
| 158 | + .base_req = NULL |
| 159 | + ) |
| 160 | +) |
| 161 | + |
| 162 | + |
| 163 | +#' Helper to remove NULL entries from a named list. |
| 164 | +#' @param ... Named arguments. |
| 165 | +#' @returns A list with NULL entries removed. |
| 166 | +#' @keywords internal |
| 167 | +compact_list <- function(...) { |
| 168 | + args <- list(...) |
| 169 | + args[!vapply(args, is.null, logical(1))] |
| 170 | +} |
0 commit comments