---
title: "All tables examples"
author: "Ewen Harrison"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{All tables examples}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
	collapse = TRUE,
	comment = "#>"
)
```

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


## 1 Cross tables

Two-way tables are used extensively in healthcare research, e.g. a 2x2 table comparing two factors with two levels each, or table 1 from a typical clinical study or trial

The main functions all take a `dependent` variable - the outcome - and `explanatory` variables - predictors or exposures (any number categorical or continuous variables). 

### 1.01 Default

```{r}
library(finalfit)
explanatory = c("age", "age.factor", "sex.factor", "obstruct.factor")
dependent = "perfor.factor"
colon_s %>%
  summary_factorlist(dependent, explanatory) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r"))
```

Note, chi-squared warnings will be generated when the expected count in any cell is less than 5. Fisher's exact test can be used as below, or go straight to a univariable logistic regression, e.g. `colon_s %>% finalfit(dependent, explanatory)`

### 1.02 Add or edit variable labels

```{r message=FALSE, warning=FALSE}
library(finalfit)
library(dplyr)
explanatory = c("age", "age.factor", "sex.factor", "obstruct.factor")
dependent = "perfor.factor"
colon_s %>%
	mutate(
		sex.factor = ff_label(sex.factor, "Gender")
	) %>% 
  summary_factorlist(dependent, explanatory) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r"))
```

### 1.03 P-value for hypothesis test

Defaults are chi-squared for categorical explanatory variables and an F-test for continuous (`aov`, analysis of variance). Alternatives can be specified as per below. 

```{r, warning=FALSE}
library(finalfit)
explanatory = c("age", "age.factor", "sex.factor", "obstruct.factor")
dependent = "perfor.factor"
colon_s %>%
	summary_factorlist(dependent, explanatory, p = TRUE) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r"))
```

### 1.04 With Fisher's exact test

```{r}
library(finalfit)
explanatory = c("age", "age.factor", "sex.factor", "obstruct.factor")
dependent = "perfor.factor"
colon_s %>%
  summary_factorlist(dependent, explanatory, p = TRUE, p_cat = "fisher") -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r"))
```

### 1.05 Parametric explanatory variables

Summaries for continuous explanatory variables are mean (standard deviation) with `aov` statistical test by default. 
The statistical test can be changed to the Welch t-test when there are two dependent variable levels if desired. 

```{r}
library(finalfit)
explanatory = c("age", "age.factor", "sex.factor", "obstruct.factor")
dependent = "perfor.factor"
colon_s %>%
  summary_factorlist(dependent, explanatory, p = TRUE, p_cont_para = "t.test") -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r"))
```

### 1.06 Non-parametric explanatory variables

If desired, all continuous explanatory variables can be considered non-parametric. Summaries will be median (interquartile range) and the statistical test is Kruskal-Wallis/Mann-Whitney U.

```{r, warning=FALSE}
library(finalfit)
explanatory = c("age", "nodes", "age.factor", "sex.factor", "obstruct.factor")
dependent = "perfor.factor"
colon_s %>%
	summary_factorlist(dependent, explanatory, p = TRUE, cont = "median") -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r"))
```

### 1.07 Select specific non-parametric variables

Many have asked in the past if only particular variables can be considered non-parametric. 
The argument `cont_nonpara` can take a vector (e.g. `c(1, 2, 3, 4)`) of values corresponding to the explanatory variable to specify which should be summarised as a median and be passed to a non-parametric test. 

```{r, warning=FALSE}
library(finalfit)
explanatory = c("age", "nodes", "age.factor", "sex.factor", "obstruct.factor")
dependent = "perfor.factor"
colon_s %>%
	summary_factorlist(dependent, explanatory, p = TRUE, cont_nonpara = c(2)) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r"))
```

### 1.08 Missing values for the explanatory variables

Always consider summarising missing values when describing your data.

```{r, warning=FALSE}
library(finalfit)
explanatory = c("age", "age.factor", "sex.factor", "obstruct.factor")
dependent = "perfor.factor"
colon_s %>%
	summary_factorlist(dependent, explanatory, p = TRUE, na_include = TRUE) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r"))
```

### 1.09 Pass missing values to statistical tests

This is a change from the default behaviour introduced in Finalfit 1.0.0.
Previously, when missing data was presented it was also considered as a level in the statistical test. 
This may or may not be desired. 
Control this now using `na_to_p = TRUE` to include missing data in test.
A message is produced reminding you that you are doing that. 

```{r, warning=FALSE}
library(finalfit)
explanatory = c("age", "age.factor", "sex.factor", "obstruct.factor")
dependent = "perfor.factor"
colon_s %>%
	summary_factorlist(dependent, explanatory, p = TRUE, na_include = TRUE, 
										 na_to_p = TRUE) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r"))
