Installation and Configuration Guide

This guide is written for people who work with health databases and may still be learning R: installing a package from GitHub with pak and setting up the WHO API key are not obvious steps for them, so they are explained here in detail. If you are already comfortable with R, you can skip this vignette: pak::pak("ropensci/ciecl") is all you need to get started.

Installation

The simplest way to install ciecl is with the pak package, which automatically resolves R and system dependencies.

From CRAN (stable version)

install.packages("ciecl")

From GitHub (development version)

install.packages("pak")
pak::pak("ropensci/ciecl")

To also install all optional dependencies (comorbidities, GT tables, ICD-11 API):

pak::pak("ropensci/ciecl", dependencies = TRUE)

Dependencies by feature

The package core (ICD-10 code lookup and search) requires no optional packages. These are the suggested dependencies by task:

Feature Package Installation
Charlson/Elixhauser comorbidity indices with cie_comorbid() comorbidity install.packages("comorbidity")
Formatted HTML tables with cie_table() gt install.packages("gt")
Read MINSAL Excel files readxl install.packages("readxl")

System requirements

Windows

No additional dependencies: the installation works out of the box.

macOS

Install the Xcode Command Line Tools if you compile from source:

xcode-select --install

Linux (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install -y \
  r-base-dev \
  libcurl4-openssl-dev \
  libssl-dev \
  libxml2-dev

Linux (Fedora/RHEL/CentOS)

sudo dnf install -y \
  R-devel \
  libcurl-devel \
  openssl-devel \
  libxml2-devel

ICD-11 API Configuration (optional)

The CIE-10 functions (the core of the package) work without credentials. You only need free WHO credentials to use cie11_search(), which queries the WHO ICD-11 classification.

Security: never write the literal key in your scripts (not even via api_key = "..."): sharing the code would expose your credentials. The recommended way is the ICD_API_KEY environment variable, set with usethis::edit_r_environ() (Option B) or via keyring (Option A). The api_key argument of cie11_search() exists only for exceptional cases (e.g. multiple keys or environments where env vars cannot be set).

Step 1: Get credentials

  1. Visit https://icd.who.int/icdapi
  2. Register with your email (free)
  3. You will receive a Client ID and a Client Secret

Step 2: Store the credentials

Option A: keyring (recommended)

The keyring package stores secrets in the OS native keychain (macOS Keychain, Windows Credential Store, Linux Secret Service), avoiding plain-text secrets in .Renviron.

# Once: store "client_id:client_secret" in the keychain
keyring::key_set("ciecl_icd11")

# In each session where you use the API
Sys.setenv(ICD_API_KEY = keyring::key_get("ciecl_icd11"))

Option B: .Renviron file

Create or edit ~/.Renviron (for example with usethis::edit_r_environ() if you have usethis installed) and add:

ICD_API_KEY=your_client_id:your_client_secret

Restart R for it to take effect. Do not commit .Renviron to Git.

Option C: Current session only (temporary)

Sys.setenv(ICD_API_KEY = "your_client_id:your_client_secret")

Step 3: Verify the configuration

# Check that the environment variable is set
Sys.getenv("ICD_API_KEY")

# Test an ICD-11 search
library(ciecl)
cie11_search("diabetes")

SQLite cache

The package uses a local SQLite database for efficient searches. It is created automatically on first use, in the user data directory:

# Show the cache location
tools::R_user_dir("ciecl", "data")

You can change that location by setting the CIECL_CACHE_DIR environment variable before loading the package. To force a rebuild of the database (for example, after updating the package):

library(ciecl)
cie10_clear_cache()

Verify the installation

library(ciecl)

# Check that the package loads correctly
packageVersion("ciecl")

# Verify catalogue access
nrow(cie10_cl)

# Test a basic lookup
cie_lookup("E11.0")

# Test fuzzy search
cie_search("diabetes")

Troubleshooting

Error: “package ‘ciecl’ is not available”

Check that a CRAN repository is configured in your R session, then install as usual:

install.packages("ciecl")

Compilation error on Linux

Install the system dependencies listed in the “System requirements” section and try the installation again.

The ICD-11 API does not respond

  1. Check that the credential is set: Sys.getenv("ICD_API_KEY") must not return an empty string.
  2. Check your internet connection.
  3. Check the WHO service status at https://icd.who.int/icdapi: if it is down, the ICD-10 functions keep working because they do not depend on the API.

Corrupt cache

Clear the cache and restart R:

ciecl::cie10_clear_cache()