re-factor icd_search

NAMESPACE

@@ -1,15 +1,15 @@
 # Generated by roxygen2: do not edit by hand
 
 export(icd_authenticate)
+export(icd_autocode)
 export(icd_autocode_foundation)
-export(icd_autocode_mms)
 export(icd_check_language)
 export(icd_check_release)
 export(icd_get_entities)
 export(icd_get_entity)
 export(icd_get_foundation)
+export(icd_get_info)
 export(icd_get_languages)
-export(icd_get_mms_release)
 export(icd_get_releases)
 export(icd_oauth_client)
 export(icd_search)

R/icd_autocode.R

@@ -1,15 +1,17 @@
 #'
-#' Perform autocoding
+#' Autocode against the foundation component or linearizations of the ICD-11
 #'
-#' @param q String. Text to be searched. Having the character `%` at the end will
-#'   be regarded as a wild card for that word.
+#' @param q String. Text to be searched. Having the character `%` at the end
+#'   will be regarded as a wild card for that word.
+#' @param linearization A character value for which linearization to search.
+#'   Currently, the possible values for this are *"mms"* and *"icf"*.
 #' @param release A string specifying the release version of the Foundation to
 #'   search from. If not specified, defaults to the latest release version. See
 #'   the available versions with `icd_versions`.
 #' @param subtree A string or vector of strings of URIs. If provided, the
 #'   search will be performed on the entities provided and their descendants.
-#' @param threshold A numeric value between 0 and 1 that indicates the similarity
-#'   between the input text and the matched term. `threshold` is the
+#' @param threshold A numeric value between 0 and 1 that indicates the
+#'   similarity between the input text and the matched term. `threshold` is the
 #'   minimum score to be included in the output. Default is NULL to use
 #'   default value specified by API.
 #' @param api_version Version of the API. Possible values are `v1` or `v2`.
@@ -27,15 +29,19 @@
 #' @param base_url The base URL of the API. Default uses the WHO API server at
 #'   https://id.who.int. If you are using a locally deployed server or hosting
 #'   your own ICD API server, you should specify the URL of your instance here.
-#' @param client The OAuth2 client produced through a call to `icd_oauth_client()`.
+#' @param client The OAuth2 client produced through a call to
+#'   `icd_oauth_client()`.
 #' @param scope Scopes to be requested from the resource owner. Default is
 #'   *"icdapi_access"* as specified in the ICD API documentation.
 #'
-#' @return An autocode
+#' @return A tibble of autocode results showing the search text, the matching
+#'   text, the code, URIs for the foundation and linearization entities, the
+#'   matching level, the matching score, and the matching type.
 #'
 #' @examples
 #' icd_autocode_foundation("cholera")
-#' icd_autocode_mms(release = "2024-01", q = "cholera")
+#' icd_autocode(q = "cholera")
+#' icd_autocode(q = "impairment", linearization = "icf")
 #'
 #' @rdname icd_autocode
 #' @export
