Help for package sjmisc (original) (raw)

Type:	Package
Encoding:	UTF-8
Title:	Data and Variable Transformation Functions
Version:	2.8.11
Maintainer:	Daniel Lüdecke d.luedecke@uke.de
Description:	Collection of miscellaneous utility functions, supporting data transformation tasks like recoding, dichotomizing or grouping variables, setting and replacing missing values. The data transformation functions also support labelled data, and all integrate seamlessly into a 'tidyverse'-workflow.
License:	GPL-3
Depends:	R (≥ 3.4)
Imports:	dplyr, insight, datawizard, magrittr, methods, purrr, rlang, sjlabelled (≥ 1.1.1), stats, tidyselect, utils
Suggests:	ggplot2, graphics, haven (≥ 2.0.0), mice, nnet, sjPlot, sjstats, knitr, rmarkdown, stringdist, testthat, tidyr
URL:	https://strengejacke.github.io/sjmisc/
BugReports:	https://github.com/strengejacke/sjmisc/issues
RoxygenNote:	7.3.2
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2025-07-30 09:59:14 UTC; Daniel
Author:	Daniel Lüdecke [aut, cre], Iago Giné-Vázquez [ctb], Alexander Bartel [ctb]
Repository:	CRAN
Date/Publication:	2025-07-30 10:50:02 UTC

Data and Variable Transformation Functions

Description

Purpose of this package

Collection of miscellaneous utility functions, supporting data transformation tasks like recoding, dichotomizing or grouping variables, setting and replacing missing values. The data transformation functions also support labelled data, and all integrate seamlessly into a 'tidyverse'-workflow.

Design philosophy - consistent api

The design of this package follows, where appropriate, the tidyverse-approach, with the first argument of a function always being the data (either a data frame or vector), followed by variable names that should be processed by the function. If no variables are specified as argument, the function applies to the complete data that was indicated as first function argument.

There are two types of function designs:

transformation/recoding functions

Functions like rec() or dicho(), which transform or recode variables, typically return the complete data frame that was given as first argument, additionally including the transformed and recoded variables specified in the ...-ellipses argument. The variables usually get a suffix, so original variables are preserved in the data.

coercing/converting functions

Functions like to_factor() or to_label(), which convert variables into other types or add additional information like variable or value labels as attribute, also typically return the complete data frame that was given as first argument. However, the variables specified in the ...-ellipses argument are converted ("overwritten"), all other variables remain unchanged. Hence, these functions do not return any new, additional variables.

Author(s)

Daniel Lüdecke d.luedecke@uke.de

Value matching

Description

%nin% is the complement to %in%. It looks which values in x do not match (hence, are not in) values in y.

Usage

x %nin% y

Arguments

Details

