---
title: "Guía de Instalación y Configuración"
author: "Rodolfo Tasso Suazo"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Guía de Instalación y Configuración}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)
```

Esta guía está pensada para personas que trabajan con bases de datos de salud y que quizás están recién aprendiendo R: para ellas, instalar un paquete desde GitHub con `pak` y configurar la API key de la OMS no son pasos obvios, así que aquí se explican con detalle. Si ya tienes experiencia con R, puedes saltarte esta viñeta: basta con `pak::pak("ropensci/ciecl")` para empezar.

## Instalación

La forma más simple de instalar `ciecl` es con el paquete [`pak`](https://pak.r-lib.org/), que resuelve automáticamente las dependencias de R y del sistema operativo.

### Desde CRAN (versión estable)

```{r eval=FALSE}
install.packages("ciecl")
```

### Desde GitHub (versión de desarrollo)

```{r eval=FALSE}
install.packages("pak")
pak::pak("ropensci/ciecl")
```

Para instalar además todas las dependencias opcionales (comorbilidades, tablas GT, API CIE-11):

```{r eval=FALSE}
pak::pak("ropensci/ciecl", dependencies = TRUE)
```

### Dependencias por funcionalidad

El núcleo del paquete (búsqueda y consulta de códigos CIE-10) no requiere
paquetes opcionales. Estas son las dependencias sugeridas según la tarea:

| Funcionalidad | Paquete | Instalación |
|---------------|---------|-------------|
| Índices de comorbilidad Charlson/Elixhauser con `cie_comorbid()` | `comorbidity` | `install.packages("comorbidity")` |
| Tablas HTML formateadas con `cie_table()` | `gt` | `install.packages("gt")` |
| Leer archivos Excel del MINSAL | `readxl` | `install.packages("readxl")` |

## Requisitos del sistema

### Windows

No requiere dependencias adicionales: la instalación funciona directamente.

### macOS

Instala las Xcode Command Line Tools si compilas desde fuente:

```bash
xcode-select --install
```

### Linux (Ubuntu/Debian)

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

### Linux (Fedora/RHEL/CentOS)

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

## Configuración de la API CIE-11 (opcional)

Las funciones de CIE-10 (núcleo del paquete) funcionan sin credenciales. Solo para usar `cie11_search()`, que consulta la clasificación CIE-11 de la OMS, necesitas credenciales gratuitas.

> **Seguridad:** nunca escribas la llave literal en tus scripts (ni con
> `api_key = "..."`): al compartir el código expondrías tus credenciales.
> La vía recomendada es la variable de entorno `ICD_API_KEY`, configurada
> con `usethis::edit_r_environ()` (Opción B) o vía `keyring` (Opción A).
> El argumento `api_key` de `cie11_search()` existe solo para casos
> excepcionales (p. ej. múltiples llaves o entornos sin variables de
> entorno).

### Paso 1: Obtener credenciales

1. Visita <https://icd.who.int/icdapi>
2. Regístrate con tu email (proceso gratuito)
3. Obtendrás un `Client ID` y un `Client Secret`

### Paso 2: Guardar las credenciales

**Opción A: `keyring` (recomendado)**

El paquete [`keyring`](https://keyring.r-lib.org/) guarda secretos
en el keychain nativo del sistema operativo (macOS Keychain, Windows
Credential Store, Linux Secret Service), evitando que el `Client ID` y
el `Client Secret` queden en texto plano en `.Renviron`.

```{r eval=FALSE}
# Una sola vez: guarda "client_id:client_secret" en el keychain
keyring::key_set("ciecl_icd11")

# En cada sesión en la que uses la API
Sys.setenv(ICD_API_KEY = keyring::key_get("ciecl_icd11"))
```

**Opción B: Archivo `.Renviron`**

Crea o edita `~/.Renviron` (por ejemplo con `usethis::edit_r_environ()`
si tienes `usethis` instalado) y agrega:

```
ICD_API_KEY=tu_client_id:tu_client_secret
```

Reinicia R para que tome efecto. No subas `.Renviron` a Git.

**Opción C: Solo en la sesión actual (temporal)**

```{r eval=FALSE}
Sys.setenv(ICD_API_KEY = "tu_client_id:tu_client_secret")
```

### Paso 3: Verificar la configuración

```{r eval=FALSE}
# Verificar que la variable de entorno esta definida
Sys.getenv("ICD_API_KEY")

# Probar una busqueda CIE-11
library(ciecl)
cie11_search("diabetes")
```

## Caché SQLite

El paquete usa una base SQLite local para búsquedas eficientes. Se crea automáticamente en la primera consulta, en el directorio de datos del usuario:

```{r eval=FALSE}
# Ver la ubicacion del cache
tools::R_user_dir("ciecl", "data")
```

Puedes cambiar esa ubicación definiendo la variable de entorno `CIECL_CACHE_DIR` antes de cargar el paquete. Si necesitas forzar la reconstrucción de la base (por ejemplo, tras actualizar el paquete):

```{r eval=FALSE}
library(ciecl)
cie10_clear_cache()
```

## Verificar la instalación

```{r eval=FALSE}
library(ciecl)

# Verificar que el paquete carga correctamente
packageVersion("ciecl")

# Verificar acceso al catálogo
nrow(cie10_cl)

# Probar búsqueda básica
cie_lookup("E11.0")

# Probar búsqueda fuzzy
cie_search("diabetes")
```

## Problemas comunes

### Error: "package 'ciecl' is not available"

Verifica que el repositorio de CRAN esté configurado en tu sesión de R y luego instala normalmente:

```{r eval=FALSE}
install.packages("ciecl")
```

### Error de compilación en Linux

Instala las dependencias del sistema indicadas en la sección
"Requisitos del sistema" y vuelve a intentar la instalación.

### La API CIE-11 no responde

1. Verifica que la credencial esté configurada: `Sys.getenv("ICD_API_KEY")` no debe retornar una cadena vacía.
2. Verifica tu conexión a internet.
3. Comprueba el estado del servicio de la OMS en <https://icd.who.int/icdapi>: si está caído, las funciones de CIE-10 siguen operativas porque no dependen de la API.

### Caché corrupto

Limpia la caché y reinicia R:

```{r eval=FALSE}
ciecl::cie10_clear_cache()
```

## Soporte

- Reportar problemas: <https://github.com/ropensci/ciecl/issues>
- Documentación: <https://docs.ropensci.org/ciecl/>