@@ -105,17 +111,21 @@ icd_autocode_foundation <- function(q,
 #' @rdname icd_autocode
 #' @export
 #'
-icd_autocode_mms <- function(q,
-                             subtree = NULL,
-                             release = NULL,
-                             threshold = NULL,
-                             api_version = c("v2", "v1"),
-                             language = "en",
-                             tabular = TRUE,
-                             verbose = TRUE,
-                             base_url = "https://id.who.int",
-                             client = icd_oauth_client(),
-                             scope = "icdapi_access") {
+icd_autocode <- function(q,
+                         linearization = c("mms", "icf"),
+                         subtree = NULL,
+                         release = NULL,
+                         threshold = NULL,
+                         api_version = c("v2", "v1"),
+                         language = "en",
+                         tabular = TRUE,
+                         verbose = TRUE,
+                         base_url = "https://id.who.int",
+                         client = icd_oauth_client(),
+                         scope = "icdapi_access") {
+  ## Get linearization ----
+  linearization <- match.arg(linearization)
+
   ## Get API version to use ----
   api_version <- match.arg(api_version)
 
@@ -130,9 +140,8 @@ icd_autocode_mms <- function(q,
     language <- icd_check_language(release, language, verbose = verbose)
 
   ## Make base request ----
-  req <- httr2::request(
-    file.path(base_url, "icd/release/11", release, "mms/autocode")
-  ) |>
+  req <- httr2::request(base_url) |>
+    httr2::req_url_path("icd/release/11", release, linearization, "autocode") |>
     httr2::req_url_query(searchText = q)
 
   ## Add query components ----

R/icd_get.R

@@ -1,10 +1,13 @@
 #'
-#' Get information on various ICD 11 Foundation entities
+#' Get information on various ICD-11 foundation and linearization entities
 #'
 #' @param id Unique numerical identifier for an entity.
 #' @param release A string specifying the release version of the Foundation to
 #'   search from. If not specified, defaults to the latest release version. See
 #'   the available versions with `icd_versions`.
+#' @param linearization A character value for which linearization to search.
+#'   Currently, the possible values for this are *"mms"* and *"icf"*. Default
+#'   is *"mms"*.
 #' @param include A string or a vector of strings for optional property values
 #'   to be included in the response. The property values that can be included
 #'   are *"ancestor"*, *"descendant"*, or *"diagnosticCriteria"*. If not
@@ -24,7 +27,8 @@
 #' @param base_url The base URL of the API. Default uses the WHO API server at
 #'   https://id.who.int. If you are using a locally deployed server or hosting
 #'   your own ICD API server, you should specify the URL of your instance here.
-#' @param client The OAuth2 client produced through a call to `icd_oauth_client()`.
+#' @param client The OAuth2 client produced through a call to
+#'   `icd_oauth_client()`.
 #' @param scope Scopes to be requested from the resource owner. Default is
 #'   *"icdapi_access"* as specified in the ICD API documentation.
 #'
@@ -36,7 +40,8 @@
 #' icd_get_entity(id = "1435254666")     ## chapter
 #' icd_get_entity(id = "588616678")      ## block; depth 1
 #' icd_get_entity(id = "1465325727")     ## category; depth 1
-#' icd_get_mms_release()
+#' icd_get_info()
+#' icd_get_info("icf")
 #'
 #' @rdname icd_get
 #' @export
@@ -149,11 +154,15 @@ icd_get_entity <- function(id,
 #' @rdname icd_get
 #' @export
 #'
-icd_get_mms_release <- function(api_version = c("v2", "v1"),
-                                language = "en",
-                                base_url = "https://id.who.int",
-                                client = icd_oauth_client(),
-                                scope = "icdapi_access") {
+icd_get_info <- function(linearization = c("mms", "icf"),
+                         api_version = c("v2", "v1"),
+                         language = "en",
+                         base_url = "https://id.who.int",
+                         client = icd_oauth_client(),
+                         scope = "icdapi_access") {
+  ## Get linearization to search ----
+  linearization <- match.arg(linearization)
+
   ## Get API version to use ----
   api_version <- match.arg(api_version)
 
@@ -166,7 +175,7 @@ icd_get_mms_release <- function(api_version = c("v2", "v1"),
 
   ## Make base request ----
   req <- httr2::request(base_url) |>
-    httr2::req_url_path("icd/release/11/mms") |>
+    httr2::req_url_path("icd/release/11", linearization) |>
     httr2::req_headers(
       Accept = "application/json",
       "API-Version" = api_version,

R/icd_search.R

@@ -1,52 +1,6 @@
 #'
 #' Search the foundation component or linearizations of the ICD-11
 #'
-#' @section On `flexisearch`: In the regular search mode (`flexisearch = FALSE`),
-#'   the function will only give you results that contain all of the words that
-#'   you've used in your search. It accepts different variants or synonyms of
-#'   the words but essentially it searches for a result that contains all
-#'   components of your search. Whereas in flexible search mode, the results do
-#'   not have to contain all of the words that are typed. It would still try to
-#'   find the best matching phrase but there may be words in your search that
-#'   are not matched at all. It is recommended to use flexible search only when
-#'   regular search does not provide a result.
-#'
-#' @section On `keyword`: If set to true, the search result will also include
-#'   keyword list. If the last word provided is incomplete, keyword list
-#'   includes all words that start with the incomplete word
-#'   (word completion mode). If the last word is complete, the keyword list
-#'   will provide suggested additional words that could be added to the search
-#'   query (word suggestion mode).
-#'
-#' @section On `medical_mode`: When searching the classification for
-#'   medical coding purposes, this should be set to TRUE (default). In this
-#'   mode, the search gives results only from the entities that have a code.
-#'   The system will search all index terms of an entity. i.e. *titles*,
-#'   *synonyms*, *fully specified term*, all terms of other entities that are in
-#'   the foundation are aggregated into this entity. By default, *chapters 26*,
-#'   *V*, and *X* are not included in the search results. If `medical_mode` is
-#'   set to FALSE, then the `properties` argument will need to be specified
-#'   (see next section).
-#'
-#' @section On `properties`: In the Foundation search, by default the function
-#'   searches  *"Title"*, *"Synonyms"*, and *"FullySpecifiedName"*. The valid
-#'   values that could be used for properties are: *"Title"*, *"Synonym"*,
-#'   *"NarrowerTerm"*, *"FullySpecifiedName"*, *"Definition"*, and
-#'   *"Exclusion"*. In the MMS search, this argument is only used when
-#'   `medical_mode = FALSE`. The valid values that could be used are:
-#'   *"Title"*, *"FullySpecifiedName"*, *"Definition"*, *"Exclusion"*, and
-#'   *"IndexTerm"*. If *"IndexTerm"* is used, the search will be performed on
-#'   all *"Titles"*, *"Synonyms"*, and *"FullySpecifiedNames"* including the
-#'   ones that are under shoreline (i.e Entities in the foundation but not in
-#'   MMS). In such cases the results will be shown based on where the match is
-#'   aggregated into in MMS.
-#'
-#' @section On `language`: ICD-API is multi-lingual. By setting the language,
-#'   you may make the API respond in different languages. Languages will be
-#'   available as the translations of ICD-11 completes. The values are language
-#'   codes such as en, es, zh, etc. Depending on the `release` specified, the
-#'   available languages will vary.
-#'
 #' @param q String. Text to be searched. Having the character `%` at the end
 #'   will be regarded as a wild card for that word.
 #' @param linearization A character value for which linearization to search.
@@ -98,6 +52,52 @@
 #'
 #' @return A tibble of search results.
 #'
+#' @section On `flexisearch`: In the regular search mode (`flexisearch = FALSE`),
+#'   the function will only give you results that contain all of the words that
+#'   you've used in your search. It accepts different variants or synonyms of
+#'   the words but essentially it searches for a result that contains all
+#'   components of your search. Whereas in flexible search mode, the results do
+#'   not have to contain all of the words that are typed. It would still try to
+#'   find the best matching phrase but there may be words in your search that
+#'   are not matched at all. It is recommended to use flexible search only when
+#'   regular search does not provide a result.
+#'
+#' @section On `keyword`: If set to true, the search result will also include
+#'   keyword list. If the last word provided is incomplete, keyword list
+#'   includes all words that start with the incomplete word
+#'   (word completion mode). If the last word is complete, the keyword list
+#'   will provide suggested additional words that could be added to the search
+#'   query (word suggestion mode).
+#'
+#' @section On `medical_mode`: When searching the classification for
+#'   medical coding purposes, this should be set to TRUE (default). In this
+#'   mode, the search gives results only from the entities that have a code.
+#'   The system will search all index terms of an entity. i.e. *titles*,
+#'   *synonyms*, *fully specified term*, all terms of other entities that are in
+#'   the foundation are aggregated into this entity. By default, *chapters 26*,
+#'   *V*, and *X* are not included in the search results. If `medical_mode` is
+#'   set to FALSE, then the `properties` argument will need to be specified
+#'   (see next section).
+#'
+#' @section On `properties`: In the Foundation search, by default the function
+#'   searches  *"Title"*, *"Synonyms"*, and *"FullySpecifiedName"*. The valid
+#'   values that could be used for properties are: *"Title"*, *"Synonym"*,
+#'   *"NarrowerTerm"*, *"FullySpecifiedName"*, *"Definition"*, and
+#'   *"Exclusion"*. In the MMS search, this argument is only used when
+#'   `medical_mode = FALSE`. The valid values that could be used are:
+#'   *"Title"*, *"FullySpecifiedName"*, *"Definition"*, *"Exclusion"*, and
+#'   *"IndexTerm"*. If *"IndexTerm"* is used, the search will be performed on
+#'   all *"Titles"*, *"Synonyms"*, and *"FullySpecifiedNames"* including the
+#'   ones that are under shoreline (i.e Entities in the foundation but not in
+#'   MMS). In such cases the results will be shown based on where the match is
+#'   aggregated into in MMS.
+#'
+#' @section On `language`: ICD-API is multi-lingual. By setting the language,
+#'   you may make the API respond in different languages. Languages will be
+#'   available as the translations of ICD-11 completes. The values are language
+#'   codes such as en, es, zh, etc. Depending on the `release` specified, the
+#'   available languages will vary.
+#'
 #' @examples
 #' icd_search_foundation("colorectal cancer")
 #' icd_search("colorectal cancer")
@@ -280,7 +280,7 @@ icd_search <- function(q,
         )
     } else {
       stop(
-        "The `properties` argument needs to be specified if `medical_mode = FALSE`"
+        "The `properties` argument should be specified if `medical_mode = FALSE`"
       )
     }
   } else {

R/icd_structure.R

@@ -62,21 +62,37 @@ icd_structure_search <- function(icd_search) {
     meta,
     {
       error <- ifelse(is.logical(error), error, as.logical(error))
+
       errorMessage <- ifelse(
-        is.character(errorMessage), errorMessage, as.character(errorMessage)
+        is.character(errorMessage),
+        errorMessage,
+        as.character(errorMessage)
       )
+
       resultChopped <- ifelse(
-        is.logical(resultChopped), resultChopped, as.logical(resultChopped)
+        is.logical(resultChopped),
+        resultChopped,
+        as.logical(resultChopped)
       )
+
       wordSuggestionsChopped <- ifelse(
         is.logical(wordSuggestionsChopped),
         wordSuggestionsChopped,
         as.logical(wordSuggestionsChopped)
       )
-      guessType <- ifelse(is.integer(guessType), guessType, as.integer(guessType))
+
+      guessType <- ifelse(
+        is.integer(guessType),
+        guessType,
+        as.integer(guessType)
+      )
+
       uniqueSearchId <- ifelse(
-        is.character(uniqueSearchId), uniqueSearchId, as.character(uniqueSearchId)
+        is.character(uniqueSearchId),
+        uniqueSearchId,
+        as.character(uniqueSearchId)
       )
+
       words <- ifelse(is.character(words), words, as.character(words))
     }
   )

inst/WORDLIST

@@ -42,9 +42,11 @@ iCatLink
 icd
 icdapi
 icdcdn
+icf
 int
 isLeaf
 linearizations
+mms
 nd
 noOfNonResidualChildren
 releasefiles