hrdag/verdata

Una herramienta para el uso y análisis de los datos de Conflicto armado en Colombia resultantes del proyecto conjunto JEP-CEV-HRDAG.

Click here for instructions in English.

verdata

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, 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).

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). 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). Además, el repositorio verdata-examples contiene ejemplos que ilustran cómo usar correctamente estos datos (réplicas) a través del paquete previamente mencionado.

Instalación

Se puede instalar la versión la versión en desarrollo de verdata desde GitHub así:

if (!require("devtools")) {install.packages("devtools")}
devtools::install_github("HRDAG/verdata")

verdata requiere algunos paquetes como dependencia. Para esto es recomendable la instalación del GNU Scientific Library. Es posible que necesite instalar esta librería en su computadora por separado antes de instalar verdata.

Diccionario de datos

verdata presenta dos data frames que contienen información relacionada con el diccionario de datos de las réplicas. En diccionario_replicas encontrará la definición de cada una de las variables que se encuentran allí y, en diccionario_vars_adicional, encontrará nuevas variables que fueron usadas en algunos análisis estadísticos durante la construcción del informe final de la CEV.

Uso

Para el uso de este paquete es necesario haber descargado previamente los datos de alguno de los sitios en los que se encuentran publicados. Este paquete ofrece al público 8 funciones para el tratamiento de los datos, divididas así:

Verificación y lectura de datos en R:

• La función confirm_files permite autenticar que los archivos descargados correspondan exactamente a los archivos originalmente publicados. Esta función acepta archivos en cualquiera de los dos formatos publicados (parquet o csv).

• Además, la función read_replicates permite autenticar el contenido de los archivos, así como importar el número deseado de réplicas a R. Esta función acepta archivos en cualquiera de los dos formatos publicados (parquet o csv).

Transformación de datos:

• Para sus análisis en violaciones a derechos humanos, la Comisión de la Verdad especificó diferentes períodos y condiciones. En caso de querer replicar los resultados del Informe Final de la CEV, es necesario aplicar estos mismos filtros a los datos. El uso de la función filter_standard_cev es opcional y permite filtrar los datos del mismo modo que la CEV lo hizo, dependiendo de la violación a derechos humanos a analizar.

Datos observados:

• La función summary_observed ofrece un conteo del número observado de víctimas -totales o agrupadas por diferentes variables- antes de la imputación estadística de campos faltantes. El número que se obtiene es la media entre las diferentes réplicas.

Datos imputados:

• 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 para más información.

Datos estimados:

• 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. 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.

• La función mse permite hacer estimaciones del subregistro, usando el modelo de LCMCR (ver sección 6 del informe metodológico del proyecto). Para usar esta función es necesario haber definido variables de estratificación, es decir, agrupación, para hacer la estimación y haber hecho la estratificación (ver ejemplo y sección 8.4.2 del informe metodológico del proyecto). Además, considerando que la estimación requiere de tiempo y recursos computacionales, en caso de querer hacer uso de las estimaciones ya calculadas por el equipo, es necesario haberlas descargado del sitio de la Comisión a su máquina local. Esta función requiere como insumo los datos ya estratificados y el directorio en el que se encuentran las estimaciones publicadas -en caso de querer hacer uso de estas-. Tenga presente que al proveer un directorio la función asume las mismas especificaciones para el modelo usadas en el proyecto. Si usted quiere usar otras especificaciones, no debe suministrar un directorio a las estimaciones.

• Por último, la función combine_estimates permite combinar los resultados de la estimación, lo que, una vez más, dará como resultado un intervalo (que incluye la media). Usa la aproximación normal usando las reglas de total expectativa y varianza. Ver sección 18.2 de Bayesian Data Analysis para más información.

Agradecimientos

Agradecemos a Micaela Morales por su atenta prueba beta.

Contribuir al paquete

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().

Cómo citar el paquete

Se puede citar el paquete como:

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.

Entrada de BibTex:

@article{Gargiulo2024,
    doi = {10.21105/joss.05844},
    url = {https://doi.org/10.21105/joss.05844},
    year = {2024},
    publisher = {The Open Journal},
    volume = {9},
    number = {93},
    pages = {5844},
    author = {Maria Gargiulo and María Juliana Durán and Paula Andrea Amado and Patrick Ball},
    title = {verdata: An R package for analyzing data from the Truth Commission in Colombia},
    journal = {Journal of Open Source Software}
} 

verdata's Issues

Create a list of the stratification used in the methodological report?

Hi @thegargiulian, since I have been trying to figure out the issue with mse, I thought it would be helpful in making the package a little bit more user friendly to provide a list of the stratification used for different estimations in the methodological report. For example, the estimates by year for desaparicion used a stratification by year and is_forced_dis. I don't think this would be obvious for everybody, maybe someone would just filter by is_conflict and is_forced_dis and the stratify by year, which would mean they wouldn't find the estimates, mse would take too long to run and they would end up with different results. Or in secuestro, the stratification for the estimates by year was by year and sex.

Maybe some people would like to use their own stratification, but I was thinking, for someone who wants to save time or just wants to replicate the results, maybe providing this would be helpful.

What do you think? And, in case you agree, where do you think we should put it?

Thanks!

Updates to DESCRIPTION file

• Defne acronyms in JEP-CEV-HRDAG
• Add references to description field in the form authors (year) doi:...

Explicit checks of input structure

Not all functions provide explicit checks for correctness of inputs or helpful error messages if the inputs take incorrect forms. There should be explicit input checking for each function in verdata and associated testthat tests.

Make data dictionary available as data frame in package

The README tells users that the data dictionary can be found in inst/docs however R users that are not package developers are not familiar with these files. The data dictionary should be made easy to access and interact with and preferably within R.

Consider exporting the data dictionary as a data.frame see R Packages Ch. 7.

At minimum, it would be helpful to demonstrate to users how to download or load the file itself. For example:

verdata_dict_fp <- system.file(
  "docs/diccionario-variables-replicas.xlsx",
  package = "verdata"
)

readxl::read_excel(verdata_dict_fp)
#> # A tibble: 55 × 4
#>    `Nombre variable` Tipo     `Detalle variable`           `Categorías variable`
#>    <chr>             <chr>    <chr>                        <chr>                
#>  1 replica           caracter Número de réplica            "R1 - R100"          
#>  2 match_group_id    caracter Identificador único           <NA>                
#>  3 in_1              numérico Variable dicotómica que tom… "1 \r\n0"            
#>  4 in_2              numérico Variable dicotómica que tom… "1 \r\n0"            
#>  5 in_3              numérico Variable dicotómica que tom… "1 \r\n0"            
#>  6 in_4              numérico Variable dicotómica que tom… "1 \r\n0"            
#>  7 in_5              numérico Variable dicotómica que tom… "1 \r\n0"            
#>  8 in_6              numérico Variable dicotómica que tom… "1 \r\n0"            
#>  9 in_7              numérico Variable dicotómica que tom… "1 \r\n0"            
#> 10 in_8              numérico Variable dicotómica que tom… "1 \r\n0"            
#> # ℹ 45 more rows

Perhaps even adding download.file(verdata_dict_fp)

Function to automatically download data from DANE website

See suggestion in #20

`confirm_files` should rely on users to input a vector of files they'd like to read

Responding to an issue raised in the beta test, confirm_files (and read_replicates) should just take a vector from the user containing the number of the replicates they'd like to read. It's fine to note that we're imposing structure on the file naming convention to achieve this

Function documentation in Spanish

Ideally, we would be able to produce nicely formatted documentation in both Spanish and English for all aspects of the code and have that organized in a easy to access way for all users.

I've asked around the R-Ladies Slack for best practices for multilingual documentation and was suggested to take a look at this proof of concept: https://github.com/eliocamp/translated

Function that shows if estimates for a stratum already exist in the pre-calculated chunks

An auxiliary function that given stratum data, returns the stratum identifier and a column that is TRUE if the stratum has already been estimated and FALSE if it has not.

`confirm_files` should return an object with the results of the confirmation test

From points raised in the beta test:

Currently confirm_files prints a message for the user indicating they have the right files/an error if the file is incorrect. It would be more helpful for the function to output a data frame with two columns: file_path indicating the path to the file being checked and result indicating whether the file has been verified.

It would be helpful for the function to crash and list which files are broken rather than just stopping at the first broken file it encounters.

replace `\dontrun` with `\donttest`

For any examples that can be run, replace \dontrun with \donttest. \dontrun should only be used in instances where the example really can't be run by the user, \donttest can handle the examples that take >5 seconds to run

Improve title for combine_estimates

Provide a better title for combine_estimates() right now it is the name of the function which makes for odd reading in the help page:

I suspect this can be changed to Combine Estimates silly, but important change :)

