Merge pull request #33 from HRDAG/readme-updates

Updates to README

Closes #17
Closes #20
Closes #26
Closes #27
Closes #29

DESCRIPTION

@@ -17,7 +17,7 @@ Authors@R:
     person(given = "Patrick",
            family = "Ball",
            role = "rev"))
-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.
+Description: This package facilitates use and analysis of data about the armed conflict in Colombia resulting from the joint JEP-CEV-HRDAG project.
 License: GPL-2
 URL: https://github.com/HRDAG/verdata
 BugReports: https://github.com/HRDAG/verdata/issues

README.md

@@ -1,9 +1,9 @@
 Click [here](https://github.com/HRDAG/verdata/blob/main/inst/docs/README-en.md) for instructions in English.
 
- <!-- badges: start -->
+<!-- badges: start -->
 [![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)
   [![Codecov test coverage](https://codecov.io/gh/HRDAG/verdata/branch/main/graph/badge.svg)](https://app.codecov.io/gh/HRDAG/verdata?branch=main)
-  <!-- badges: end -->
+<!-- badges: end -->
 
 <div class="columns">
 
@@ -15,7 +15,9 @@ Click [here](https://github.com/HRDAG/verdata/blob/main/inst/docs/README-en.md)
 
 # 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 resultantes del [proyecto conjunto JEP-CEV-HRDAG](https://hrdag.org/wp-content/uploads/2022/08/20220818-fase4-informe-corrected.pdf). Se pueden descargar los datos sobre desaparición, homicidio, reclutamiento de niños, niñas y adolescentes y secuestro del [sitio web del Departamento Administrativo Nacional de Estadística](https://microdatos.dane.gov.co/index.php/catalog/795). Estos datos corresponden a 100 réplicas, producto del proceso de imputación estadística de campos faltantes (ver sección 4 del [informe metedológico del proyecto](https://hrdag.org/wp-content/uploads/2022/08/20220818-fase4-informe-corrected.pdf)). El repositorio [`verdata-examples`](https://github.com/HRDAG/verdata-examples) contiene ejemplos que ilustran cómo usar correctamente los datos y este paquete.
+`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).
+
+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.
 
 <div class="column" width="60%">
 
@@ -28,19 +30,18 @@ Click [here](https://github.com/HRDAG/verdata/blob/main/inst/docs/README-en.md)
 Se puede instalar la versión la versión en desarrollo de `verdata` desde GitHub así:
 
 ```r
-install.packages("devtools")
+if (!require("devtools")) {install.packages("devtools")}
 devtools::install_github("HRDAG/verdata")
 ```
-
-`verdata` requiere el paquete [`LCMCR`](https://cran.r-project.org/web/packages/LCMCR/index.html) como dependencia. La instalación de `LCMCR` requiere la instalación del [GNU Scientific Library](https://www.gnu.org/software/gsl/). Es posible que necesite instalar esta librería en su computadora por separado antes de instalar `verdata`.
+`verdata` requiere algunos paquetes como dependencia. Para esto es recomendable la instalación del [GNU Scientific Library](https://www.gnu.org/software/gsl/). Es posible que necesite instalar esta librería en su computadora por separado antes de instalar `verdata`.
 
 ## Diccionario de datos
 
-En el subdirectorio `inst/docs` usted puede encontrar la información relacionada con el diccionario de datos de las réplicas. En este encontrará la definición de cada una de las variables que se encuentran allí, así como nuevas variables que fueron usadas en algunos análisis estadísticos durante la construcción del informe final de la CEV.
+`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 los datos previamente 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í:
+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`:
 
@@ -62,7 +63,7 @@ Para el uso de este paquete es necesario haber descargado los datos previamente
 
 ### Datos estimados:
 
-* La función `estimates_exist` permite validar si la estimación de los estratos de intré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).
+* 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).
 
 * 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)).
 Para usar esta función es necesario haber definido variables de estratificación, es decir, agrupación, para hacer la estimación
@@ -78,3 +79,6 @@ resultado un intervalo (que incluye la media). Usa la aproximación normal usand
 
 ## Agradecimientos
 Agradecemos a [Micaela Morales](https://github.com/mmazul) 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.

inst/docs/README-en.md

@@ -3,7 +3,7 @@ Haga clic [aquí](https://github.com/HRDAG/verdata/blob/main/README.md) para ins
  <!-- badges: start -->
 [![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)
   [![Codecov test coverage](https://codecov.io/gh/HRDAG/verdata/branch/main/graph/badge.svg)](https://app.codecov.io/gh/HRDAG/verdata?branch=main)
-  <!-- badges: end -->
+<!-- badges: end -->
 
 <div class="columns">
 
@@ -15,7 +15,9 @@ Haga clic [aquí](https://github.com/HRDAG/verdata/blob/main/README.md) para ins
 
 # verdata
 
-`verdata` is an `R` package designed as a tool for the use and analysis of data about the armed conflict in Colombia resulting from the [joint JEP-CEV-HRDAG project](https://hrdag.org/wp-content/uploads/2022/08/20220818-fase4-informe-corrected.pdf). Data about disappearance, homicide, recruitment of children and adolescents, and kidnapping can be downloaded from the [National Administrative Department of Statistics' website](https://microdatos.dane.gov.co/index.php/catalog/795). The data about each of the four human rights violations correspond to 100 replicates, which are the result of a statistical imputation process of missing fields (see Section 4 of the [methodological report of the project](https://www.comisiondelaverdad.co/sites/default/files/descargables/2022-08/04_Anexo_Proyecto_JEP_CEV_HRDAG_08022022.pdf)). The repository [`verdata-examples`](https://github.com/HRDAG/verdata-examples) contains examples that illustrate how to correctly use the data and this package. These examples are currently only available in Spanish, but we are working on translating them to English.
+`verdata` is an `R` package designed as a tool for the use and analysis of data about the armed conflict in Colombia resulting from the [joint JEP-CEV-HRDAG project](https://hrdag.org/wp-content/uploads/2022/08/20220818-fase4-informe-corrected.pdf). `verdata` has three main sets of features. First, researchers can use `verdata` to verify that they are using unaltered versions of the published data. Second, they can use `verdata` to replicate the main findings of the joint JEP-CEV-HRDAG project. Finally, they can use `verdata` to design their own statistical analyses of patterns of violence that address the two forms of missing data present in the documented data.
+
+Data about disappearance, homicide, recruitment of children and adolescents, and kidnapping can be downloaded from the [National Administrative Department of Statistics' (DANE in Spanish)  website](https://microdatos.dane.gov.co/index.php/catalog/795/get-microdata). The data about each of the four human rights violations correspond to 100 replicates, which are the result of a statistical imputation process of missing fields (see Section 4 of the [methodological report of the project](https://www.comisiondelaverdad.co/sites/default/files/descargables/2022-08/04_Anexo_Proyecto_JEP_CEV_HRDAG_08022022.pdf)). To download the data, click the *descargar* button next to the files you would like to download. The repository [`verdata-examples`](https://github.com/HRDAG/verdata-examples) contains examples that illustrate how to correctly use the data and this package. These examples are currently only available in Spanish, but we are working on translating them to English.
 
 <div class="column" width="60%">
 
@@ -28,15 +30,15 @@ Haga clic [aquí](https://github.com/HRDAG/verdata/blob/main/README.md) para ins
 You can install the development version of `verdata` from GitHub with:
 
 ```r
-install.packages("devtools")
+if (!require("devtools")) {install.packages("devtools")}
 devtools::install_github("HRDAG/verdata")
 ```
 
-`verdata` requires the package [`LCMCR`](https://cran.r-project.org/web/packages/LCMCR/index.html) as a dependency. Installing `LCMCR` requires installing the [GNU Scientific Library](https://www.gnu.org/software/gsl/). It's possible that you will need to install this library separately before installing `verdata`.
+One of the `verdata`'s dependencies requires the installation of the [GNU Scientific Library](https://www.gnu.org/software/gsl/). It's possible that you will need to install this library separately before installing `verdata`.
 
 ## Data dictionary
 
-In the subdirectory `inst/docs` you can find the data dictionary for the replicate files. This dictionary includes the definition of each one of the variables in the replicate files, as well as information about additional variables that were constructed for the final report of the Colombian Truth Commission. The dicionary is currently only available in Spanish, but we are working on translating it to English.
+`verdata` has two data frames that contain information about the data dictionary for the replicate files. In `diccionario_replias`, you will find the definition of each of the variables contained within. In `diccionario_vars_adicional`, you will find additional variables that were constructed for the final report of the Colombian Truth Commission. These data dictionaries are currently only available in Spanish, but we are working on translating them to English.
 
 ## Usage
 
@@ -68,5 +70,8 @@ To use this package, it is necessary to have previously downloaded the data from
 
 * Finally, the `combine_estimates` function allows you to combine the results of the estimation, yielding an approximate 95% credibility interval and the point estimate of the mean of the total number of victims in a stratum of interest including both the uncertainty from the missing data imputation and from the multiple systems estimation model. The function uses the Normal approximation using the laws of total expectation and total variance. See Section 18.2 of [*Bayesian Data Analysis*](http://www.stat.columbia.edu/~gelman/book/) for more information.
 
-## Thank yous
+## Acknowledgments
 We thank [Micaela Morales](https://github.com/mmazul) for her thoughtful beta testing of the package.
+
+## Contribute to the package
+Comments and suggestions are very welcome. If you have a problem, question, or issue with `verdata`, please open an issue on GitHub. If you would like to add new functionality to the package, please open a pull request.