README.rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#",
  fig.path = "README-"
)
```

# BIENVENIDOS!!!

# EN LA SIGUIENTE GUÍA SE MOSTRARÁ COMO USAR EL PAQUETE DATAMETRÍA. 

## FUNCIONES.

El paquete está en pleno desarrollo, por el momento sólo contamos con 7 funciones:

1. **limpiecito**: Esta función limpia elementos o vectores caracter, quitando las tildes, espacios en blanco al inicio, entre caracteres y al final. Tiene la opción de arrojar los resultados en minúsculas o mayúsculas. 
2. **estadisticos**: Esta función permite calcular los principales estadísticos como: la media, mediana, desviación estándar, mínimo, máximo, coeficiente de variación y el total de observaciones. 
3. **dpto_peru**: Esta función permite convertir el ubigeo de las regiones de Perú a su descripción, es decir, al nombre de la región. 
4. **n_percentil**: Esta función permite calcular el número de elementos de un vector que pertenecen a un determinado percentil. Arroja los resultados mostrando los puntos de corte o por bloques determinados por el percentil.
5. **test_grubbs**: Test que permite determinar si un elemento de un vector es outliers, mediante el test de grubss. Esta función tiene la opción de arrojar como resultado un valor lógico o todos los estadísticos de grubbs que se usaron para determinar si es o no outliers. 
6. **grubss_total**: Esta función realiza, el test de grubbs, que sirve para determinar si uno o varios elementos del vector son outliers.
7. **area_quantile**:  Esta función grafica la funciones de densidad y divide el gráfico por percetiles.

Para usar el paquete primero se tiene que instalar el paquete `devtools` (si aún no lo tienes instalado). 

```{r, eval=FALSE}
install.packages("devtools")
```

Una vez instalado `devtools`, se procede a descargar el paquete `datametria`, para lo cual digitamos el siguiente código: 

```{r, eval=FALSE}
devtools::install_github("CesarAHN/datametria")
```

Una vez descargado, se tiene que cargar el paquete `datametria`. Para esto corremos el siguiente código:

```{r}
library(datametria)
```

## EJEMPLOS DE COMO USAR LAS FUNCIONES:

### FUNCIÓN limpiecito():

La función `limpiecito()` es una función para limpiar espacios por demás al inicio, final o intermedio. Asimismo elimina tildes y arroja los resultados en letras mayúsculas o minúsculas. Esta función sólo recibe dos parámetros: `x` que es un elemento o vector caracter y `capital` que es un valor lógico que si toma el valor de `TRUE` arrojará los resultados en mayúsculas, mientras que si toma el valor `FALSE` arrojará los resultados en minúsuculas, el valor por defecto es `TRUE`.

Veamos un ejemplo de uso. 

Si se tiene el siguiente vector:

```{r}
x<-c("   mucho    espacio", "VAYA      de     espacios    ", "CÓMO se hicieron    tantos espacios   ")
x
```

Como se puede ver el vector `x` tiene 3 elementos caracter y cada elemento tienen más de un espacio ya sea al inicio, intermedio o fin, además hay palabras con mayúscula y minúsculas, y por último, palabras con tildes. Entonces, si queremos que el vector `x` tenga una estructura homogénea tendremos que usar la función `limpiecito()`. 

Veamos como:

```{r}
# Si deseamos que los resultados del vector x sean mayúsculas.
limpiecito(x)
```

Gracias a la función `limpiecito()` se ha podido eliminar los espacios y homogenizar las palabras quitandole las tíldes y convirtiendo todo a mayúscula. 

Pero si nosotros deseamos que los resultados estén en minúsculas, entonces, usaremos el argumento `capital`. Veamos como:

```{r}
# Si deseamos que los resultados del vector x sean minúsculas.
limpiecito(x, capital = FALSE)
```

### FUNCIÓN estadísticos():

Esta función se usa para calcular los principales estadísticos como: la media, mediana, desviación estándar, mínimo, máximo, coeficiente de variación y el total de observaciones. Solo recibe 2 argumentos: `x` que tiene que ser un vector numérico y `miss` que toma un valor lógico, si es `TRUE` entonces para el cálculo de los estadísticos no se toma en cuenta los **missings values**, por el contrario si es `FALSE` si se toma en consideración los **missings values**. 

Veamos un ejemplo de como usarlo. Pero primero carguemos una tabla de datos `gender`, para cargarlo usamos la siguiente sintaxis. 

```{r}
df<-read.csv("http://r.datametria.com/wp-content/uploads/2020/08/gender.csv", sep = ";")