See 'Details' in [match](../../../../doc/manuals/r-patched/packages/base/refman/base.html#topic+match).

Value

A logical vector, indicating if a match was not located for each element of x, thus the values are TRUE or FALSE and never NA.

Examples

c("a", "B", "c") %in% letters
c("a", "B", "c") %nin% letters

c(1, 2, 3, 4) %in% c(3, 4, 5, 6)
c(1, 2, 3, 4) %nin% c(3, 4, 5, 6)

Add or replace data frame columns

Description

add_columns() combines two or more data frames, but unlike[cbind](../../../../doc/manuals/r-patched/packages/base/refman/base.html#topic+cbind) or [dplyr::bind_cols()](../../dplyr/refman/dplyr.html#topic+bind), this function binds data as last columns of a data frame (i.e., behind columns specified in ...). This can be useful in a "pipe"-workflow, where a data frame returned by a previous function should be appended_at the end_ of another data frame that is processed inadd_colums().

replace_columns() replaces all columns in data with identically named columns in ..., and adds remaining (non-duplicated) columns from ... to data.

add_id() simply adds an ID-column to the data frame, with values from 1 to nrow(data), respectively for grouped data frames, values from 1 to group size. See 'Examples'.

Usage

add_columns(data, ..., replace = TRUE)

replace_columns(data, ..., add.unique = TRUE)

add_id(data, var = "ID")

Arguments

Value

For add_columns(), a data frame, where columns of dataare appended after columns of ....

For replace_columns(), a data frame where columns in datawill be replaced by identically named columns in ..., and remaining columns from ... will be appended to data (ifadd.unique = TRUE).

For add_id(), a new column with ID numbers. This column is always the first column in the returned data frame.

Note

For add_columns(), by default, columns in data with identical names like columns in one of the data frames in ...will be dropped (i.e. variables with identical names in ... will replace existing variables in data). Use replace = FALSE to keep all columns. Identical column names will then be renamed, to ensure unique column names (which happens by default when using[dplyr::bind_cols()](../../dplyr/refman/dplyr.html#topic+bind)). When replacing columns, replaced columns are not added to the end of the data frame. Rather, the original order of columns will be preserved.

Examples

data(efc)
d1 <- efc[, 1:3]
d2 <- efc[, 4:6]

if (require("dplyr") && require("sjlabelled")) {
head(bind_cols(d1, d2))
add_columns(d1, d2) %>% head()

d1 <- efc[, 1:3]
d2 <- efc[, 2:6]

add_columns(d1, d2, replace = TRUE) %>% head()
add_columns(d1, d2, replace = FALSE) %>% head()

# use case: we take the original data frame, select specific
# variables and do some transformations or recodings
# (standardization in this example) and add the new, transformed
# variables *to the end* of the original data frame
efc %>%
  select(e17age, c160age) %>%
  std() %>%
  add_columns(efc) %>%
  head()

# new variables with same name will overwrite old variables
# in "efc". order of columns is not changed.
efc %>%
  select(e16sex, e42dep) %>%
  to_factor() %>%
  add_columns(efc) %>%
  head()

# keep both old and new variables, automatically
# rename variables with identical name
efc %>%
  select(e16sex, e42dep) %>%
  to_factor() %>%
  add_columns(efc, replace = FALSE) %>%
  head()

# create sample data frames
d1 <- efc[, 1:10]
d2 <- efc[, 2:3]
d3 <- efc[, 7:8]
d4 <- efc[, 10:12]

# show original
head(d1)

library(sjlabelled)
# slightly change variables, to see effect
d2 <- as_label(d2)
d3 <- as_label(d3)

# replace duplicated columns, append remaining
replace_columns(d1, d2, d3, d4) %>% head()

# replace duplicated columns, omit remaining
replace_columns(d1, d2, d3, d4, add.unique = FALSE) %>% head()

# add ID to dataset
library(dplyr)
data(mtcars)
add_id(mtcars)

mtcars %>%
  group_by(gear) %>%
  add_id() %>%
  arrange(gear, ID) %>%
  print(n = 100)
}

Merge labelled data frames

Description

Merges (full join) data frames and preserve value and variable labels.

Usage

add_rows(..., id = NULL)

merge_df(..., id = NULL)

Arguments

Details

This function works like [dplyr::bind_rows()](../../dplyr/refman/dplyr.html#topic+bind), but preserves variable and value label attributes. add_rows() row-binds all data frames in ..., even if these have different numbers of columns. Non-matching columns will be column-bound and filled with NA-values for rows in those data frames that do not have this column.

Value and variable labels are preserved. If matching columns have different value label attributes, attributes from first data frame will be used.

merge_df() is an alias for add_rows().

Value

A full joined data frame.

Examples

library(dplyr)
data(efc)
x1 <- efc %>% select(1:5) %>% slice(1:10)
x2 <- efc %>% select(3:7) %>% slice(11:20)

mydf <- add_rows(x1, x2)
mydf
str(mydf)

## Not run: 
library(sjPlot)
view_df(mydf)
## End(Not run)

x3 <- efc %>% select(5:9) %>% slice(21:30)
x4 <- efc %>% select(11:14) %>% slice(31:40)

mydf <- add_rows(x1, x2, x3, x4, id = "subsets")
mydf
str(mydf)

Add variables or cases to data frames

Description

add_variables() adds a new column to a data frame, whileadd_case() adds a new row to a data frame. These are convenient functions to add columns or rows not only at the end of a data frame, but at any column or row position. Furthermore, they allow easy integration into a pipe-workflow.

Usage

add_variables(data, ..., .after = Inf, .before = NULL)

add_case(data, ..., .after = Inf, .before = NULL)

Arguments

Value

data, including the new variables or cases from ....

Note

For add_case(), if variable does not exist, a new variable is created and existing cases for this new variable get the value NA. See 'Examples'.

Examples

d <- data.frame(
  a = c(1, 2, 3),
  b = c("a", "b", "c"),
  c = c(10, 20, 30),
  stringsAsFactors = FALSE
)

add_case(d, b = "d")
add_case(d, b = "d", a = 5, .before = 1)

# adding a new case for a new variable
add_case(d, e = "new case")

add_variables(d, new = 5)
add_variables(d, new = c(4, 4, 4), new2 = c(5, 5, 5), .after = "b")

Check if vector only has NA values

Description

Check if all values in a vector are NA.

Usage

all_na(x)

Arguments

Value

Logical, TRUE if x has only NA values, FALSE ifx has at least one non-missing value.

Examples

x <- c(NA, NA, NA)
y <- c(1, NA, NA)

all_na(x)
all_na(y)
all_na(data.frame(x, y))
all_na(list(x, y))

Format numbers

Description

big_mark() formats large numbers with big marks, whileprcn() converts a numeric scalar between 0 and 1 into a character vector, representing the percentage-value.

Usage

big_mark(x, big.mark = ",", ...)

prcn(x)

Arguments

Value

For big_mark(), a prettified x as character, with big marks. For prcn, a character vector with a percentage number.

Examples

# simple big mark
big_mark(1234567)

# big marks for several values at once, mixed numeric and character
big_mark(c(1234567, "55443322"))

# pre-defined width of character output
big_mark(c(1234567, 55443322), width = 15)

# convert numbers into percentage, as character
prcn(0.2389)
prcn(c(0.2143887, 0.55443, 0.12345))

dat <- data.frame(
  a = c(.321, .121, .64543),
  b = c("a", "b", "c"),
  c = c(.435, .54352, .234432)
)
prcn(dat)

Frequency table of tagged NA values

Description

This method counts tagged NA values (see [tagged_na](../../haven/refman/haven.html#topic+tagged%5Fna)) in a vector and prints a frequency table of counted tagged NAs.

Usage

count_na(x, ...)

Arguments

Value

A data frame with counted tagged NA values.

Examples

if (require("haven")) {
  x <- labelled(
    x = c(1:3, tagged_na("a", "c", "z"),
          4:1, tagged_na("a", "a", "c"),
          1:3, tagged_na("z", "c", "c"),
          1:4, tagged_na("a", "c", "z")),
    labels = c("Agreement" = 1, "Disagreement" = 4,
               "First" = tagged_na("c"), "Refused" = tagged_na("a"),
               "Not home" = tagged_na("z"))
  )
  count_na(x)

  y <- labelled(
    x = c(1:3, tagged_na("e", "d", "f"),
          4:1, tagged_na("f", "f", "d"),
          1:3, tagged_na("f", "d", "d"),
          1:4, tagged_na("f", "d", "f")),
    labels = c("Agreement" = 1, "Disagreement" = 4, "An E" = tagged_na("e"),
              "A D" = tagged_na("d"), "The eff" = tagged_na("f"))
  )

  # create data frame
  dat <- data.frame(x, y)

  # possible count()-function calls
  count_na(dat)
  count_na(dat$x)
  count_na(dat, x)
  count_na(dat, x, y)
}

Compute group-meaned and de-meaned variables

Description

de_mean() computes group- and de-meaned versions of a variable that can be used in regression analysis to model the between- and within-subject effect.

Usage

de_mean(x, ..., grp, append = TRUE, suffix.dm = "_dm", suffix.gm = "_gm")

Arguments

Details

de_mean() is intended to create group- and de-meaned variables for complex random-effect-within-between models (see Bell et al. 2018), where group-effects (random effects) and fixed effects correlate (seeBafumi and Gelman 2006)). This violation of one of the_Gauss-Markov-assumptions_ can happen, for instance, when analysing panel data. To control for correlating predictors and group effects, it is recommended to include the group-meaned and de-meaned version of_time-varying covariates_ in the model. By this, one can fit complex multilevel models for panel data, including time-varying, time-invariant predictors and random effects. This approach is superior to simple fixed-effects models, which lack information of variation in the group-effects or between-subject effects.

A description of how to translate the formulas described in Bell et al. 2018 into R using lmer()from lme4 or glmmTMB() from glmmTMB can be found here:for lmer()and for glmmTMB().

Value

For append = TRUE, x including the group-/de-meaned variables as new columns is returned; if append = FALSE, only the group-/de-meaned variables will be returned.

References

Bafumi J, Gelman A. 2006. Fitting Multilevel Models When Predictors and Group Effects Correlate. In. Philadelphia, PA: Annual meeting of the American Political Science Association.

Bell A, Fairbrother M, Jones K. 2018. Fixed and Random Effects Models: Making an Informed Choice. Quality & Quantity. doi:10.1007/s11135-018-0802-x

Examples

data(efc)
efc$ID <- sample(1:4, nrow(efc), replace = TRUE) # fake-ID
de_mean(efc, c12hour, barthtot, grp = ID, append = FALSE)

Basic descriptive statistics

Description

This function prints a basic descriptive statistic, including variable labels.

Usage

descr(
  x,
  ...,
  max.length = NULL,
  weights = NULL,
  show = "all",
  out = c("txt", "viewer", "browser"),
  encoding = "UTF-8",
  file = NULL
)

Arguments

Value

A data frame with basic descriptive statistics.

Note

data may also be a grouped data frame (see [group_by](../../dplyr/refman/dplyr.html#topic+group%5Fby)) with up to two grouping variables. Descriptive tables are created for each subgroup then.

Examples

data(efc)
descr(efc, e17age, c160age)

efc$weights <- abs(rnorm(nrow(efc), 1, .3))
descr(efc, c12hour, barthtot, weights = weights)

library(dplyr)
efc %>% select(e42dep, e15relat, c172code) %>% descr()

# show just a few elements
efc %>% select(e42dep, e15relat, c172code) %>% descr(show = "short")

# with grouped data frames
efc %>%
  group_by(e16sex) %>%
  select(e16sex, e42dep, e15relat, c172code) %>%
  descr()

# you can select variables also inside 'descr()'
efc %>%
  group_by(e16sex, c172code) %>%
  descr(e16sex, c172code, e17age, c160age)

# or even use select-helpers
descr(efc, contains("cop"), max.length = 20)

Dichotomize variables

Description

Dichotomizes variables into dummy variables (0/1). Dichotomization is either done by median, mean or a specific value (see dich.by).dicho_if() is a scoped variant of dicho(), where recoding will be applied only to those variables that match the logical condition of predicate.

Usage

dicho(
  x,
  ...,
  dich.by = "median",
  as.num = FALSE,
  var.label = NULL,
  val.labels = NULL,
  append = TRUE,
  suffix = "_d"
)

dicho_if(
  x,
  predicate,
  dich.by = "median",
  as.num = FALSE,
  var.label = NULL,
  val.labels = NULL,
  append = TRUE,
  suffix = "_d"
)

Arguments

Details

dicho() also works on grouped data frames (see [group_by](../../dplyr/refman/dplyr.html#topic+group%5Fby)). In this case, dichotomization is applied to the subsets of variables in x. See 'Examples'.

Value

x, dichotomized. If x is a data frame, for append = TRUE, x including the dichotomized. variables as new columns is returned; if append = FALSE, only the dichotomized variables will be returned. If append = TRUE andsuffix = "", recoded variables will replace (overwrite) existing variables.

Note

Variable label attributes are preserved (unless changed viavar.label-argument).

Examples

data(efc)
summary(efc$c12hour)
# split at median
table(dicho(efc$c12hour))
# split at mean
table(dicho(efc$c12hour, dich.by = "mean"))
# split between value lowest to 30, and above 30
table(dicho(efc$c12hour, dich.by = 30))

# sample data frame, values from 1-4
head(efc[, 6:10])

# dichtomized values (1 to 2 = 0, 3 to 4 = 1)
library(dplyr)
efc %>%
  select(6:10) %>%
  dicho(dich.by = 2) %>%
  head()

# dichtomize several variables in a data frame
dicho(efc, c12hour, e17age, c160age, append = FALSE)

# dichotomize and set labels
frq(dicho(
  efc, e42dep,
  var.label = "Dependency (dichotomized)",
  val.labels = c("lower", "higher"),
  append = FALSE
))

# works also with gouped data frames
mtcars %>%
  dicho(disp, append = FALSE) %>%
  table()

mtcars %>%
  group_by(cyl) %>%
  dicho(disp, append = FALSE) %>%
  table()

# dichotomizing grouped data frames leads to different
# results for a dichotomized variable, because the split
# value is different for each group.
# compare:
mtcars %>%
  group_by(cyl) %>%
  summarise(median = median(disp))

median(mtcars$disp)

# dichotomize only variables with more than 10 unique values
p <- function(x) dplyr::n_distinct(x) > 10
dicho_if(efc, predicate = p, append = FALSE)

Sample dataset from the EUROFAMCARE project

Description

A SPSS sample data set, imported with the [read_spss](../../sjlabelled/refman/sjlabelled.html#topic+read%5Fspss) function.

Examples

# Attach EFC-data
data(efc)

# Show structure
str(efc)

# show first rows
head(efc)

Return or remove variables or observations that are completely missing

Description

These functions check which rows or columns of a data frame completely contain missing values, i.e. which observations or variables completely have missing values, and either 1) returns their indices; or 2) removes them from the data frame.

Usage

empty_cols(x)

empty_rows(x)

remove_empty_cols(x)

remove_empty_rows(x)

Arguments

Value

For empty_cols and empty_rows, a numeric (named) vector with row or column indices of those variables that completely have missing values.

For remove_empty_cols and remove_empty_rows, a data frame with "empty" columns or rows removed.

Examples

tmp <- data.frame(a = c(1, 2, 3, NA, 5),
                  b = c(1, NA, 3, NA , 5),
                  c = c(NA, NA, NA, NA, NA),
                  d = c(1, NA, 3, NA, 5))

tmp

empty_cols(tmp)
empty_rows(tmp)

remove_empty_cols(tmp)
remove_empty_rows(tmp)

Find variable by name or label

Description

This functions finds variables in a data frame, which variable names or variable (and value) label attribute match a specific pattern. Regular expression for the pattern is supported.

Usage

find_var(
  data,
  pattern,
  ignore.case = TRUE,
  search = c("name_label", "name_value", "label_value", "name", "label", "value", "all"),
  out = c("table", "df", "index"),
  fuzzy = FALSE,
  regex = FALSE
)

find_in_data(
  data,
  pattern,
  ignore.case = TRUE,
  search = c("name_label", "name_value", "label_value", "name", "label", "value", "all"),
  out = c("table", "df", "index"),
  fuzzy = FALSE,
  regex = FALSE
)

Arguments

Details

This function searches for pattern in data's column names and - for labelled data - in all variable and value labels of data's variables (see [get_label](../../sjlabelled/refman/sjlabelled.html#topic+get%5Flabel) for details on variable labels and labelled data). Regular expressions are supported as well, by simply usingpattern = stringr::regex(...) or regex = TRUE.

Value

By default (i.e. out = "table", returns a data frame with three columns: column number, variable name and variable label. Ifout = "index", returns a named vector with column indices of matching variables (variable names are used as names-attribute); if out = "df", returns the matching variables as data frame

Examples

data(efc)

# find variables with "cop" in variable name
find_var(efc, "cop")

# return data frame with matching variables
find_var(efc, "cop", out = "df")

# or return column numbers
find_var(efc, "cop", out = "index")

# find variables with "dependency" in names and variable labels
library(sjlabelled)
find_var(efc, "dependency")
get_label(efc$e42dep)

# find variables with "level" in names and value labels
res <- find_var(efc, "level", search = "name_value", out = "df")
res
get_labels(res, attr.only = FALSE)

# use sjPlot::view_df() to view results
## Not run: 
library(sjPlot)
view_df(res)
## End(Not run)

Flat (proportional) tables

Description

This function creates a labelled flat table or flat proportional (marginal) table.

Usage

flat_table(
  data,
  ...,
  margin = c("counts", "cell", "row", "col"),
  digits = 2,
  show.values = FALSE,
  weights = NULL
)

Arguments

Value

An object of class [ftable](../../../../doc/manuals/r-patched/packages/stats/refman/stats.html#topic+ftable).

Note

data may also be a grouped data frame (see [group_by](../../dplyr/refman/dplyr.html#topic+group%5Fby)) with up to two grouping variables. Cross tables are created for each subgroup then.

See Also

[frq](#topic+frq) for simple frequency table of labelled vectors.

Examples

data(efc)

# flat table with counts
flat_table(efc, e42dep, c172code, e16sex)

# flat table with proportions
flat_table(efc, e42dep, c172code, e16sex, margin = "row")

# flat table from grouped data frame. You need to select
# the grouping variables and at least two more variables for
# cross tabulation.
library(dplyr)
efc %>%
  group_by(e16sex) %>%
  select(e16sex, c172code, e42dep) %>%
  flat_table()

efc %>%
  group_by(e16sex, e42dep) %>%
  select(e16sex, e42dep, c172code, n4pstu) %>%
  flat_table()

# now it gets weird...
efc %>%
  group_by(e16sex, e42dep) %>%
  select(e16sex, e42dep, c172code, n4pstu, c161sex) %>%
  flat_table()

Frequency table of labelled variables

Description

This function returns a frequency table of labelled vectors, as data frame.

Usage

frq(
  x,
  ...,
  sort.frq = c("none", "asc", "desc"),
  weights = NULL,
  auto.grp = NULL,
  show.strings = TRUE,
  show.na = TRUE,
  grp.strings = NULL,
  min.frq = 0,
  out = c("txt", "viewer", "browser"),
  title = NULL,
  encoding = "UTF-8",
  file = NULL
)

Arguments

Details

The ...-argument not only accepts variable names or expressions from select-helpers. You can also use logical conditions, math operations, or combining variables to produce "crosstables". See 'Examples' for more details.

Value

A list of data frames with values, value labels, frequencies, raw, valid and cumulative percentages of x.

Note

x may also be a grouped data frame (see [group_by](../../dplyr/refman/dplyr.html#topic+group%5Fby)) with up to two grouping variables. Frequency tables are created for each subgroup then.

The print()-method adds a table header with information on the variable label, variable type, total and valid N, and mean and standard deviations. Mean and SD are always printed, even for categorical variables (factors) or character vectors. In this case, values are coerced into numeric vector to calculate the summary statistics.

To print tables in markdown or HTML format, use print_md() orprint_html().

See Also

[flat_table](#topic+flat%5Ftable) for labelled (proportional) tables.

Examples

# simple vector
data(efc)
frq(efc$e42dep)

# with grouped data frames, in a pipe
library(dplyr)
efc %>%
  group_by(e16sex, c172code) %>%
  frq(e42dep)

# show only categories with a minimal amount of frequencies
frq(mtcars$gear)

frq(mtcars$gear, min.frq = 10)

frq(mtcars$gear, min.frq = 15)

# with select-helpers: all variables from the COPE-Index
# (which all have a "cop" in their name)
frq(efc, contains("cop"))

# all variables from column "c161sex" to column "c175empl"
frq(efc, c161sex:c175empl)

# for non-labelled data, variable name is printed,
# and "label" column is removed from output
data(iris)
frq(iris, Species)

# also works on grouped data frames
efc %>%
  group_by(c172code) %>%
  frq(is.na(nur_pst))

# group variables with large range and with weights
efc$weights <- abs(rnorm(n = nrow(efc), mean = 1, sd = .5))
frq(efc, c160age, auto.grp = 5, weights = weights)

# different weight options
frq(efc, c172code, weights = weights)
frq(efc, c172code, weights = "weights")
frq(efc, c172code, weights = efc$weights)
frq(efc$c172code, weights = efc$weights)

# group string values
dummy <- efc[1:50, 3, drop = FALSE]
dummy$words <- sample(
  c("Hello", "Helo", "Hole", "Apple", "Ape",
    "New", "Old", "System", "Systemic"),
  size = nrow(dummy),
  replace = TRUE
)

frq(dummy)
frq(dummy, grp.strings = 2)

#### other expressions than variables

# logical conditions
frq(mtcars, cyl ==6)

frq(efc, is.na(nur_pst), contains("cop"))

iris %>%
  frq(starts_with("Petal"), Sepal.Length > 5)

# computation of variables "on the fly"
frq(mtcars, (gear + carb) / cyl)

# crosstables
set.seed(123)
d <- data.frame(
  var_x = sample(letters[1:3], size = 30, replace = TRUE),
  var_y = sample(1:2, size = 30, replace = TRUE),
  var_z = sample(LETTERS[8:10], size = 30, replace = TRUE)
)
table(d$var_x, d$var_z)
frq(d, paste0(var_x, var_z))
frq(d, paste0(var_x, var_y, var_z))

Group near elements of string vectors

Description

This function groups elements of a string vector (character or string variable) according to the element's distance ('similatiry'). The more similar two string elements are, the higher is the chance to be combined into a group.

Usage

group_str(
  strings,
  precision = 2,
  strict = FALSE,
  trim.whitespace = TRUE,
  remove.empty = TRUE,
  verbose = FALSE,
  maxdist
)

Arguments

Value

A character vector where similar string elements (values) are recoded into a new, single value. The return value is of same length asstrings, i.e. grouped elements appear multiple times, so the count for each grouped string is still avaiable (see 'Examples').

See Also

[str_find](#topic+str%5Ffind)

Examples

oldstring <- c("Hello", "Helo", "Hole", "Apple",
               "Ape", "New", "Old", "System", "Systemic")
newstring <- group_str(oldstring)

# see result
newstring

# count for each groups
table(newstring)

# print table to compare original and grouped string
frq(oldstring)
frq(newstring)

# larger groups
newstring <- group_str(oldstring, precision = 3)
frq(oldstring)
frq(newstring)

# be more strict with matching pairs
newstring <- group_str(oldstring, precision = 3, strict = TRUE)
frq(oldstring)
frq(newstring)

Recode numeric variables into equal-ranged groups

Description

Recode numeric variables into equal ranged, grouped factors, i.e. a variable is cut into a smaller number of groups, where each group has the same value range. group_labels() creates the related value labels. group_var_if() and group_labels_if() are scoped variants of group_var() and group_labels(), where grouping will be applied only to those variables that match the logical condition of predicate.

Usage

group_var(
  x,
  ...,
  size = 5,
  as.num = TRUE,
  right.interval = FALSE,
  n = 30,
  append = TRUE,
  suffix = "_gr"
)

group_var_if(
  x,
  predicate,
  size = 5,
  as.num = TRUE,
  right.interval = FALSE,
  n = 30,
  append = TRUE,
  suffix = "_gr"
)

group_labels(x, ..., size = 5, right.interval = FALSE, n = 30)

group_labels_if(x, predicate, size = 5, right.interval = FALSE, n = 30)

Arguments

Details

If size is set to a specific value, the variable is recoded into several groups, where each group has a maximum range of size. Hence, the amount of groups differ depending on the range of x.

If size = "auto", the variable is recoded into a maximum ofn groups. Hence, independent from the range ofx, always the same amount of groups are created, so the range within each group differs (depending on x's range).

right.interval determins which boundary values to include when grouping is done. If TRUE, grouping starts with the lower bound of size. For example, having a variable ranging from 50 to 80, groups cover the ranges from 50-54, 55-59, 60-64 etc. If FALSE (default), grouping starts with the upper boundof size. In this case, groups cover the ranges from 46-50, 51-55, 56-60, 61-65 etc. Note: This will cover a range from 46-50 as first group, even if values from 46 to 49 are not present. See 'Examples'.

If you want to split a variable into a certain amount of equal sized groups (instead of having groups where values have all the same range), use the [split_var](#topic+split%5Fvar) function!

group_var() also works on grouped data frames (see [group_by](../../dplyr/refman/dplyr.html#topic+group%5Fby)). In this case, grouping is applied to the subsets of variables in x. See 'Examples'.

Value

• For group_var(), a grouped variable, either as numeric or as factor (see paramter as.num). If x is a data frame, only the grouped variables will be returned.
• For group_labels(), a string vector or a list of string vectors containing labels based on the grouped categories of x, formatted as "from lower bound to upper bound", e.g. "10-19" "20-29" "30-39" etc. See 'Examples'.

Note

Variable label attributes (see, for instance,[set_label](../../sjlabelled/refman/sjlabelled.html#topic+set%5Flabel)) are preserved. Usually you should use the same values for size and right.interval ingroup_labels() as used in the group_var function if you want matching labels for the related recoded variable.

See Also

[split_var](#topic+split%5Fvar) to split variables into equal sized groups,[group_str](#topic+group%5Fstr) for grouping string vectors or[rec_pattern](#topic+rec%5Fpattern) and [rec](#topic+rec) for another convenient way of recoding variables into smaller groups.

Examples

age <- abs(round(rnorm(100, 65, 20)))
age.grp <- group_var(age, size = 10)
hist(age)
hist(age.grp)

age.grpvar <- group_labels(age, size = 10)
table(age.grp)
print(age.grpvar)

# histogram with EUROFAMCARE sample dataset
# variable not grouped
library(sjlabelled)
data(efc)
hist(efc$e17age, main = get_label(efc$e17age))

# bar plot with EUROFAMCARE sample dataset
# grouped variable
ageGrp <- group_var(efc$e17age)
ageGrpLab <- group_labels(efc$e17age)
barplot(table(ageGrp), main = get_label(efc$e17age), names.arg = ageGrpLab)

# within a pipe-chain
library(dplyr)
efc %>%
  select(e17age, c12hour, c160age) %>%
  group_var(size = 20)

# create vector with values from 50 to 80
dummy <- round(runif(200, 50, 80))
# labels with grouping starting at lower bound
group_labels(dummy)
# labels with grouping startint at upper bound
group_labels(dummy, right.interval = TRUE)

# works also with gouped data frames
mtcars %>%
  group_var(disp, size = 4, append = FALSE) %>%
  table()

mtcars %>%
  group_by(cyl) %>%
  group_var(disp, size = 4, append = FALSE) %>%
  table()

Check if variables or cases have missing / infinite values

Description

This functions checks if variables or observations in a data frame have NA, NaN or Inf values.

Usage

has_na(x, ..., by = c("col", "row"), out = c("table", "df", "index"))

incomplete_cases(x, ...)

complete_cases(x, ...)

complete_vars(x, ...)

incomplete_vars(x, ...)

Arguments

Value

If x is a vector, returns TRUE if x has any missing or infinite values. If x is a data frame, returns TRUE for each variable (if by = "col") or observation (if by = "row") that has any missing or infinite values. If out = "table", results are returned as data frame, with column number, variable name and label, and a logical vector indicating if a variable has missing values or not. However, it's printed in colors, with green rows indicating that a variable has no missings, while red rows indicate the presence of missings or infinite values. If out = "index", a named vector is returned.

Note

complete_cases() and incomplete_cases() are convenient shortcuts for has_na(by = "row", out = "index"), where the first only returns case-id's for all complete cases, and the latter only for non-complete cases.

complete_vars() and incomplete_vars() are convenient shortcuts for has_na(by = "col", out = "index"), and again only return those column-id's for variables which are (in-)complete.

Examples

data(efc)
has_na(efc$e42dep)
has_na(efc, e42dep, tot_sc_e, c161sex)
has_na(efc)

has_na(efc, e42dep, tot_sc_e, c161sex, out = "index")
has_na(efc, out = "df")

has_na(efc, by = "row")
has_na(efc, e42dep, tot_sc_e, c161sex, by = "row", out = "index")
has_na(efc, by = "row", out = "df")

complete_cases(efc, e42dep, tot_sc_e, c161sex)
incomplete_cases(efc, e42dep, tot_sc_e, c161sex)
complete_vars(efc, e42dep, tot_sc_e, c161sex)
incomplete_vars(efc, e42dep, tot_sc_e, c161sex)

Check whether two factors are crossed or nested

Description

These functions checks whether two factors are (fully) crossed or nested, i.e. if each level of one factor occurs in combination with each level of the other factor (is_crossed()) resp. if each category of the first factor co-occurs with only one category of the other (is_nested()). is_cross_classified() checks if one factor level occurs in some, but not all levels of another factor.

Usage

is_crossed(f1, f2)

is_nested(f1, f2)

is_cross_classified(f1, f2)

Arguments

Value

Logical. For is_crossed(), TRUE if factors are (fully) crossed, FALSE otherwise. For is_nested(), TRUE if factors are nested, FALSE otherwise. For is_cross_classified(),TRUE, if one factor level occurs in some, but not all levels of another factor.

Note

If factors are nested, a message is displayed to tell whether f1is nested within f2 or vice versa.

References

Grace, K. The Difference Between Crossed and Nested Factors. (web)

Examples

# crossed factors, each category of
# x appears in each category of y
x <- c(1,4,3,2,3,2,1,4)
y <- c(1,1,1,2,2,1,2,2)
# show distribution
table(x, y)
# check if crossed
is_crossed(x, y)

# not crossed factors
x <- c(1,4,3,2,3,2,1,4)
y <- c(1,1,1,2,1,1,2,2)
# show distribution
table(x, y)
# check if crossed
is_crossed(x, y)


# nested factors, each category of
# x appears in one category of y
x <- c(1,2,3,4,5,6,7,8,9)
y <- c(1,1,1,2,2,2,3,3,3)
# show distribution
table(x, y)
# check if nested
is_nested(x, y)
is_nested(y, x)

# not nested factors
x <- c(1,2,3,4,5,6,7,8,9,1,2)
y <- c(1,1,1,2,2,2,3,3,3,2,3)
# show distribution
table(x, y)
# check if nested
is_nested(x, y)
is_nested(y, x)

# also not fully crossed
is_crossed(x, y)

# but partially crossed
is_cross_classified(x, y)

Check whether string, list or vector is empty

Description

This function checks whether a string or character vector (of length 1), a list or any vector (numeric, atomic) is empty or not.

Usage

is_empty(x, first.only = TRUE, all.na.empty = TRUE)

Arguments

Value

Logical, TRUE if x is a character vector or string and is empty, TRUE if x is a vector or list and of length 0,FALSE otherwise.

Note

NULL- or NA-values are also considered as "empty" (see 'Examples') and will return TRUE, unless all.na.empty==FALSE.

Examples

is_empty("test")
is_empty("")
is_empty(NA)
is_empty(NULL)

# string is not empty
is_empty(" ")

# however, this trimmed string is
is_empty(trim(" "))

# numeric vector
x <- 1
is_empty(x)
x <- x[-1]
is_empty(x)

# check multiple elements of character vectors
is_empty(c("", "a"))
is_empty(c("", "a"), first.only = FALSE)

# empty data frame
d <- data.frame()
is_empty(d)

# empty list
is_empty(list(NULL))

# NA vector
x <- rep(NA,5)
is_empty(x)
is_empty(x, all.na.empty = FALSE)

Check whether value is even or odd

Description

Checks whether x is an even or odd number. Only accepts numeric vectors.

Usage

is_even(x)

is_odd(x)

Arguments

Value

is_even() returns TRUE for each even value of x, FALSE for odd values. is_odd() returns TRUE for each odd value of xand FALSE for even values.

Examples

is_even(4)
is_even(5)
is_even(1:4)

is_odd(4)
is_odd(5)
is_odd(1:4)

Check if a variable is of (non-integer) double type or a whole number

Description

is_float() checks whether an input vector or value is a numeric non-integer (double), depending on fractional parts of the value(s).is_whole() does the opposite and checks whether an input vector is a whole number (without fractional parts).

Usage

is_float(x)

is_whole(x)

Arguments

Value

For is_float(), TRUE if x is a floating value (non-integer double), FALSE otherwise (also returns FALSEfor character vectors and factors). For is_whole(), TRUEif x is a vector with whole numbers only, FALSE otherwise (returns TRUE for character vectors and factors).

Examples

data(mtcars)
data(iris)

is.double(4)
is_float(4)
is_float(4.2)
is_float(iris)

is_whole(4)
is_whole(4.2)
is_whole(mtcars)

Check whether a factor has numeric levels only

Description

is_num_fac() checks whether a factor has only numeric or any non-numeric factor levels, while is_num_chr() checks whether a character vector has only numeric strings.

Usage

is_num_fac(x)

is_num_chr(x)

Arguments

Value

Logical, TRUE if factor has numeric factor levels only, or if character vector has numeric strings only, FALSE otherwise.

Examples

# numeric factor levels
f1 <- factor(c(NA, 1, 3, NA, 2, 4))
is_num_fac(f1)

# not completeley numeric factor levels
f2 <- factor(c(NA, "C", 1, 3, "A", NA, 2, 4))
is_num_fac(f2)

# not completeley numeric factor levels
f3 <- factor(c("Justus", "Bob", "Peter"))
is_num_fac(f3)

is_num_chr(c("a", "1"))
is_num_chr(c("2", "1"))

Merges multiple imputed data frames into a single data frame

Description

This function merges multiple imputed data frames from[mice::mids()](../../mice/refman/mice.html#topic+mids-class)-objects into a single data frame by computing the mean or selecting the most likely imputed value.

Usage

merge_imputations(
  dat,
  imp,
  ori = NULL,
  summary = c("none", "dens", "hist", "sd"),
  filter = NULL
)

Arguments

Details

This method merges multiple imputations of variables into a single variable by computing the (rounded) mean of all imputed values of missing values. By this, each missing value is replaced by those values that have been imputed the most times.

imp must be a mids-object, which is returned by themice()-function of the mice-package. merge_imputations()than creates a data frame for each imputed variable, by combining all imputations (as returned by the [complete](../../mice/refman/mice.html#topic+complete)-function) of each variable, and computing the row means of this data frame. The mean value is then rounded for integer values (and not for numerical values with fractional part), which corresponds to the most frequent imputed value (mode) for a missing value. Missings in the original variable are replaced by the most frequent imputed value.

Value

A data frame with (merged) imputed variables; or ori with appended imputed variables, if ori was specified. If summary is included, returns a list with the data framedata with (merged) imputed variables and some other summary information, including the plot as ggplot-object.

Note

Typically, further analyses are conducted on pooled results of multiple imputed data sets (see [pool](../../mice/refman/mice.html#topic+pool)), however, sometimes (in social sciences) it is also feasible to compute the mean or mode of multiple imputed variables (see Burns et al. 2011).

References

Burns RA, Butterworth P, Kiely KM, Bielak AAM, Luszcz MA, Mitchell P, et al. 2011. Multiple imputation was an efficient method for harmonizing the Mini-Mental State Examination with missing item-level data. Journal of Clinical Epidemiology;64:787-93 doi:10.1016/j.jclinepi.2010.10.011

Examples

if (require("mice")) {
  imp <- mice(nhanes)

  # return data frame with imputed variables
  merge_imputations(nhanes, imp)

  # append imputed variables to original data frame
  merge_imputations(nhanes, imp, nhanes)

  # show summary of quality of merging imputations
  merge_imputations(nhanes, imp, summary = "dens", filter = c("chl", "hyp"))
}

Move columns to other positions in a data frame

Description

move_columns() moves one or more columns in a data frame to another position.

Usage

move_columns(data, ..., .before, .after)

Arguments

Value

data, with resorted columns.

Note

If neither .before nor .after are specified, the column is moved to the end of the data frame by default. .beforeand .after are evaluated in a non-standard fashion, so you need quasi-quotation when the value for .before or .after is a vector with the target-column value. See 'Examples'.

Examples

## Not run: 
data(iris)

iris %>%
  move_columns(Sepal.Width, .after = "Species") %>%
  head()

iris %>%
  move_columns(Sepal.Width, .before = Sepal.Length) %>%
  head()

iris %>%
  move_columns(Species, .before = 1) %>%
  head()

iris %>%
  move_columns("Species", "Petal.Length", .after = 1) %>%
  head()

library(dplyr)
iris %>%
  move_columns(contains("Width"), .after = "Species") %>%
  head()
## End(Not run)

# using quasi-quotation
target <- "Petal.Width"
# does not work, column is moved to the end
iris %>%
  move_columns(Sepal.Width, .after = target) %>%
  head()

# using !! works
iris %>%
  move_columns(Sepal.Width, .after = !!target) %>%
  head()

Convert numeric vectors into factors associated value labels

Description

This function converts numeric variables into factors, and uses associated value labels as factor levels.

Usage

numeric_to_factor(x, n = 4)

Arguments

Details

If x is a labelled vector, associated value labels will be used as level. Else, the numeric vector is simply coerced using as.factor().

Value

x, with numeric values with a maximum of n unique values being converted to factors.

Examples

library(dplyr)
data(efc)
efc %>%
  select(e42dep, e16sex, c12hour, c160age, c172code) %>%
  numeric_to_factor()

Recode variables

Description

rec() recodes values of variables, where variable selection is based on variable names or column position, or on select helpers (see documentation on ...). rec_if() is a scoped variant of rec(), where recoding will be applied only to those variables that match the logical condition of predicate.

Usage

rec(
  x,
  ...,
  rec,
  as.num = TRUE,
  var.label = NULL,
  val.labels = NULL,
  append = TRUE,
  suffix = "_r",
  to.factor = !as.num
)

rec_if(
  x,
  predicate,
  rec,
  as.num = TRUE,
  var.label = NULL,
  val.labels = NULL,
  append = TRUE,
  suffix = "_r",
  to.factor = !as.num
)

Arguments

Details

The rec string has following syntax:

recode pairs

each recode pair has to be separated by a ;, e.g. rec = "1=1; 2=4; 3=2; 4=3"

multiple values

multiple old values that should be recoded into a new single value may be separated with comma, e.g. "1,2=1; 3,4=2"

value range

a value range is indicated by a colon, e.g. "1:4=1; 5:8=2" (recodes all values from 1 to 4 into 1, and from 5 to 8 into 2)

value range for doubles

for double vectors (with fractional part), all values within the specified range are recoded; e.g. 1:2.5=1;2.6:3=2 recodes 1 to 2.5 into 1 and 2.6 to 3 into 2, but 2.55 would not be recoded (since it's not included in any of the specified ranges)

"min" and "max"

minimum and maximum values are indicates by min (or lo) and max (or hi), e.g. "min:4=1; 5:max=2" (recodes all values from minimum values of x to 4 into 1, and from 5 to maximum values of x into 2)

"else"

all other values, which have not been specified yet, are indicated by else, e.g. "3=1; 1=2; else=3" (recodes 3 into 1, 1 into 2 and all other values into 3)

"copy"

the "else"-token can be combined with copy, indicating that all remaining, not yet recoded values should stay the same (are copied from the original value), e.g. "3=1; 1=2; else=copy" (recodes 3 into 1, 1 into 2 and all other values like 2, 4 or 5 etc. will not be recoded, but copied, see 'Examples')

NA's

[NA](../../../../doc/manuals/r-patched/packages/base/refman/base.html#topic+NA) values are allowed both as old and new value, e.g. "NA=1; 3:5=NA" (recodes all NA into 1, and all values from 3 to 5 into NA in the new variable)

"rev"

"rev" is a special token that reverses the value order (see 'Examples')

direct value labelling

value labels for new values can be assigned inside the recode pattern by writing the value label in square brackets after defining the new value in a recode pair, e.g. "15:30=1 [young aged]; 31:55=2 [middle aged]; 56:max=3 [old aged]". See 'Examples'.

Value

x with recoded categories. If x is a data frame, for append = TRUE, x including the recoded variables as new columns is returned; if append = FALSE, only the recoded variables will be returned. If append = TRUE andsuffix = "", recoded variables will replace (overwrite) existing variables.

Note

Please note following behaviours of the function:

• the "else"-token should always be the last argument in the rec-string.
• Non-matching values will be set to NA, unless captured by the "else"-token.
• Tagged NA values (see [tagged_na](../../haven/refman/haven.html#topic+tagged%5Fna)) and their value labels will be preserved when copying NA values to the recoded vector with "else=copy".
• Variable label attributes (see, for instance, [get_label](../../sjlabelled/refman/sjlabelled.html#topic+get%5Flabel)) are preserved (unless changed via var.label-argument), however, value label attributes are removed (except for "rev", where present value labels will be automatically reversed as well). Use val.labels-argument to add labels for recoded values.
• If x is a data frame, all variables should have the same categories resp. value range (else, see second bullet, NAs are produced).

See Also

[set_na](../../sjlabelled/refman/sjlabelled.html#topic+set%5Fna) for setting NA values, [replace_na](#topic+replace%5Fna)to replace NA's with specific value, [recode_to](#topic+recode%5Fto)for re-shifting value ranges and [ref_lvl](#topic+ref%5Flvl) to change the reference level of (numeric) factors.

Examples

data(efc)
table(efc$e42dep, useNA = "always")

# replace NA with 5
table(rec(efc$e42dep, rec = "1=1;2=2;3=3;4=4;NA=5"), useNA = "always")

# recode 1 to 2 into 1 and 3 to 4 into 2
table(rec(efc$e42dep, rec = "1,2=1; 3,4=2"), useNA = "always")

# keep value labels. variable label is automatically preserved
library(dplyr)
efc %>%
  select(e42dep) %>%
  rec(rec = "1,2=1; 3,4=2",
      val.labels = c("low dependency", "high dependency")) %>%
  frq()

# works with mutate
efc %>%
  select(e42dep, e17age) %>%
  mutate(dependency_rev = rec(e42dep, rec = "rev")) %>%
  head()

# recode 1 to 3 into 1 and 4 into 2
table(rec(efc$e42dep, rec = "min:3=1; 4=2"), useNA = "always")

# recode 2 to 1 and all others into 2
table(rec(efc$e42dep, rec = "2=1; else=2"), useNA = "always")

# reverse value order
table(rec(efc$e42dep, rec = "rev"), useNA = "always")

# recode only selected values, copy remaining
table(efc$e15relat)
table(rec(efc$e15relat, rec = "1,2,4=1; else=copy"))

# recode variables with same category in a data frame
head(efc[, 6:9])
head(rec(efc[, 6:9], rec = "1=10;2=20;3=30;4=40"))

# recode multiple variables and set value labels via recode-syntax
dummy <- rec(
  efc, c160age, e17age,
  rec = "15:30=1 [young]; 31:55=2 [middle]; 56:max=3 [old]",
  append = FALSE
)
frq(dummy)

# recode variables with same value-range
lapply(
  rec(
    efc, c82cop1, c83cop2, c84cop3,
    rec = "1,2=1; NA=9; else=copy",
    append = FALSE
  ),
  table,
  useNA = "always"
)

# recode character vector
dummy <- c("M", "F", "F", "X")
rec(dummy, rec = "M=Male; F=Female; X=Refused")

# recode numeric to character
rec(efc$e42dep, rec = "1=first;2=2nd;3=third;else=hi") %>% head()

# recode non-numeric factors
data(iris)
table(rec(iris, Species, rec = "setosa=huhu; else=copy", append = FALSE))

# recode floating points
table(rec(
  iris, Sepal.Length, rec = "lo:5=1;5.01:6.5=2;6.501:max=3", append = FALSE
))

# preserve tagged NAs
if (require("haven")) {
  x <- labelled(c(1:3, tagged_na("a", "c", "z"), 4:1),
                c("Agreement" = 1, "Disagreement" = 4, "First" = tagged_na("c"),
                  "Refused" = tagged_na("a"), "Not home" = tagged_na("z")))
  # get current value labels
  x
  # recode 2 into 5; Values of tagged NAs are preserved
  rec(x, rec = "2=5;else=copy")
}

# use select-helpers from dplyr-package
out <- rec(
  efc, contains("cop"), c161sex:c175empl,
  rec = "0,1=0; else=1",
  append = FALSE
)
head(out)

# recode only variables that have a value range from 1-4
p <- function(x) min(x, na.rm = TRUE) > 0 && max(x, na.rm = TRUE) < 5
out <- rec_if(efc, predicate = p, rec = "1:3=1;4=2;else=copy")
head(out)

Create recode pattern for 'rec' function

Description

Convenient function to create a recode pattern for the[rec](#topic+rec) function, which recodes (numeric) vectors into smaller groups.

Usage

rec_pattern(from, to, width = 5, other = NULL)

Arguments

Value

A list with two values:

pattern

string pattern that can be used as rec argument for the [rec](#topic+rec)-function.

labels

the associated values labels that can be used with [set_labels](../../sjlabelled/refman/sjlabelled.html#topic+set%5Flabels).

See Also

[group_var](#topic+group%5Fvar) for recoding variables into smaller groups, and[group_labels](#topic+group%5Flabels) to create the asssociated value labels.

Examples

rp <- rec_pattern(1, 100)
rp

# sample data, inspect age of carers
data(efc)
table(efc$c160age, exclude = NULL)
table(rec(efc$c160age, rec = rp$pattern), exclude = NULL)

# recode carers age into groups of width 5
x <- rec(
  efc$c160age,
  rec = rp$pattern,
  val.labels = rp$labels
)
# watch result
frq(x)

Recode variable categories into new values

Description

Recodes (or "renumbers") the categories of variables into new category values, beginning with the lowest value specified by lowest. Useful when recoding dummy variables with 1/2 values to 0/1 values, or recoding scales from 1-4 to 0-3 etc.recode_to_if() is a scoped variant of recode_to(), where recoding will be applied only to those variables that match the logical condition of predicate.

Usage

recode_to(x, ..., lowest = 0, highest = -1, append = TRUE, suffix = "_r0")

recode_to_if(
  x,
  predicate,
  lowest = 0,
  highest = -1,
  append = TRUE,
  suffix = "_r0"
)

Arguments

Value

x with recoded category values, where lowest indicates the lowest value; If x is a data frame, for append = TRUE,x including the recoded variables as new columns is returned; ifappend = FALSE, only the recoded variables will be returned. Ifappend = TRUE and suffix = "", recoded variables will replace (overwrite) existing variables.

Note

Value and variable label attributes are preserved.

See Also

[rec](#topic+rec) for general recoding of variables and [set_na](../../sjlabelled/refman/sjlabelled.html#topic+set%5Fna)for setting [NA](../../../../doc/manuals/r-patched/packages/base/refman/base.html#topic+NA) values.

Examples

# recode 1-4 to 0-3
dummy <- sample(1:4, 10, replace = TRUE)
recode_to(dummy)

# recode 3-6 to 0-3
# note that numeric type is returned
dummy <- as.factor(3:6)
recode_to(dummy)

# lowest value starting with 1
dummy <- sample(11:15, 10, replace = TRUE)
recode_to(dummy, lowest = 1)

# lowest value starting with 1, highest with 3
# all others set to NA
dummy <- sample(11:15, 10, replace = TRUE)
recode_to(dummy, lowest = 1, highest = 3)

# recode multiple variables at once
data(efc)
recode_to(efc, c82cop1, c83cop2, c84cop3, append = FALSE)

library(dplyr)
efc %>%
  select(c82cop1, c83cop2, c84cop3) %>%
  mutate(
    c82new = recode_to(c83cop2, lowest = 5),
    c83new = recode_to(c84cop3, lowest = 3)
  ) %>%
  head()

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

insight

[print_html](../../insight/refman/insight.html#topic+display), [print_md](../../insight/refman/insight.html#topic+display)

magrittr

[%>%](../../magrittr/refman/magrittr.html#topic+pipe)

sjlabelled

[set_na](../../sjlabelled/refman/sjlabelled.html#topic+set%5Fna), [to_character](../../sjlabelled/refman/sjlabelled.html#topic+as%5Flabel), [to_factor](../../sjlabelled/refman/sjlabelled.html#topic+as%5Ffactor), [to_label](../../sjlabelled/refman/sjlabelled.html#topic+as%5Flabel), [to_numeric](../../sjlabelled/refman/sjlabelled.html#topic+as%5Fnumeric)

Change reference level of (numeric) factors

Description

Changes the reference level of (numeric) factor.

Usage

ref_lvl(x, ..., lvl = NULL)

Arguments

Details

Unlike [relevel](../../../../doc/manuals/r-patched/packages/stats/refman/stats.html#topic+relevel), this function behaves differently for factor with numeric factor levels or for labelled data, i.e. factors with value labels for the values. ref_lvl() changes the reference level by recoding the factor's values using the [rec](#topic+rec) function. Hence, all values from lowest up to the reference level indicated bylvl are recoded, with lvl starting as lowest factor value. For factors with non-numeric factor levels, the function simply returnsrelevel(x, ref = lvl). See 'Examples'.

Value

x with new reference level. If xis a data frame, the complete data frame x will be returned, where variables specified in ... will be re-leveled; if ... is not specified, applies to all variables in the data frame.

See Also

[to_factor](#topic+to%5Ffactor) to convert numeric vectors into factors;[rec](#topic+rec) to recode variables.

Examples

data(efc)
x <- to_factor(efc$e42dep)
str(x)
frq(x)

# see column "val" in frq()-output, which indicates
# how values/labels were recoded after using ref_lvl()
x <- ref_lvl(x, lvl = 3)
str(x)
frq(x)

library(dplyr)
dat <- efc %>%
  select(c82cop1, c83cop2, c84cop3) %>%
  to_factor()

frq(dat)
ref_lvl(dat, c82cop1, c83cop2, lvl = 2) %>% frq()

# compare numeric and string value for "lvl"-argument
x <- to_factor(efc$e42dep)
frq(x)
ref_lvl(x, lvl = 2) %>% frq()
ref_lvl(x, lvl = "slightly dependent") %>% frq()

# factors with non-numeric factor levels
data(iris)
levels(iris$Species)
levels(ref_lvl(iris$Species, lvl = 3))
levels(ref_lvl(iris$Species, lvl = "versicolor"))

Remove variables from a data frame

Description

This function removes variables from a data frame, and is intended to use within a pipe-workflow. remove_cols() is an alias for remove_var().

Usage

remove_var(x, ...)

remove_cols(x, ...)

Arguments

Value

x, with variables specified in ... removed.

Examples

mtcars %>% remove_var("disp", "cyl")
mtcars %>% remove_var(c("wt", "vs"))
mtcars %>% remove_var(drat:am)

Replace NA with specific values

Description

This function replaces (tagged) NA's of a variable, data frame or list of variables with value.

Usage

replace_na(x, ..., value, na.label = NULL, tagged.na = NULL)

Arguments

Details

While regular NA values can only be completely replaced with a single value, [tagged_na](../../haven/refman/haven.html#topic+tagged%5Fna) allows to differentiate between different qualitative values of NAs. Tagged NAs work exactly like regular R missing values except that they store one additional byte of information: a tag, which is usually a letter ("a" to "z") or character number ("0" to "9"). Therewith it is possible to replace only specific NA values, while other NA values are preserved.

Value

x, where NA's are replaced with value. If xis a data frame, the complete data frame x will be returned, with replaced NA's for variables specified in ...; if ... is not specified, applies to all variables in the data frame.

Note

Value and variable label attributes are preserved.

See Also

[set_na](../../sjlabelled/refman/sjlabelled.html#topic+set%5Fna) for setting NA values, [rec](#topic+rec)for general recoding of variables and [recode_to](#topic+recode%5Fto)for re-shifting value ranges.

Examples

library(sjlabelled)
data(efc)
table(efc$e42dep, useNA = "always")
table(replace_na(efc$e42dep, value = 99), useNA = "always")

# the original labels
get_labels(replace_na(efc$e42dep, value = 99))
# NA becomes "99", and is labelled as "former NA"
get_labels(
  replace_na(efc$e42dep, value = 99, na.label = "former NA"),
  values = "p"
)

dummy <- data.frame(
  v1 = efc$c82cop1,
  v2 = efc$c83cop2,
  v3 = efc$c84cop3
)
# show original distribution
lapply(dummy, table, useNA = "always")
# show variables, NA's replaced with 99
lapply(replace_na(dummy, v2, v3, value = 99), table, useNA = "always")

if (require("haven")) {
  x <- labelled(c(1:3, tagged_na("a", "c", "z"), 4:1),
                c("Agreement" = 1, "Disagreement" = 4, "First" = tagged_na("c"),
                  "Refused" = tagged_na("a"), "Not home" = tagged_na("z")))
  # get current NA values
  x
  get_na(x)

  # replace only the NA, which is tagged as NA(c)
  replace_na(x, value = 2, tagged.na = "c")
  get_na(replace_na(x, value = 2, tagged.na = "c"))

  table(x)
  table(replace_na(x, value = 2, tagged.na = "c"))

  # tagged NA also works for non-labelled class
  # init vector
  x <- c(1, 2, 3, 4)
  # set values 2 and 3 as tagged NA
  x <- set_na(x, na = c(2, 3), as.tag = TRUE)
  # see result
  x
  # now replace only NA tagged with 2 with value 5
  replace_na(x, value = 5, tagged.na = "2")
}

Reshape data into long format

Description

reshape_longer() reshapes one or more columns from wide into long format.

Usage

reshape_longer(
  x,
  columns = colnames(x),
  names.to = "key",
  values.to = "value",
  labels = NULL,
  numeric.timevar = FALSE,
  id = ".id"
)

Arguments

Value

A reshaped data frame.

See Also

[to_long](#topic+to%5Flong)

Examples

# Reshape one column group into long format
mydat <- data.frame(
  age = c(20, 30, 40),
  sex = c("Female", "Male", "Male"),
  score_t1 = c(30, 35, 32),
  score_t2 = c(33, 34, 37),
  score_t3 = c(36, 35, 38)
)

reshape_longer(
  mydat,
  columns = c("score_t1", "score_t2", "score_t3"),
  names.to = "time",
  values.to = "score"
)


# Reshape multiple column groups into long format
mydat <- data.frame(
  age = c(20, 30, 40),
  sex = c("Female", "Male", "Male"),
  score_t1 = c(30, 35, 32),
  score_t2 = c(33, 34, 37),
  score_t3 = c(36, 35, 38),
  speed_t1 = c(2, 3, 1),
  speed_t2 = c(3, 4, 5),
  speed_t3 = c(1, 8, 6)
)

reshape_longer(
  mydat,
  columns = list(
    c("score_t1", "score_t2", "score_t3"),
    c("speed_t1", "speed_t2", "speed_t3")
  ),
  names.to = "time",
  values.to = c("score", "speed")
)

# or ...
reshape_longer(
  mydat,
  list(3:5, 6:8),
  names.to = "time",
  values.to = c("score", "speed")
)

# gather multiple columns, label columns
x <- reshape_longer(
  mydat,
  list(3:5, 6:8),
  names.to = "time",
  values.to = c("score", "speed"),
  labels = c("Test Score", "Time needed to finish")
)

library(sjlabelled)
str(x$score)
get_label(x$speed)

Rotate a data frame

Description

This function rotates a data frame, i.e. columns become rows and vice versa.

Usage

rotate_df(x, rn = NULL, cn = FALSE)

Arguments

Value

A (rotated) data frame.

Examples

x <- mtcars[1:3, 1:4]
rotate_df(x)
rotate_df(x, rn = "property")

# use values in 1. column as column name
rotate_df(x, cn = TRUE)
rotate_df(x, rn = "property", cn = TRUE)

# also works on list-results
library(purrr)

dat <- mtcars[1:3, 1:4]
tmp <- purrr::map(dat, function(x) {
  sdev <- stats::sd(x, na.rm = TRUE)
  ulsdev <- mean(x, na.rm = TRUE) + c(-sdev, sdev)
  names(ulsdev) <- c("lower_sd", "upper_sd")
  ulsdev
})
tmp
as.data.frame(tmp)
rotate_df(tmp)

tmp <- purrr::map_df(dat, function(x) {
  sdev <- stats::sd(x, na.rm = TRUE)
  ulsdev <- mean(x, na.rm = TRUE) + c(-sdev, sdev)
  names(ulsdev) <- c("lower_sd", "upper_sd")
  ulsdev
})
tmp
rotate_df(tmp)

Round numeric variables in a data frame

Description

round_num() rounds numeric variables in a data frame that also contains non-numeric variables. Non-numeric variables are ignored.

Usage

round_num(x, digits = 0)

Arguments

Value

x with all numeric variables rounded.

Examples

data(iris)
round_num(iris)

Count row or column indices

Description

row_count() mimics base R's rowSums(), with sums for a specific value indicated by count. Hence, it is equivalent to rowSums(x == count, na.rm = TRUE). However, this function is designed to work nicely within a pipe-workflow and allows select-helpers for selecting variables and the return value is always a data frame (with one variable).

col_count() does the same for columns. The return value is a data frame with one row (the column counts) and the same number of columns as x.

Usage

row_count(x, ..., count, var = "rowcount", append = TRUE)

col_count(x, ..., count, var = "colcount", append = TRUE)

Arguments

Value

For row_count(), a data frame with one variable: the sum of countappearing in each row of x; for col_count(), a data frame with one row and the same number of variables as in x: each variable holds the sum of count appearing in each variable of x. If append = TRUE, x including this variable will be returned.

Examples

dat <- data.frame(
  c1 = c(1, 2, 3, 1, 3, NA),
  c2 = c(3, 2, 1, 2, NA, 3),
  c3 = c(1, 1, 2, 1, 3, NA),
  c4 = c(1, 1, 3, 2, 1, 2)
)

row_count(dat, count = 1, append = FALSE)
row_count(dat, count = NA, append = FALSE)
row_count(dat, c1:c3, count = 2, append = TRUE)

col_count(dat, count = 1, append = FALSE)
col_count(dat, count = NA, append = FALSE)
col_count(dat, c1:c3, count = 2, append = TRUE)

Row sums and means for data frames

Description

row_sums() and row_means() compute row sums or means for at least n valid values per row. The functions are designed to work nicely within a pipe-workflow and allow select-helpers for selecting variables.

Usage

row_sums(x, ...)

## Default S3 method:
row_sums(x, ..., n, var = "rowsums", append = TRUE)

## S3 method for class 'mids'
row_sums(x, ..., var = "rowsums", append = TRUE)

row_means(x, ...)

total_mean(x, ...)

## Default S3 method:
row_means(x, ..., n, var = "rowmeans", append = TRUE)

## S3 method for class 'mids'
row_means(x, ..., var = "rowmeans", append = TRUE)

Arguments

Details

For n, must be a numeric value from 0 to ncol(x). If a row in x has at least n non-missing values, the row mean or sum is returned. If n is a non-integer value from 0 to 1,n is considered to indicate the proportion of necessary non-missing values per row. E.g., if n = .75, a row must have at least ncol(x) * nnon-missing values for the row mean or sum to be calculated. See 'Examples'.

Value

For row_sums(), a data frame with a new variable: the row sums fromx; for row_means(), a data frame with a new variable: the row means from x. If append = FALSE, only the new variable with row sums resp. row means is returned. total_mean() returns the mean of all values from all specified columns in a data frame.

Examples

data(efc)
efc %>% row_sums(c82cop1:c90cop9, n = 3, append = FALSE)

library(dplyr)
row_sums(efc, contains("cop"), n = 2, append = FALSE)

dat <- data.frame(
  c1 = c(1,2,NA,4),
  c2 = c(NA,2,NA,5),
  c3 = c(NA,4,NA,NA),
  c4 = c(2,3,7,8),
  c5 = c(1,7,5,3)
)
dat

row_means(dat, n = 4)
row_sums(dat, n = 4)

row_means(dat, c1:c4, n = 4)
# at least 40% non-missing
row_means(dat, c1:c4, n = .4)
row_sums(dat, c1:c4, n = .4)

# total mean of all values in the data frame
total_mean(dat)

# create sum-score of COPE-Index, and append to data
efc %>%
  select(c82cop1:c90cop9) %>%
  row_sums(n = 1)

# if data frame has only one column, this column is returned
row_sums(dat[, 1, drop = FALSE], n = 0)

Sequence generation for column or row counts of data frames

Description

seq_col(x) is a convenient wrapper for seq_len(ncol(x)), while seq_row(x) is a convenient wrapper for seq_len(nrow(x)).

Usage

seq_col(x)

seq_row(x)

Arguments

Value

A numeric sequence from 1 to number of columns or rows.

Examples

data(iris)
seq_col(iris)
seq_row(iris)

Replace specific values in vector with NA

Description

set_na_if() is a scoped variant of[set_na](../../sjlabelled/refman/sjlabelled.html#topic+set%5Fna), where values will be replaced only with NA's for those variables that match the logical condition ofpredicate.

Usage

set_na_if(x, predicate, na, drop.levels = TRUE, as.tag = FALSE)

Arguments

Value

x, with all values in na being replaced by NA. If x is a data frame, the complete data frame x will be returned, with NA's set for variables specified in ...; if ... is not specified, applies to all variables in the data frame.

See Also

[replace_na](#topic+replace%5Fna) to replace [NA](../../../../doc/manuals/r-patched/packages/base/refman/base.html#topic+NA)'s with specific values, [rec](#topic+rec) for general recoding of variables and[recode_to](#topic+recode%5Fto) for re-shifting value ranges. See[get_na](../../sjlabelled/refman/sjlabelled.html#topic+get%5Fna) to get values of missing values in labelled vectors.

Examples

dummy <- data.frame(var1 = sample(1:8, 100, replace = TRUE),
                    var2 = sample(1:10, 100, replace = TRUE),
                    var3 = sample(1:6, 100, replace = TRUE))

p <- function(x) max(x, na.rm = TRUE) > 7
tmp <- set_na_if(dummy, predicate = p, na = 8:9)
head(tmp)

Shorten character strings

Description

This function shortens strings that are longer than max.lengthchars, without cropping words.

Usage

shorten_string(s, max.length = NULL, abbr = "...")

Arguments

Details

If the string length defined in max.length happens to be inside a word, this word is removed from the returned string (see 'Examples'), so the returned string has a maximum length of max.length, but might be shorter.

Value

A shortened string.

Examples

s <- "This can be considered as very long string!"

# string is shorter than max.length, so returned as is
shorten_string(s, 60)

# string is shortened to as many words that result in
# a string of maximum 20 chars
shorten_string(s, 20)

# string including "considered" is exactly of length 22 chars
shorten_string(s, 22)

Split numeric variables into smaller groups

Description

Recode numeric variables into equal sized groups, i.e. a variable is cut into a smaller number of groups at specific cut points.split_var_if() is a scoped variant of split_var(), where transformation will be applied only to those variables that match the logical condition of predicate.

Usage

split_var(
  x,
  ...,
  n,
  as.num = FALSE,
  val.labels = NULL,
  var.label = NULL,
  inclusive = FALSE,
  append = TRUE,
  suffix = "_g"
)

split_var_if(
  x,
  predicate,
  n,
  as.num = FALSE,
  val.labels = NULL,
  var.label = NULL,
  inclusive = FALSE,
  append = TRUE,
  suffix = "_g"
)

Arguments

Details

split_var() splits a variable into equal sized groups, where the amount of groups depends on the n-argument. Thus, this functions [cut](../../../../doc/manuals/r-patched/packages/base/refman/base.html#topic+cut)s a variable into groups at the specified[quantile](../../../../doc/manuals/r-patched/packages/stats/refman/stats.html#topic+quantile)s.

By contrast, [group_var](#topic+group%5Fvar) recodes a variable into groups, where groups have the same value range (e.g., from 1-5, 6-10, 11-15 etc.).

split_var() also works on grouped data frames (see [group_by](../../dplyr/refman/dplyr.html#topic+group%5Fby)). In this case, splitting is applied to the subsets of variables in x. See 'Examples'.

Value

A grouped variable with equal sized groups. If x is a data frame, for append = TRUE, x including the grouped variables as new columns is returned; if append = FALSE, only the grouped variables will be returned. If append = TRUE and suffix = "", recoded variables will replace (overwrite) existing variables.

Note

In case a vector has only few number of unique values, splitting into equal sized groups may fail. In this case, use the inclusive-argument to shift a value at the cut point into the lower, preceeding group to get equal sized groups. See 'Examples'.

See Also

[group_var](#topic+group%5Fvar) to group variables into equal ranged groups, or [rec](#topic+rec) to recode variables.

Examples

data(efc)
# non-grouped
table(efc$neg_c_7)

# split into 3 groups
table(split_var(efc$neg_c_7, n = 3))

# split multiple variables into 3 groups
split_var(efc, neg_c_7, pos_v_4, e17age, n = 3, append = FALSE)
frq(split_var(efc, neg_c_7, pos_v_4, e17age, n = 3, append = FALSE))

# original
table(efc$e42dep)

# two groups, non-inclusive cut-point
# vector split leads to unequal group sizes
table(split_var(efc$e42dep, n = 2))

# two groups, inclusive cut-point
# group sizes are equal
table(split_var(efc$e42dep, n = 2, inclusive = TRUE))

# Unlike dplyr's ntile(), split_var() never splits a value
# into two different categories, i.e. you always get a clean
# separation of original categories
library(dplyr)

x <- dplyr::ntile(efc$neg_c_7, n = 3)
table(efc$neg_c_7, x)

x <- split_var(efc$neg_c_7, n = 3)
table(efc$neg_c_7, x)

# works also with gouped data frames
mtcars %>%
  split_var(disp, n = 3, append = FALSE) %>%
  table()

mtcars %>%
  group_by(cyl) %>%
  split_var(disp, n = 3, append = FALSE) %>%
  table()

Spread model coefficients of list-variables into columns

Description

This function extracts coefficients (and standard error and p-values) of fitted model objects from (nested) data frames, which are saved in a list-variable, and spreads the coefficients into new colummns.

Usage

spread_coef(data, model.column, model.term, se, p.val, append = TRUE)

Arguments

Details

This function requires a (nested) data frame (e.g. created by the[nest](../../tidyr/refman/tidyr.html#topic+nest)-function of the tidyr-package), where several fitted models are saved in a list-variable (see 'Examples'). Since nested data frames with fitted models stored as list-variable are typically fit with an identical formula, all models have the same dependent and independent variables and only differ in their subsets of data. The function then extracts all coefficients from each model and saves each estimate in a new column. The result is a data frame, where each row is a model with each model's coefficients in an own column.

Value

A data frame with columns for each coefficient of the models that are stored in the list-variable of data; or, ifmodel.term is given, a data frame with the term's estimate. If se = TRUE or p.val = TRUE, the returned data frame also contains columns for the coefficients' standard error and p-value. If append = TRUE, the columns are appended to data, i.e. data is also returned.

Examples

if (require("dplyr") && require("tidyr") && require("purrr")) {
  data(efc)

  # create nested data frame, grouped by dependency (e42dep)
  # and fit linear model for each group. These models are
  # stored in the list variable "models".
  model.data <- efc %>%
    filter(!is.na(e42dep)) %>%
    group_by(e42dep) %>%
    nest() %>%
    mutate(
      models = map(data, ~lm(neg_c_7 ~ c12hour + c172code, data = .x))
    )

  # spread coefficients, so we can easily access and compare the
  # coefficients over all models. arguments `se` and `p.val` default
  # to `FALSE`, when `model.term` is not specified
  spread_coef(model.data, models)
  spread_coef(model.data, models, se = TRUE)

  # select only specific model term. `se` and `p.val` default to `TRUE`
  spread_coef(model.data, models, c12hour)

  # spread_coef can be used directly within a pipe-chain
  efc %>%
    filter(!is.na(e42dep)) %>%
    group_by(e42dep) %>%
    nest() %>%
    mutate(
      models = map(data, ~lm(neg_c_7 ~ c12hour + c172code, data = .x))
    ) %>%
    spread_coef(models)
}

Standardize and center variables

Description

std() computes a z-transformation (standardized and centered) on the input. center() centers the input. std_if() andcenter_if() are scoped variants of std() and center(), where transformation will be applied only to those variables that match the logical condition of predicate.

Usage

std(
  x,
  ...,
  robust = c("sd", "2sd", "gmd", "mad"),
  include.fac = FALSE,
  append = TRUE,
  suffix = "_z"
)

std_if(
  x,
  predicate,
  robust = c("sd", "2sd", "gmd", "mad"),
  include.fac = FALSE,
  append = TRUE,
  suffix = "_z"
)

center(x, ..., include.fac = FALSE, append = TRUE, suffix = "_c")

center_if(x, predicate, include.fac = FALSE, append = TRUE, suffix = "_c")

Arguments

Details

std() and center() also work on grouped data frames (see [group_by](../../dplyr/refman/dplyr.html#topic+group%5Fby)). In this case, standardization or centering is applied to the subsets of variables in x. See 'Examples'.

For more complicated models with many predictors, Gelman and Hill (2007) suggest leaving binary inputs as is and only standardize continuous predictors by dividing by two standard deviations. This ensures a rough comparability in the coefficients.

Value

If x is a vector, returns a vector with standardized or centered variables. If x is a data frame, for append = TRUE,x including the transformed variables as new columns is returned; if append = FALSE, only the transformed variables will be returned. If append = TRUE and suffix = "", recoded variables will replace (overwrite) existing variables.

Note

std() and center() only return a vector, if x is a vector. If x is a data frame and only one variable is specified in the ...-ellipses argument, both functions do return a data frame (see 'Examples').

References

Examples

data(efc)
std(efc$c160age) %>% head()
std(efc, e17age, c160age, append = FALSE) %>% head()

center(efc$c160age) %>% head()
center(efc, e17age, c160age, append = FALSE) %>% head()

# NOTE!
std(efc$e17age) # returns a vector
std(efc, e17age) # returns a data frame

# with quasi-quotation
x <- "e17age"
center(efc, !!x, append = FALSE) %>% head()

# works with mutate()
library(dplyr)
efc %>%
  select(e17age, neg_c_7) %>%
  mutate(age_std = std(e17age), burden = center(neg_c_7)) %>%
  head()

# works also with grouped data frames
mtcars %>% std(disp)

# compare new column "disp_z" w/ output above
mtcars %>%
  group_by(cyl) %>%
  std(disp)

data(iris)
# also standardize factors
std(iris, include.fac = TRUE, append = FALSE)
# don't standardize factors
std(iris, include.fac = FALSE, append = FALSE)

# standardize only variables with more than 10 unique values
p <- function(x) dplyr::n_distinct(x) > 10
std_if(efc, predicate = p, append = FALSE)

Check if string contains pattern

Description

This functions checks whether a string or character vectorx contains the string pattern. By default, this function is case sensitive.

Usage

str_contains(x, pattern, ignore.case = FALSE, logic = NULL, switch = FALSE)

Arguments

Details

This function iterates all elements in pattern and looks for each of these elements if it is found in_any_ element of x, i.e. which elements of pattern are found in the vector x.

Technically, it iterates pattern and callsgrep(x, pattern[i], fixed = TRUE) for each element of pattern. If switch = TRUE, it iteratespattern and calls grep(pattern[i], x, fixed = TRUE)for each element of pattern. Hence, in the latter case (if switch = TRUE), x must be of length 1.

Value

TRUE if x contains pattern.

Examples

str_contains("hello", "hel")
str_contains("hello", "hal")

str_contains("hello", "Hel")
str_contains("hello", "Hel", ignore.case = TRUE)

# which patterns are in "abc"?
str_contains("abc", c("a", "b", "e"))

# is pattern in any element of 'x'?
str_contains(c("def", "abc", "xyz"), "abc")
# is "abcde" in any element of 'x'?
str_contains(c("def", "abc", "xyz"), "abcde") # no...
# is "abc" in any of pattern?
str_contains("abc", c("defg", "abcde", "xyz12"), switch = TRUE)

str_contains(c("def", "abcde", "xyz"), c("abc", "123"))

# any pattern in "abc"?
str_contains("abc", c("a", "b", "e"), logic = "or")

# all patterns in "abc"?
str_contains("abc", c("a", "b", "e"), logic = "and")
str_contains("abc", c("a", "b"), logic = "and")

# no patterns in "abc"?
str_contains("abc", c("a", "b", "e"), logic = "not")
str_contains("abc", c("d", "e", "f"), logic = "not")

Find partial matching and close distance elements in strings

Description

This function finds the element indices of partial matching or similar strings in a character vector. Can be used to find exact or slightly mistyped elements in a string vector.

Usage

str_find(string, pattern, precision = 2, partial = 0, verbose = FALSE)

Arguments

Details

Computation Details

Fuzzy string matching is based on regular expressions, in particulargrep(pattern = "(<pattern>){~<precision>}", x = string). This means, precision indicates the number of chars inside patternthat may differ in string to cosinder it as "matching". The higherprecision is, the more tolerant is the search (i.e. yielding more possible matches). Furthermore, the higher the value for partialis, the more matches may be found.

Partial Distance Matching

For partial = 1, a substring of length(pattern) is extracted from string, starting at position 0 in string until the end of string is reached. Each substring is matched againstpattern, and results with a maximum distance of precisionare considered as "matching". If partial = 2, the range of the extracted substring is increased by 2, i.e. the extracted substring is two chars longer and so on.

Value

A numeric vector with index position of elements in string that partially match or are similar to pattern. Returns -1 if no match was found.

Note

This function does not return the position of a matching string _inside_another string, but the element's index of the string vector, where a (partial) match with pattern was found. Thus, searching for "abc" in a string "this is abc" will not return 9 (the start position of the substring), but 1 (the element index, which is always 1 if string only has one element).

See Also

[group_str](#topic+group%5Fstr)

Examples

string <- c("Hello", "Helo", "Hole", "Apple", "Ape", "New", "Old", "System", "Systemic")
str_find(string, "hel")   # partial match
str_find(string, "stem")  # partial match
str_find(string, "R")     # no match
str_find(string, "saste") # similarity to "System"

# finds two indices, because partial matching now
# also applies to "Systemic"
str_find(string,
        "sytsme",
        partial = 1)

# finds partial matching of similarity
str_find("We are Sex Pistols!", "postils")

Find start and end index of pattern in string

Description

str_start() finds the beginning position of patternin each element of x, while str_end() finds the stopping position of pattern in each element of x.

Usage

str_start(x, pattern, ignore.case = TRUE, regex = FALSE)

str_end(x, pattern, ignore.case = TRUE, regex = FALSE)

Arguments

Value

A numeric vector with index of start/end position(s) of patternfound in x, or -1, if pattern was not found in x.

Examples

path <- "this/is/my/fileofinterest.csv"
str_start(path, "/")

path <- "this//is//my//fileofinterest.csv"
str_start(path, "//")
str_end(path, "//")

x <- c("my_friend_likes me", "your_friend likes_you")
str_start(x, "_")

# pattern "likes" starts at position 11 in first, and
# position 13 in second string
str_start(x, "likes")

# pattern "likes" ends at position 15 in first, and
# position 17 in second string
str_end(x, "likes")

x <- c("I like to move it, move it", "You like to move it")
str_start(x, "move")
str_end(x, "move")

x <- c("test1234testagain")
str_start(x, "\\d+4")
str_start(x, "\\d+4", regex = TRUE)
str_end(x, "\\d+4", regex = TRUE)

Clean values of character vectors.

Description

This function "cleans" values of a character vector or levels of a factor by removing space and punctuation characters.

Usage

tidy_values(x, ...)

clean_values(x, ...)

Arguments

Value

x, with "cleaned" values or levels.

Examples

f1 <- sprintf("Char %s", sample(LETTERS[1:5], size = 10, replace = TRUE))
f2 <- as.factor(sprintf("F / %s", sample(letters[1:5], size = 10, replace = TRUE)))
f3 <- sample(1:5, size = 10, replace = TRUE)

x <- data.frame(f1, f2, f3, stringsAsFactors = FALSE)

clean_values(f1)
clean_values(f2)
clean_values(x)

Split (categorical) vectors into dummy variables

Description

This function splits categorical or numeric vectors with more than two categories into 0/1-coded dummy variables.

Usage

to_dummy(x, ..., var.name = "name", suffix = c("numeric", "label"))

Arguments

Value

A data frame with dummy variables for each category of x. The dummy coded variables are of type [atomic](../../../../doc/manuals/r-patched/packages/base/refman/base.html#topic+atomic).

Note

NA values will be copied from x, so each dummy variable has the same amount of NA's at the same position as x.

Examples

data(efc)
head(to_dummy(efc$e42dep))

# add value label as suffix to new variable name
head(to_dummy(efc$e42dep, suffix = "label"))

# use "dummy" as new variable name
head(to_dummy(efc$e42dep, var.name = "dummy"))

# create multiple dummies, append to data frame
to_dummy(efc, c172code, e42dep)

# pipe-workflow
library(dplyr)
efc %>%
  select(e42dep, e16sex, c172code) %>%
  to_dummy()

Convert wide data to long format

Description

This function converts wide data into long format. It allows to transform multiple key-value pairs to be transformed from wide to long format in one single step.

Usage

to_long(data, keys, values, ..., labels = NULL, recode.key = FALSE)

Arguments

Details

This function reshapes data from wide to long format, however, you can gather multiple column groups at once. Value and variable labels for non-gathered variables are preserved. Attributes from gathered variables, such as information about the variable labels, are lost during reshaping. Hence, the new created variables from gathered columns don't have any variable label attributes. In such cases, use labels argument to set back variable label attributes.

See Also

[reshape_longer](#topic+reshape%5Flonger)

Examples

# create sample
mydat <- data.frame(age = c(20, 30, 40),
                    sex = c("Female", "Male", "Male"),
                    score_t1 = c(30, 35, 32),
                    score_t2 = c(33, 34, 37),
                    score_t3 = c(36, 35, 38),
                    speed_t1 = c(2, 3, 1),
                    speed_t2 = c(3, 4, 5),
                    speed_t3 = c(1, 8, 6))

# gather multiple columns. both time and speed are gathered.
to_long(
  data = mydat,
  keys = "time",
  values = c("score", "speed"),
  c("score_t1", "score_t2", "score_t3"),
  c("speed_t1", "speed_t2", "speed_t3")
)

# alternative syntax, using "reshape_longer()"
reshape_longer(
  mydat,
  columns = list(
    c("score_t1", "score_t2", "score_t3"),
    c("speed_t1", "speed_t2", "speed_t3")
  ),
  names.to = "time",
  values.to = c("score", "speed")
)

# or ...
reshape_longer(
  mydat,
  list(3:5, 6:8),
  names.to = "time",
  values.to = c("score", "speed")
)

# gather multiple columns, use numeric key-value
to_long(
  data = mydat,
  keys = "time",
  values = c("score", "speed"),
  c("score_t1", "score_t2", "score_t3"),
  c("speed_t1", "speed_t2", "speed_t3"),
  recode.key = TRUE
)

# gather multiple columns by colum names and colum indices
to_long(
  data = mydat,
  keys = "time",
  values = c("score", "speed"),
  c("score_t1", "score_t2", "score_t3"),
  6:8,
  recode.key = TRUE
)

# gather multiple columns, use separate key-columns
# for each value-vector
to_long(
  data = mydat,
  keys = c("time_score", "time_speed"),
  values = c("score", "speed"),
  c("score_t1", "score_t2", "score_t3"),
  c("speed_t1", "speed_t2", "speed_t3")
)

# gather multiple columns, label columns
mydat <- to_long(
  data = mydat,
  keys = "time",
  values = c("score", "speed"),
  c("score_t1", "score_t2", "score_t3"),
  c("speed_t1", "speed_t2", "speed_t3"),
  labels = c("Test Score", "Time needed to finish")
)

library(sjlabelled)
str(mydat$score)
get_label(mydat$speed)

Convert factors to numeric variables

Description

This function converts (replaces) factor levels with the related factor level index number, thus the factor is converted to a numeric variable. to_value() and to_numeric() are aliases.

Usage

to_value(x, ..., start.at = NULL, keep.labels = TRUE, use.labels = FALSE)

Arguments

Value

A numeric variable with values ranging either from start.at tostart.at + length of factor levels, or to the corresponding factor levels (if these were numeric). If x is a data frame, the complete data frame x will be returned, where variables specified in ... are coerced to numeric; if ... is not specified, applies to all variables in the data frame.

Note

This function is kept for backwards-compatibility. It is preferred to use [as_numeric](../../sjlabelled/refman/sjlabelled.html#topic+as%5Fnumeric).

Examples

library(sjlabelled)
data(efc)
test <- as_label(efc$e42dep)
table(test)
table(to_value(test))

# Find more examples at '?sjlabelled::as_numeric'

Trim leading and trailing whitespaces from strings

Description

Trims leading and trailing whitespaces from strings or character vectors.

Usage

trim(x)

Arguments

Value

Trimmed x, i.e. with leading and trailing spaces removed.

Examples

trim("white space at end ")
trim(" white space at start and end ")
trim(c(" string1 ", "   string2", "string 3   "))

tmp <- data.frame(a = c(" string1 ", "   string2", "string 3   "),
                  b = c(" strong one  ", "    string two", "  third string "),
                  c = c(" str1 ", "   str2", "str3   "))
tmp
trim(tmp)

Return the typical value of a vector

Description

This function returns the "typical" value of a variable.

Usage

typical_value(x, fun = "mean", weights = NULL, ...)

Arguments

Details

By default, for numeric variables, typical_value() returns the mean value of x (unless changed with the fun-argument).

For factors, the reference level is returned or the most common value (if fun = "mode"), unless fun is a named vector. Iffun is a named vector, specify the function for integer, numeric and categorical variables as element names, e.g.fun = c(integer = "median", factor = "mean"). In this case, factors are converted to numeric values (using [to_value](#topic+to%5Fvalue)) and the related function is applied. You may abbreviate the namesfun = c(i = "median", f = "mean"). See also 'Examples'.

For character vectors the most common value (mode) is returned.

Value

The "typical" value of x.

Examples

data(iris)
typical_value(iris$Sepal.Length)

library(purrr)
map(iris, ~ typical_value(.x))

# example from ?stats::weighted.mean
wt <- c(5,  5,  4,  1) / 15
x <- c(3.7, 3.3, 3.5, 2.8)

typical_value(x, fun = "weighted.mean")
typical_value(x, fun = "weighted.mean", weights = wt)

# for factors, return either reference level or mode value
set.seed(123)
x <- sample(iris$Species, size = 30, replace = TRUE)
typical_value(x)
typical_value(x, fun = "mode")

# for factors, use a named vector to apply other functions than "mode"
map(iris, ~ typical_value(.x, fun = c(n = "median", f = "mean")))

Rename variables

Description

This function renames variables in a data frame, i.e. it renames the columns of the data frame.

Usage

var_rename(x, ..., verbose = TRUE)

rename_variables(x, ..., verbose = TRUE)

rename_columns(x, ..., verbose = TRUE)

Arguments

Value

x, with new column names for those variables specified in ....

Examples

dummy <- data.frame(
  a = sample(1:4, 10, replace = TRUE),
  b = sample(1:4, 10, replace = TRUE),
  c = sample(1:4, 10, replace = TRUE)
)

rename_variables(dummy, a = "first.col", c = "3rd.col")

# using quasi-quotation
library(rlang)
v1 <- "first.col"
v2 <- "3rd.col"
rename_variables(dummy, a = !!v1, c = !!v2)

x1 <- "a"
x2 <- "b"
rename_variables(dummy, !!x1 := !!v1, !!x2 := !!v2)

# using a named vector
new_names <- c(a = "first.col", c = "3rd.col")
rename_variables(dummy, new_names)

Determine variable type

Description

This function returns the type of a variable as character. It is similar to pillar::type_sum(), however, the return value is not truncated, and var_type() works on data frames and within pipe-chains.

Usage

var_type(x, ..., abbr = FALSE)

Arguments

Value

The variable type of x, as character.

Examples

data(efc)

var_type(1)
var_type(1L)
var_type("a")

var_type(efc$e42dep)
var_type(to_factor(efc$e42dep))

library(dplyr)
var_type(efc, contains("cop"))

Insert line breaks in long labels

Description

Insert line breaks in long character strings. Useful if you want to wordwrap labels / titles for plots or tables.

Usage

word_wrap(labels, wrap, linesep = NULL)

Arguments

Value

New label(s) with line breaks inserted at every wrap's position.

Examples

word_wrap(c("A very long string", "And another even longer string!"), 10)

message(word_wrap("Much too long string for just one line!", 15))

Convert infiite or NaN values into regular NA

Description

Replaces all infinite (Inf and -Inf) or NaNvalues with regular NA.

Usage

zap_inf(x, ...)

Arguments

Value

x, where all Inf, -Inf and NaN are converted to NA.

Examples

x <- c(1, 2, NA, 3, NaN, 4, NA, 5, Inf, -Inf, 6, 7)
zap_inf(x)

data(efc)
# produce some NA and NaN values
efc$e42dep[1] <- NaN
efc$e42dep[2] <- NA
efc$c12hour[1] <- NaN
efc$c12hour[2] <- NA
efc$e17age[2] <- NaN
efc$e17age[1] <- NA

# only zap NaN for c12hour
zap_inf(efc$c12hour)

# only zap NaN for c12hour and e17age, not for e42dep,
# but return complete data framee
zap_inf(efc, c12hour, e17age)

# zap NaN for complete data frame
zap_inf(efc)