Skip to content

Commit f2f0a85

Browse files
committed
updating README + some docs
1 parent 0049bd9 commit f2f0a85

File tree

6 files changed

+118
-76
lines changed

6 files changed

+118
-76
lines changed

R/combine_replicates.R

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
# ============================================
22
# Authors: PA
3-
# Maintainers: PA
3+
# Maintainers: PA, MG
44
# Copyright: 2023, HRDAG, GPL v2 or later
55
# ============================================
66

77
#' Calculate the proportions of each level of a variable after
8-
#' applying `combine_replicates` to complete data (includes imputed values).
8+
#' applying `combine_replicates` to completed data (includes imputed values).
99
#'
1010
#' @param complete_data A data frame containing the output from `combine_replicates`.
1111
#' @param strata_vars A vector of column names identifying the variables to be
@@ -56,7 +56,9 @@ proportions_imputed <- function(complete_data,
5656

5757
}
5858

59-
#' Combine replicates according to the Normal approximation using the laws of total expectation and variance.
59+
#' Combine imputed replicates according to calculate totals. Combination
60+
#' is done using the standard approach that makes use of the laws of total
61+
#' expectation and total variance.
6062
#'
6163
#' @param replicates_obs_data The data frame that results from applying `summary_observed`.
6264
#' @param replicates_data A data frame containing replicates data.
@@ -67,7 +69,7 @@ proportions_imputed <- function(complete_data,
6769
#' "reclutamiento" and "desaparicion".
6870
#' @param forced_dis_filter Filter that indicates if the data is filtered using the
6971
#' "is_forced_dis" rule.
70-
#' @param edad_minors_filter Optional filter by age ("edad") < 18.
72+
#' @param edad_minors_filter Optional filter by age (`edad`) < 18.
7173
#' @param include_props A logical value indicating whether or not to include
7274
#' the proportions from the calculations before merging with summary_observed's output.
7375
#' @param digits Number of decimal places to round the results to. Default value

README.md

Lines changed: 28 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
Click [here](https://github.com/HRDAG/verdata/blob/main/inst/docs/README-en.md) for instructions in English.
22

33
<!-- badges: start -->
4-
[![DOI](https://joss.theoj.org/papers/10.21105/joss.05844/status.svg)](https://doi.org/10.21105/joss.05844)
54
[![R-CMD-check](https://github.com/HRDAG/verdata/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/HRDAG/verdata/actions/workflows/check-standard.yaml)
65
[![Codecov test coverage](https://codecov.io/gh/HRDAG/verdata/branch/main/graph/badge.svg)](https://app.codecov.io/gh/HRDAG/verdata?branch=main)
76
<!-- badges: end -->
@@ -16,9 +15,31 @@ Click [here](https://github.com/HRDAG/verdata/blob/main/inst/docs/README-en.md)
1615

1716
# verdata
1817

19-
`verdata` es un paquete de `R` que está pensado como una herramienta para el uso y análisis de los datos de conflicto armado en Colombia. Estos datos derivan del [proyecto conjunto JEP-CEV-HRDAG](https://hrdag.org/wp-content/uploads/2022/08/20220818-fase4-informe-corrected.pdf), los cuales, a través del paquete, pueden ser analizados utilizando tres conjuntos de funciones: En primer lugar, las personas interesadas pueden utilizar `verdata` para verificar que están utilizando los datos originalmente publicados, es decir, permite autenticar tanto los archivos como su contenido. Segundo, pueden usar `verdata` para replicar los principales resultados del proyecto conjunto JEP-CEV-HRDAG. Finalmente, para el tercer conjunto, pueden utilizar `verdata` para diseñar sus propios análisis estadísticos de patrones de violencia que abordan los dos tipos de datos faltantes presentes en el proyecto (campos faltantes y registros faltantes).
18+
`verdata` es un paquete de `R` que está pensado como una herramienta para el uso y análisis de los datos de conflicto armado en Colombia. Estos datos derivan del [proyecto conjunto JEP-CEV-HRDAG](https://hrdag.org/CEV-JEP/20250306-methodological-report-ES.pdf), los cuales, a través del paquete, pueden ser analizados utilizando tres conjuntos de funciones: En primer lugar, las personas interesadas pueden utilizar `verdata` para verificar que están utilizando los datos originalmente publicados, es decir, permite autenticar tanto los archivos como su contenido. Segundo, pueden usar `verdata` para replicar los principales resultados del proyecto conjunto JEP-CEV-HRDAG. Finalmente, para el tercer conjunto, pueden utilizar `verdata` para diseñar sus propios análisis estadísticos de patrones de violencia que abordan los dos tipos de datos faltantes presentes en el proyecto (campos faltantes y registros faltantes).
2019

21-
Se pueden descargar los datos sobre las cuatro violaciones a los derechos humanos que se trabajaron en el proyecto: desaparición, homicidio, secuestro y reclutamiento de niños, niñas y adolescentes, los cuales se encuentran en el [sitio web del Departamento Administrativo Nacional de Estadística (DANE)](https://microdatos.dane.gov.co/index.php/catalog/795/get-microdata). Estos datos corresponden a 100 réplicas para cada violación, los cuales fueron producto del proceso de imputación estadística múltiple de campos faltantes (ver sección 4 del [informe metodológico del proyecto](https://hrdag.org/wp-content/uploads/2022/08/20220818-fase4-informe-corrected.pdf)). Además, el repositorio [`verdata-examples`](https://github.com/HRDAG/verdata-examples) contiene ejemplos que ilustran cómo usar correctamente estos datos (réplicas) a través del paquete previamente mencionado.
20+
Dos versions de los datos sobre las cuatro violaciones a los derechos humanos que se trabajaron en el proyecto: desaparición, homicidio, secuestro y reclutamiento existen. La primera versión, (v1) corresponde a los datos usados para el análisis del informe metodológico del proyecto conjunto JEP-CEV-HRDAG. Se puede usar esta versión de los datos para replicar los hallazgos del Informe Metodológico. Después de la publicación de la primera versión de los datos, una entidad estatal con acceso legítimo a los datos originales descubrió algunos problemas con los datos publicados. La entidad encontró algunas instancias de la inclusión de víctimas indirectas en una de las fuentes analizadas en el proyecto. La segunda versión de los datos (v2) corrige estos errores y es adecuado para nuevos análisis del conflicto colombiano. Más información está disponible [aquí](https://hrdag.org/colombia/).
21+
22+
### Descargar datos para replicar los análisis del informe metodológico (v1)
23+
24+
Descargar datos del Departamento Administrativo Nacional de Estadística (DANE): [https://microdatos.dane.gov.co/index.php/catalog/795/get-microdata](https://microdatos.dane.gov.co/index.php/catalog/795/get-microdata)
25+
26+
Descargar datos del Human Rights Data Analysis Group (HRDAG) con IPFS:
27+
28+
- Desaparición [[csv]](https://bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm.ipfs.w3s.link/ipfs/bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm/desaparicion-v1.csv.zip) [[parquet]](https://bafybeicfjzjsl72ntzvne5apc4mubhtvsb7pd2qgvtqhuzbjznm7bxkuzy.ipfs.w3s.link/ipfs/bafybeicfjzjsl72ntzvne5apc4mubhtvsb7pd2qgvtqhuzbjznm7bxkuzy/desaparicion-v1.parquet.zip)
29+
- Reclutamiento [[csv]](https://bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm.ipfs.w3s.link/ipfs/bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm/reclutamiento-v1.csv.zip) [[parquet]](https://bafybeicfjzjsl72ntzvne5apc4mubhtvsb7pd2qgvtqhuzbjznm7bxkuzy.ipfs.w3s.link/ipfs/bafybeicfjzjsl72ntzvne5apc4mubhtvsb7pd2qgvtqhuzbjznm7bxkuzy/reclutamiento-v1.parquet.zip)
30+
- Homicidio [[csv]](https://bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm.ipfs.w3s.link/ipfs/bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm/homicidio-v1.csv.zip) [[parquet]](https://bafybeicfjzjsl72ntzvne5apc4mubhtvsb7pd2qgvtqhuzbjznm7bxkuzy.ipfs.w3s.link/ipfs/bafybeicfjzjsl72ntzvne5apc4mubhtvsb7pd2qgvtqhuzbjznm7bxkuzy/homicidio-v1.parquet.zip)
31+
- Secuestro [[csv]](https://bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm.ipfs.w3s.link/ipfs/bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm/secuestro-v1.csv.zip) [[parquet]](https://bafybeicfjzjsl72ntzvne5apc4mubhtvsb7pd2qgvtqhuzbjznm7bxkuzy.ipfs.w3s.link/ipfs/bafybeicfjzjsl72ntzvne5apc4mubhtvsb7pd2qgvtqhuzbjznm7bxkuzy/secuestro-v1.parquet.zip)
32+
33+
### Descargar datos para diseñar nuevos análisis del conflicto colombiano (v2)
34+
35+
Descargar datos del Human Rights Data Analysis Group (HRDAG) con IPFS:
36+
37+
- Desaparición [[csv]](https://bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm.ipfs.w3s.link/ipfs/bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm/desaparicion-v2.csv.zip) [[parquet]](https://bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm.ipfs.w3s.link/ipfs/bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm/desaparicion-v2.parquet.zip)
38+
- Reclutamiento [[csv]](https://bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm.ipfs.w3s.link/ipfs/bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm/reclutamiento-v2.csv.zip) [[parquet]](https://bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm.ipfs.w3s.link/ipfs/bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm/reclutamiento-v2.parquet.zip)
39+
- Homicidio [[csv]](https://bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm.ipfs.w3s.link/ipfs/bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm/homicidio-v2.csv.zip) [[parquet]](https://bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm.ipfs.w3s.link/ipfs/bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm/homicidio-v2.parquet.zip)
40+
- Secuestro [[csv]](https://bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm.ipfs.w3s.link/ipfs/bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm/secuestro-v2.csv.zip) [[parquet]](https://bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm.ipfs.w3s.link/ipfs/bafybeicb22gzaugj6jlrg47542oh7i2alzqbxwijedx7jfrstwgaxkxonm/secuestro-v2.parquet.zip)
41+
42+
Ambas versiones de los datos corresponden a 100 réplicas para cada violación, los cuales fueron producto del proceso de imputación estadística múltiple de campos faltantes (ver sección 4 del [informe metodológico del proyecto](https://hrdag.org/CEV-JEP/20250306-methodological-report-ES.pdf)). Además, el repositorio [`verdata-examples`](https://github.com/HRDAG/verdata-examples) contiene ejemplos que ilustran cómo usar correctamente estos datos (réplicas) a través del paquete previamente mencionado.
2243

2344
<div class="column" width="60%">
2445

@@ -28,7 +49,7 @@ Se pueden descargar los datos sobre las cuatro violaciones a los derechos humano
2849

2950
## Instalación
3051

31-
Se puede instalar la versión la versión en desarrollo de `verdata` desde GitHub así:
52+
Se puede instalar la versión en desarrollo de `verdata` desde GitHub así:
3253

3354
```r
3455
if (!require("devtools")) {install.packages("devtools")}
@@ -60,13 +81,13 @@ Para el uso de este paquete es necesario haber descargado previamente los datos
6081

6182
### Datos imputados:
6283

63-
* La función `combine_replicates` usa la aproximación normal usando las reglas de total expectativa y varianza para combinar las réplicas, lo que permite obtener un intervalo de la imputación. Ver sección 18.2 de [*Bayesian Data Analysis*](http://www.stat.columbia.edu/~gelman/book/) para más información.
84+
* La función `combine_replicates` usa la aproximación normal usando las reglas de total expectativa y varianza para combinar las réplicas, lo que permite obtener un intervalo de la imputación. Ver sección 18.2 de [*Bayesian Data Analysis*](https://www.stat.columbia.edu/~gelman/book/) para más información.
6485

6586
### Datos estimados:
6687

6788
* La función `estimates_exist` permite validar si la estimación de los estratos de interés ya existen, y se encuentran en los archivos de estimaciones precalculadas publicados, que deben haber sido previamente descargados del [sitio de la Comisión](https://www.comisiondelaverdad.co/analitica-de-datos-informacion-y-recursos#c3). Esta función requiere los datos estratificados y el directorio en el que se encuentran las estimaciones precalculadas y devolverá un valor lógico que indica si la estimación existe o no, y la ruta en la que se encuentra, en caso de que exista. En caso de que usted quiera replicar los resultados de la Comisión de la Verdad, los objetos de datos `estratificacion` (en español) y `stratification` (en inglés) especifican qué estratificaciones se usaron para cada estimación presente en el [informe metodológico del proyecto](https://hrdag.org/wp-content/uploads/2022/08/20220818-fase4-informe-corrected.pdf).
6889

69-
* La función `mse` permite hacer estimaciones del subregistro, usando el modelo de [LCMCR](https://doi.org/10.1111/biom.12502) (ver sección 6 del [informe metodológico del proyecto](https://hrdag.org/wp-content/uploads/2022/08/20220818-fase4-informe-corrected.pdf)).
90+
* La función `mse` permite hacer estimaciones del subregistro, usando el modelo de [LCMCR](https://onlinelibrary.wiley.com/doi/10.1111/biom.12502) (ver sección 6 del [informe metodológico del proyecto](https://hrdag.org/wp-content/uploads/2022/08/20220818-fase4-informe-corrected.pdf)).
7091
Para usar esta función es necesario haber definido variables de estratificación, es decir, agrupación, para hacer la estimación
7192
y haber hecho la estratificación (ver ejemplo y sección 8.4.2 del [informe metodológico del proyecto](https://hrdag.org/wp-content/uploads/2022/08/20220818-fase4-informe-corrected.pdf)).
7293
Además, considerando que la estimación requiere de tiempo y recursos computacionales, en caso de querer hacer uso de las
@@ -82,29 +103,4 @@ resultado un intervalo (que incluye la media). Usa la aproximación normal usand
82103
Agradecemos a [Micaela Morales](https://github.com/mmazul) por su atenta prueba beta.
83104

84105
## Contribuir al paquete
85-
Contribuciones y sugerencias siempre son bienvenidas. Si tiene un problema, pregunta o duda sobre `verdata` puede abrir un issue en GitHub. Si quiere contribuir nueva funcionalidad puede abrir un pull request. La integración continua está configurada para ejecutar las pruebas automáticamente cuando abre un pull request. Si desea ejecutar las pruebas localmente antes de abrir un pull request, puede hacerlo con `testthat::test_local()`.
86-
87-
## Cómo citar el paquete
88-
89-
Se puede citar el paquete como:
90-
91-
> Gargiulo et al., (2024). verdata: An R package for analyzing data from the Truth Commission in Colombia. Journal of Open Source Software, 9(93), 5844, <https://doi.org/10.21105/joss.05844>.
92-
93-
Entrada de BibTex:
94-
95-
```
96-
@article{Gargiulo2024,
97-
doi = {10.21105/joss.05844},
98-
url = {https://doi.org/10.21105/joss.05844},
99-
year = {2024},
100-
publisher = {The Open Journal},
101-
volume = {9},
102-
number = {93},
103-
pages = {5844},
104-
author = {Maria Gargiulo and María Juliana Durán and Paula Andrea Amado and Patrick Ball},
105-
title = {verdata: An R package for analyzing data from the Truth Commission in Colombia},
106-
journal = {Journal of Open Source Software}
107-
}
108-
```
109-
110-
<!-- done. -->
106+
Contribuciones y sugerencias siempre son bienvenidas. Si tiene un problema, pregunta o duda sobre `verdata` puede abrir un issue en GitHub. Si quiere contribuir nueva funcionalidad puede abrir un pull request.

0 commit comments

Comments
 (0)