```

### 1.10 Row proportions (rather than column)

```{r, warning=FALSE}
library(finalfit)
explanatory = c("age", "age.factor", "sex.factor", "obstruct.factor")
dependent = "perfor.factor"
colon_s %>%
	summary_factorlist(dependent, explanatory, p = TRUE, na_include = TRUE,
										 column = FALSE) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r"))
```

### 1.11 Total column

The terms total column was introduced before this function summarised continuous variables. It would be better to be "All data" or something similar, as the continous explanatory variables a summary statistic is produced for all data. However, to keep backwards compatibility we have left it unchanged for now. For producing row totals including continous explanatory variables, see `add_row_total` below. 

```{r, warning=FALSE}
library(finalfit)
explanatory = c("age", "age.factor", "sex.factor", "obstruct.factor")
dependent = "perfor.factor"
colon_s %>%
	summary_factorlist(dependent, explanatory, p = TRUE, cont = "median", na_include = TRUE,
										 column = TRUE, total_col = TRUE) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r"))
```


### 1.12 Row totals with missing
This was introduced to deal with the problem of summarising missing data for continuous variables.
By default, it provides the total N for the variable and includes a column enumerating missing values. 

```{r message=FALSE, warning=FALSE}
library(finalfit)
explanatory = c("age", "age.factor", "sex.factor", "obstruct.factor")
dependent = "perfor.factor"
colon_s %>%
	summary_factorlist(dependent, explanatory, p = TRUE, na_include = TRUE,
										 total_col = TRUE,
										 add_row_total = TRUE) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r"))
```

### 1.13 Row totals without missing

Remove missing column.

```{r message=FALSE, warning=FALSE}
library(finalfit)
explanatory = c("age", "age.factor", "sex.factor", "obstruct.factor")
dependent = "perfor.factor"
colon_s %>%
	summary_factorlist(dependent, explanatory, p = TRUE, na_include = TRUE,
										 total_col = TRUE,
										 add_row_total = TRUE,
										 include_row_missing_col = FALSE) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r"))
```

### 1.14 Row totals with user-specified column names

```{r message=FALSE, warning=FALSE}
library(finalfit)
explanatory = c("age", "age.factor", "sex.factor", "obstruct.factor")
dependent = "perfor.factor"
colon_s %>%
	summary_factorlist(dependent, explanatory, p = TRUE,
										 total_col = TRUE,
										 add_row_total = TRUE,
										 row_totals_colname = "N (total)",
										 row_missing_colname = "N (missing)") -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r"))
```

### 1.15 Order a variable by total

This is intended for when there is only one `explanatory` variable.  

```{r, warning=FALSE}
library(finalfit)
explanatory = c("extent.factor")
dependent = "perfor.factor"
colon_s %>%
	summary_factorlist(dependent, explanatory, p = TRUE, cont = "median", na_include = TRUE,
										 column = TRUE, total_col = TRUE, orderbytotal = TRUE) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r"))
```

### 1.17 Add column totals

Column totals can be added, and by default are presented with a row percentage. 

```{r, warning=FALSE}
explanatory = c("age.factor", "sex.factor")
dependent = "rx.factor"

colon_s %>%
	summary_factorlist(dependent, explanatory, p = TRUE,
										 add_col_totals = TRUE)	-> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "l", "l", "r", "r", "r"))
```

### 1.18 Add column totals without proportion.

```{r, warning=FALSE}
explanatory = c("age.factor", "sex.factor")
dependent = "rx.factor"

colon_s %>%
	summary_factorlist(dependent, explanatory, p = TRUE,
										 add_col_totals = TRUE,
										 include_col_totals_percent = FALSE)	-> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "l", "l", "r", "r", "r"))
```


### 1.19 Add column totals with user-specified row name and prefix.

```{r, warning=FALSE}
explanatory = c("age.factor", "sex.factor")
dependent = "rx.factor"

colon_s %>%
	summary_factorlist(dependent, explanatory, p = TRUE,
										 add_col_totals = TRUE,
										 include_col_totals_percent = FALSE,
										 col_totals_rowname = "",
										 col_totals_prefix = "N=")	-> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "l", "l", "r", "r", "r"))
```

### 1.20 Label with `dependent` name

```{r, warning=FALSE}
library(finalfit)
explanatory = c("age", "age.factor", "sex.factor", "obstruct.factor")
dependent = "perfor.factor"
colon_s %>%
	summary_factorlist(dependent, explanatory, p = TRUE, cont = "median", na_include = TRUE,
										 column = TRUE, total_col = TRUE, add_dependent_label = TRUE) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r"))
