added vignette of freq

vignettes/freq.R

@@ -0,0 +1,91 @@
+## ----setup, include = FALSE, results = 'markup'--------------------------
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#"
+)
+library(dplyr)
+library(AMR)
+
+## ---- echo = TRUE, results = 'hide'--------------------------------------
+# # just using base R
+freq(septic_patients$sex)
+
+# # using base R to select the variable and pass it on with a pipe
+septic_patients$sex %>% freq()
+
+# # do it all with pipes, using the `select` function of the dplyr package
+septic_patients %>%
+  select(sex) %>%
+  freq()
+
+## ---- echo = TRUE--------------------------------------------------------
+freq(septic_patients$sex)
+
+## ---- echo = TRUE, results = 'hide'--------------------------------------
+my_patients <- septic_patients %>% 
+  left_join_microorganisms()
+
+## ---- echo = TRUE--------------------------------------------------------
+colnames(microorganisms)
+
+## ---- echo = TRUE--------------------------------------------------------
+dim(septic_patients)
+dim(my_patients)
+
+## ---- echo = TRUE--------------------------------------------------------
+my_patients %>%
+  select(genus, species) %>%
+  freq()
+
+## ---- echo = TRUE--------------------------------------------------------
+# # get age distribution of unique patients
+septic_patients %>% 
+  distinct(patient_id, .keep_all = TRUE) %>% 
+  select(age) %>% 
+  freq(nmax = 5)
+
+## ---- echo = TRUE--------------------------------------------------------
+septic_patients %>%
+  select(hospital_id) %>% 
+  freq()
+
+## ---- echo = TRUE--------------------------------------------------------
+septic_patients %>%
+  select(hospital_id) %>% 
+  freq(sort.count = TRUE)
+
+## ---- echo = TRUE--------------------------------------------------------
+septic_patients %>%
+  select(amox) %>% 
+  freq()
+
+## ---- echo = TRUE--------------------------------------------------------
+septic_patients %>%
+  select(date) %>% 
+  freq(nmax = 5)
+
+## ---- echo = TRUE--------------------------------------------------------
+septic_patients %>%
+  select(amox) %>% 
+  freq(na.rm = FALSE)
+
+## ---- echo = TRUE--------------------------------------------------------
+septic_patients %>%
+  select(hospital_id) %>% 
+  freq(markdown = TRUE)
+
+## ---- echo = TRUE--------------------------------------------------------
+my_df <- septic_patients %>%
+  select(hospital_id) %>% 
+  freq(as.data.frame = TRUE)
+
+my_df
+
+class(my_df)
+
+## ---- echo = FALSE-------------------------------------------------------
+# this will print "2018" in 2018, and "2018-yyyy" after 2018.
+yrs <- c(2018:format(Sys.Date(), "%Y"))
+yrs <- c(min(yrs), max(yrs))
+yrs <- paste(unique(yrs), collapse = "-")
+

vignettes/freq.Rmd

