Skip to content

Commit

Permalink
chore(vignette): updated with the changes of README file
Browse files Browse the repository at this point in the history 
Sections have been deleted and moved to improve and facilitate its comprehension.

Ref: #133
  • Loading branch information
@GeraldineGomez
GeraldineGomez committed Apr 24, 2024
1 parent 63906c9 commit d246705
Showing 1 changed file with 39 additions and 254 deletions.
293 changes: 39 additions & 254 deletions vignettes/sivirep.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,289 +46,74 @@ El objetivo de `sivirep` es proporcionar un conjunto de herramientas para:
- Estudiantes del área de la salud y epidemiología.
- Investigadores y analistas de datos a nivel nacional e internacional.

## Instalación

Puedes instalar la versión de desarrollo de `sivirep` desde GitHub con el siguiente comando:

```{r setup_sivirep, eval = FALSE}
install.packages("pak")
pak::pak("epiverse-trace/sivirep") # nolint: nonportable_path_linter
```

## Inicio rápido

Puedes revisar las enfermedades y los años disponibles de forma libre utilizando:

```{r list_events}
lista_eventos <- list_events()
knitr::kable(lista_eventos)
```

## Versiones futuras

Las versiones futuras de `sivirep` podrían incluir:

- Interacción con otras fuentes de datos en Colombia.
- Otros sistemas de vigilancia epidemiológica en América Latina.
- Interacción con otras fuentes de datos en Colombia.
- Otros sistemas de vigilancia epidemiológica en América Latina.

## Contribuciones

