README.Rmd

---
md_document:
  variant: markdown_github
title: "compareGroups"
output: md_document
always_allow_html: true
---



```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, warning=FALSE, message=FALSE, comment="")
library(knitr)
```

compareGroups <img src="man/figures/logo.png" align="right" style="margin-top:30px" width="80px"/>
=========

**_package to create descriptive tables_**

[![CRAN version](https://www.r-pkg.org/badges/version/compareGroups)](https://cran.r-project.org/package=compareGroups) ![](https://cranlogs.r-pkg.org/badges/grand-total/compareGroups) ![](https://cranlogs.r-pkg.org/badges/last-month/compareGroups)

-   [Overview](#overview)
-   [News](#news)
-   [Package installation](#package-installation)
-   [Costumizing the table](#costumizing-the-table)
-   [Visual exploration](#visual-exploration)
-   [Exporting the table](#exporting-the-table)
-   [Stratified tables](#stratified-tables)
-   [Odds Ratios and Hazard Ratios](#odds-ratios-and-hazard-ratios)
-   [Web-based User Interface](#web-based-user-interface)
-   [Citation](#citation)



## Overview

**compareGroups** is an R package available on CRAN which performs descriptive tables displaying means, standard deviation, quantiles or frequencies of several variables. Also, p-value to test equality between groups is computed using the appropiate test. <br>

With a very simple code, nice, compact and ready-to-publish descriptives table are displayed on R console. They can also be exported to different formats, such as Word, Excel, PDF or inserted in a R-Sweave or R-markdown document.<br>

You will find an extensive manual describing all **compareGropus** capabilities with real examples in the [vignette](http://htmlpreview.github.io/?https://github.com/isubirana/compareGroups/blob/master/compareGroups_vignette.html).<br>


Also, **compareGroups** package has been published in Journal of Statistical Software [Subirana et al, 2014 [http://www.jstatsoft.org/v57/i12/.](https://www.jstatsoft.org/v57/i12/.)].


## News

**_Version 4.9_**

- new argument `nmax.method` to compute the N shown in the header. By default N is computed as the number of rows with at least one valid value in the described variables, but also N can be computed as the total number of rows in the data set or in each group regardless the available data in the described variables. 

- new argument `stars` to show significance levels asterisks beside p-values.

- new argument `p.trend.method`  to choose between Spearman, Kendall or "Cuzick's trend test for non-normal numerical variables.



**_Version 4.8_**

- new argument added "lab.ref" to change label for reference category.


**_Version 4.7_**

- WUI: new functionality to convert to factors integer variables. Useful to plot numeric variables with few values as bar plots.


**_Version 4.6_**

- new function `padjustCompareGroups` to adjust p-values for multiple testing.

- new arguments `header.background` and `header.color` to change header colors when exporting to PDF.


**_Version 4.5_**

- new argument 'lab.missing' to specify label for missing category.


**_Version 4.4_**

- new argument 'compute.prop' to compute proportions instead of percentages for categorical row-variables.

- new argument 'all.last' added to place descriptives of the whole sample after descriptives by groups.


**_Version 4.3_**

- `export2word` supports stratified tables

- Risk Ratios are now computed.


**_Version 4.2_**

- **`flextable`** package dependency

- `export2md` supports tables and stratified tables to export to word in nicer format using flextable.



**_Version 4.1_**

- Compute confidence intervals of means, medians, proporcions or incidences

- Proportions can be computed by rows as well as by columns, or by combinations of rows and columns (i.e. to sum up 100%).

- New argument "position" to place tables justified to the left, centered or to the right using Rmarkdown.

- When exporting tables to Excel, `export2xls` no longer uses `xlsx` package and uses `write_xlsx` function from writexl pacakge, instead.

- The web-based user interface , `cGroupsWUI()`, has been improved and updated.

**_Version 4.0_**

- New argument `var.equal` to consider unequal variances when performing ANOVA tests.

- Date variables are supported.

- New **`strataTable`** function: to create stratified tables without having to use cbind.

- package vignette improved.

- New **`descrTable`** function that builds a descriptive table in one step.

- New options added in `export2md`, to export tables in nicer format.

- New options added in `compareGroups` to control permutated chisquared test.


## Package installation


Install the **`compareGroups`** package from CRAN and then load it by typing:

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

or from github to get the latest version

```{r, eval=FALSE}
library(devtools)
devtools::install_github(repo = "isubirana/compareGroups")
```

## Costumizing the table

In the following table, some variables from the REGICOR ("Registre Gironí del Cor") project ([www.regicor.cat](https://www.regicor.cat)) data set available in the package are analysed. We illustrate the syntax of **`compareGroups`** functions to display tables containing descriptives or possible tests to compare groups.


Following, to describe all the variables of the data set just type:

```{r}
library(compareGroups) # load compareGroups package
data(regicor) # load example data
descrTable(regicor)
```


**Example**

In the following table, variables are described by year of recruitment. 
Some variables such as tryglicerides (`triglyc`), physical activity (`phyact`), days to cardiovascular event (`tocv`) or days to death (`todeath`) have been treated as non-normal distributed, and medians and quantiles within square brackets instead of means and standard deviations within round brackets are displayed.
Also, individuals older than 55 years old are selected. Appropiate tests to compare means, medians or proportions are performed.
For those binary variables of type "yes/no", you may desire to show only the proportion of "yes" category without showing "yes" but only the variable name or label. For example, for "Cholesterol treatment" you may want to see simply "Cholesterol treatment" instead of "Cholesterol treatment: yes". This is possible by `hide.no` argument.
Finally, patient id (`id`) has been removed using `-` from the formula environment.

Note the simplicity of the syntax. Also, note the use of `formula` to select the variables, and the use of `subset` to filter some individuals as usual in many other R funcions.


```{r}
tab <- descrTable(year ~ . - id, regicor, hide.no="no", method=c(triglyc=2, tocv=2, todeath=2), 
                  subset=age>55)
tab
```



Also, number of decimals and much more options can be changed to costumize the table as desired (see the  [package manual](https://CRAN.R-project.org/package=compareGroups))



## Visual exploration

With **`compareGroups`** it is also possible to visualize the distribution of analysed variables. This can be done by the `plot` function applied on the table:

```{r, eval=FALSE}
plot(tab["sex"]) # barplot
plot(tab["age"]) # histogram and normality plot
```

```{r, echo=FALSE}
plot(tab["sex"],file="./man/figures/var1") # barplot
plot(tab["age"],file="./man/figures/var1") # histogram and normality plot
```


|                                     |                                      |
|:-----------------------------------:|:------------------------------------:|
|![](./man/figures/var1sex.png) | ![](./man/figures/var1age.png) |



## Exporting the table

Once the table is created, it can be printed on the R console in a nice and compact format, or it can be exported to different formats, such as PDF, Excel, Word or LaTex code.

```{r, eval=FALSE}
export2pdf(tab, file = "example.pdf")
export2xls(tab, file = "example.xlsx")
export2word(tab, file = "example.docx")
export2latex(tab, file = "example.tex")
```

This is how the table looks like in PDF:

![](./man/figures/examplePDF.png)


Also, by using `export2md` function a descriptive table can be inserted in a Rmarkdown chunk to be compiled in HTML, PDF or Word report. Here there is an example of a Rmarkdown compiled to HTML.

```{r, results="asis"}
export2md(tab, strip = TRUE, first = TRUE, 
          header.background = "blue", header.color = "white", 
          caption = "Description of variables by recruitment year",
          size=10)
```


## Stratified tables


After creating a table you may want to repeat the descriptives within stratas. For example, you may want to compare the groups for men and for women. This is very easy using the `strataTable` function:

```{r}
# stratify by sex
tabestr <- strataTable(tab, strata="sex")

# remove sex variable from the table
tabestr[-2]
```


or when is complied in HTML 

```{r, results="asis"}
export2md(tabestr, strip = TRUE, first = TRUE, 
          header.background = "blue", header.color = "white", size=8)
```


## Odds Ratios and Hazard Ratios


Using **`compareGroups`** package you can compute Odds Ratios for transversal or case-control studies, or Hazard Ratios for cohort studies

- **Example of case-control study: Odds Ratios**

```{r}
data(SNPs)
descrTable(casco ~ .-id, SNPs, show.ratio=TRUE, show.p.overall=FALSE)[1:4]
```


- **Example of cohort study: Hazard Ratios**


```{r, eval=FALSE}
# create a Surv response:
library(survival)
regicor$tcv <- Surv(regicor$tocv, regicor$cv=="Yes")

# perform descriptive table placing the Surv object as the response (left side of ~):
tab <- descrTable(tcv ~ .-id-cv-tocv, regicor, 
           method=c(triglyc=2, tocv=2, todeath=2),
           hide.no="no", ref.no="no",
           show.ratio=TRUE, show.p.overall=FALSE)

# print table on R console
print(tab, header.label=c("p.ratio"="p-value"))           
```

```{r, echo=FALSE}
# create a Surv response:
library(survival)
regicor$tcv <- Surv(regicor$tocv, regicor$cv=="Yes")

# perform descriptive table placing the Surv object as the response (left side of ~):
tab <- descrTable(tcv ~ .-id-cv-tocv, regicor, 
           method=c(triglyc=2, tocv=2, todeath=2),
           hide.no="no", ref.no="no",
           show.ratio=TRUE, show.p.overall=FALSE)

# print table on R console
print(tab, header.label=c("p.ratio"="p-value"))          
```



# Web-based User Interface

For those not familiar to R syntax, a Web User Interface (**WUI**) has been implemented using [Shiny](https://shiny.rstudio.com/) tools, which can be used remotely just accessing the [**compareGroups project website**](https://isubirana.github.io/compareGroups)




![ ](./man/figures/WUI.png)

Try the WUI compareGroups [here](https://isubirana.github.io/compareGroups/articles/wui.html)

<br>



# Citation


```{r}
citation("compareGroups")
```


# References


<p>Subirana, Isaac, Héctor Sanz, and Joan Vila. 2014. “Building Bivariate Tables: The compareGroups Package for R.” <em>Journal of Statistical Software</em> 57 (12): 1–16. <a href="https://www.jstatsoft.org/v57/i12/" class="uri">https://www.jstatsoft.org/v57/i12/</a>.</p>