```

The dependent name cannot be passed directly to the table intentionally. This is to avoid errors when code is copied and the name is not updated. Change the dependent label using the following. The prefix ("Dependent: ") and any suffix can be altered. 

```{r, warning=FALSE}
library(finalfit)
explanatory = c("age", "age.factor", "sex.factor", "obstruct.factor")
dependent = "perfor.factor"
colon_s %>%
  dplyr::mutate(
    perfor.factor = ff_label(perfor.factor, "Perforated cancer")
	) %>% 
  summary_factorlist(dependent, explanatory, p = TRUE, cont = "median", na_include = TRUE,
    column = TRUE, total_col = TRUE, add_dependent_label = TRUE, dependent_label_prefix = "") -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r"))
```

### 1.21 Dependent variable with any number of factor levels supported

```{r, warning=FALSE}
library(finalfit)
explanatory = c("age", "age.factor", "sex.factor", "obstruct.factor")
dependent = "extent.factor"
colon_s %>%
  dplyr::mutate(
    perfor.factor = ff_label(perfor.factor, "Perforated cancer")
  ) %>% 
  summary_factorlist(dependent, explanatory, p = TRUE, cont = "median", na_include = TRUE,
    column = TRUE, total_col = TRUE, add_dependent_label = TRUE, dependent_label_prefix = "") -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 1.22 Missing data in the dependent

If you are careful to count totals and you know your data, you should realise when there is data missing from the dependent, e.g.:

```{r}
explanatory = c("age", "age.factor", "sex.factor", "obstruct.factor")
dependent = "mort_5yr"
colon_s %>% 
	ff_glimpse(dependent, explanatory)
```

To make sure, a warning is generated when data are dropped from the dependent: 

```{r, warning=FALSE}
library(finalfit)
explanatory = c("age", "age.factor", "sex.factor", "obstruct.factor")
dependent = "mort_5yr"
colon_s %>%
  summary_factorlist(dependent, explanatory, p = TRUE, na_include = TRUE,
  									 total_col = TRUE,
  									 add_col_totals = TRUE, add_row_totals = TRUE) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

You may consider making the missing data explicit.

```{r, warning=FALSE}
library(finalfit)
explanatory = c("age", "age.factor", "sex.factor", "obstruct.factor")
dependent = "mort_5yr"
colon_s %>%
	mutate(
		mort_5yr = forcats::fct_explicit_na(mort_5yr)
	) %>% 
  summary_factorlist(dependent, explanatory, p = TRUE, na_include = TRUE,
  									 total_col = TRUE,
  									 add_col_totals = TRUE, add_row_totals = TRUE) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 1.23 Directly include missing data in dependent

Rather than making the data explicit in the dataset, you can use `na_include_dependent = TRUE` to do the same in `summary_factorlist()`. 

```{r, warning=FALSE}
library(finalfit)
explanatory = c("age", "age.factor", "sex.factor", "obstruct.factor")
dependent = "mort_5yr"
colon_s %>%
  summary_factorlist(dependent, explanatory, p = TRUE, 
  									 na_include = TRUE, na_include_dependent = TRUE,
  									 total_col = TRUE,
  									 add_col_totals = TRUE, add_row_totals = TRUE) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 1.24 Summarise complete cases

You may wish to see summaries for complete cases across included variables. Rather than selecting including variables and `drop_na()`, you can pass `na_complete_cases = TRUE` to `summary_factorlist()` to do the same. 

```{r, warning=FALSE}
library(finalfit)
explanatory = c("age", "age.factor", "sex.factor", "obstruct.factor")
dependent = "mort_5yr"
colon_s %>%
  summary_factorlist(dependent, explanatory, p = TRUE, 
  									 na_complete_cases = TRUE,
  									 total_col = TRUE,
  									 add_col_totals = TRUE, add_row_totals = TRUE) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```


### 1.25 Actively dropping missing data (and tidyverse functions that strip attributes)

You may wish to actively remove any rows with missing data, so you are explicit around which data are being used in models. 
Unfortunately some tidyverse functions silently remove variable attributes (labels). This is complained about then put right. But here is a workaround if it is happening with a variable you wish to use, such as `tidyr::drop_na()`. 

```{r, warning=FALSE}
library(finalfit)
explanatory = c("age", "age.factor", "sex.factor", "obstruct.factor")
dependent = "mort_5yr"
vlabels = colon_s %>% 
	extract_variable_label()

colon_s %>%
	select(dependent, explanatory) %>% 
	tidyr::drop_na() %>% # Silently removes attributes
	ff_relabel(vlabels) %>% # Relabel
  summary_factorlist(dependent, explanatory, p = TRUE, na_include = TRUE,
  									 total_col = TRUE,
  									 add_col_totals = TRUE, add_row_totals = TRUE) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```


### 1.26 Explanatory variable defaults to factor when ≤5 distinct values

```{r message=FALSE, warning=FALSE}
library(finalfit)