@@ -0,0 +1,183 @@
+---
+title: "Creating Frequency Tables"
+author: "Matthijs S. Berends"
+output: 
+  rmarkdown::html_vignette:
+    toc: true
+vignette: >
+  %\VignetteIndexEntry{Vignette Title}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r setup, include = FALSE, results = 'markup'}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#"
+)
+library(dplyr)
+library(AMR)
+```
+
+## Introduction
+
+Frequency tables (or frequency distributions) are summaries of the distribution of values in a sample. With the `freq` function, you can create univariate frequency tables. Multiple variables will be pasted into one variable, so it forces a univariate distribution. We take the `septic_patients` dataset (included in this AMR package) as example.
+
+## Frequencies of one variable
+
+To only show and quickly review the content of one variable, you can just select this variable in various ways. Let's say we want to get the frequencies of the `sex` variable of the `septic_patients` dataset:
+```{r, echo = TRUE, results = 'hide'}
+# # just using base R
+freq(septic_patients$sex)
+
+# # using base R to select the variable and pass it on with a pipe
+septic_patients$sex %>% freq()
+
+# # do it all with pipes, using the `select` function of the dplyr package
+septic_patients %>%
+  select(sex) %>%
+  freq()
+```
+This will all lead to the following table:
+```{r, echo = TRUE}
+freq(septic_patients$sex)
+```
+This immediately shows the class of the variable, its length and availability (i.e. the amount of `NA`), the amount of unique values and (most importantly) that among septic patients men are more prevalent than women.
+
+## Frequencies of more than one variable
+
+Multiple variables will be pasted into one variable to review individual cases, keeping a univariate frequency table.
+
+For illustration, we could add some more variables to the `septic_patients` dataset to learn about bacterial properties:
+```{r, echo = TRUE, results = 'hide'}
+my_patients <- septic_patients %>% 
+  left_join_microorganisms()
+```
+Now all variables of the `microorganisms` dataset have been joined to the `septic_patients` dataset. The `microorganisms` dataset consists of the following variables:
+```{r, echo = TRUE}
+colnames(microorganisms)
+```
+
+If we compare the dimensions between the old and new dataset, we can see that these `r ncol(my_patients) - ncol(septic_patients)` variables were added:
+```{r, echo = TRUE}
+dim(septic_patients)
+dim(my_patients)
+```
+
+So now the `genus` and `species` variables are available. A frequency table of these combined variables can be created like this:
+```{r, echo = TRUE}
+my_patients %>%
+  select(genus, species) %>%
+  freq()
+```
+
+## Frequencies of numeric values
+
+Frequency tables can be created of any input.
+
+In case of numeric values (like integers, doubles, etc.) additional descriptive statistics will be calculated and shown into the header:
+
+```{r, echo = TRUE}
+# # get age distribution of unique patients
+septic_patients %>% 
+  distinct(patient_id, .keep_all = TRUE) %>% 
+  select(age) %>% 
+  freq(nmax = 5)
+```
+
+So the following properties are determined, where `NA` values are always ignored:
+
+* **Mean**
+
+* **Standard deviation**
+
+* **Coefficient of variation** (CV), the standard deviation divided by the mean
+
+* **Five numbers of Tukey** (min, Q1, median, Q3, max)
+
+* **Coefficient of quartile variation** (CQV, sometimes called coefficient of dispersion), calculated as (Q3 - Q1) / (Q3 + Q1) using quantile with `type = 6` as quantile algorithm to comply with SPSS standards
+
+* **Outliers** (total count and unique count)
+
+So for example, the above frequency table quickly shows the median age of patients being `r my_patients %>% distinct(patient_id, .keep_all = TRUE) %>% pull(age) %>% median(na.rm = TRUE)`.
+
+## Frequencies of factors
+
+Frequencies of factors will be sorted on factor level instead of item count by default. This can be changed with the `sort.count` parameter. Frequency tables of factors always show the factor level as an additional last column.
+
+`sort.count` is `TRUE` by default, except for factors. Compare this default behaviour:
+
+```{r, echo = TRUE}
+septic_patients %>%
+  select(hospital_id) %>% 
+  freq()
+```
+
+To this, where items are now sorted on item count:
+
+```{r, echo = TRUE}
+septic_patients %>%
+  select(hospital_id) %>% 
+  freq(sort.count = TRUE)
+```
+
+All classes will be printed into the header. Variables with the new `rsi` class of this AMR package are actually ordered factors and have three classes (look at `Class` in the header):
+
+```{r, echo = TRUE}
+septic_patients %>%
+  select(amox) %>% 
+  freq()
+```
+
+## Frequencies of dates
+
+Frequencies of dates will show the oldest and newest date in the data, and the amount of days between them:
+
+```{r, echo = TRUE}
+septic_patients %>%
+  select(date) %>% 
+  freq(nmax = 5)
+```
+
+## Additional parameters
+
+### Parameter `na.rm`
+With the `na.rm` parameter (defaults to `TRUE`, but they will always be shown into the header), you can include `NA` values in the frequency table:
+```{r, echo = TRUE}
+septic_patients %>%
+  select(amox) %>% 
+  freq(na.rm = FALSE)
+```
+
+### Parameter `markdown`
+The `markdown` parameter can be used in reports created with R Markdown. This will always print all rows:
+
+```{r, echo = TRUE}
+septic_patients %>%
+  select(hospital_id) %>% 
+  freq(markdown = TRUE)
+```
+
+### Parameter `as.data.frame`
+With the `as.data.frame` parameter you can assign the frequency table to an object, or just print it as a `data.frame` to the console:
+
+```{r, echo = TRUE}
+my_df <- septic_patients %>%
+  select(hospital_id) %>% 
+  freq(as.data.frame = TRUE)
+
+my_df
+
+class(my_df)
+```
+
+----
+```{r, echo = FALSE}
+# this will print "2018" in 2018, and "2018-yyyy" after 2018.
+yrs <- c(2018:format(Sys.Date(), "%Y"))
+yrs <- c(min(yrs), max(yrs))
+yrs <- paste(unique(yrs), collapse = "-")
+```
+AMR, (c) `r yrs`, `r packageDescription("AMR")$URL`
+
+Licensed under the [GNU General Public License v2.0](https://github.com/msberends/AMR/blob/master/LICENSE).