Ampliando ejemplos

README.Rmd

@@ -16,14 +16,29 @@ knitr::opts_chunk$set(
 # ClustMC
 
 <!-- badges: start -->
-[![R-CMD-check](https:/SGS2000/ClustMC/actions/workflows/R-CMD-check.yaml/badge.svg)](https:/SGS2000/ClustMC/actions/workflows/R-CMD-check.yaml)
-[![codecov](https://codecov.io/gh/SGS2000/ClustMC/branch/master/graph/badge.svg)](https://codecov.io/gh/SGS2000/ClustMC)
-[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
+
+[![R-CMD-check](https:/SGS2000/ClustMC/actions/workflows/R-CMD-check.yaml/badge.svg)](https:/SGS2000/ClustMC/actions/workflows/R-CMD-check.yaml) [![codecov](https://codecov.io/gh/SGS2000/ClustMC/branch/master/graph/badge.svg)](https://codecov.io/gh/SGS2000/ClustMC) [![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
+
 <!-- badges: end -->
 
-ClustMC implements cluster-based multiple comparisons tests.
+🇬🇧 ClustMC implements cluster-based multiple comparisons tests.
+
+All tests included in the package share similar features:
+
+- Inspired by the [agricolae](https://myaseen208.com/agricolae/) package, it is possible work with either two vectors (one for the response variable and one for the treatments) or a model (created with `lm()` or `aov()`). In the latter case, the name of the variable with the treatments must be indicated.
+- After applying the corresponding method, a table containing the treatments and their group (indicated by a number) is printed to the console. Treatments within the same group are not significantly different. The user can choose not not display the table.
+- By default, a dendrogram is plotted. The dendrogram can be customized with any argument passed to the `plot()` function. In addition, the data used to create it is made available to the user, so it is possible to use other libraries such as ggplot2. 
+
+------------------------------------------------------------------------
+
+🇪🇸 ClustMC implementa pruebas de comparaciones múltiples basadas en conglomerados.
+
+Todos los tests incluidos en el paquete tienen características similares:
+
+- Basándose en el paquete [agricolae](https://myaseen208.com/agricolae/), es posible trabajar con dos vectores (uno para la variable respuesta y otro para los tratamientos) o con un modelo (creado con `lm()` o `aov()`). En el segundo caso, se debe indicar el nombre de la variable con los tratamientos a comparar.
+- Luego de aplicar el método correspondiente, se imprime en la consola una tabla con los tratamientos y el grupo al que han sido asignados (indicado por un número). Los tratamientos dentro del mismo grupo no son significativamente diferentes. Se puede optar por no mostrar estos resultados.
+- Por defecto, se grafica un dendrograma. El dendrograma puede ser personalizado con cualquier argumento de la función `plot()`. Además, el usuario tiene acceso a los datos usados para crearlo, por lo que es posible recurrir a otros paquetes como ggplot2.
 
-ClustMC implementa pruebas de comparaciones múltiples basadas en conglomerados.
 
 ## Installation / Instalación
 
@@ -35,20 +50,79 @@ devtools::install_github("SGS2000/ClustMC")
 
 ## Examples / Ejemplos
 
-The following example applies the Di Rienzo, Guzmán, and Casanoves Test to evaluate whether there are significant differences between the yields obtained under a control and two different treatment conditions.
+### Tests
 
-El siguiente ejemplo aplica la Prueba de Di Rienzo, Guzmán y Casanoves para evaluar si existen diferencias significativas entre los rendimientos obtenidos bajo una condición de control y dos condiciones de tratamiento diferentes.
+🇬🇧 The following example applies the Di Rienzo, Guzmán, and Casanoves test to evaluate whether there are significant differences between the yields obtained under a control and two different treatment conditions. In this case, vectors are passed as arguments.
 
+🇪🇸 El siguiente ejemplo aplica la prueba de Di Rienzo, Guzmán y Casanoves para evaluar si existen diferencias significativas entre los rendimientos obtenidos bajo una condición de control y dos condiciones de tratamiento diferentes. En este caso, se pasan vectores como argumentos.
 
-```{r example}
+```{r example1}
 library(ClustMC)
 
 data(PlantGrowth)
 plants_weights <- PlantGrowth$weight
 plants_trt <- PlantGrowth$group
 
-anova_model <- aov(plants_weights ~ plants_trt)
+dgc_test(y = plants_weights, trt = plants_trt)
+```
+
+------------------------------------------------------------------------
 
-dgc_test(y = anova_model, trt = "plants_trt")
+🇬🇧 In the following example, a dataset with results from a bread-baking experiment is used. An ANOVA model is fitted, with the volume of the loaves as a response variable and the amount of potassium bromate and the variety of wheat as explanatory variables. The Jolliffe test is then applied to evaluate differences between the 17 varieties.
+
+
+🇪🇸 En el siguiente ejemplo, se utiliza un dataset con los resultados de un experimento de panadería. Se ajusta un modelo ANOVA con el volumen de los panes como variable respuesta y la cantidad de bromato de potasio y la variedad de trigo como variables explicativas. La prueba de Jolliffe se aplica luego para evaluar las diferencias entre las 17 variedades.
+
+```{r example2}
+library(ClustMC)
+
+data(bread)
+anova_model <- aov(volume ~ variety + as.factor(bromate), data = bread)
+
+jolliffe_test(y = anova_model, trt = "variety")
 ```
 
+### Customizing plots / Personalizar gráficos
+
+🇬🇧 Dendrograms can be customized, using any argument available for the `plot()` function. In the case of the lines, arguments for the `abline()` function must be passed as list.
+
+🇪🇸 Los dendrogramas pueden ser personalizados, utilizando cualquier argumento disponible para la función `plot()`. En el caso de las rectas, se debe utilizar una lista conteniendo argumentos para la función `abline()`.
+
+```{r example3}
+library(ClustMC)
+
+data(PlantGrowth)
+plants_weights <- PlantGrowth$weight
+plants_trt <- PlantGrowth$group
+
+dgc_test(
+ y = plants_weights, trt = plants_trt,
+ abline_options = list(col = "red", lty = 3, lwd = 1),
+ main = "A customized plot",
+ xlab = "Treatments",
+ col = "grey50",
+ cex = 0.75
+)
+```
+
+------------------------------------------------------------------------
+
+🇬🇧 Alternatively, the `hclust` object that creates the dendrogram is made available to the user, which allows other libraries to be used. In the following example, the [ggdendro](https://andrie.github.io/ggdendro/) package is used to plot the dendrogram with ggplot2.
+
+🇪🇸 Como alternativa, el usuario tiene acceso al objeto de clase `hclust` usado por la función para crear el dendrograma, lo cual permite la aplicación de otros paquetes. En el siguiente ejemplo se recurre al paquete [ggdendro](https://andrie.github.io/ggdendro/) para graficar el dendrograma con ggplot2.
+
+
+```{r example4}
+library(ClustMC)
+library(ggplot2)
+library(ggdendro)
+
+data(bread)
+anova_model <- aov(volume ~ variety + as.factor(bromate), data = bread)
+
+test_results <- jolliffe_test(y = anova_model, trt = "variety", console = F, show_plot = F)
+
+ggdendro::ggdendrogram(test_results$dendrogram_data) +
+ geom_hline(yintercept = 0.95, colour = "blue", linetype = "dotted", linewidth = 0.75) +
+ ggtitle("SLCA dendrogram for bread baking data")
+```

README.md

@@ -9,13 +9,51 @@
 [![codecov](https://codecov.io/gh/SGS2000/ClustMC/branch/master/graph/badge.svg)](https://codecov.io/gh/SGS2000/ClustMC)
 [![Lifecycle:
 experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
+
 <!-- badges: end -->
 
-ClustMC implements cluster-based multiple comparisons tests.
+🇬🇧 ClustMC implements cluster-based multiple comparisons tests.
+
+All tests included in the package share similar features:
+
+- Inspired by the [agricolae](https://myaseen208.com/agricolae/)
+ package, it is possible work with either two vectors (one for the
+ response variable and one for the treatments) or a model (created with
+ `lm()` or `aov()`). In the latter case, the name of the variable with
+ the treatments must be indicated.
+- After applying the corresponding method, a table containing the
+ treatments and their group (indicated by a number) is printed to the
+ console. Treatments within the same group are not significantly
+ different. The user can choose not not display the table.
+- By default, a dendrogram is plotted. The dendrogram can be customized
+ with any argument passed to the `plot()` function. In addition, the
+ data used to create it is made available to the user, so it is
+ possible to use other libraries such as ggplot2.
 
-ClustMC implementa pruebas de comparaciones múltiples basadas en
+------------------------------------------------------------------------
+
+🇪🇸 ClustMC implementa pruebas de comparaciones múltiples basadas en
 conglomerados.
 
+Todos los tests incluidos en el paquete tienen características
+similares:
+
+- Basándose en el paquete
+ [agricolae](https://myaseen208.com/agricolae/), es posible trabajar
+ con dos vectores (uno para la variable respuesta y otro para los
+ tratamientos) o con un modelo (creado con `lm()` o `aov()`). En el
+ segundo caso, se debe indicar el nombre de la variable con los
+ tratamientos a comparar.
+- Luego de aplicar el método correspondiente, se imprime en la consola
+ una tabla con los tratamientos y el grupo al que han sido asignados
+ (indicado por un número). Los tratamientos dentro del mismo grupo no
+ son significativamente diferentes. Se puede optar por no mostrar estos
+ resultados.
+- Por defecto, se grafica un dendrograma. El dendrograma puede ser
+ personalizado con cualquier argumento de la función `plot()`. Además,
+ el usuario tiene acceso a los datos usados para crearlo, por lo que es
+ posible recurrir a otros paquetes como ggplot2.
+
 ## Installation / Instalación
 
 The package can be installed from GitHub: / El paquete puede instalarse
@@ -27,14 +65,18 @@ devtools::install_github("SGS2000/ClustMC")
 
 ## Examples / Ejemplos
 
-The following example applies the Di Rienzo, Guzmán, and Casanoves Test
-to evaluate whether there are significant differences between the yields
-obtained under a control and two different treatment conditions.
+### Tests
+
+🇬🇧 The following example applies the Di Rienzo, Guzmán, and Casanoves
+test to evaluate whether there are significant differences between the
+yields obtained under a control and two different treatment conditions.
+In this case, vectors are passed as arguments.
 
-El siguiente ejemplo aplica la Prueba de Di Rienzo, Guzmán y Casanoves
-para evaluar si existen diferencias significativas entre los
+🇪🇸 El siguiente ejemplo aplica la prueba de Di Rienzo, Guzmán y
+Casanoves para evaluar si existen diferencias significativas entre los
 rendimientos obtenidos bajo una condición de control y dos condiciones
-de tratamiento diferentes.
+de tratamiento diferentes. En este caso, se pasan vectores como
+argumentos.
 
 ``` r
 library(ClustMC)
@@ -43,15 +85,125 @@ data(PlantGrowth)
 plants_weights <- PlantGrowth$weight
 plants_trt <- PlantGrowth$group
 
-anova_model <- aov(plants_weights ~ plants_trt)
+dgc_test(y = plants_weights, trt = plants_trt)
+```
+
+<img src="man/figures/README-example1-1.png" width="100%" />
+
+ #> group
+ #> ctrl 1
+ #> trt1 1
+ #> trt2 2
+ #> Treatments within the same group are not significantly different
+
+------------------------------------------------------------------------
+
+🇬🇧 In the following example, a dataset with results from a bread-baking
+experiment is used. An ANOVA model is fitted, with the volume of the
+loaves as a response variable and the amount of potassium bromate and
+the variety of wheat as explanatory variables. The Jolliffe test is then
+applied to evaluate differences between the 17 varieties.
+
+🇪🇸 En el siguiente ejemplo, se utiliza un dataset con los resultados de
+un experimento de panadería. Se ajusta un modelo ANOVA con el volumen de
+los panes como variable respuesta y la cantidad de bromato de potasio y
+la variedad de trigo como variables explicativas. La prueba de Jolliffe
+se aplica luego para evaluar las diferencias entre las 17 variedades.
+
+``` r
+library(ClustMC)
+
+data(bread)
+anova_model <- aov(volume ~ variety + as.factor(bromate), data = bread)
+
+jolliffe_test(y = anova_model, trt = "variety")
+```
+
+<img src="man/figures/README-example2-1.png" width="100%" />
+
+ #> group
+ #> M 1
+ #> P 2
+ #> D 2
+ #> C 2
+ #> Q 2
+ #> L 2
+ #> H 2
+ #> G 2
+ #> N 2
+ #> B 2
+ #> F 2
+ #> I 2
+ #> K 2
+ #> J 2
+ #> E 2
+ #> A 2
+ #> O 2
+ #> Treatments within the same group are not significantly different
+
+### Customizing plots / Personalizar gráficos
+
+🇬🇧 Dendrograms can be customized, using any argument available for the
+`plot()` function. In the case of the lines, arguments for the
+`abline()` function must be passed as list.
+
+🇪🇸 Los dendrogramas pueden ser personalizados, utilizando cualquier
+argumento disponible para la función `plot()`. En el caso de las rectas,
+se debe utilizar una lista conteniendo argumentos para la función
+`abline()`.
+
+``` r
+library(ClustMC)
+
+data(PlantGrowth)
+plants_weights <- PlantGrowth$weight
+plants_trt <- PlantGrowth$group
 
-dgc_test(y = anova_model, trt = "plants_trt")
+dgc_test(
+ y = plants_weights, trt = plants_trt,
+ abline_options = list(col = "red", lty = 3, lwd = 1),
+ main = "A customized plot",
+ xlab = "Treatments",
+ col = "grey50",
+ cex = 0.75
+)
 ```
 
-<img src="man/figures/README-example-1.png" width="100%" />
+<img src="man/figures/README-example3-1.png" width="100%" />
 
  #> group
  #> ctrl 1
  #> trt1 1
  #> trt2 2
  #> Treatments within the same group are not significantly different
+
+------------------------------------------------------------------------
+
+🇬🇧 Alternatively, the `hclust` object that creates the dendrogram is
+made available to the user, which allows other libraries to be used. In
+the following example, the
+[ggdendro](https://andrie.github.io/ggdendro/) package is used to plot
+the dendrogram with ggplot2.
+
+🇪🇸 Como alternativa, el usuario tiene acceso al objeto de clase `hclust`
+usado por la función para crear el dendrograma, lo cual permite la
+aplicación de otros paquetes. En el siguiente ejemplo se recurre al
+paquete [ggdendro](https://andrie.github.io/ggdendro/) para graficar el
+dendrograma con ggplot2.
+
+``` r
+library(ClustMC)
+library(ggplot2)
+library(ggdendro)
+
+data(bread)
+anova_model <- aov(volume ~ variety + as.factor(bromate), data = bread)
+
+test_results <- jolliffe_test(y = anova_model, trt = "variety", console = F, show_plot = F)
+
+ggdendro::ggdendrogram(test_results$dendrogram_data) +
+ geom_hline(yintercept = 0.95, colour = "blue", linetype = "dotted", linewidth = 0.75) +
+ ggtitle("SLCA dendrogram for bread baking data")
+```
+
+<img src="man/figures/README-example4-1.png" width="100%" />