2 Introducción

2.1 ¿Qué es BrechaSnipApp?

BrechaSnipApp es un sistema de análisis y planificación que permite calcular las brechas de infraestructura del país en múltiples sectores (Agua, Educación, Salud, Transporte y Vivienda). El sistema ayuda a:

Cuantificar brechas: Medir la diferencia entre la infraestructura existente y la necesaria
Estimar inversiones: Calcular los recursos necesarios para cerrar las brechas
Planificar presupuestos: Distribuir inversiones a lo largo del tiempo
Optimizar recursos: Asignar presupuestos de manera eficiente

2.2 Problema que Resuelve

La planificación de infraestructura nacional requiere responder preguntas complejas:

Enfoque de Necesidades: ¿Cuántos hospitales, escuelas o kilómetros de carretera se necesitan para cerrar la brecha al 100% y cuánto costará?
Enfoque de Restricción Presupuestaria: ¿Cuánto logro cerrar la brecha si dispongo de una cantidad limitada de dinero (X inversión)?
¿Qué nivel de cobertura es realista alcanzar en un periodo determinado?

BrechaSnipApp automatiza estos cálculos usando datos demográficos, inventarios de infraestructura existente y parámetros técnicos configurables.

2.3 Arquitectura del Sistema

El sistema consta de tres componentes principales:

sequenceDiagram
    participant U as Usuario
    participant W as Aplicación Web
    participant A as API REST
    participant P as Paquete R
    participant D as Datos

    Note over U, W: 1. El usuario se comunica con el app
    U->>W: Interacción / Configuración
    
    Note over W, A: 2. El app se comunica con el api
    W->>A: Solicitud HTTP (JSON)
    
    Note over A, P: 3. El api se comunica con el paquete
    A->>P: Ejecuta función R
    
    Note over P, D: 4. El paquete consume los datos
    P->>D: Lee archivos/DB
    D-->>P: Retorna dataframes
    
    Note over P, A: 5. El paquete responde al api
    P-->>A: Retorna lista de resultados
    
    Note over A, W: 6. El api responde al web app
    A-->>W: Respuesta JSON
    
    Note over W, U: 7. El web app le responde al usuario
    W-->>U: Visualización / Reporte

2.3.1 Aplicación Web (Frontend)

Tecnología: Next.js + React + TypeScript (Dockerizado)
Función: Interfaz de usuario para configurar parámetros y visualizar resultados
Ubicación: web/

2.3.2 API REST (Middleware)

Tecnología: R + plumber2 (Dockerizado)
Función: Puente entre la aplicación web y el paquete R
Ubicación: api/

2.3.3 Paquete R (Motor de Cálculos)

Tecnología: R + dplyr + tidyr
Función: Motor que realiza todos los cálculos de brechas e inversiones
Ubicación: brechaspnip/

2.4 Conceptos Fundamentales

2.4.1 Horizonte de Planificación

Para realizar cálculos, el sistema requiere definir un periodo de tiempo claro:

Año de inicio (.anio_plan): Primer año del plan de inversión.
Año meta (.anio_meta): Último año del plan, para el cual se evalúa el cumplimiento de metas.

Este horizonte define la duración de vida de los activos a simular y la proyección de brechas.

2.4.2 Plan de Inversión

El sistema opera bajo dos modalidades de inversión:

Automático (Optimización): El sistema calcula cuánto dinero se requiere año tras año para cerrar la brecha (Enfoque de Necesidades).
Manual (Restricción): El usuario define un techo presupuestario anual (.plan_inversion), y el sistema calcula qué porcentaje de la brecha se logra cerrar (Enfoque de Restricción Presupuestaria).

2.4.3 Universo

El universo representa la cantidad total de infraestructura necesaria para satisfacer la demanda. Se calcula dividiendo la población por la cobertura por unidad:

\[ \text{Universo} = \frac{\text{Población}}{\text{Cobertura por Unidad}} \]

Por ejemplo, si hay 500,000 habitantes y cada hospital cubre 50,000 personas: \[ \text{Universo} = \frac{500{,}000}{50{,}000} = 10 \text{ hospitales} \]

Redondeo del Universo

Como no se pueden construir fracciones de infraestructura (ej. 10.37 hospitales), el sistema redondea el universo. Ver Section 8.1.7 para detalles.