# Here, `extent` is a continuous variable with 4 distinct values. 
# Any continuous variable with 5 or fewer unique values is converted silently to factor 
# e.g.
explanatory = c("extent")
dependent = "mort_5yr"
colon_s %>%
  summary_factorlist(dependent, explanatory) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 1.27 Keep as continous variable when ≤5 distinct values

```{r, warning=FALSE}
library(finalfit)
explanatory = c("age", "age.factor", "sex.factor", "obstruct.factor")
dependent = "mort_5yr"
colon_s %>%
  summary_factorlist(dependent, explanatory, p = TRUE, 
  									 digits = c(1,2,3,4)) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 1.28 Stratified crosstables

I've been meaning to include support for table stratification for a while. I have delayed for a good reason. Perhaps the most straightforward way to implement stratificiation is with `dplyr::group_by()`. However, the non-standard evaluation required for multiple strata may confuse as it is not implemented else where in the package.

This translates to whether variable names are passed in quotes or not. 

Here is a solution, which while not that pretty, is effective. 

Note that `tidyverse` functions every so often start stripping labels/attributes. Hence the addition of the help function. 

```{r, warning=FALSE}
library(dplyr)
explanatory = c("age.factor", "sex.factor")
dependent = "perfor.factor"

# Pick option below
split = "rx.factor"
split = c("rx.factor", "node4.factor")

# Piped function to generate stratified crosstabs table
colon_s %>%
  group_by(!!! syms(split)) %>% # Looks awkward, but avoids unquoted var names
  group_modify(~ summary_factorlist(.x, dependent, explanatory)) %>%
  ff_stratify_helper(colon_s) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "l", "l", "r", "r", "r"))
```

### 1.29 Digits / decimal places

```{r, warning=FALSE}
explanatory = c("age", "age.factor", "sex.factor", "obstruct.factor")
dependent = "perfor.factor"
colon_s %>%
  summary_factorlist(dependent, explanatory, p = TRUE, digits = c(1,2,3,4)) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```


## 2 Model tables with `finalfit()`

### 2.01 Default

Logistic regression first.

```{r, warning=FALSE, message=FALSE}
library(finalfit)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"
colon_s %>%
	finalfit(dependent, explanatory) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 2.02 Hide reference levels

Most appropriate when all explanatory variables are continuous or well-known binary variables, such as sex. 

```{r, warning=FALSE, message=FALSE}
library(finalfit)
explanatory = c("age", "sex.factor")
dependent = "mort_5yr"
colon_s %>%
	finalfit(dependent, explanatory, add_dependent_label = FALSE) %>% 
	ff_remove_ref() %>% 
	dependent_label(colon_s, dependent)-> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 2.03 Model metrics

```{r, warning=FALSE, message=FALSE}
library(finalfit)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"
colon_s %>%
	finalfit(dependent, explanatory, metrics = TRUE) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t[[1]], row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
kable(t[[2]], row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"), col.names = "")
```

### 2.04 Model metrics can be applied to all supported base models

```{r, warning=FALSE, message=FALSE}
library(finalfit)
glm(mort_5yr ~ age.factor + sex.factor + obstruct.factor + perfor.factor, data = colon_s, family = "binomial") %>% 
	ff_metrics() -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"), col.names = "")
```

### 2.05 Reduced model

```{r, warning=FALSE, message=FALSE}
library(finalfit)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
explanatory_multi = c("age.factor", "obstruct.factor")
dependent = "mort_5yr"
colon_s %>%
	finalfit(dependent, explanatory, explanatory_multi) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 2.06 Include all models

```{r, warning=FALSE, message=FALSE}
library(finalfit)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
explanatory_multi = c("age.factor", "obstruct.factor")
dependent = "mort_5yr"
colon_s %>%
	finalfit(dependent, explanatory, explanatory_multi, metrics = TRUE, keep_models = TRUE) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t[[1]], row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
kable(t[[2]], row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"), col.names = "")
```

### 2.06 Interactions

Interactions can be specified in the normal way. Formatting the output is trickier. At the moment, we have left the default model output. This can be adjusted as necessary.

```{r, warning=FALSE, message=FALSE}
library(finalfit)
explanatory = c("age.factor*sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"
colon_s %>%
	finalfit(dependent, explanatory) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 2.07 Interactions: create interaction variable with two factors

```{r, warning=FALSE, message=FALSE}
library(finalfit)
#explanatory = c("age.factor*sex.factor", "obstruct.factor", "perfor.factor")
explanatory = c("obstruct.factor", "perfor.factor")
dependent = "mort_5yr"
colon_s %>%
	ff_interaction(age.factor, sex.factor) %>% 
	finalfit(dependent, c(explanatory, "age.factor__sex.factor")) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 2.08 Dependent name

The dependent name cannot be specified directly intentionally. This is to prevent errors when copying code. Re-label using `ff_label()`. The dependent prefix and suffix can also be altered. 

```{r, warning=FALSE, message=FALSE}
library(finalfit)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"
colon_s %>%
	dplyr::mutate(
		mort_5yr = ff_label(mort_5yr, "5-year mortality")
	) %>% 
	finalfit(dependent, explanatory, dependent_label_prefix = "",
					 dependent_label_suffix = " (full model)") -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 2.09 Estimate name

```{r, warning=FALSE, message=FALSE}
library(finalfit)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"
colon_s %>%
	finalfit(dependent, explanatory, estimate_name = "Odds ratio") -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 2.10 Digits / decimal places

Number of digits to round to regression results. (1) estimate, (2) confidence interval limits, (3) p-value. Default is c(2,2,3). Trailing zeros are preserved. Number of decimal places for counts and mean (sd) / median (IQR) not currently supported. Defaults are senisble :)