Las contribuciones son bienvenidas via [pull requests](https://github.com/epiverse-trace/sivirep/pulls).
Las contribuciones son bienvenidas via [pull
requests](https://github.com/epiverse-trace/sivirep/pulls).

Los contribuyentes al paquete incluyen:

- [Geraldine Gómez-Millán](https://github.com/GeraldineGomez) (author)

- [Zulma M. Cucunubá](https://github.com/zmcucunuba) (author)
**Autores**: [Geraldine Gómez-Millán](https://github.com/GeraldineGomez) y [Zulma M. Cucunubá](https://github.com/zmcucunuba)

- [Hugo Gruson](https://github.com/Bisaloo) (contributor)

- [Laura Gómez-Bermeo](https://github.com/lgbermeo) (contributor to documentation)

- [Miguel Gámez](https://github.com/megamezl) (contributor)

- Jennifer Méndez-Romero (contributor)

- Johan Calderón (contributor)

- Claudia Huguett-Aragón (contributor)

- Lady Flórez-Tapiero (contributor)

- Verónica Tangarife-Arredondo (contributor)
**Contribuyentes**:
[Hugo Gruson](https://github.com/Bisaloo), [Juanita Romero-Garcés](https://github.com/juanitaromerog), [Andrés Moreno](https://github.com/andresmore), [Miguel Gámez](https://github.com/megamezl), Jennifer Méndez-Romero, Claudia Huguett-Aragón, [Laura Gómez-Bermeo](https://github.com/lgbermeo), Johan Calderón, Lady Flórez-Tapiero, Verónica Tangarife-Arredondo y Gerard Alarcon

## Código de conducta

Por favor, ten en cuenta que el proyecto `sivirep` se publica con un
[Código de Conducta para Contribuyentes](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html). Al contribuir a este proyecto, aceptas cumplir con sus términos.

## Comenzar

### Para reportes automatizados

Después de la instalación de `sivirep`, puedes comenzar importando el paquete a través del siguiente comando:

```{r import_sivirep}
library(sivirep)
```

Ante de iniciar con el reporte automatizado, revisa la lista de enfermedades disponibles para hacer un reporte con `sivirep` en:

```{r eventos_disponibles, results = 'hide'}
list_events()
```

Actualmente, `sivirep` provee una plantilla de reporte llamada `Reporte Básico {sivirep}`, la cual contiene seis secciones y recibe los siguientes parámetros de entrada: el nombre de la enfermedad, el año, el nombre de departamento (opcional) y nombre del municipio (opcional) para descargar los datos de la fuente de SIVIGILA.

Para hacer uso de la plantilla del reporte se deben seguir los siguientes pasos:

1. En RStudio hacer click *'File/New File/R'* Markdown:

![](man/figures/file_rmarkdown.png){.rmarkdown-img align="center" style="margin-left: 2.8em; margin-top: 0.8em; margin-bottom: 0.8em;"width="560"}

2. Selecciona la opción del panel izquierdo: *'From Template'*, después selecciona el template del reporte llamado `Reporte Básico {sivirep}`, indica el nombre que deseas para el reporte (i.e. Reporte_Laura), la ubicación donde deseas guardarlo y presiona *'Ok'*.

![](man/figures/reporte_basico.png){.rmarkdown-img align="center" style="margin-left: 2.8em; margin-top: 0.8em; margin-bottom: 0.8em;" width="550"}

3. A continuación, podrás seleccionar el nombre de la enfermedad, el año, el departamento (opcional) y el municipio (opcional) del reporte. Esta acción descargará los datos deseados y también proporcionará la plantilla en un archivo R Markdown (.Rmd). Para esto, es importante encontrar el botón *'Knit'*, desplegar las opciones y seleccionar *'Knit with parameters'*.

![](man/figures/button_knit.png){.rmarkdown-img align="center" style="margin-left: 2.8em; margin-top: 0.8em; margin-bottom: 0.8em;" width="560"}

4. Espera unos segundos mientras el informe se genera en un archivo PDF.

5. Puedes agregar, editar, eliminar y personalizar las secciones del reporte en el archivo R Markdown generado anteriormente.

![](man/figures/editable_rmarkdown.png){.rmarkdown-img align="center" style="margin-left: 2.8em; margin-top: 0.8em; margin-bottom: 0.8em;" width="560"}

Para obtener más detalles sobre plantillas y reportes genéricos de R Markdown, por favor consulta [rmarkdown
templates](https://rstudio.github.io/rstudio-extensions/rmarkdown_templates.html).

## Para análisis o reportes personalizados

Esta sección proporciona un conjunto básico de instrucciones para usar `sivirep`
0.0.2 si:
- Ya has producido un archivo .Rmd y deseas editar un reporte.
- Deseas realizar análisis personalizados sin un archivo .Rmd.

### 1. Importación de datos de SIVIGILA

La fuente de SIVIGILA proporciona los datos de la lista de casos históricos hasta el último año epidemiológico cerrado. El cierre de un año epidemiológico generalmente ocurre en abril del siguiente año (por ejemplo, si estás utilizando `sivirep` en marzo de 2023, es posible que puedas acceder a los datos históricos hasta diciembre de 2021) para la mayoría de las enfermedades, con algunas excepciones.

Por favor, verifica las enfermedades y años disponibles utilizando:

```{r eventos,results = 'hide'}
lista_eventos <- list_events()
```

Una vez que hayas decidido la enfermedad y el año de la cual deseas obtener la información, `import_data_event` es la función que permite la importación de datos desde la fuente de SIVIGILA utilizando un formato parametrizado basado en la enfermedad y el año.

```{r import_data_event}
data_event <- import_data_event(nombre_event = "Dengue",
year = 2020)
```

##### 💡 Tip 1 - Evita retrasos en el tiempo al importar los datos

- `sivirep` 0.0.2 está diseñado para ayudar con el acceso a la fuente de SIVIGILA. Este proceso de descarga de información puede tomar unos minutos dependiendo del tamaño del conjunto de datos. Para evitar descargar los mismos datos repetidamente, puedes utilizar `cache = TRUE` en la función `import_data_event`. Esta opción está configurada de forma predeterminada.

### 2. Limpieza de datos de SIVIGILA

Los datos de SIVIGILA son una fuente de información oficial altamente confiable, con certificación ISO de calidad de datos. Sin embargo, a veces puede haber algunos valores atípicos en los datos que requieran una limpieza adicional.

`sivirep` proporciona una función genérica llamada `limpiar_data_sivigila` que envuelve diversas tareas para identificar y corregir errores, inconsistencias y discrepancias en los conjuntos de datos con el fin de mejorar su calidad y precisión. Este proceso puede incluir la eliminación de duplicados, la corrección de errores tipográficos, el reemplazo de valores faltantes y la validación de datos, entre otras tareas, como eliminar fechas improbables, limpiar códigos de geolocalización y estandarizar los nombres de las columnas y las categorías de edad.

```{r limpiar_data_sivigila}
data_limpia <- limpiar_data_sivigila(data_event = data_event)
```

Las funciones de limpieza dentro de `limpiar_data_sivigila` se han recopilado y creado en base a la experiencia de epidemiólogos de campo. Estas pueden incluir funciones internas como:
[Código de Conducta para
Contribuyentes](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html).
Al contribuir a este proyecto, aceptas cumplir con sus términos.

- `limpiar_encabezado`: función que limpia y estandariza los nombres de las columnas de los datos de lista de casos de SIVIGILA basándose en el diccionario de datos de SIVIGILA.

- `limpiar_edad_event`: función que limpia las edades de los datos de lista de casos de SIVIGILA.

- `format_fecha`: función que da un formato específico a una fecha.

- `limpiar_fecha_event`: función que limpia las fechas de los datos de enfermedades.

- `limpiar_cods_dpto`: función que limpia los códigos geográficos de departamentos en los datos de enfermedades.

El usuario puede utilizar estas funciones individualmente o simplemente utilizar la función envolvente genérica `limpiar_data_sivigila`.

### 3. Filtrar casos

`sivirep` proporciona una función que permite filtrar los datos de enfermedades por departamento o nombre del municipio llamada `geo_filtro`. Esto permite al usuario crear un informe a nivel subnacional, seleccionando casos específicos basados en la ubicación geográfica.

```{r geo_filtro}
data_event_filtrada <- geo_filtro(data_event = data_limpia,
dpto = "Choco")
```

### 4. Distribución temporal de casos

En `sivirep`, la distribución temporal de casos se define por las variables de fecha de inicio de síntomas y fecha de notificación. Para cada una de estas variables, existen funciones especializadas para agrupar los datos y generar los gráficos.

#### 4.1. Agrupar los datos por fecha de inicio de síntomas en la escala temporal deseada

Para generar la distribución de casos por fecha de inicio de síntomas, es necesario agrupar los datos por estas variables. `sivirep` proporciona una función que permite esta agrupación llamada `agrupar_fecha_inisintomas`, en la cual puedes especificar la unidad de tiempo para agrupar estas fechas. Los valores permitidos para este parámetro son: día y mes.

```{r agrupar_fecha_inicio_sintomas}
casos_ini_sintomas <- agrupar_fecha_inisintomas(data_event =
data_limpia)
```

##### 💡 Tip 2 - Obtén los primeros n meses con más casos

- Al construir una sección del reporte o analizar estos datos, puede ser útil obtener los meses con más casos. En `sivirep`, puedes utilizar la función `obtener_meses_mas_casos` para obtener esta información.

El gráfico que permite visualizar esta distribución se debe generar con la función `plot_fecha_inisintomas`. Ten en cuenta que, incluso si has agrupado los datos por día, es posible que prefieras representarlo por semana epidemiológica, como en:

```{r plot_fecha_inicio_sintomas, fig.height = 5, fig.width = 10}
plot_fecha_inisintomas(data_agrupada = casos_ini_sintomas,
uni_marca = "semanaepi")
```

#### 4.2. Agrupar los datos por fecha de notificación en la escala temporal deseada

El proceso para generar la distribución de casos por fecha de notificación consiste en agrupar los datos de enfermedades por esta variable. Puedes utilizar la siguiente función de `sivirep` para hacer esto:

```{r agrupar_fecha_notificacion}
casos_fecha_notificacion <- agrupar_fecha_notifica(data_event =
data_limpia)
```

El gráfico que permite visualizar esta distribución debe generarse con la función `plot_fecha_notifica`. Ten en cuenta que, aunque hayas agrupado los datos por día, es posible que prefieras representarlos por semana epidemiológica, como en:

```{r plot_fecha_notificacion, fig.height = 5, fig.width = 10}
plot_fecha_notifica(data_agrupada = casos_fecha_notificacion,
uni_marca = "semanaepi")
```

### 5. Edad y sexo

### 5.1. Variable de sexo

Cuando se analizan o se informan datos de enfermedades, a menudo es necesario determinar la distribución de casos por género o sexo. Sin embargo, la fuente de SIVIGILA solo registra el sexo.

`sivirep` proporciona una función que agrega y calcula automáticamente los porcentajes por sexo después del proceso de limpieza.

```{r agrupar_sexo}
casos_sex <- agrupar_sex(data_event = data_limpia,
porcentaje = TRUE)
```

Además, `sivirep` cuenta con una función para generar el gráfico por esta variable llamada `plot_sex`:

```{r plot_sexo, fig.height = 5, fig.width = 8}
plot_sex(data_agrupada = casos_sex)
```

La distribución de casos por sexo y semana epidemiológica se puede generar utilizando la función `agrupar_sex_semanaepi` proporcionada por `sivirep`.

```{r agrupar_sex_semana_epidemiologica}
casos_sex_semanaepi <- agrupar_sex_semanaepi(data_event = data_limpia)
```

La función de visualización correspondiente es `plot_sex_semanaepi`, que `sivirep` proporciona para mostrar la distribución de casos por sexo y semana epidemiológica.

```{r plot_sex_semana_epidemiologica, fig.height = 9, fig.width = 11}
plot_sex_semanaepi(data_agrupada = casos_sex_semanaepi)
```

### 5.2. Variable de edad

La edad es una variable importante para analizar, ya que es un factor de riesgo conocido para muchas enfermedades. Ciertas enfermedades y condiciones tienden a ocurrir con más frecuencia en grupos de edad específicos, y esta distribución puede ayudar a identificar poblaciones con mayor riesgo e implementar estrategias de prevención y control dirigidas.

`sivirep` proporciona una función llamada `agrupar_edad`, que puede agrupar los datos de enfermedades por grupos de edad. De forma predeterminada, esta función produce rangos de edad con intervalos de 10 años. Además, los usuarios pueden personalizar un rango de edad diferente.

```{r agrupar_edad}
casos_edad <- agrupar_edad(data_event = data_limpia, interval_edad = 10)
```
## Instalación

La función de visualización correspondiente es `plot_edad`.
Puedes instalar la versión de desarrollo de `sivirep` desde GitHub con
el siguiente comando:

```{r plot_edad, fig.height = 3, fig.width = 8}
plot_edad(data_agrupada = casos_edad)
```{r setup_sivirep, eval = FALSE}
install.packages("pak")
pak::pak("epiverse-trace/sivirep")
```

### 5.3. Edad y sexo simultáneamente

`sivirep` proporciona una función llamada `agrupar_edad_sex`, que puede agrupar los datos de enfermedades por rangos de edad y sexo de forma simultánea y obtener el número de casos y los porcentajes correspondientes. Además, permite personalizar el intervalo de edad.

```{r agrupar_edad_sexo}
casos_edad_sex <- agrupar_edad_sex(data_event = data_limpia,
interval_edad = 10)
```
## Inicio rápido

La función de visualización correspondiente es `plot_edad_sex`.
Puedes iniciar importando el paquete después de finalizada su
instalación con el siguiente comando:

```{r plot_edad_sexo, fig.height = 3, fig.width = 9}
plot_edad_sex(data_agrupada = casos_edad_sex)
```{r import_sivirep, eval = FALSE}
library(sivirep)
```

### 6. Distribución espacial de casos
Puedes revisar las enfermedades y los años disponibles para su descarga
de forma libre utilizando:

Obtener la distribución espacial de los casos es útil para identificar áreas con una alta concentración de casos, agrupaciones de enfermedades y factores de riesgo ambientales o sociales.

En Colombia, existen 32 unidades geográficas administrativas (adm1) llamadas departamentos. `sivirep` proporciona una función llamada `agrupar_mpio` que permite obtener un data.frame de casos agrupados por departamento o municipio.

```{r agrupar_municipios}
dist_esp_dept <- agrupar_mpio(data_event = data_event_filtrada,
dpto = "Choco")
```{r list_events}
lista_eventos <- list_events()
knitr::kable(lista_eventos)
```
## Reporte automatizado

Actualmente, con la función llamada `plot_map`, el usuario puede generar un mapa estático de Colombia que muestra la distribución de casos por departamentos y municipios.
Actualmente, `sivirep` provee una plantilla de reporte llamada
`Reporte Básico {sivirep}`, la cual recibe los siguientes parámetros de
entrada: el nombre de la enfermedad, el año, el nombre de departamento
(opcional) y nombre del municipio (opcional) para descargar los datos de
la fuente de SIVIGILA.

```{r plot_mapa, results = 'hide', echo = FALSE}
mapa <- plot_map(data_agrupada = dist_esp_dept, dpto = "Choco")
```
Para hacer uso de la plantilla del reporte puedes seguir los
siguientes pasos:

```{r mapa, fig.height = 14, fig.width = 10}
mapa
```
<img src="../man/figures/template.gif" width="900" height="540"/>

El reporte que obtendrás al utilizar la plantilla de `sivirep` es este:

##### 💡 Tip 3 - Obtén la fila con más casos
<img src="../man/figures/template-report.gif" width="900" height="600"/>

- Al construir una sección del reporte o analizar estos datos, puede ser útil saber cuál es la variable que tiene la mayoría de los casos. En `sivirep`, puedes utilizar la función `obtener_fila_mas_casos` para obtener esta información. Esta función funciona con cualquier conjunto de datos que contenga una columna llamada "casos" en cualquier nivel de agregación.
Si deseas generar el reporte en formato PDF debes instalar LateX. Puedes instalarlo siguiendo las instrucciones que se
encuentran en [R Markdown Cookbook](https://bookdown.org/yihui/rmarkdown-cookbook/install-latex.html).

0 comments on commit d246705

Please sign in to comment.