# Viendo las 5 primeras filas del data frame.
head(df)
```

Tenemos los ingresos (`income`), los años de educación (`educ`), los años de experiencia (`jobexp`) y el género (`female`). 

Entonces si nosotros queremos sacar los principales estadísticos de los ingresos vamos a usar la función `estadisticos()`. 

```{r}
estadisticos(df$income)
```

En efecto, hemos logrado obtener los principales estadísticos de los ingresos. Pero si deseo no solo de los ingresos sino también de los años de educación y los años de experiencia, entonces usaría la siguiente sintaxis.

```{r}
do.call(cbind,lapply(df[,1:3], estadisticos))
```

### FUNCIÓN dpto_peru():

Esta función nos permite obtener los nombres de las regiones cuando ingresamos el número de ubigeo, también si sólo le indicamos los cuatro o dos primeros números del ubigeo. Sólo necesita un argumento el cual es `x` que es un elemento o vector numérico o caracter.

Para ver un ejemplo carguemos la tabla de datos de la ENAHO del 2019, en donde se tiene en consideración el ubigeo de los encuestados. 

```{r, eval=FALSE}
df<-read.table("http://r.datametria.com/wp-content/uploads/2020/09/enaho_2019.txt", colClasses = "character")
```

```{r, echo=FALSE}
df<-read.table("F:/enaho_2019.txt", colClasses = "character")
```

El archivo pesa 7MB puede que tarde un poco la descarga de la tabla. Una ve que ha cargado la tabla, podemos ver las 5 primeras filas. 

```{r}
head(df)
```

Vemos que la variable ubigeo es una vector con elementos de 6 caracteres. Entonces, si nosotros queremos colocar los nombres de las regiones dado este ubigeo, tedríamos que usar la siguiente sintaxis. 

```{r}
df$region<-dpto_peru(df$ubigeo)
```

Viendo las 5 primeras filas. 

```{r}
head(df)
```

En efecto podemos ver que en la columna región ahora se muestran los nombres de las regiones. 

Pero se puede dar el caso que sólo tienes un vector en donde sólo se tiene los dos primeros dígitos del ubigeo. Hagamos un ejemplo, en donde se muestre el vector con sólo dos caracteres. 

```{r}
# Para esto se usará la función substring.
df$region2<-substring(df$ubigeo, 1,2)

# Convirtiendo este vector para que arroje los nombres de las regiones. 
df$region2_a<-dpto_peru(df$region2)

# Viendo las 5 primeras filas.
head(df)
```

En efecto, se ha obtenido los nombres de las regiones. 

Esta función también sirve si sólo tienes en consideración los 4 primeros caracteres del ubigeo, incluso si el vector de ubigeos es numérico. 

Veamos un ejemplo para el caso de vectores numéricos. 

```{r}
# Vamos a convertir a numérico el vector region2 que tiene sólo dos caracteres. 
df$region3<-as.numeric(df$region2)

# Convirtiendo este vector para que arroje los nombres de las regiones. 
df$region3_a<-dpto_peru(df$region3)

# Viendo las 5 primeras filas.
head(df)
```

Y como se mencionó se obtuvieron los nombres de las regiones. Para poder ver el número de encuestados por regiones vamos a realizar una tabla, no se va a considerar el factor de expansión porque el objetivo de esta guía no es aquello. 

```{r}
# Creando la tabla. 
table(df$region)
```

### FUNCIÓN n_percentil():

Esta función permite calcular el número de elementos de un vector que pertenecen a un determinado percentil. Arroja los resultados mostrando los puntos de corte o por bloques determinados por el percentil. Esta función tiene 3 argumentos: `x` que tiene que ser un vector numérico, `len` que es el número de cortes que se desea realizar, el valor por defecto es 4, es así que arrojará el número de elementos por cuartiles. Por último, el argumento `p_corte` que es un valor lógico que toma el valor por defecto de `TRUE`, lo que indica que en los resultados se muestre el número de puntos de corte, en el caso de que `len` sea 4, entonces mostrará los elementos en 4 bloques; y si toma el valor de `FALSE` entonces mostrará los resultados con los puntos de corte. 

Veamos algunos ejemplos, pero primero cargamos la tabla de datos gender. 

```{r}
# Cargamos la tabla de datos gender.
df<-read.csv("http://r.datametria.com/wp-content/uploads/2020/08/gender.csv", sep = ";")

# Viendo las 5 primeras filas del data frame.
head(df)