```{r, warning=FALSE, message=FALSE}
library(finalfit)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"
colon_s %>%
	finalfit(dependent, explanatory, digits = c(3,3,4)) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 2.11 Confidence interval type

One of `c("profile", "default")` for GLM models (`confint.glm()`). Note, a little awkwardly, the 'default' setting is `profile`, rather than `default`. Profile levels are probably a little more accurate. Only go to default if taking a significant length of time for profile, i.e. data is greater than hundreds of thousands of lines.

For glmer/lmer models (`confint.merMod()`), `c("profile", "Wald", "boot")`. Not implemented for `lm()`, `coxph()` or `coxphlist`, which use default.

```{r, warning=FALSE, message=FALSE}
library(finalfit)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"
colon_s %>%
	finalfit(dependent, explanatory, confint_type = "default") -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 2.12 Confidence interval level

Probably never change this :) Note, the p-value is intentionally not included for confidence levels other than 95% to avoid confusion.

```{r, warning=FALSE, message=FALSE}
library(finalfit)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"
colon_s %>%
	finalfit(dependent, explanatory, confint_level = 0.90) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 2.13 Confidence interval separation

Some like to avoid the hyphen so as not to confuse with minus sign. Obviously not an issue in logistic regression.   

```{r, warning=FALSE, message=FALSE}
library(finalfit)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"
colon_s %>%
	finalfit(dependent, explanatory, confint_sep = " to ") -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 2.14 Remove p-value

```{r, warning=FALSE, message=FALSE}
library(finalfit)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"
colon_s %>%
	finalfit(dependent, explanatory) %>% 
	ff_remove_p() -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 2.15 Mixed effects random-intercept model

At its simplest, a random-intercept model can be specified using a single quoted variable. In this example, it is the equivalent of quoting `random_effect = "(1 | hospital)"`. 

```{r, warning=FALSE, message=FALSE}
library(finalfit)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"
random_effect = "hospital"
colon_s %>%
	finalfit(dependent, explanatory, random_effect = random_effect,
					 dependent_label_suffix = " (random intercept)") -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 2.16 Mixed effects random-slope model

In the example below, allow the effect of age on outcome to vary by hospital. Note, this specification must have parentheses included.

```{r, warning=FALSE, message=FALSE}
library(finalfit)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"
random_effect = "(age.factor | hospital)"
colon_s %>%
	finalfit(dependent, explanatory, random_effect = random_effect,
					 dependent_label_suffix = " (random slope: age)") -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 2.17 Mixed effects random-slope model directly from `lme4`

Clearly, as models get more complex, parameters such as random effect group variances may require to be extracted directly from model outputs. 

```{r eval=FALSE, message=FALSE, warning=FALSE, include=TRUE}
library(finalfit)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"
random_effect = "(age.factor | hospital)"
colon_s %>% 
	lme4::glmer(mort_5yr ~ age.factor + (age.factor | hospital), family = "binomial", data = .) %>% 
	broom::tidy() -> t
