Package 'finalfit'

Description

Quickly create elegant final results tables and plots when modelling.

finalfit model wrappers

glmuni, glmmulti, glmmulti_boot, glmmixed, lmuni, lmmulti, lmmixed, coxphuni, coxphmulti, crruni, crrmulti, svyglmuni, svyglmmulti.

finalfit model extractor

Generic: fit2df

Methods (not called directly): fit2df.glm, fit2df.glmlist, fit2df.glmboot, fit2df.lm, fit2df.lmlist, fit2df.glmerMod, fit2df.lmerMod, fit2df.coxph, fit2df.coxphlist, fit2df.crr, fit2df.crrlist, fit2df.stanfit.

finalfit all-in-one function

Generic: finalfit. finalfit_permute.

Methods (not called directly): finalfit.glm, finalfit.lm, finalfit.coxph.

finalfit plotting functions

coefficient_plot, or_plot, hr_plot, surv_plot, ff_plot.

finalfit helper functions

ff_glimpse, ff_label, ff_merge, ff_interaction.

finalfit prediction functions

boot_predict, finalfit_newdata.

Methods (not called directly): boot_compare.

finalfit missing data functions

missing_glimpse, missing_pattern, missing_compare, missing_plot, missing_pairs.

Description

Not usually called directly. Included in boot_predict. Usually used in combination with A function that takes the output from summary_factorlist(..., fit_id=TRUE) and merges with any number of model dataframes, usually produced with a model wrapper followed by the fit2df() function (see examples).

Usage

boot_compare(
  bs.out,
  confint_level = 0.95,
  confint_sep = " to ",
  comparison = "difference",
  condense = TRUE,
  compare_name = NULL,
  digits = c(2, 3),
  ref_symbol = 1
)

Arguments

Value

A dataframe of first differences or ratios for boostrapped distributions of a metric of interest.

finalfit predict functions

See Also

boot_predict finalfit_newdata

Examples

# See boot_predict.

Description

Generate model predictions against a specified set of explanatory levels with bootstrapped confidence intervals. Add a comparison by difference or ratio of the first row of newdata with all subsequent rows.

Usage

boot_predict(
  fit,
  newdata,
  type = "response",
  R = 100,
  estimate_name = NULL,
  confint_level = 0.95,
  conf.method = "perc",
  confint_sep = " to ",
  condense = TRUE,
  boot_compare = TRUE,
  compare_name = NULL,
  comparison = "difference",
  ref_symbol = "-",
  digits = c(2, 3)
)

Arguments

Details

To use this, first generate newdata for specified levels of explanatory variables using finalfit_newdata. Pass model objects from lm, glm, lmmulti, and glmmulti. The comparison metrics are made on individual bootstrap samples distribution returned as a mean with confidence intervals. A p-value is generated on the proportion of values on the other side of the null from the mean, e.g. for a ratio greater than 1.0, p is the number of bootstrapped predictions under 1.0, multiplied by two so is two-sided.

Value

A dataframe of predicted values and confidence intervals, with the option of including a comparison of difference between first row and all subsequent rows of newdata.

See Also

finalfit_newdata

Examples

library(finalfit)
library(dplyr)

# Predict probability of death across combinations of factor levels
explanatory = c("age.factor", "extent.factor", "perfor.factor")
dependent = 'mort_5yr'

# Generate combination of factor levels
colon_s %>%
  finalfit_newdata(explanatory = explanatory, newdata = list(
    c("<40 years",  "Submucosa", "No"),
    c("<40 years", "Submucosa", "Yes"),
    c("<40 years", "Adjacent structures", "No"),
    c("<40 years", "Adjacent structures", "Yes")
   )) -> newdata

# Run simulation
colon_s %>%
  glmmulti(dependent, explanatory) %>%
  boot_predict(newdata, estimate_name = "Predicted probability of death",
    compare_name = "Absolute risk difference", R=100, digits = c(2,3))

# Plotting
explanatory = c("nodes", "extent.factor", "perfor.factor")
colon_s %>%
  finalfit_newdata(explanatory = explanatory, rowwise = FALSE, newdata = list(
  rep(seq(0, 30), 4),
  c(rep("Muscle", 62), rep("Adjacent structures", 62)),
  c(rep("No", 31), rep("Yes", 31), rep("No", 31), rep("Yes", 31))
)) -> newdata

colon_s %>%
  glmmulti(dependent, explanatory) %>%
  boot_predict(newdata, boot_compare = FALSE, R=100, condense=FALSE) -> plot

  library(ggplot2)
  theme_set(theme_bw())
  plot %>%
    ggplot(aes(x = nodes, y = estimate, ymin = estimate_conf.low,
        ymax = estimate_conf.high, fill=extent.factor))+
      geom_line(aes(colour = extent.factor))+
      geom_ribbon(alpha=0.1)+
      facet_grid(.~perfor.factor)+
      xlab("Number of postive lymph nodes")+
      ylab("Probability of death")+
      labs(fill = "Extent of tumour", colour = "Extent of tumour")+
      ggtitle("Probability of death by lymph node count")

Description