El sistema clasifica el inventario en tres estados para determinar la intervención necesaria (Ver TODO: motor-calculos.R):

Aceptable: Infraestructura que cumple con las condiciones recomendadas de seguridad y calidad.
Recuperable: Infraestructura que no se corresponde con las condiciones recomendadas de seguridad y calidad, que se puede adecuar para cumplir con las condiciones recomendadas.
No recuperable: Infraestructura que no se corresponde con las condiciones recomendadas de seguridad y calidad, que no se puede adecuar para cumplir con las condiciones recomendadas.

2.4.4 Meta y tasa de meta

La meta es el objetivo de cobertura que se desea alcanzar en el plan. No siempre se busca cubrir el 100% del universo, sino un porcentaje configurable según las prioridades o restricciones del sector.

La tasa de meta ($\text{Tasa\_meta}$) es ese porcentaje objetivo, y se aplica sobre el universo:

\[ \text{Meta} = \text{Universo} \times \text{Tasa\_meta} \]

Por ejemplo, si el universo es 10 hospitales y la tasa de meta es 0.95 (95%), la meta será 9.5 hospitales.

Esto permite modelar escenarios donde la cobertura total no es necesaria o posible, y comparar resultados bajo diferentes metas.

2.4.5 Cobertura

La cobertura es la cantidad de infraestructura existente más la que se construirá durante el plan. Mide cuánto de la necesidad total está satisfecha:

\[ \text{Tasa de Cobertura} = \frac{\text{Cobertura}}{\text{Universo}} \]

Una tasa de cobertura de 100% significa que toda la demanda está satisfecha.

2.4.5.1 Tasa de cobertura ajustada

La tasa de cobertura ajustada es la proporción entre la cobertura ajustada y el universo:

\[ \text{Tasa de cobertura ajustada} = \frac{\text{Cobertura ajustada}}{\text{Universo}} \]

Donde la cobertura ajustada pondera cada unidad aportada según su condición técnica:

\[ \text{Cobertura ajustada} = \sum \left( \text{UA} \times \frac{\text{CU}}{\text{CU} + \text{CUR}} \right) \]

Aquí, UA es la cantidad de unidades aportadas (existentes + nuevas), CU es el costo de una unidad nueva y CUR es el costo de recuperación de una unidad en mal estado.

Esto significa que las unidades en estado “aceptable” cuentan como 1, mientras que las “recuperables” aportan menos según el costo de su recuperación. Así, la tasa de cobertura ajustada refleja la cobertura efectiva considerando la calidad y recuperabilidad de la infraestructura, no solo la cantidad bruta.

2.4.6 Brecha

La brecha es la diferencia entre lo necesario y lo existente:

\[ \text{Brecha} = \text{Universo} - \text{Cobertura Existente} \]

Representa cuánta infraestructura falta por construir.

Tasa de Brecha:

\[ \text{Tasa de Brecha} = \frac{\text{Brecha}}{\text{Universo}} \]

La tasa de brecha es la proporción de infraestructura que falta por construir.

Por definición, la tasa de cobertura y la tasa de brecha suman 100%.

Es posible calcular la brecha considerando la cobertura ajustada, lo que da una visión más precisa de la necesidad real.

2.4.7 Costos

El modelo utiliza los siguientes conceptos de costos:

Costo unitario (costo_unitario): Costo de construir una unidad nueva de infraestructura.
Costo unitario de recuperación (costo_unitario_recuperacion): Costo adicional necesario para recuperar una unidad en mal estado.
Tasa de mantenimiento (tasa_mantenimiento): Proporción anual del valor de la infraestructura que se debe invertir para mantenerla en condiciones adecuadas.
Valor original (valor_original): Valor base de cada unidad de infraestructura, considerando su estado y costos asociados.
Costo de recuperación (costo_recuperacion): Costo total de recuperar una unidad específica, calculado a partir de los parámetros anteriores.
Costo de brecha (costo_brecha): Costo total necesario para cerrar la brecha de infraestructura identificada.

Estos conceptos se utilizan para calcular las necesidades de inversión, el mantenimiento anual y la priorización de intervenciones en el modelo.

2.4.8 Inversión

El sistema calcula cuatro tipos de inversión:

Construcción: Nuevas unidades para cerrar la brecha
Mantenimiento: Conservación de infraestructura existente y nueva
Recuperación: Reparación de infraestructura obsoleta
Reemplazo: Renovación de infraestructura al final de su vida útil
Ahorro: Fondos acumulados para reemplazos futuros