```

```{r, echo=FALSE, eval=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 2.18 Exclude all missing data in final model from univariable analyses 

This can be useful if you want the numbers in the final table to match the final multivariable model. However, be careful to include a full explanation of this in the methods and the reason for exluding the missing data. 

```{r, warning=FALSE, message=FALSE}
library(finalfit)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = 'mort_5yr'
colon_s %>%
	dplyr::select(explanatory, dependent) %>%
	na.omit() %>%
	finalfit(dependent, explanatory) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 2.19 Linear regression

```{r, warning=FALSE, message=FALSE}
library(finalfit)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = 'nodes'
colon_s %>%
	finalfit(dependent, explanatory) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 2.20 Mixed effects random-intercept linear regression

```{r, warning=FALSE, message=FALSE}
library(finalfit)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "nodes"
random_effect = "hospital"
colon_s %>%
	finalfit(dependent, explanatory, random_effect = random_effect,
					 dependent_label_suffix = " (random intercept)") -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 2.21 Mixed effects random-slope linear regression

```{r, warning=FALSE, message=FALSE}
library(finalfit)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "nodes"
random_effect = "(age.factor | hospital)"
colon_s %>%
	finalfit(dependent, explanatory, random_effect = random_effect,
					 dependent_label_suffix = " (random slope: age)") -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 2.22 Cox proportional hazards model (survival / time to event)

```{r, warning=FALSE, message=FALSE}
library(finalfit)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "Surv(time, status)"
colon_s %>%
	finalfit(dependent, explanatory) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 2.23 Cox proportional hazards model: change dependent label

As above, the dependent label cannot be specfied directly in the model to avoid errors. However, in survival modelling the surivial object specification can be long or awkward. Therefore, here is the work around. 

```{r, warning=FALSE, message=FALSE}
library(finalfit)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "Surv(time, status)"
colon_s %>%
	finalfit(dependent, explanatory, add_dependent_label = FALSE) %>% 
	dplyr::rename("Overall survival" = label) %>% 
	dplyr::rename(" " = levels)	-> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

## 3 Model tables manually using `ff_merge()`

### 3.1 Basic table

Note `summary_factorlist()` needs argument, `fit_id = TRUE`. 

```{r, warning=FALSE, message=FALSE}
library(finalfit)
library(dplyr)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"

## Crosstable
colon_s %>%
	summary_factorlist(dependent, explanatory, fit_id=TRUE) -> table_1

## Univariable
colon_s %>%
	glmuni(dependent, explanatory) %>%
	fit2df(estimate_suffix=" (univariable)") -> table_2

## Merge

table_1 %>% 
	ff_merge(table_2) %>% 
	select(-c(fit_id, index)) %>% 
	dependent_label(colon_s, dependent)-> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 3.2 Complex table (all in single pipe)

```{r, warning=FALSE, message=FALSE}
library(finalfit)
library(dplyr)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
random_effect = "hospital"
dependent = "mort_5yr"

# All in one pipe

colon_s %>%
	## Crosstable
	summary_factorlist(dependent, explanatory, fit_id=TRUE)  %>% 
	
	## Add univariable
	ff_merge(
		glmuni(colon_s, dependent, explanatory) %>%
			fit2df(estimate_suffix=" (univariable)")
	) %>% 
	
	## Add multivariable
	ff_merge(
		glmmulti(colon_s, dependent, explanatory) %>%
			fit2df(estimate_suffix=" (multivariable)")
	) %>% 
	
	## Add mixed effects
	ff_merge(
		glmmixed(colon_s, dependent, explanatory, random_effect) %>%
			fit2df(estimate_suffix=" (multilevel)"),
		last_merge = TRUE
	) %>% 
	dependent_label(colon_s, dependent) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 3.3 Other GLM models

#### Poisson

```{r, warning=FALSE, message=FALSE}
library(finalfit)
library(dplyr)

## Dobson (1990) Page 93: Randomized Controlled Trial :
counts = c(18,17,15,20,10,20,25,13,12)
outcome = gl(3,1,9)
treatment = gl(3,3)
d.AD <- data.frame(treatment, outcome, counts)

dependent = "counts"
explanatory = c("outcome", "treatment")

fit_uni = d.AD %>% 
	glmuni(dependent, explanatory, family = poisson) %>% 
	fit2df(estimate_name = "Rate ratio (univariable)")

fit_multi = d.AD %>% 
	glmmulti(dependent, explanatory, family = poisson) %>% 
	fit2df(estimate_name = "Rate ratio (multivariable)")

# All in one pipe
d.AD %>%
	## Crosstable
	summary_factorlist(dependent, explanatory, cont = "median", fit_id=TRUE)  %>% 
	
	## Add univariable
	ff_merge(fit_uni, estimate_name = "Rate ratio") %>% 
	
	## Add multivariable
	ff_merge(fit_multi, estimate_name = "Rate ratio",
					 last_merge = TRUE) %>% 
	dependent_label(d.AD, dependent) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

#### Gamma

```{r, warning=FALSE, message=FALSE}
library(finalfit)
library(dplyr)

# A Gamma example, from McCullagh & Nelder (1989, pp. 300-2)
clotting <- data.frame(
    u = c(5,10,15,20,30,40,60,80,100),
    lot1 = c(118,58,42,35,27,25,21,19,18),
    lot2 = c(69,35,26,21,18,16,13,12,12))

dependent = "lot1"
explanatory = "log(u)"

fit_uni = clotting %>% 
	glmuni(dependent, explanatory, family = Gamma) %>% 
	fit2df(estimate_name = "Coefficient", exp = FALSE, digits = c(3,3,4))

# All in one pipe
clotting %>%
	## Crosstable
	summary_factorlist(dependent, explanatory, cont = "median", fit_id=TRUE)  %>% 
	
	## Add fit
	ff_merge(fit_uni, last_merge = TRUE) %>% 
	dependent_label(colon_s, dependent) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 3.4 Weighted regression

```{r, warning=FALSE, message=FALSE}
library(finalfit)
library(dplyr)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"
weights = runif(dim(colon_s)[1]) # random just for example

# All in one pipe
colon_s %>%
	## Crosstable
	summary_factorlist(dependent, explanatory, fit_id=TRUE)  %>% 
	
	## Add univariable
	ff_merge(
		glmuni(colon_s, dependent, explanatory, weights = weights, family = quasibinomial) %>%
			fit2df(estimate_suffix=" (univariable)")
	) %>% 
	
	## Add multivariable
	ff_merge(
		glmmulti(colon_s, dependent, explanatory, weights = weights, family = quasibinomial) %>%
			fit2df(estimate_suffix=" (multivariable)"),
		last_merge = TRUE
	) %>% 
	dependent_label(colon_s, dependent) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 3.5 Using base R functions

Note `ff_formula()` convenience function to make multivariable formula (`y ~ x1 + x2 + x3` etc.) from a `dependent` and `explanatory` vector of names. 

```{r, warning=FALSE, message=FALSE}
library(finalfit)
library(dplyr)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"

# All in one pipe

colon_s %>%
	## Crosstable
	summary_factorlist(dependent, explanatory, fit_id=TRUE)  %>% 
	
	## Add univariable
	ff_merge(
		glmuni(colon_s, dependent, explanatory) %>%
			fit2df(estimate_suffix=" (univariable)")
	) %>% 
	
	## Add multivariable
	ff_merge(
		glm(
			ff_formula(dependent, explanatory), data = colon_s, family = "binomial", weights = NULL
		) %>%
			fit2df(estimate_suffix=" (multivariable)"),
		last_merge = TRUE
	) %>% 
	dependent_label(colon_s, dependent) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 3.6 Edit table rows

This can be done as any dataframe would be edited. 

```{r, warning=FALSE, message=FALSE}
library(finalfit)
library(dplyr)
explanatory = c("age.factor*sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"

# Run model for term test
fit <- glm(
	ff_formula(dependent, explanatory), 
	data=colon_s, family = binomial
)

# Not run
#term_test <- survey::regTermTest(fit, "age.factor:sex.factor")

# Run final table with results of term test
colon_s %>%
	finalfit(dependent, explanatory) %>%
	rbind(c(
		"age.factor:sex.factor (overall)",
		"Interaction",
		"-",
		"-",
		"-",
		paste0("p = 0.775")
	))-> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r"))
```

### 3.7 Base model + individual explanatory variables

This was an email enquiry about how to build on a base model. The example request was in a survival context.

This has been updated August 2019. We have left the original example of building the table from scratch as a comparison.

`ff_permute()` allows combinations of variables to be built on a base model. See options on help page to,

* include the base model and/or the full model,
* present the permuted variables at the top or bottom of the table,
* produce separate model tables, or the default which is a single table. 

```{r, warning=FALSE, message=FALSE}
library(dplyr)
mydata = colon_s
explanatory_base = c("age.factor", "sex.factor")
explanatory_permute = c("obstruct.factor", "perfor.factor", "node4.factor")
dependent = "Surv(time, status)"

mydata %>% 
	ff_permute(dependent, explanatory_base, explanatory_permute) %>% 
	rename("Overall survival" = `Dependent: Surv(time, status)`, # optional tidying
				 `n (%)` = "all") -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r", "r", "r"))
```

```{r, warning=FALSE, message=FALSE}
library(finalfit)
library(dplyr)

mydata = colon_s
base_explanatory = c("age.factor", "sex.factor")
explanatory = c("obstruct.factor", "perfor.factor", "node4.factor")
dependent = "Surv(time, status)"

mydata %>%
	# Counts
	summary_factorlist(dependent, c(base_explanatory,
																	explanatory),
										 column = TRUE,
										 fit_id = TRUE) %>% 
	
	# Univariable
	ff_merge(
		coxphuni(mydata, dependent, c(base_explanatory, explanatory)) %>% 
			fit2df(estimate_suffix = " (Univariable)")
	) %>% 
	
	# Base
	ff_merge(
		coxphmulti(mydata, dependent, base_explanatory) %>% 
			fit2df(estimate_suffix = " (Base model)")
	) %>% 
	
	# Model 1
	ff_merge(
		coxphmulti(mydata, dependent, c(base_explanatory, explanatory[1])) %>% 
			fit2df(estimate_suffix = " (Model 1)")
	) %>% 
	
	# Model 2
	ff_merge(
		coxphmulti(mydata, dependent, c(base_explanatory, explanatory[2])) %>% 
			fit2df(estimate_suffix = " (Model 2)")
	) %>% 
	
	# Model 3
	ff_merge(
		coxphmulti(mydata, dependent, c(base_explanatory, explanatory[3])) %>% 
			fit2df(estimate_suffix = " (Model 3)")
	) %>% 
	
	# Full
	ff_merge(
		coxphmulti(mydata, dependent, c(base_explanatory, explanatory)) %>% 
			fit2df(estimate_suffix = " (Full)"),
		last_merge = TRUE
	) %>% 
	
	# Tidy-up
	rename("Overall survival" = label) %>% 
	rename(" " = levels) %>% 
	rename(`n (%)` = all) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r", "r", "r"))
```

## 4 Support for complex survey structures via `library(survey)`

### 4.1 Linear regression

Examples taken from `survey::svyglm()` help page.

```{r, warning=FALSE, message=FALSE}
library(survey)
library(dplyr)

data(api)
dependent = "api00"
explanatory = c("ell", "meals", "mobility")

# Label data frame
apistrat = apistrat %>%
  mutate(
  api00 = ff_label(api00, "API in 2000 (api00)"),
  ell = ff_label(ell, "English language learners (percent)(ell)"),
  meals = ff_label(meals, "Meals eligible (percent)(meals)"),
  mobility = ff_label(mobility, "First year at the school (percent)(mobility)"),
  sch.wide = ff_label(sch.wide, "School-wide target met (sch.wide)")
  )

# Linear example
dependent = "api00"
explanatory = c("ell", "meals", "mobility")

# Stratified design
dstrat = svydesign(id=~1,strata=~stype, weights=~pw, data=apistrat, fpc=~fpc)

# Univariable fit
fit_uni = dstrat %>%
  svyglmuni(dependent, explanatory) %>%
  fit2df(estimate_suffix = " (univariable)")

# Multivariable fit
fit_multi = dstrat %>%
  svyglmmulti(dependent, explanatory) %>%
  fit2df(estimate_suffix = " (multivariable)")

# Pipe together
apistrat %>%
  summary_factorlist(dependent, explanatory, fit_id = TRUE) %>%
  ff_merge(fit_uni) %>%
  ff_merge(fit_multi, last_merge = TRUE) %>%
  dependent_label(apistrat, dependent) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r", "r", "r"))
```

### 4.2 Binomial example

Note model family needs specified and exponentiation set to `TRUE` if desired.

```{r, warning=FALSE, message=FALSE}
library(survey)
library(dplyr)

data(api)
dependent = "sch.wide"
explanatory = c("ell", "meals", "mobility")

# Label data frame
apistrat = apistrat %>%
  mutate(
  api00 = ff_label(api00, "API in 2000 (api00)"),
  ell = ff_label(ell, "English language learners (percent)(ell)"),
  meals = ff_label(meals, "Meals eligible (percent)(meals)"),
  mobility = ff_label(mobility, "First year at the school (percent)(mobility)"),
  sch.wide = ff_label(sch.wide, "School-wide target met (sch.wide)")
  )
  
# Univariable fit
fit_uni = dstrat %>%
  svyglmuni(dependent, explanatory, family = "quasibinomial") %>%
  fit2df(exp = TRUE, estimate_name = "OR", estimate_suffix = " (univariable)")

# Multivariable fit
fit_multi = dstrat %>%
  svyglmmulti(dependent, explanatory, family = "quasibinomial") %>%
  fit2df(exp = TRUE, estimate_name = "OR", estimate_suffix = " (multivariable)")

# Pipe together
apistrat %>%
  summary_factorlist(dependent, explanatory, fit_id = TRUE) %>%
  ff_merge(fit_uni) %>%
  ff_merge(fit_multi, last_merge = TRUE) %>%
  dependent_label(apistrat, dependent) -> t
```

```{r, echo=FALSE}
library(knitr)
kable(t, row.names=FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r", "r", "r"))
```