verdata/R/combine_estimates.R

Line 7 in 8bf2329

#' @title combine_estimates

Add plain text license

Add license file to .Rbuildignore

Tests are not replicable

Note that these tests use data frome extdata which is not inclduded in the github repository. As such, tests are not reproducible.

verdata/tests/testthat/test-confirm_files.R

Line 7 in 8bf2329

right_dir <- system.file("extdata", "right", package = "verdata", "verdata-reclutamiento-R1.parquet")

Review test warnings

Currently test-estimate_mse.R, test-lookup_estimates.R, and test-read_replicates.R are giving testthat warnings

Only raise "Not filtering in is_forced_dis" if user is working with data about disappearances

Replicates not found

If replicates aren't in the folder where they should be, the function should alert the user that a replicate was not found.

Move part of package description to README

In my opinion, the second sentence onwards might be better placed in the README as it seems to get lost in the package DESCRIPTION file.

verdata/DESCRIPTION

Line 20 in 9c5af3d

Description: This package facilitates use and analysis of data about the armed conflict in Colombia resulting from the joint JEP-CEV-HRDAG project. The package has three main sets of features. First, researchers can use this package to verify that they are using unaltered versions of the data published by the Colombian National Administrative Department of Statistics. Second, they can use the package to replicate the main findings of the joint JEP-CEV-HRDAG project. Finally, they can use the package to design their own statistical analyses of patterns of violence that address the two forms of missing data present in the documented data.

This issue is in relation to the JOSS review here openjournals/joss-reviews#5844

README updates

Hi @thegargiulian and @pamadoa I've made updated the README, please change anything as you see fit .

@thegargiulian I added the estimates_exist function and made just a draft for it, but feel free to change it completely if you need to.

Translate data dictionary to English

Provide contribution instructions

In the README, could you please provide information on how to contribute to this package and how to report issues, bugs, errors, and other problems with the package?

This issue is with reference to the JOSS review here openjournals/joss-reviews#5844

README contains unnecessary instructions

verdata requiere el paquete LCMCR como dependencia. La instalación de LCMCR requiere la instalación del GNU Scientific Library. Es posible que necesite instalar esta librería en su computadora por separado antes de instalar verdata.

This tells the user to install LCMCR and GNU Scientific Library. This is not necessary as the package LCMCR is available on CRAN and is listed, correctly, as a package Import. This suggestion may cause confusion for new users.

Remove `options(warn=-1)`

You are setting options(warn=-1) in your function. This is not allowed. Please rather use suppressWarnings() if really needed.
-> R/estimate_mse.R; tests/testthat/test-combine_estimates.R

Argument naming consistency

Many functions refer to the same/similar inputs or arguments and there should be consistency in naming across all function files. In my original review of the documentation I noticed the use of violation and violacion as arguments, there may be other instances where argument names (and associated documentation) can be harmonized

Issue with lookup_estimates and mse

Hi @thegargiulian I have been working on figuring out why it takes so long to run mse for strata that should already have estimates. I had worried about the changes we made to the data for DANE or the code we were using in the examples, so I created a temporary branch in the CO-examples repository for all the regarding testing. This code summarizes what I have tried.

