# Paquete R (brechaspnip) {#sec-pkg}

El paquete **brechaspnip** es el motor de cálculos del sistema. Contiene las funciones para calcular brechas, inversiones y optimizar planes.

## Visión General

- **Lenguaje**: R 4.4+
- **Dependencias principales**: dplyr, tidyr, readr, sf, geodom
- **Ubicación**: `brechaspnip/`
- **Licencia**: [Especificar]

## Estructura del Paquete

```
brechaspnip/
├── R/
│   ├── motor-calculos.R    # Motor principal
│   ├── a11.R, a21.R        # Indicadores Agua
│   ├── e11.R, e12.R        # Indicadores Educación
│   ├── s11.R, s21.R, s31.R # Indicadores Salud
│   ├── t11-t31.R           # Indicadores Transporte
│   ├── v11-v32.R           # Indicadores Vivienda
│   ├── proyecciones.R      # Proyecciones demográficas
│   └── utils.R             # Utilidades
├── inst/extdata/           # Datos de entrada
├── man/                    # Documentación
└── tests/                  # Tests unitarios
```

## Filosofía de Diseño

El paquete sigue principios de:

- **Modularidad**: Cada indicador es independiente
- **Consistencia**: Todos usan el motor genérico
- **Flexibilidad**: Parámetros ampliamente configurables
- **Reproducibilidad**: Resultados determinísticos
- **Transparencia**: Código documentado y testeado

## Características Principales

### 16 Indicadores

Cada uno con función `calcular_<id>()`:

- `calcular_a11()`, `calcular_a21()` (Agua)
- `calcular_e11()`, `calcular_e12()` (Educación)
- `calcular_s11()`, `calcular_s21()`, `calcular_s31()` (Salud)
- `calcular_t11()`, ... `calcular_t31()` (Transporte)
- `calcular_v11()`, ... `calcular_v32()` (Vivienda)

### Motor Genérico

Función `calcular()` que:

1. Carga datos de población e inventario
2. Calcula universo por provincia y año
3. Determina brecha (universo - cobertura existente)
4. Optimiza plan de construcción
5. Calcula inversiones (construcción, mantenimiento, reemplazo, ahorro)
6. Retorna resultados estructurados

### Optimización Automática

Algoritmo de búsqueda binaria que:

- **Modo Meta**: Ajusta la cuota de construcción para alcanzar una meta de cobertura específica (Enfoque de Necesidades).
- **Modo Presupuesto**: Maximiza la cobertura dado un techo presupuestario anual o total (Enfoque de Restricción).
- Minimiza la diferencia entre lo planificado y el objetivo, respetando restricciones físicas y financieras.

### Gestión de Datos

- Lectura de datos demográficos, inventarios, costos
- Limpieza de nombres geográficos (package geodom)
- Proyecciones poblacionales

## Casos de Uso

### 1. Usuario Final (vía Webapp)

Usuario no interactúa directamente con R, pero se beneficia de:
- Cálculos precisos y rápidos
- Flexibilidad de parámetros
- Resultados estructurados

### 2. Analista Técnico

Puede ejecutar cálculos desde R:

```r
library(brechaspnip)
resultado <- calcular_s21(
  .anio_plan = 2025,
  .anio_meta = 2030,
  .tasa_meta = 0.95,
  .vida_util_nueva = 40
)
```

### 3. Desarrollador

Puede extender el paquete:
- Agregar nuevos indicadores
- Modificar el motor
- Integrar nuevas fuentes de datos

## Documentación del Paquete

::: {.features-grid}

::: {.feature-card}
**Instalación**
Requisitos del sistema y guía de instalación.
[Ver Instalación &rarr;](installation.qmd)
:::

::: {.feature-card}
**Indicadores**
Definición de los 16 indicadores de brecha.
[Ver Indicadores &rarr;](indicators.qmd)
:::

::: {.feature-card}
**Parámetros**
Referencia de parámetros de configuración.
[Ver Parámetros &rarr;](parameters.qmd)
:::

::: {.feature-card}
**Motor de Cálculo**
Lógica de optimización y estados de infraestructura.
[Ver Motor &rarr;](motor.qmd)
:::

::: {.feature-card}
**Ejemplos**
Casos de uso programático y scripts.
[Ver Ejemplos &rarr;](examples.qmd)
:::

:::