This was written a few days after the retraction of a paper in JAMA due to an error in recoding the treatment variable (https://jamanetwork.com/journals/jama/fullarticle/2752474). This takes a data frame or tibble, fuzzy matches variable names, and produces crosstables of all matched variables. A visual inspection should reveal any miscoding.

Usage

check_recode(
  .data,
  dependent = NULL,
  explanatory = NULL,
  include_numerics = TRUE,
  ...
)

Arguments

Value

List of length two. The first is an index of variable combiations. The second is a nested list of crosstables as tibbles.

Examples

library(dplyr)
data(colon_s)
colon_s_small = colon_s %>%
  select(-id, -rx, -rx.factor) %>%
  mutate(
    age.factor2 = forcats::fct_collapse(age.factor,
      "<60 years" = c("<40 years", "40-59 years")),
    sex.factor2 = forcats::fct_recode(sex.factor,
    # Intentional miscode
      "F" = "Male",
      "M" = "Female")
  )

# Check
colon_s_small %>%
  check_recode(include_numerics = FALSE)

out = colon_s_small %>%
  select(-extent, -extent.factor,-time, -time.years) %>%
  check_recode()
out

# Select a tibble and expand
out$counts[[9]]
# Note this variable (node4) appears miscoded in original dataset survival::colon.

# Choose to only include variables that you actually use. 
# This uses standard Finalfit grammar. 
dependent = "mort_5yr"
explanatory = c("age.factor2", "sex.factor2")
colon_s_small %>% 
  check_recode(dependent, explanatory)

Description

Produce a coefficient and plot from a lm() model.

Usage

coefficient_plot(
  .data,
  dependent,
  explanatory,
  random_effect = NULL,
  factorlist = NULL,
  lmfit = NULL,
  confint_type = "default",
  confint_level = 0.95,
  remove_ref = FALSE,
  breaks = NULL,
  column_space = c(-0.5, -0.1, 0.5),
  dependent_label = NULL,
  prefix = "",
  suffix = NULL,
  table_text_size = 4,
  title_text_size = 13,
  plot_opts = NULL,
  table_opts = NULL,
  ...
)

Arguments

Value

Returns a table and plot produced in ggplot2.

See Also

Other finalfit plot functions: ff_plot(), hr_plot(), or_plot(), surv_plot()

Examples

library(finalfit)
library(ggplot2)

# Coefficient plot
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "nodes"
colon_s %>%
  coefficient_plot(dependent, explanatory)

colon_s %>%
  coefficient_plot(dependent, explanatory, table_text_size=4, title_text_size=14,
    plot_opts=list(xlab("Beta, 95% CI"), theme(axis.title = element_text(size=12))))

Description

This is a modified version of survival::colon.These are data from one of the first successful trials of adjuvant chemotherapy for colon cancer. Levamisole is a low-toxicity compound previously used to treat worm infestations in animals; 5-FU is a moderately toxic (as these things go) chemotherapy agent. There are two records per person, one for recurrence and one for death

Usage

data(colon_s)

Format

A data frame with 929 rows and 33 variables

Source

colon

Description

Using finalfit conventions, produces multivariable Cox Proportional Hazard regression models for a set of explanatory variables against a survival object.

Usage

coxphmulti(.data, dependent, explanatory, ...)

Arguments

Details

Uses coxph with finalfit modelling conventions. Output can be passed to fit2df.

Value

A multivariable coxph fitted model output. Output is of class coxph.

See Also

fit2df, finalfit_merge

Other finalfit model wrappers: coxphuni(), crrmulti(), crruni(), glmmixed(), glmmulti_boot(), glmmulti(), glmuni(), lmmixed(), lmmulti(), lmuni(), svyglmmulti(), svyglmuni()

Examples

# Cox Proportional Hazards multivariable analysis.
library(finalfit)
library(dplyr)

explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "Surv(time, status)"
colon_s %>%
	coxphmulti(dependent, explanatory) %>%
	fit2df()

Description

Using finalfit conventions, produces multiple univariable Cox Proportional Hazard regression models for a set of explanatory variables against a survival object.

Usage

coxphuni(.data, dependent, explanatory)

Arguments

Details

Uses coxph with finalfit modelling conventions. Output can be passed to fit2df.

Value

A list of univariable coxph fitted model outputs. Output is of class coxphlist.

See Also

fit2df, finalfit_merge

Other finalfit model wrappers: coxphmulti(), crrmulti(), crruni(), glmmixed(), glmmulti_boot(), glmmulti(), glmuni(), lmmixed(), lmmulti(), lmuni(), svyglmmulti(), svyglmuni()

Examples

# Cox Proportional Hazards univariable analysis.
library(finalfit)
library(dplyr)

explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "Surv(time, status)"
colon_s %>%
	coxphuni(dependent, explanatory) %>%
	fit2df()

Description

Using finalfit conventions, produces multivariable Competing Risks Regression models for a set of explanatory variables.

Usage

crrmulti(.data, dependent, explanatory, ...)

Arguments

Details

Uses crr with finalfit modelling conventions. Output can be passed to fit2df.

Value

A multivariable crr fitted model class crr.

See Also

fit2df, finalfit_merge

Other finalfit model wrappers: coxphmulti(), coxphuni(), crruni(), glmmixed(), glmmulti_boot(), glmmulti(), glmuni(), lmmixed(), lmmulti(), lmuni(), svyglmmulti(), svyglmuni()

Examples

library(dplyr)
melanoma = boot::melanoma
melanoma = melanoma %>%
  mutate(
    # Cox PH to determine cause-specific hazards
    status_coxph = ifelse(status == 2, 0, # "still alive"
      ifelse(status == 1, 1, # "died of melanoma"
        0)), # "died of other causes is censored"
        
    # Fine and Gray to determine subdistribution hazards
    status_crr = ifelse(status == 2, 0, # "still alive"
      ifelse(status == 1, 1, # "died of melanoma"
        2)), # "died of other causes"
    sex = factor(sex),
    ulcer = factor(ulcer)
  )

dependent_coxph = c("Surv(time, status_coxph)")
dependent_crr = c("Surv(time, status_crr)")
explanatory = c("sex", "age", "ulcer")

# Create single well-formatted table
melanoma %>%
  summary_factorlist(dependent_crr, explanatory, column = TRUE, fit_id = TRUE) %>%
  ff_merge(
    melanoma %>%
      coxphmulti(dependent_coxph, explanatory) %>%
      fit2df(estimate_suffix = " (Cox PH multivariable)")
    ) %>%
  ff_merge(
    melanoma %>%
      crrmulti(dependent_crr, explanatory) %>%
      fit2df(estimate_suffix = " (competing risks multivariable)")
    ) %>%
  select(-fit_id, -index) %>%
  dependent_label(melanoma, dependent_crr)

Description

Using finalfit conventions, produces univariable Competing Risks Regression models for a set of explanatory variables.

Usage

crruni(.data, dependent, explanatory, ...)

Arguments

Details

Uses crr with finalfit modelling conventions. Output can be passed to fit2df.

Value

A list of univariable crr fitted models class crrlist.

See Also

fit2df, finalfit_merge

Other finalfit model wrappers: coxphmulti(), coxphuni(), crrmulti(), glmmixed(), glmmulti_boot(), glmmulti(), glmuni(), lmmixed(), lmmulti(), lmuni(), svyglmmulti(), svyglmuni()

Examples

library(dplyr)
melanoma = boot::melanoma
melanoma = melanoma %>%
  mutate(
    # Cox PH to determine cause-specific hazards
    status_coxph = ifelse(status == 2, 0, # "still alive"
      ifelse(status == 1, 1, # "died of melanoma"
        0)), # "died of other causes is censored"
        
    # Fine and Gray to determine subdistribution hazards
    status_crr = ifelse(status == 2, 0, # "still alive"
      ifelse(status == 1, 1, # "died of melanoma"
        2)), # "died of other causes"
    sex = factor(sex),
    ulcer = factor(ulcer)
  )

dependent_coxph = c("Surv(time, status_coxph)")
dependent_crr = c("Surv(time, status_crr)")
explanatory = c("sex", "age", "ulcer")

# Create single well-formatted table
melanoma %>%
  summary_factorlist(dependent_crr, explanatory, column = TRUE, fit_id = TRUE) %>%
  ff_merge(
    melanoma %>%
      coxphmulti(dependent_coxph, explanatory) %>%
      fit2df(estimate_suffix = " (Cox PH multivariable)")
    ) %>%
  ff_merge(
    melanoma %>%
      crrmulti(dependent_crr, explanatory) %>%
      fit2df(estimate_suffix = " (competing risks multivariable)")
    ) %>%
  select(-fit_id, -index) %>%
  dependent_label(melanoma, dependent_crr)

Description

Can be add dependent label to final results dataframe.

Usage

dependent_label(df.out, .data, dependent, prefix = "Dependent: ", suffix = "")

Arguments

Value

Returns the label for the dependent variable, if specified.

Examples

library(dplyr)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
explanatory_multi = c("age.factor", "obstruct.factor")
random_effect = "hospital"
dependent = 'mort_5yr'

# Separate tables
colon_s %>%
	summary_factorlist(dependent, explanatory, fit_id=TRUE) -> example.summary

colon_s %>%
	glmuni(dependent, explanatory) %>%
	fit2df(estimate_suffix=" (univariable)") -> example.univariable

colon_s %>%
	 glmmulti(dependent, explanatory) %>%
	 fit2df(estimate_suffix=" (multivariable)") -> example.multivariable

colon_s %>%
  glmmixed(dependent, explanatory, random_effect) %>%
	 fit2df(estimate_suffix=" (multilevel") -> example.multilevel

# Pipe together
example.summary %>%
  finalfit_merge(example.univariable) %>%
  finalfit_merge(example.multivariable) %>%
	 finalfit_merge(example.multilevel) %>%
	 select(-c(fit_id, index)) %>%
	 dependent_label(colon_s, dependent) -> example.final
  example.final

Description

Variable labels can be created using ff_label. Some functions strip variable labels (variable attributes), e.g. forcats::fct_recode. Use this function to create a vector of variable labels from a data frame. Then use ff_relabel to relabel variables in data frame.

Usage

extract_variable_label(.data)

Arguments

Examples

colon_s %>%
  extract_variable_label

Description

Add column totals to summary_factorlist() output

Usage

ff_column_totals(
  df.in,
  .data,
  dependent,
  na_include_dependent = FALSE,
  percent = TRUE,
  digits = c(1, 0),
  label = NULL,
  prefix = "",
  weights = NULL
)

finalfit_column_totals(
  df.in,
  .data,
  dependent,
  na_include_dependent = FALSE,
  percent = TRUE,
  digits = c(1, 0),
  label = NULL,
  prefix = "",
  weights = NULL
)

Arguments

Value

Data frame.

Examples

explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = 'mort_5yr'
colon_s %>%
 summary_factorlist(dependent, explanatory) %>%
 ff_column_totals(colon_s, dependent)

# Ensure works with missing data in dependent
colon_s = colon_s %>%
 dplyr::mutate(
  mort_5yr = forcats::fct_na_value_to_level(mort_5yr, level = "(Missing)")
 )
 colon_s %>%
 summary_factorlist(dependent, explanatory) %>%
 ff_column_totals(colon_s, dependent)

Description

When producing conditional estimates from a regression model, it is often useful to set variables not of interest to their mode for factors and mean or median for numerics when creating the newdata object, and combine these with all levels for factors of interest.

Usage

ff_expand(.data, ..., cont = "mean")

finalfit_expand(.data, ..., cont = "mean")

Arguments

Value

A data frame or tibble with the mode for factors and mean/median for continuous variables, with given factors expanded to include all levels.

See Also

ff_mode summary_df

Examples

library(dplyr)
colon_s %>% 
select(-hospital) %>% 
ff_expand(age.factor, sex.factor)

Description

Useful when passing finalfit dependent and explanatory lists to base R functions

Usage

ff_formula(dependent, explanatory, random_effect = NULL)

finalfit_formula(dependent, explanatory, random_effect = NULL)

Arguments

Value

Character vector

Examples

explanatory = c("age", "nodes", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"
ff_formula(dependent, explanatory)

explanatory = c("age", "nodes", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"
random_effect = "(age.factor | hospital)"
ff_formula(dependent, explanatory)

Description

Everyone has a funcion like this, str, glimpse, glance etc. This one is specifically designed for use with finalfit language. It is different in dividing variables by numeric vs factor.

Usage

ff_glimpse(
  .data,
  dependent = NULL,
  explanatory = NULL,
  digits = 1,
  levels_cut = 5
)

finalfit_glimpse(
  .data,
  dependent = NULL,
  explanatory = NULL,
  digits = 1,
  levels_cut = 5
)

Arguments

Value

Dataframe on summary data.

Examples

library(finalfit)
dependent = 'mort_5yr'
explanatory = c("age", "nodes", "age.factor", "extent.factor", "perfor.factor")
colon_s %>%
  finalfit_glimpse(dependent, explanatory)

Description

Combine two factor variables to make an interaction variable. Factor level order is determined by the order in the variables themselves. Note, names of the factor variables should not be quoted. The name of the variable is created from the names of the two factors. The variable is also labelled with a name derived from any pre-existing labels.

Usage

ff_interaction(.data, ..., levels_sep = "_", var_sep = "_", label_sep = ":")

finalfit_interaction(
  .data,
  ...,
  levels_sep = "_",
  var_sep = "_",
  label_sep = ":"
)

Arguments

Value

Original data frame with new variable added via 'dplyr::mutate'.

Examples

colon_s %>%
  ff_interaction(sex.factor, perfor.factor) %>%
    summary_factorlist("mort_5yr", "sex.factor_perfor.factor")

Description

Label a variable

Usage

ff_label(.var, variable_label)

finalfit_label(.var, variable_label)

Arguments

Value

Labelled variable

See Also

extract_variable_label ff_relabel

Examples

colon_s$sex.factor %>%
  ff_label("Sex") %>%
  str()

Merge a summary_factorlist() table with any number of model results tables.

Description

A function that takes the output from summary_factorlist(..., fit_id=TRUE) and merges with any number of model dataframes, usually produced with a model wrapper followed by the fit2df() function (see examples).

Usage

ff_merge(
  factorlist,
  fit2df_df,
  ref_symbol = "-",
  estimate_name = NULL,
  last_merge = FALSE
)

finalfit_merge(
  factorlist,
  fit2df_df,
  ref_symbol = "-",
  estimate_name = NULL,
  last_merge = FALSE
)

Arguments

Value

Returns a dataframe of combined tables.

See Also

summary_factorlist fit2df

Examples

library(finalfit)
library(dplyr)

explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
explanatory_multi = c("age.factor", "obstruct.factor")
random_effect = "hospital"
dependent = "mort_5yr"

# Create separate tables
colon_s %>%
 summary_factorlist(dependent, explanatory, fit_id=TRUE) -> example.summary

colon_s %>%
 glmuni(dependent, explanatory) %>%
 fit2df(estimate_suffix=" (univariable)") -> example.univariable

colon_s %>%
 glmmulti(dependent, explanatory) %>%
 fit2df(estimate_suffix=" (multivariable)") -> example.multivariable

colon_s %>%
 glmmixed(dependent, explanatory, random_effect) %>%
 fit2df(estimate_suffix=" (multilevel)") -> example.multilevel

# Pipe together
example.summary %>%
 ff_merge(example.univariable) %>%
 ff_merge(example.multivariable) %>%
 ff_merge(example.multilevel, last_merge = TRUE)

# Using finalfit()
colon_s %>%
 finalfit(dependent, explanatory, keep_fit_id = TRUE) %>%
 ff_merge(example.multilevel, last_merge = TRUE)

Description

Generate common metrics for regression model results

Usage

ff_metrics(.data)

## S3 method for class 'lm'
ff_metrics(.data)

## S3 method for class 'lmlist'
ff_metrics(.data)

## S3 method for class 'glm'
ff_metrics(.data)

## S3 method for class 'glmlist'
ff_metrics(.data)

## S3 method for class 'lmerMod'
ff_metrics(.data)

## S3 method for class 'glmerMod'
ff_metrics(.data)

## S3 method for class 'coxph'
ff_metrics(.data)

## S3 method for class 'coxphlist'
ff_metrics(.data)

Arguments

Value

Model metrics vector for output.

Examples

library(finalfit)

# glm
fit = glm(mort_5yr ~  age.factor + sex.factor + obstruct.factor + perfor.factor,
  data=colon_s, family="binomial")
fit %>%
  ff_metrics()

# glmlist
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"
colon_s %>%
  glmmulti(dependent, explanatory) %>%
  ff_metrics()

# glmerMod
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
random_effect = "hospital"
dependent = "mort_5yr"
colon_s %>%
  glmmixed(dependent, explanatory, random_effect) %>%
  ff_metrics()

# lm
fit = lm(nodes ~  age.factor + sex.factor + obstruct.factor + perfor.factor,
  data=colon_s)
fit %>%
  ff_metrics()

# lmerMod
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
random_effect = "hospital"
dependent = "nodes"

colon_s %>%
  lmmixed(dependent, explanatory, random_effect) %>%
  ff_metrics()

# coxphlist
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "Surv(time, status)"


colon_s %>%
  coxphmulti(dependent, explanatory) %>%
  ff_metrics()

# coxph
fit = survival::coxph(survival::Surv(time, status) ~ age.factor + sex.factor +
  obstruct.factor + perfor.factor,
  data = colon_s)

fit %>%
  ff_metrics()

Description

When producing conditional estimates from a regression model, it is often useful to set variables not of interest to their mode when creating the newdata object.

Usage

ff_mode(...)

finalfit_mode(...)

Arguments

Value

The most frequent level in a factor.

See Also

summary_df ff_expand

Examples

library(dplyr)
colon_s %>% 
  summarise(age.factor = ff_mode(age.factor))
  
colon_s %>% 
  select(sex.factor, rx.factor, obstruct.factor, perfor.factor) %>% 
  summarise(across(everything(), ff_mode))
  
colon_s %>% 
  reframe(across(where(is.factor), ff_mode))
  # Note, 4 rows is returned in this example because 4 factor levels within `hospital` 
  # have the same frequency.

Description

Generate newdata while respecting the variable types and factor levels in the primary data frame used to run model.

Usage

ff_newdata(
  .data,
  dependent = NULL,
  explanatory = NULL,
  rowwise = TRUE,
  newdata
)

finalfit_newdata(
  .data,
  dependent = NULL,
  explanatory = NULL,
  rowwise = TRUE,
  newdata
)

Arguments

Details

Generate model predictions against a specified set of explanatory levels with bootstrapped confidence intervals. Add a comparison by difference or ratio of the first row of newdata with all subsequent rows.

Value

A list of multivariable glm fitted model outputs. Output is of class glmlist.

See Also

boot_predict boot_compare

Examples

# See boot_predict.
library(finalfit)
library(dplyr)

# Predict probability of death across combinations of factor levels
explanatory = c("age.factor", "extent.factor", "perfor.factor")
dependent = 'mort_5yr'

# Generate combination of explanatory variable levels rowwise
colon_s %>%
  finalfit_newdata(explanatory = explanatory, newdata = list(
    c("<40 years",  "Submucosa", "No"),
    c("<40 years", "Submucosa", "Yes"),
    c("<40 years", "Adjacent structures", "No"),
    c("<40 years", "Adjacent structures", "Yes")
   )) -> newdata

# Generate combination of explanatory variable levels colwise.
explanatory = c("nodes", "extent.factor", "perfor.factor")
colon_s %>%
  finalfit_newdata(explanatory = explanatory, rowwise = FALSE, newdata = list(
  rep(seq(0, 30), 4),
  c(rep("Muscle", 62), rep("Adjacent structures", 62)),
  c(rep("No", 31), rep("Yes", 31), rep("No", 31), rep("Yes", 31))
)) -> newdata

Description

Parse a formula to finalfit grammar

Usage

ff_parse_formula(.formula)

Arguments

Value

A list containing dependent, explanatory and random effects variables

Examples

ff_parse_formula(mort ~ age + sex + (1 | hospital))

Include only percentages for factors in summary_factorlist output

Description

Include only percentages for factors in summary_factorlist output

Usage

ff_percent_only(.data)

finalfit_percent_only(.data)

Arguments

Value

Data frame.

Examples

explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = 'mort_5yr'
colon_s %>%
  summary_factorlist(dependent, explanatory) %>%
  ff_percent_only()

Description

Permuate explanatory variables to produce multiple output tables for common regression models

Usage

ff_permute(
  .data,
  dependent = NULL,
  explanatory_base = NULL,
  explanatory_permute = NULL,
  multiple_tables = FALSE,
  include_base_model = TRUE,
  include_full_model = TRUE,
  base_on_top = TRUE,
  ...
)

finalfit_permute(
  .data,
  dependent = NULL,
  explanatory_base = NULL,
  explanatory_permute = NULL,
  multiple_tables = FALSE,
  include_base_model = TRUE,
  include_full_model = TRUE,
  base_on_top = TRUE,
  ...
)

Arguments

Value

Returns a list of data frame with the final model table.

Examples

explanatory_base = c("age.factor", "sex.factor")
explanatory_permute = c("obstruct.factor", "perfor.factor", "node4.factor")

# Linear regression
colon_s %>%
  finalfit_permute("nodes", explanatory_base, explanatory_permute)

# Cox proportional hazards regression
colon_s %>%
  finalfit_permute("Surv(time, status)", explanatory_base, explanatory_permute)

# Logistic regression
# colon_s %>%
#   finalfit_permute("mort_5yr", explanatory_base, explanatory_permute)

# Logistic regression with random effect (glmer)
# colon_s %>%
#   finalfit_permute("mort_5yr", explanatory_base, explanatory_permute,
#     random_effect = "hospital")

Description

Wraps or_plot, hr_plot, and coefficient_plot and sends to the appropriate method depending on the dependent variable type.

Usage

ff_plot(.data, dependent, explanatory, ...)

finalfit_plot(.data, dependent, explanatory, ...)

Arguments

Value

A table and a plot using ggplot2.

See Also

Other finalfit plot functions: coefficient_plot(), hr_plot(), or_plot(), surv_plot()

Examples

# Coefficient plot
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "nodes"
colon_s %>%
	ff_plot(dependent, explanatory)

# Odds ratio plot
dependent = "mort_5yr"
colon_s %>%
	ff_plot(dependent, explanatory)

	# Hazard ratio plot	
dependent = "Surv(time, status)"
colon_s %>%
	ff_plot(dependent, explanatory, dependent_label = "Survival")

Description

Variable labels can be created using ff_label. Some functions strip variable labels (variable attributes), e.g. forcats::fct_recode. Use this function to create a vector of variable labels from a data frame. Then use ff_relabel to relabel variables in data frame.

Usage

ff_relabel(.data, .labels)

finalfit_relabel(.data, .labels)

Arguments

Examples

# Label variable
colon_s$sex.factor %>%
  ff_label("Sex") %>%
  str()

# Make factor level "Unknown" NA
colon_s %>%
  dplyr::mutate_if(is.factor, forcats::fct_recode, 
  NULL = "Unknown") %>% 
  str()

# Reset data
data(colon_s)

# Extract variable labels
vlabels = colon_s %>% extract_variable_label()

# Run function where labels are lost
colon_s %>%
  dplyr::mutate_if(is.factor, forcats::fct_recode, 
  NULL = "Unknown") %>% 
  str()

# Relabel
colon_s %<>% ff_relabel(vlabels)
colon_s %>% str()

Description

Relabel variables from data frame after tidyverse functions

Usage

ff_relabel_df(.data, .df)

finalfit_relabel_df(.data, .df)

Arguments

Value

Data frame or tibble

Description

This will work with finalfit and any fit2df output.

Usage

ff_remove_p(.data)

finalfit_remove_p(.data)

Arguments

Value

Data frame.

Examples

explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = 'mort_5yr'
colon_s %>%
  finalfit(dependent, explanatory) %>%
  ff_remove_p()

Description

This looks for a column with a name including "Coefficient", "OR", or "HR" (finalfit defaults) and removes any rows with "-" (the default for the reference level). Can also be combined to produce an or_plot, see below.

Usage

ff_remove_ref(.data, only_binary = TRUE)

finalfit_remove_ref(.data, only_binary = TRUE)

Arguments

Value

Data frame.

Examples

# Table example
explanatory = c("age.factor", "age", "sex.factor", "nodes", "obstruct.factor", "perfor.factor")
dependent = 'mort_5yr'
colon_s %>%
	 finalfit(dependent, explanatory, add_dependent_label = FALSE) %>%
	 ff_remove_ref() %>%
	 dependent_label(colon_s, dependent)

# Plot example
explanatory = c("age.factor", "age", "sex.factor", "nodes", "obstruct.factor", "perfor.factor")
dependent = 'mort_5yr'
colon_s %>%
  summary_factorlist(dependent, explanatory, total_col = TRUE, fit_id=TRUE) %>%
  ff_merge(
    glmuni(colon_s, dependent, explanatory) %>%
    fit2df()) %>%
  ff_remove_ref() %>%
  dplyr::select(-`OR`) -> factorlist_plot

colon_s %>%
   or_plot(dependent, explanatory, factorlist = factorlist_plot)

Description

This adds a total and missing count to variables. This is useful for continuous variables. Compare this to summary_factorlist(total_col = TRUE) which includes a count for each dummy variable as a factor and mean (sd) or median (iqr) for continuous variables.

Usage

ff_row_totals(
  df.in,
  .data,
  dependent,
  explanatory,
  missing_column = TRUE,
  percent = TRUE,
  digits = 1,
  na_include_dependent = FALSE,
  na_complete_cases = FALSE,
  total_name = "Total N",
  na_name = "Missing N"
)

finalfit_row_totals(
  df.in,
  .data,
  dependent,
  explanatory,
  missing_column = TRUE,
  percent = TRUE,
  digits = 1,
  na_include_dependent = FALSE,
  na_complete_cases = FALSE,
  total_name = "Total N",
  na_name = "Missing N"
)

Arguments

Value

Data frame.

Examples

explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = 'mort_5yr'
colon_s %>%
 summary_factorlist(dependent, explanatory) %>%
	ff_row_totals(colon_s, dependent, explanatory)

Description

Help making stratified summary_factorlist tables

Usage

ff_stratify_helper(df.out, .data)

Arguments

Examples

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)

Description

An "all-in-one" function that takes a single dependent variable with a vector of explanatory variable names (continuous or categorical variables) to produce a final table for publication including summary statistics. The appropriate model is selected on the basis of dependent variable and whether a random effect is specified.

finalfit.lm method (not called directly)

finalfit.glm method (not called directly)

finalfit.coxph method (not called directly)

Usage

finalfit(
  .data,
  dependent = NULL,
  explanatory = NULL,
  explanatory_multi = NULL,
  random_effect = NULL,
  formula = NULL,
  model_args = list(),
  weights = NULL,
  cont_cut = 5,
  column = NULL,
  keep_models = FALSE,
  metrics = FALSE,
  add_dependent_label = TRUE,
  dependent_label_prefix = "Dependent: ",
  dependent_label_suffix = "",
  keep_fit_id = FALSE,
  ...
)

finalfit.lm(
  .data,
  dependent,
  explanatory,
  explanatory_multi = NULL,
  random_effect = NULL,
  model_args = NULL,
  weights = NULL,
  cont_cut = 5,
  column = FALSE,
  keep_models = FALSE,
  metrics = FALSE,
  add_dependent_label = TRUE,
  dependent_label_prefix = "Dependent: ",
  dependent_label_suffix = "",
  keep_fit_id = FALSE,
  ...
)

finalfit.glm(
  .data,
  dependent,
  explanatory,
  explanatory_multi = NULL,
  random_effect = NULL,
  model_args = NULL,
  weights = NULL,
  cont_cut = 5,
  column = FALSE,
  keep_models = FALSE,
  metrics = FALSE,
  add_dependent_label = TRUE,
  dependent_label_prefix = "Dependent: ",
  dependent_label_suffix = "",
  keep_fit_id = FALSE,
  ...
)

finalfit.coxph(
  .data,
  dependent,
  explanatory,
  explanatory_multi = NULL,
  random_effect = NULL,
  model_args = NULL,
  column = TRUE,
  cont_cut = 5,
  keep_models = FALSE,
  metrics = FALSE,
  add_dependent_label = TRUE,
  dependent_label_prefix = "Dependent: ",
  dependent_label_suffix = "",
  keep_fit_id = FALSE,
  ...
)

Arguments

Value

Returns a data frame with the final model table.

Examples

library(finalfit)
library(dplyr)

# Summary, univariable and multivariable analyses of the form:
# glm(depdendent ~ explanatory, family="binomial")
# lmuni(), lmmulti(), lmmixed(), glmuni(), glmmulti(), glmmixed(), glmmultiboot(),
#   coxphuni(), coxphmulti()

data(colon_s) # Modified from survival::colon
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = 'mort_5yr'
colon_s %>%
  finalfit(dependent, explanatory)

# Multivariable analysis with subset of explanatory
#   variable set used in univariable analysis
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)

# Summary, univariable and multivariable analyses of the form:
# lme4::glmer(dependent ~ explanatory + (1 | random_effect), family="binomial")

explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
explanatory_multi = c("age.factor", "obstruct.factor")
random_effect = "hospital"
dependent = "mort_5yr"
# colon_s %>%
#   finalfit(dependent, explanatory, explanatory_multi, random_effect)

# Include model metrics:
colon_s %>%
  finalfit(dependent, explanatory, explanatory_multi,  metrics=TRUE)

# Summary, univariable and multivariable analyses of the form:
# survival::coxph(dependent ~ explanatory)

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

colon_s %>%
  finalfit(dependent, explanatory)

# Rather than going all-in-one, any number of subset models can
# be manually added on to a summary_factorlist() table using finalfit.merge().
# This is particularly useful when models take a long-time to run or are complicated.

# Note requirement for fit_id=TRUE.
# `fit2df` is a subfunction extracting most common models to a dataframe.

explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = 'mort_5yr'
colon_s %>%
  finalfit(dependent, explanatory, metrics=TRUE)

explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
explanatory_multi = c("age.factor", "obstruct.factor")
random_effect = "hospital"
dependent = 'mort_5yr'

# Separate tables
colon_s %>%
  summary_factorlist(dependent, explanatory, fit_id=TRUE) -> example.summary

colon_s %>%
  glmuni(dependent, explanatory) %>%
  fit2df(estimate_suffix=" (univariable)") -> example.univariable

colon_s %>%
  glmmulti(dependent, explanatory) %>%
  fit2df(estimate_suffix=" (multivariable)") -> example.multivariable

# Edited as CRAN slow to run these
# colon_s %>%
#   glmmixed(dependent, explanatory, random_effect) %>%
#   fit2df(estimate_suffix=" (multilevel") -> example.multilevel

# Pipe together
example.summary %>%
  finalfit_merge(example.univariable) %>%
  finalfit_merge(example.multivariable, last_merge = TRUE)
# finalfit_merge(example.multilevel)

Description

Takes output from finalfit model wrappers and extracts to a dataframe, convenient for further processing in preparation for final results table.

fit2df.lm is the model extract method for lm.

fit2df.lmlist is the model extract method for lmuni and lmmulti.

fit2df.glm is the model extract method for standard glm models, which have not used finalfit model wrappers.

fit2df.glmboot is the model extract method for glmmulti_boot models.

fit2df.glmlist is the model extract method for glmuni and glmmulti.

fit2df.svyglmlist is the model extract method for svyglmuni and svyglmmulti.

fit2df.lmerMod is the model extract method for standard lme4::lmer models and for the finalfit::lmmixed model wrapper.

fit2df.glmerMod is the model extract method for standard lme4::glmer models and for the finalfit::glmmixed model wrapper.

fit2df.coxph is the model extract method for survival::coxph.

fit2df.coxphlist is the model extract method for coxphuni and coxphmulti.

fit2df.crr is the model extract method for cmprsk::crr.

fit2df.coxme is the model extract method for eoxme::coxme.

fit2df.crr is the model extract method for crruni and crrmulti.

fit2df.stanfit is the model extract method for our standard Bayesian hierarchical binomial logistic regression models. These models will be fully documented separately. However this should work for a single or multilevel Bayesian logistic regression done in Stan, as long as the fixed effects are specified in the parameters block as a vector named beta, of length P, where P is the number of fixed effect parameters. e.g. parameters( vector[P] beta; )

fit2df.mipo is the model extract method for the mipo object created using mice::pool.

Usage

fit2df(...)

## S3 method for class 'lm'
fit2df(
  .data,
  condense = TRUE,
  metrics = FALSE,
  remove_intercept = TRUE,
  explanatory_name = "explanatory",
  estimate_name = "Coefficient",
  estimate_suffix = "",
  p_name = "p",
  digits = c(2, 2, 3),
  confint_level = 0.95,
  confint_sep = " to ",
  ...
)

## S3 method for class 'lmlist'
fit2df(
  .data,
  condense = TRUE,
  metrics = FALSE,
  remove_intercept = TRUE,
  explanatory_name = "explanatory",
  estimate_name = "Coefficient",
  estimate_suffix = "",
  p_name = "p",
  digits = c(2, 2, 3),
  confint_level = 0.95,
  confint_sep = " to ",
  ...
)

## S3 method for class 'glm'
fit2df(
  .data,
  condense = TRUE,
  metrics = FALSE,
  remove_intercept = TRUE,
  explanatory_name = "explanatory",
  estimate_name = "OR",
  estimate_suffix = "",
  p_name = "p",
  digits = c(2, 2, 3),
  exp = TRUE,
  confint_type = "profile",
  confint_level = 0.95,
  confint_sep = "-",
  ...
)

## S3 method for class 'glmboot'
fit2df(
  .data,
  condense = TRUE,
  metrics = FALSE,
  remove_intercept = TRUE,
  explanatory_name = "explanatory",
  estimate_name = "OR",
  estimate_suffix = "",
  p_name = "p",
  digits = c(2, 2, 3),
  exp = TRUE,
  confint_level = 0.95,
  confint_sep = "-",
  ...
)

## S3 method for class 'glmlist'
fit2df(
  .data,
  condense = TRUE,
  metrics = FALSE,
  remove_intercept = TRUE,
  explanatory_name = "explanatory",
  estimate_name = "OR",
  estimate_suffix = "",
  p_name = "p",
  digits = c(2, 2, 3),
  exp = TRUE,
  confint_type = "profile",
  confint_level = 0.95,
  confint_sep = "-",
  ...
)

## S3 method for class 'svyglmlist'
fit2df(
  .data,
  condense = TRUE,
  metrics = FALSE,
  remove_intercept = TRUE,
  explanatory_name = "explanatory",
  estimate_name = "Coefficient",
  estimate_suffix = "",
  p_name = "p",
  digits = c(2, 2, 3),
  exp = FALSE,
  confint_type = "profile",
  confint_level = 0.95,
  confint_sep = "-",
  ...
)

## S3 method for class 'lmerMod'
fit2df(
  .data,
  condense = TRUE,
  metrics = FALSE,
  remove_intercept = TRUE,
  explanatory_name = "explanatory",
  estimate_name = "Coefficient",
  estimate_suffix = "",
  p_name = "p",
  digits = c(2, 2, 3),
  confint_type = "Wald",
  confint_level = 0.95,
  confint_sep = " to ",
  ...
)

## S3 method for class 'glmerMod'
fit2df(
  .data,
  condense = TRUE,
  metrics = FALSE,
  remove_intercept = TRUE,
  explanatory_name = "explanatory",
  estimate_name = "OR",
  estimate_suffix = "",
  p_name = "p",
  digits = c(2, 2, 3),
  exp = TRUE,
  confint_type = "Wald",
  confint_level = 0.95,
  confint_sep = "-",
  ...
)

## S3 method for class 'coxph'
fit2df(
  .data,
  condense = TRUE,
  metrics = FALSE,
  explanatory_name = "explanatory",
  estimate_name = "HR",
  estimate_suffix = "",
  p_name = "p",
  digits = c(2, 2, 3),
  confint_sep = "-",
  ...
)

## S3 method for class 'coxphlist'
fit2df(
  .data,
  condense = TRUE,
  metrics = FALSE,
  explanatory_name = "explanatory",
  estimate_name = "HR",
  estimate_suffix = "",
  p_name = "p",
  digits = c(2, 2, 3),
  confint_sep = "-",
  ...
)

## S3 method for class 'crr'
fit2df(
  .data,
  condense = TRUE,
  metrics = FALSE,
  explanatory_name = "explanatory",
  estimate_name = "HR",
  estimate_suffix = "",
  p_name = "p",
  digits = c(2, 2, 3),
  confint_sep = "-",
  ...
)

## S3 method for class 'coxme'
fit2df(
  .data,
  condense = TRUE,
  metrics = FALSE,
  explanatory_name = "explanatory",
  estimate_name = "HR",
  estimate_suffix = "",
  p_name = "p",
  digits = c(2, 2, 3),
  confint_sep = "-",
  ...
)

## S3 method for class 'crrlist'
fit2df(
  .data,
  condense = TRUE,
  metrics = FALSE,
  explanatory_name = "explanatory",
  estimate_name = "HR",
  estimate_suffix = "",
  p_name = "p",
  digits = c(2, 2, 3),
  confint_sep = "-",
  ...
)

## S3 method for class 'stanfit'
fit2df(
  .data,
  condense = TRUE,
  metrics = FALSE,
  remove_intercept = TRUE,
  explanatory_name = "explanatory",
  estimate_name = "OR",
  estimate_suffix = "",
  p_name = "p",
  digits = c(2, 2, 3),
  confint_sep = "-",
  ...
)

## S3 method for class 'mipo'
fit2df(
  .data,
  condense = TRUE,
  metrics = FALSE,
  remove_intercept = TRUE,
  explanatory_name = "explanatory",
  estimate_name = "Coefficient",
  estimate_suffix = "",
  p_name = "p",
  digits = c(2, 2, 3),
  exp = FALSE,
  confint_level = 0.95,
  confint_sep = "-",
  ...
)

Arguments

Details

fit2df is a generic (S3) function for model extract.

Value

A dataframe of model parameters. When metrics=TRUE output is a list of two dataframes, one is model parameters, one is model metrics. length two

Examples

library(finalfit)
library(dplyr)
library(survival)
# glm
fit = glm(mort_5yr ~  age.factor + sex.factor + obstruct.factor + perfor.factor,
  data=colon_s, family="binomial")
fit %>%
  fit2df(estimate_suffix=" (multivariable)")

# glmlist
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"
colon_s %>%
  glmmulti(dependent, explanatory) %>%
  fit2df(estimate_suffix=" (univariable)")

# glmerMod
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
random_effect = "hospital"
dependent = "mort_5yr"
colon_s %>%
  glmmixed(dependent, explanatory, random_effect) %>%
  fit2df(estimate_suffix=" (multilevel)")

# glmboot
## Note number of draws set to 100 just for speed in this example
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"
colon_s %>%
  glmmulti_boot(dependent, explanatory,  R = 100) %>%
  fit2df(estimate_suffix=" (multivariable (BS CIs))")

# lm
fit = lm(nodes ~  age.factor + sex.factor + obstruct.factor + perfor.factor,
  data=colon_s)
fit %>%
  fit2df(estimate_suffix=" (multivariable)")

# lmerMod
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
random_effect = "hospital"
dependent = "nodes"

colon_s %>%
  lmmixed(dependent, explanatory, random_effect) %>%
  fit2df(estimate_suffix=" (multilevel")

# coxphlist
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "Surv(time, status)"

colon_s %>%
  coxphuni(dependent, explanatory) %>%
  fit2df(estimate_suffix=" (univariable)")

colon_s %>%
  coxphmulti(dependent, explanatory) %>%
  fit2df(estimate_suffix=" (multivariable)")

# coxph
fit = coxph(Surv(time, status) ~ age.factor + sex.factor + obstruct.factor + perfor.factor,
  data = colon_s)

fit %>%
  fit2df(estimate_suffix=" (multivariable)")
	
# crr: competing risks
melanoma = boot::melanoma
melanoma = melanoma %>% 
  mutate(
    status_crr = ifelse(status == 2, 0, # "still alive"
      ifelse(status == 1, 1, # "died of melanoma"
      2)), # "died of other causes" 
    sex = factor(sex),
    ulcer = factor(ulcer)
  )

dependent = c("Surv(time, status_crr)")
explanatory = c("sex", "age", "ulcer")
melanoma %>% 
  summary_factorlist(dependent, explanatory, column = TRUE, fit_id = TRUE) %>% 
  ff_merge(
    melanoma %>% 
      crrmulti(dependent, explanatory) %>% 
      fit2df(estimate_suffix = " (competing risks)")
  ) %>% 
select(-fit_id, -index) %>% 
dependent_label(melanoma, dependent)

Description

Internal, function, not called directly

Usage

format_n_percent(n, percent, digits, digits_n = 0, na_include = TRUE)

Arguments

Description

Using finalfit conventions, produces mixed effects binomial logistic regression models for a set of explanatory variables against a binary dependent.

Usage

glmmixed(.data, dependent, explanatory, random_effect, ...)

Arguments

Details

Uses lme4::glmer with finalfit modelling conventions. Output can be passed to fit2df. This is only currently set-up to take a single random effect as a random intercept. Can be updated in future to allow multiple random intercepts, random gradients and interactions on random effects if there is a need

Value

A list of multivariable lme4::glmer fitted model outputs. Output is of class glmerMod.

See Also

fit2df, finalfit_merge

Other finalfit model wrappers: coxphmulti(), coxphuni(), crrmulti(), crruni(), glmmulti_boot(), glmmulti(), glmuni(), lmmixed(), lmmulti(), lmuni(), svyglmmulti(), svyglmuni()

Examples

library(finalfit)
library(dplyr)

explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
random_effect = "hospital"
dependent = "mort_5yr"

colon_s %>%
  glmmixed(dependent, explanatory, random_effect) %>%
	 fit2df(estimate_suffix=" (multilevel)")

Description

Using finalfit conventions, produces a multivariable binomial logistic regression model for a set of explanatory variables against a binary dependent.

Usage

glmmulti(.data, dependent, explanatory, family = "binomial", weights = "", ...)

Arguments

Details

Uses glm with finalfit modelling conventions. Output can be passed to fit2df.

Value

A multivariable glm fitted model.

See Also

fit2df, finalfit_merge

Other finalfit model wrappers: coxphmulti(), coxphuni(), crrmulti(), crruni(), glmmixed(), glmmulti_boot(), glmuni(), lmmixed(), lmmulti(), lmuni(), svyglmmulti(), svyglmuni()

Examples

library(finalfit)
library(dplyr)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"

colon_s %>%
	glmmulti(dependent, explanatory) %>%
	fit2df(estimate_suffix=" (multivariable)")

Description

Using finalfit conventions, produces a multivariable binomial logistic regression models for a set of explanatory variables against a binary dependent.

Usage

glmmulti_boot(.data, dependent, explanatory, R = 1000)

Arguments

Details

Uses glm with finalfit modelling conventions. boot::boot is used to draw bootstrapped confidence intervals on fixed effect model coefficients. Output can be passed to fit2df.

Value

A multivariable glm fitted model with bootstrapped confidence intervals. Output is of class glmboot.

See Also

fit2df, finalfit_merge

Other finalfit model wrappers: coxphmulti(), coxphuni(), crrmulti(), crruni(), glmmixed(), glmmulti(), glmuni(), lmmixed(), lmmulti(), lmuni(), svyglmmulti(), svyglmuni()

Examples

library(finalfit)
library(dplyr)
## Note number of draws set to 100 just for speed in this example
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"

colon_s %>%
  glmmulti_boot(dependent, explanatory, R=100) %>%
  fit2df(estimate_suffix="(multivariable (BS CIs))")

Description

Using finalfit conventions, produces multiple univariable binomial logistic regression models for a set of explanatory variables against a binary dependent.

Usage

glmuni(.data, dependent, explanatory, family = "binomial", weights = "", ...)

Arguments

Details

Uses glm with finalfit modelling conventions. Output can be passed to fit2df.

Value

A list of univariable glm fitted model outputs. Output is of class glmlist.

See Also

fit2df, finalfit_merge

Other finalfit model wrappers: coxphmulti(), coxphuni(), crrmulti(), crruni(), glmmixed(), glmmulti_boot(), glmmulti(), lmmixed(), lmmulti(), lmuni(), svyglmmulti(), svyglmuni()

Examples

library(finalfit)
library(dplyr)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"

colon_s %>%
	glmuni(dependent, explanatory) %>%
	fit2df(estimate_suffix=" (univariable)")

Description

Produce hazard ratio table and plot from a Cox Proportional Hazards analysis, survival::coxph().

Usage

hr_plot(
  .data,
  dependent,
  explanatory,
  factorlist = NULL,
  coxfit = NULL,
  remove_ref = FALSE,
  breaks = NULL,
  column_space = c(-0.5, 0, 0.5),
  dependent_label = "Survival",
  prefix = "",
  suffix = ": HR (95% CI, p-value)",
  table_text_size = 4,
  title_text_size = 13,
  plot_opts = NULL,
  table_opts = NULL,
  ...
)

Arguments

Value

Returns a table and plot produced in ggplot2.

See Also

Other finalfit plot functions: coefficient_plot(), ff_plot(), or_plot(), surv_plot()

Examples

# HR plot
library(finalfit)
library(dplyr)
library(ggplot2)

explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "Surv(time, status)"
colon_s %>%
  hr_plot(dependent, explanatory, dependent_label = "Survival")

colon_s %>%
  hr_plot(dependent, explanatory, dependent_label = "Survival",
    table_text_size=4, title_text_size=14,
    plot_opts=list(xlab("HR, 95% CI"), theme(axis.title = element_text(size=12))))

Description

Labels to column names

Usage

labels_to_column(.data)

Arguments

Value

Data frame or tibble

Examples

library(dplyr)
colon_s %>% 
  select(sex.factor) %>% 
  labels_to_column()

Description

For use with forcats::fct_relabel.

Usage

labels_to_level(.data, .labels)

Arguments

Value

Data frame or tibble

Examples

library(dplyr)
vlabels = extract_variable_label(colon_s)
colon_s %>%
 select(sex.factor, obstruct.factor) %>% 
 tidyr::gather() %>% 
 mutate(
  key = forcats::fct_relabel(key, labels_to_level, vlabels)
 )

Description

Using finalfit conventions, produces mixed effects linear regression models for a set of explanatory variables against a continuous dependent.

Usage

lmmixed(.data, dependent, explanatory, random_effect, ...)

Arguments

Details

Uses lme4::lmer with finalfit modelling conventions. Output can be passed to fit2df. This is only currently set-up to take a single random effect as a random intercept. Can be updated in future to allow multiple random intercepts, random gradients and interactions on random effects if there is a need.

Value

A list of multivariable lme4::lmer fitted model outputs. Output is of class lmerMod.

See Also

fit2df

Other finalfit model wrappers: coxphmulti(), coxphuni(), crrmulti(), crruni(), glmmixed(), glmmulti_boot(), glmmulti(), glmuni(), lmmulti(), lmuni(), svyglmmulti(), svyglmuni()

Examples

library(finalfit)
library(dplyr)

explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
random_effect = "hospital"
dependent = "nodes"

colon_s %>%
  lmmixed(dependent, explanatory, random_effect) %>%
	 fit2df(estimate_suffix=" (multilevel")

Description

Using finalfit conventions, produces a multivariable linear regression model for a set of explanatory variables against a continuous dependent.

Usage

lmmulti(.data, dependent, explanatory, weights = "", ...)

Arguments

Details

Uses lm with finalfit modelling conventions. Output can be passed to fit2df.

Value

A multivariable lm fitted model.

See Also

fit2df

Other finalfit model wrappers: coxphmulti(), coxphuni(), crrmulti(), crruni(), glmmixed(), glmmulti_boot(), glmmulti(), glmuni(), lmmixed(), lmuni(), svyglmmulti(), svyglmuni()

Examples

library(finalfit)
library(dplyr)

explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "nodes"

colon_s %>%
  lmmulti(dependent, explanatory) %>%
  fit2df()

Description

Using finalfit conventions, produces multiple univariable linear regression models for a set of explanatory variables against a continuous dependent.

Usage

lmuni(.data, dependent, explanatory, weights = "", ...)

Arguments

Details

Uses lm with finalfit modelling conventions. Output can be passed to fit2df.

Value

A list of multivariable lm fitted model outputs. Output is of class lmlist.

See Also

fit2df

Other finalfit model wrappers: coxphmulti(), coxphuni(), crrmulti(), crruni(), glmmixed(), glmmulti_boot(), glmmulti(), glmuni(), lmmixed(), lmmulti(), svyglmmulti(), svyglmuni()

Examples

library(finalfit)
library(dplyr)

explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "nodes"

colon_s %>%
  lmuni(dependent, explanatory) %>%
  fit2df()

Description

Internal, not usually called directly

Usage

metrics_hoslem(y, yhat, g = 10, digits = c(2, 3))

Arguments

Value

Character string of chi-sq result, df, and p-value. Significant p-value suggests poor fit.

Author(s)

Adapted from Peter Solymos.

Source

https://github.com/psolymos/ResourceSelection/blob/master/R/hoslem.test.R

Examples

fit = glm(mort_5yr~age.factor+extent.factor, data=colon_s, family="binomial")
metrics_hoslem(fit$y, fit$fitted)

Description

Compare missing data

Usage

missing_compare(
  .data,
  dependent,
  explanatory,
  p = TRUE,
  na_include = FALSE,
  ...
)

Arguments

Value

A dataframe comparing missing data in the dependent variable across explanatory variables. Continuous data are compared with an Analysis of Variance F-test by default. Discrete data are compared with a chi-squared test.

Examples

library(finalfit)

explanatory = c("age", "age.factor", "extent.factor", "perfor.factor")
dependent = "mort_5yr"

colon_s %>%
  ff_glimpse(dependent, explanatory)

colon_s %>%
 missing_pattern(dependent, explanatory)

colon_s %>%
  missing_compare(dependent, explanatory)

Description

Summary of missing values

Usage

missing_glimpse(.data, dependent = NULL, explanatory = NULL, digits = 1)

Arguments

Value

Data frame.

Examples

colon_s %>%
	missing_glimpse()

Description

Compare the occurence of missing values in all variables by each other. Suggest limit the number of variables to a maximum of around six. Dependent and explanatory are for convenience of variable selection, are optional, and have no other specific function.

Usage

missing_pairs(
  .data,
  dependent = NULL,
  explanatory = NULL,
  use_labels = TRUE,
  title = NULL,
  position = "stack",
  showXAxisPlotLabels = TRUE,
  showYAxisPlotLabels = FALSE
)

Arguments

Value

A plot matrix comparing missing values in all variables against each other.

Examples

## Not run: 
explanatory = c("age", "nodes", "age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = 'mort_5yr'
colon_s %>%
  missing_pairs(dependent, explanatory)

## End(Not run)

Description

Using finalfit conventions, produces a missing data matrix using md.pattern.

Usage

missing_pattern(
  .data,
  dependent = NULL,
  explanatory = NULL,
  rotate.names = TRUE,
  ...
)

Arguments

Value

A matrix with ncol(x)+1 columns, in which each row corresponds to a missing data pattern (1=observed, 0=missing). Rows and columns are sorted in increasing amounts of missing information. The last column and row contain row and column counts, respectively.

Examples

library(finalfit)
library(dplyr)
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"

colon_s %>%
	missing_pattern(dependent, explanatory)

Description

Create a plot of missing values by observations on the x-axis and variable on the y-axis. Dependent and explanatory are for convenience and are optional.

Usage

missing_plot(
  .data,
  dependent = NULL,
  explanatory = NULL,
  use_labels = TRUE,
  title = NULL,
  plot_opts = NULL
)

Arguments

Value

Heat map of missing values in dataset.

Examples

colon_s %>%
  missing_plot()

Description

Create predictorMatrix for use with mice

Usage

missing_predictorMatrix(
  .data,
  drop_from_imputed = NULL,
  drop_from_imputer = NULL
)

Arguments

Value

Matrix formatted for predictorMatrix argument in mice.

Examples

library(mice)
library(dplyr)

# Create some extra missing data
## Smoking missing completely at random
set.seed(1)
colon_s$smoking_mcar =
  sample(c("Smoker", "Non-smoker", NA),
  dim(colon_s)[1], replace=TRUE,
  prob = c(0.2, 0.7, 0.1)) %>%
  factor() %>%
  ff_label("Smoking (MCAR)")

## Make smoking missing conditional on patient sex
colon_s$smoking_mar[colon_s$sex.factor == "Female"] =
  sample(c("Smoker", "Non-smoker", NA),
	 sum(colon_s$sex.factor == "Female"),
	 replace = TRUE, prob = c(0.1, 0.5, 0.4))

colon_s$smoking_mar[colon_s$sex.factor == "Male"] =
  sample(c("Smoker", "Non-smoker", NA),
	 sum(colon_s$sex.factor == "Male"),
	 replace=TRUE, prob = c(0.15, 0.75, 0.1))
colon_s$smoking_mar = factor(colon_s$smoking_mar)%>%
  ff_label("Smoking (MAR)")

explanatory = c("age", "sex.factor",
  "nodes", "obstruct.factor", "smoking_mar")
dependent = "mort_5yr"

colon_s %>%
select(dependent, explanatory) %>%
  missing_predictorMatrix(drop_from_imputed =
    c("obstruct.factor", "mort_5yr")) -> predM

colon_s %>%
	select(dependent, explanatory) %>%
	mice(m = 2, predictorMatrix = predM) %>% # e.g. m=10 when for real
	# Run logistic regression on each imputed set
	with(glm(formula(ff_formula(dependent, explanatory)),
					 family="binomial")) %>%
	pool() %>%
	summary(conf.int = TRUE, exponentiate = TRUE) %>%
	# Jiggle into finalfit format
	mutate(explanatory_name = rownames(.)) %>%
	select(explanatory_name, estimate, `2.5 %`, `97.5 %`, p.value) %>%
	condense_fit(estimate_suffix = " (multiple imputation)") %>%
	remove_intercept() -> fit_imputed

Description

Produce an odds ratio table and plot from a glm() or lme4::glmer() model.

Usage

or_plot(
  .data,
  dependent,
  explanatory,
  random_effect = NULL,
  factorlist = NULL,
  glmfit = NULL,
  confint_type = NULL,
  confint_level = 0.95,
  remove_ref = FALSE,
  breaks = NULL,
  column_space = c(-0.5, 0, 0.5),
  dependent_label = NULL,
  prefix = "",
  suffix = NULL,
  table_text_size = 4,
  title_text_size = 13,
  plot_opts = NULL,
  table_opts = NULL,
  ...
)

Arguments

Value

Returns a table and plot produced in ggplot2.

See Also

Other finalfit plot functions: coefficient_plot(), ff_plot(), hr_plot(), surv_plot()

Examples

library(finalfit)
library(dplyr)
library(ggplot2)

# OR plot
explanatory = c("age.factor", "sex.factor", "obstruct.factor", "perfor.factor")
dependent = "mort_5yr"
colon_s %>%
	 or_plot(dependent, explanatory)

colon_s %>%
  or_plot(dependent, explanatory, table_text_size=4, title_text_size=14,
    plot_opts=list(xlab("OR, 95% CI"), theme(axis.title = element_text(size=12))))

Description

Internal function, not called directly

Usage

p_tidy(x, digits, prefix = "=")

Arguments

Details

e.g. for 3 decimal places I want 0.100, not 0.1. Note this function with convert 0.000 to <0.001. All other values are prefixed with "=" by default

Value

Vector of strings.

Description

Remove duplicates and replace

Usage

rm_duplicates(.var, fromLast = FALSE, replacement = "")

Arguments

Value

Character vector.

Description

It is common to want to remove cases/rows where all variables in a particular set are missing, e.g. all symptom variables are missing in a health care dataset.

Usage

rm_empty_block(.data, ...)

Arguments

Value

Data frame.

Examples

# Pretend that we want to remove rows that are missing in group1, group2, and group3 
# but keep rest of dataset. 
colon_s %>% 
  dplyr::mutate(
    group1 = rep(c(NA, 1), length.out = 929),
    group2 = rep(c(NA, 1), length.out = 929),
	 group3 = rep(c(NA, 1), length.out = 929)
  ) %>% 
rm_empty_block(group1, group2, group3) %>% 
  head()

Description

e.g. for 3 decimal places I want 1.200, not 1.2.

Usage

round_tidy(x, digits)

Arguments

Value

Vector of strings.

Examples

round_tidy(0.01023, 3)

Description

When producing conditional estimates from a regression model, it is often useful to set variables not of interest to their mode for factors and mean or median for numerics when creating the newdata object.

Usage

summary_df(.data, cont = "mean")