```

Vamos a calcular el número de personas por cuartil de los ingresos. Recordar que el cuartil divide en 4 a nuestros datos y el valor por defecto de `len` es 4.

```{r}
n_percentil(df$income)
```

En efecto, calcula el número de elementos por cuartil. Así tenemos que en el primer cuartil hay 125 elementos que van desde 5 a 21.5, luego 150 elementos desde mayores a 21.5 y menores iguales 24.8 y así sucesivamente. 

Pero si no deseamos verlo con los puntos de corte y sólo queremos ver los bloques por percentil, entonces, tendremos que usar el argumento `p_corte` y asignarle el valor de `FALSE`. Veamos un ejemplo, pero ahora para los quintiles. 

```{r}
n_percentil(df$income, len = 3, p_corte = FALSE)
```

Podemos ver que en el primer tercil se encuentran 175 elementos, igual en el segundo tercil, por último, el tercer tercil cuenta con 150 elementos.

### FUNCIÓN test_grubbs().

Esta función nos permite determinar si un elemento de un vector es outliers, mediante el test de grubss. Esta función tiene la opción de arrojar como resultado un valor lógico o todos los estadísticos de grubbs que se usaron para determinar si es o no outliers. 

Esta función tiene 5 argumentos: `x1` es el elemento del cual se desea saber si es un outliers, `x` es el vector numérico que contiene a `x1`, `alpha` indica el nivel de significancia con los que se desea realizar el test de grubbs, esto nos permite calcular el valor o valores críticos del test, su valor por defecto es de 0.05 (5%), `num_colas` es un valor numérico que toma por defecto 2, lo que indica que el análisis se hará a dos colas y si toma el valor de 1, el análisis se hará a una cola, por último, el argumento `vista` que es un elemento lógico en donde si toma el valor de `TRUE` entonces se muestren el valor estadístico del test de grubbs, el valor crítico del test de grubbs, la comparación que se hace y el resultado que es un valor lógico TRUE o FALSE, donde TRUE indica que el elemento es un outliers.

Para ver un ejemplo, carguemos la tabla de datos llamada `outlier`.

```{r}
# Cargamos la base de datos.
df<-read.table("https://r.datametria.com/wp-content/uploads/2020/09/outlier.txt")

# Veamos las 5 primeras filas.
head(df)
```

Podemos darnos cuenta que el primer elemento del vector `dv` es 99 y quizá pueda ser un outlier. Entonces, veamos si el primer elemento de la variable `dv` es un outlier. 

```{r}
test_grubbs(df$dv[1], df$dv, vista = FALSE)
```

Como podemos ver con `df$dv[1]` le estamos diciendo que seleccione al primer elemento del vector `df`. Y  nos arrojó el valor de `TRUE`, lo cual indica que el primer elemento de la variable `dv` es un outlier.

Recordar que el test lo realizó a dos colas y con un nivel de significancia del 0.05. Pero como se mencionó anteriormente, podemos ver el estadístico de grubbs, su valor crítico y la elección. 

```{r}
test_grubbs(df$dv[1], df$dv)
```

En efecto, el estadistico de grubss es de 5.1482 y el valor crítico de es de 3.036 y si comparamos podemos ver que el estadístico de grubbs es mayor al valor crítico, por tanto, es un outlier.

Pero si nosotros deseamos calcular si más de un elemento es un valor outlier entonces, tendríamos que recurrir a un `for`, pero no será necesario ya que contamos con la función `grubbs_total` que puede hacer todo el procedimiento sin necesidad de hacer el `for`.

### FUNCIÓN grubbs_total():

Esta función realiza, el test de grubbs, pero a más de un elemento. 

Esta función sólo cuenta con tres argumentos: `x` que es el vector de donde se desea saber el número de elementos que podrían ser outliers, esea saber si es un outliers, `x` es el vector numérico que contiene a `x1`, `alpha` que indica el nivel de significancia con los que se desea realizar el test de grubbs, esto nos permite calcular el valor o valores críticos del test, su valor por defecto es de 0.05 (5%), `num_colas` es un valor numérico que toma por defecto 2, lo que indica que el análisis se hará a dos colas y si toma el valor de 1, el análisis se hará a una cola.

Para poder ver un ejemplo carguemos la tabla de datos `binlfp4` que contiene información sobre la participación de las mujeres en la fuerza laboral.

```{r}
# Cargando la base de datos.
df<-read.table("http://r.datametria.com/wp-content/uploads/2020/09/binlfp4.txt")