First, I downloaded the data directly from DANE and the estimates from the Commission site and used it for this tests.
Then, I used the same code we are using in the examples for the stratification and tested to the lookup_estimates function to see if it could find the estimates. It can. However, whenever I try to run the mse function it takes way too long, even though I know the estimates exist. So I created short_mse function, which is basically mse, except it doesn't run lcmcr if it doesn't find the estimates, just returns a tibble containing NA. When I run this, it takes 1, maybe 2 minutes, and returns the results of the estimation, not the NA tibble, so again, the estimates are there, and lookup_estimates can find them.

I can't figure out why mse takes so long. Is it possible that it is trying to run lcmcr even though the estimates exist? I checked the if_else in mse and it seems fine to me, so I don't know what the issue is.

Provide alternate Rd title for `get_valid_sources()`

verdata/R/estimate_mse.R

Line 7 in 8bf2329

#' @title get_valid_sources

Fix documentation titles

Additional function reference titles that should be in title case and not the name of the function.

title	function
proportions_imputed	proportions_imputed
proportions_observed	proportions_observed
run_lcmcr	run_lcmcr

Possible to simplify proportions arguments in `summary_observed`/`combine_replicates`?

Our beta tester noted that some of the parameter combinations can be confusing and might result in undesired results (like NaNs). Is there a way to simplify these arguments?

Provide guidance on how to download data

This package requires data to be downloaded from a government website. Naturally, it is not clear or straight forward how to download the data.

It would be very helpful if there was a vignette or short guide on how to download this data. The link provided in the readme is the dataset description and not the path to the downloads themselves.

Alternatively, it would be quite nice if the package provided a utility to actually download the data itself. For example I was able to download the secuestro data like so:

# create a temporary directory
tmp <- tempdir()

# create path to save to
ver_path <- file.path(tmp, "verdata.zip")

# download the file
download.file(
  "https://microdatos.dane.gov.co/index.php/catalog/795/download/22642",
  ver_path
)

# unzip it
unzip(ver_path, exdir = file.path(tmp, "verdata"))

# read it 
verdata::read_replicates(
  file.path(tmp, "verdata", "Secuestro.csv"),
  "secuestro",
  1
)

Replace use of &&

Hi @pamadoa!

I saw that there are a couple of places in summary_observed.R, combine_replicates.R, and test-summary-observed.R where you use &&.

Some of the latest versions of R don't like the use of && and || (explained in this Stackoverflow post). Do you think you could rewrite the affected lines of code to remove the && symbols, likely replacing them with a single & and probably also making use of all(...).

Thank you!

Provide examples as vignettes

The examples provided here in a separate repo (https://github.com/HRDAG/verdata-examples) should be properly linked to this repository. One way to do that would be through package vignettes [See the vignettes section of the R Packages book]. To take this even further, it might be better to set up a website for this repository where the vignettes can be accessed as Articles. See the website chapter of the R Packages book.

I see there is a related issue here HRDAG/verdata-examples#2 to convert the examples to a human-readable format. I will leave this to the authors' discretion.

This issue is with reference to the JOSS review here openjournals/joss-reviews#5844

Violation type checking

Many functions take a violation type as an input, but most do not do any sort of checking to ensure that the violation type matches one of the four acceptable options.

Installation instructions: Check if `devtools` is installed

Under the installation instructions, it might be better to replace
install.packages("devtools") with if (!require("devtools")) install.packages("devtools") to only install devtools if it's not already installed. This could reduce unnecessary re-installations.

This issue is with reference to the JOSS review here openjournals/joss-reviews#5844

Fix documentation for estimates_exist

The additional #' has made the conversion to a .Rd corrupted. Please remove so that documentation is fixed. Additionally, please fix the name per #22 and #23

verdata/R/estimate_mse.R

Line 162 in 8bf2329

#' #' @return A list with two entries, `estimates_exist` and `estimates_path`.

[Doc] add example for estimates_exist()

There is no example associated with the estimates_exist() function.

Set up continuous integration

Could you set up continuous integration, for example with GitHub Actions, to check that the tests and infrastructure are working correctly? The package {usethis} provides quick functionalities to get started. See here.

This issue is with reference to the JOSS review here openjournals/joss-reviews#5844