2.5 Sectores e Indicadores

BrechaSnipApp analiza 5 sectores con un total de 16 indicadores:

Sector	Indicador	Descripción
Agua Potable y Saneamiento	A11	Abastecimiento de Agua
	A21	Alcantarillado Sanitario
Educación	E11	Aulas Escolares
	E12	Educación Técnico Profesional
Salud	S11	Unidades de Atención Primaria (UNAP)
	S21	Hospitales Municipales y Provinciales
	S31	Hospitales Regionales
Transporte	T11	Red Vial Primaria y Autovías
	T12	Red Vial Secundaria
	T13	Red Vial Terciaria
	T21	Aeropuertos
	T31	Transporte Urbano Masivo
Vivienda	V11	Déficit Cualitativo - Techo
	V21	Déficit Cualitativo - Piso
	V31	Déficit Cuantitativo - Paredes
	V32	Déficit Cuantitativo - Allegamiento

Cada indicador tiene parámetros específicos que pueden ajustarse según el contexto. Ver ?sec-pkg-indicators para más detalles.

2.6 Flujo de Trabajo Típico

Configurar años: Definir año de inicio y año meta del plan
Configurar plan de inversión:
- Automático (el sistema optimiza)
- Manual (usuario define presupuestos)
Ajustar parámetros (opcional): Vida útil, tasas de mantenimiento, etc.
Ejecutar cálculos: El sistema procesa todos los indicadores
Analizar resultados: Revisar inversiones, coberturas y brechas
Exportar: Descargar datos para análisis adicional

2.7 Próximos Pasos

Usuario Final Aprenda a utilizar la herramienta web para generar planes. Ver Guía →

Desarrollador Documentación técnica del paquete R y arquitectura. Ver Instalación →

SysAdmin Guías de despliegue con Docker y configuración de servidor. Ver Despliegue →