# Viendo las 5 primeras filas. 
head(df)
```

Podemos ver la columna `inc` el cual representa el ingreso de las familias exceptuando el de las esposas. 

Entonces, si nosotros queremos saber cuales de esos ingresos son outliers por el método de grubbs, tendremos que usar nuestra función `grubbs_total`.

```{r}
grubbs_total(df$inc)
```

Se muestra el valor de `TRUE` o `FALSE` para las 753 observaciones que se tiene. Podemos ver que la observación 25 y 26 son outliers, pero hay más en las siguientes observaciones. Para saber cuantos son outliers, podemos aplicarle la función `sum()`

```{r}
sum(grubbs_total(df$inc))
```

Nos indica que hay un total de 8 outliers. 

### FUNCIÓN area_quantile():

Esta función nos permite graficar la funciones de densidad de una variable y divide el gráfico por percetiles, por tanto, nos devuelve sub áreas del gráfico de densidad.

la función tiene 6 argumentos: `x` es el vector numérico del cual se desea graficar el gráfico de densidad, `len` es un elemento numérico que nos indica el número de cortes que se le desea hacer al gráfico de densidad, su valor por defecto es 4 lo que indica que la gráfica se cortará por cuartiles, `color_area` es un elemento numérico o vector caracter que indica el número de colores con los que se desea pintar las sub áreas del gráfico de densidad, su valor por defecto es NA, lo que indica que tomará el número de colores que se especificó en `len` y tomará los colores de la función `terrain.colors`, por otro lado si desea que sólo se pinte de dos colores entonces, usted tendra que colocar el número 2, e igualmente usará los colores de la función `terrain.colors`, pero si desea asignarle los colores que usted desea entonces tendrá que colocar los nombres o códigos de los colores, `col_border` es un elemento caracter que se usa para especificar el color de los bordes que dividen las sub áreas, el color por defecto es "black". `titulo` es un elemento caracter y especifica el título que se le desea colocar a la gráfica, el valor por defecto es vacio, `dureza` es un elemento numérico que indica el grosor de la línea que divide las sub áreas, es el mismo argumento que `lwd` de la función plot. Su valor por defecto es 2, por último `...` indican otros argumentos que se pueden usar en la función plot, estos argumentos afectarán al plot, pero no a las sub áreas. Por ejemplo, puede usar `xlab`, `font`, `sub`, `bty`, etc. Pero no puede usar el argumento `main`, ya que ya está especificado con el argumento `título`.

Para poder verlo mejor veamos un ejemplo. Para esto se usa la tabla de datos ` partyid4` que es de un estudio de las elecciones de estados unidos.

```{r}
# Cargamos la tabla de datos. 
df<-read.table("https://r.datametria.com/wp-content/uploads/2020/09/partyid4.txt")

# Viendo las primeras 5 filas. 
head(df)
```

Vamos a graficar la densidad de la variable `age` y dividirlo por cuartiles. 

```{r}
area_quantile(df$age, titulo = "Grafico de densidad de la edad dividido por cuartiles")
```

En efecto, obtenemos el gráfico de densidad de la edad por cuartiles. Como se mencionó anteriormente, podemos usar otros argumentos para mejorar este gráfico. Para el caso se puede usar los argumentos xlab y ylab y cambiar de colores. 

```{r}
area_quantile(df$age, titulo = "Grafico de densidad de la edad dividido por cuartiles", 
              xlab="Edad", ylab="Densidad", color_area=c("darkolivegreen1","dodgerblue","gold1","orangered"))
```

Incluso podemos juntar esta salida con la función `n_percentil()`, para poder saber el número de elementos por sub áreas. Veamos como las unimos. 

```{r}
# Definiendo el número de elementos por cuartil.
cuartiles<-n_percentil(df$age)

area_quantile(df$age, titulo = "Grafico de densidad de la edad dividido por cuartiles", 
              xlab="Edad", ylab="", color_area=c("darkolivegreen1","dodgerblue","gold1","orangered"),
              bty="n", yaxt="n")

legend("topright", legend = c(paste("1° cuartil =", cuartiles[1]),
                              paste("2° cuartil =", cuartiles[2]),
                              paste("3° cuartil =", cuartiles[3]),
                              paste("4° cuartil =", cuartiles[4])),
       col = c("darkolivegreen1","dodgerblue","gold1","orangered"), cex=0.7, pch = 19)
```

## Actualizaciones.

Por el momento sólo se ha producido 7 funciones, pero en los siguientes días espero agregar más. Si tiene alguna sugerencia o comentario puede enviarnos un correo a: **pe.cesar.huamani.n@uni.pe** o **cesar.huamani@datametria.com**

Muchas gracias.