# Introducción {#sec-introduction} ## ¿Qué es BrechaSnipApp? BrechaSnipApp es un sistema de análisis y planificación que permite calcular las brechas de infraestructura del país en múltiples sectores (Agua, Educación, Salud, Transporte y Vivienda). El sistema ayuda a: - **Cuantificar brechas**: Medir la diferencia entre la infraestructura existente y la necesaria - **Estimar inversiones**: Calcular los recursos necesarios para cerrar las brechas - **Planificar presupuestos**: Distribuir inversiones a lo largo del tiempo - **Optimizar recursos**: Asignar presupuestos de manera eficiente ## Problema que Resuelve La planificación de infraestructura nacional requiere responder preguntas complejas: - **Enfoque de Necesidades**: ¿Cuántos hospitales, escuelas o kilómetros de carretera se necesitan para cerrar la brecha al 100% y cuánto costará? - **Enfoque de Restricción Presupuestaria**: ¿Cuánto logro cerrar la brecha si dispongo de una cantidad limitada de dinero (X inversión)? - ¿Qué nivel de cobertura es realista alcanzar en un periodo determinado? BrechaSnipApp automatiza estos cálculos usando datos demográficos, inventarios de infraestructura existente y parámetros técnicos configurables. ## Arquitectura del Sistema El sistema consta de tres componentes principales: ```{mermaid} sequenceDiagram participant U as Usuario participant W as Aplicación Web participant A as API REST participant P as Paquete R participant D as Datos Note over U, W: 1. El usuario se comunica con el app U->>W: Interacción / Configuración Note over W, A: 2. El app se comunica con el api W->>A: Solicitud HTTP (JSON) Note over A, P: 3. El api se comunica con el paquete A->>P: Ejecuta función R Note over P, D: 4. El paquete consume los datos P->>D: Lee archivos/DB D-->>P: Retorna dataframes Note over P, A: 5. El paquete responde al api P-->>A: Retorna lista de resultados Note over A, W: 6. El api responde al web app A-->>W: Respuesta JSON Note over W, U: 7. El web app le responde al usuario W-->>U: Visualización / Reporte ``` ### Aplicación Web (Frontend) - **Tecnología**: Next.js + React + TypeScript (Dockerizado) - **Función**: Interfaz de usuario para configurar parámetros y visualizar resultados - **Ubicación**: `web/` ### API REST (Middleware) - **Tecnología**: R + plumber2 (Dockerizado) - **Función**: Puente entre la aplicación web y el paquete R - **Ubicación**: `api/` ### Paquete R (Motor de Cálculos) - **Tecnología**: R + dplyr + tidyr - **Función**: Motor que realiza todos los cálculos de brechas e inversiones - **Ubicación**: `brechaspnip/` ## Conceptos Fundamentales ### Horizonte de Planificación Para realizar cálculos, el sistema requiere definir un periodo de tiempo claro: - **Año de inicio (`.anio_plan`)**: Primer año del plan de inversión. - **Año meta (`.anio_meta`)**: Último año del plan, para el cual se evalúa el cumplimiento de metas. Este horizonte define la duración de vida de los activos a simular y la proyección de brechas. ### Plan de Inversión El sistema opera bajo dos modalidades de inversión: 1. **Automático (Optimización)**: El sistema calcula cuánto dinero se requiere año tras año para cerrar la brecha (Enfoque de Necesidades). 2. **Manual (Restricción)**: El usuario define un techo presupuestario anual (`.plan_inversion`), y el sistema calcula qué porcentaje de la brecha se logra cerrar (Enfoque de Restricción Presupuestaria). ### Universo El **universo** representa la cantidad total de infraestructura necesaria para satisfacer la demanda. Se calcula dividiendo la población por la cobertura por unidad: $$ \text{Universo} = \frac{\text{Población}}{\text{Cobertura por Unidad}} $$ Por ejemplo, si hay 500,000 habitantes y cada hospital cubre 50,000 personas: $$ \text{Universo} = \frac{500{,}000}{50{,}000} = 10 \text{ hospitales} $$ ::: {.callout-important} ## Redondeo del Universo Como no se pueden construir fracciones de infraestructura (ej. 10.37 hospitales), el sistema redondea el universo. Ver @sec-parameters-redondeo para detalles. ::: El sistema clasifica el inventario en tres estados para determinar la intervención necesaria (Ver TODO: `motor-calculos.R`): 1. **Aceptable**: Infraestructura que cumple con las condiciones recomendadas de seguridad y calidad. 2. **Recuperable**: Infraestructura que no se corresponde con las condiciones recomendadas de seguridad y calidad, que se puede adecuar para cumplir con las condiciones recomendadas. 3. **No recuperable**: Infraestructura que no se corresponde con las condiciones recomendadas de seguridad y calidad, que no se puede adecuar para cumplir con las condiciones recomendadas. ### Meta y tasa de meta La **meta** es el objetivo de cobertura que se desea alcanzar en el plan. No siempre se busca cubrir el 100% del universo, sino un porcentaje configurable según las prioridades o restricciones del sector. La **tasa de meta** ($\text{Tasa\_meta}$) es ese porcentaje objetivo, y se aplica sobre el universo: $$ \text{Meta} = \text{Universo} \times \text{Tasa\_meta} $$ Por ejemplo, si el universo es 10 hospitales y la tasa de meta es 0.95 (95%), la meta será 9.5 hospitales. Esto permite modelar escenarios donde la cobertura total no es necesaria o posible, y comparar resultados bajo diferentes metas. ### Cobertura La **cobertura** es la cantidad de infraestructura existente más la que se construirá durante el plan. Mide cuánto de la necesidad total está satisfecha: $$ \text{Tasa de Cobertura} = \frac{\text{Cobertura}}{\text{Universo}} $$ Una tasa de cobertura de 100% significa que toda la demanda está satisfecha. #### Tasa de cobertura ajustada La **tasa de cobertura ajustada** es la proporción entre la cobertura ajustada y el universo: $$ \text{Tasa de cobertura ajustada} = \frac{\text{Cobertura ajustada}}{\text{Universo}} $$ Donde la **cobertura ajustada** pondera cada unidad aportada según su condición técnica: $$ \text{Cobertura ajustada} = \sum \left( \text{UA} \times \frac{\text{CU}}{\text{CU} + \text{CUR}} \right) $$ Aquí, UA es la cantidad de unidades aportadas (existentes + nuevas), CU es el costo de una unidad nueva y CUR es el costo de recuperación de una unidad en mal estado. Esto significa que las unidades en estado "aceptable" cuentan como 1, mientras que las "recuperables" aportan menos según el costo de su recuperación. Así, la tasa de cobertura ajustada refleja la cobertura efectiva considerando la calidad y recuperabilidad de la infraestructura, no solo la cantidad bruta. ### Brecha La **brecha** es la diferencia entre lo necesario y lo existente: $$ \text{Brecha} = \text{Universo} - \text{Cobertura Existente} $$ Representa cuánta infraestructura falta por construir. Tasa de Brecha: $$ \text{Tasa de Brecha} = \frac{\text{Brecha}}{\text{Universo}} $$ La tasa de brecha es la proporción de infraestructura que falta por construir. Por definición, la tasa de cobertura y la tasa de brecha suman 100%. Es posible calcular la brecha considerando la cobertura ajustada, lo que da una visión más precisa de la necesidad real. ### Costos El modelo utiliza los siguientes conceptos de costos: - **Costo unitario (`costo_unitario`)**: Costo de construir una unidad nueva de infraestructura. - **Costo unitario de recuperación (`costo_unitario_recuperacion`)**: Costo adicional necesario para recuperar una unidad en mal estado. - **Tasa de mantenimiento (`tasa_mantenimiento`)**: Proporción anual del valor de la infraestructura que se debe invertir para mantenerla en condiciones adecuadas. - **Valor original (`valor_original`)**: Valor base de cada unidad de infraestructura, considerando su estado y costos asociados. - **Costo de recuperación (`costo_recuperacion`)**: Costo total de recuperar una unidad específica, calculado a partir de los parámetros anteriores. - **Costo de brecha (`costo_brecha`)**: Costo total necesario para cerrar la brecha de infraestructura identificada. Estos conceptos se utilizan para calcular las necesidades de inversión, el mantenimiento anual y la priorización de intervenciones en el modelo. ### Inversión El sistema calcula cuatro tipos de inversión: 1. **Construcción**: Nuevas unidades para cerrar la brecha 2. **Mantenimiento**: Conservación de infraestructura existente y nueva 3. **Recuperación**: Reparación de infraestructura obsoleta 4. **Reemplazo**: Renovación de infraestructura al final de su vida útil 5. **Ahorro**: Fondos acumulados para reemplazos futuros ## Sectores e Indicadores BrechaSnipApp analiza **5 sectores** con un total de **16 indicadores**: | Sector | Indicador | Descripción | |-----------------------------|-----------|---------------------------------------------| | Agua Potable y Saneamiento | A11 | Abastecimiento de Agua | | | A21 | Alcantarillado Sanitario | | Educación | E11 | Aulas Escolares | | | E12 | Educación Técnico Profesional | | Salud | S11 | Unidades de Atención Primaria (UNAP) | | | S21 | Hospitales Municipales y Provinciales | | | S31 | Hospitales Regionales | | Transporte | T11 | Red Vial Primaria y Autovías | | | T12 | Red Vial Secundaria | | | T13 | Red Vial Terciaria | | | T21 | Aeropuertos | | | T31 | Transporte Urbano Masivo | | Vivienda | V11 | Déficit Cualitativo - Techo | | | V21 | Déficit Cualitativo - Piso | | | V31 | Déficit Cuantitativo - Paredes | | | V32 | Déficit Cuantitativo - Allegamiento | Cada indicador tiene parámetros específicos que pueden ajustarse según el contexto. Ver @sec-pkg-indicators para más detalles. ## Flujo de Trabajo Típico 1. **Configurar años**: Definir año de inicio y año meta del plan 2. **Configurar plan de inversión**: - Automático (el sistema optimiza) - Manual (usuario define presupuestos) 3. **Ajustar parámetros** (opcional): Vida útil, tasas de mantenimiento, etc. 4. **Ejecutar cálculos**: El sistema procesa todos los indicadores 5. **Analizar resultados**: Revisar inversiones, coberturas y brechas 6. **Exportar**: Descargar datos para análisis adicional ## Próximos Pasos ::: {.features-grid} ::: {.feature-card} **Usuario Final** Aprenda a utilizar la herramienta web para generar planes. [Ver Guía →](02-webapp/index.qmd) ::: ::: {.feature-card} **Desarrollador** Documentación técnica del paquete R y arquitectura. [Ver Instalación →](03-pkg/index.qmd) ::: ::: {.feature-card} **SysAdmin** Guías de despliegue con Docker y configuración de servidor. [Ver Despliegue →](05-deployment/index.qmd) ::: :::