get_labels: Retrieve value labels of labelled data

Description Usage Arguments Details Value Note See Also Examples

Description

This function returns the value labels of labelled data.

Usage

1
2
get_labels(x, attr.only = FALSE, include.values = NULL,
  include.non.labelled = FALSE, drop.na = TRUE, drop.unused = FALSE)

Arguments

x

A data frame with variables that have value label attributes (e.g. from an imported SPSS, SAS or STATA data set, via read_spss, read_sas or read_stata); a variable (vector) with value label attributes; or a list of variables with values label attributes. If x has no label attributes, factor levels are returned. See 'Examples'.

attr.only

Logical, if TRUE, labels are only searched for in the the vector's attributes; else, if attr.only = FALSE and x has no label attributes, factor levels or string values are returned. See 'Examples'.

include.values

String, indicating whether the values associated with the value labels are returned as well. If include.values = "as.name" (or include.values = "n"), values are set as names attribute of the returned object. If include.values = "as.prefix" (or include.values = "p"), values are included as prefix to each label. See 'Examples'.

include.non.labelled

Logical, if TRUE, values without labels will also be included in the returned labels (see fill_labels).

drop.na

Logical, whether labels of tagged NA values (see tagged_na) should be included in the return value or not. By default, labelled (tagged) missing values are not returned. See get_na for more details on tagged NA values.

drop.unused

Logical, if TRUE, unused labels will be removed from the return value.

Details

This package can add (and read) value and variable labels either in foreign package style (attributes are named value.labels and variable.label) or in haven package style (attributes are named labels and label). By default, the haven package style is used.

Working with labelled data is a key feature of the sjPlot package, which accesses these attributes to automatically read label attributes for labelling axis categories and titles or table rows and columns in graphical or tabular outputs.

When working with labelled data, you can, e.g., use get_label or get_labels to get a vector of value and variable labels, which can then be used with other functions like barplot etc. See 'Examples'. Furthermore, value and variable labels are used when saving data, e.g. to SPSS (see write_spss), which means that the written SPSS file contains proper labels for each variable.

Value

Either a list with all value labels from all variables if x is a data.frame or list; a string with the value labels, if x is a variable; or NULL if no value label attribute was found.

Note

This function works with vectors that have value and variable label attributes (as provided, for instance, by labelled objects). Adding label attributes is automatically done when importing data sets with the read_spss, read_sas or read_stata functions. Labels can also manually be added using the set_labels and set_label functions. If vectors do not have label attributes, either factor-levels or the numeric values of the vector are returned as labels.

Most functions of the sjPlot package make use of value and variable labels to automatically label axes, legend or title labels in plots (sjp.-functions) respectively column or row headers in table outputs (sjt.-functions).

See Also

See vignette Labelled Data and the sjmisc-Package for more details; set_labels to manually set value labels, get_label to get variable labels and get_values to retrieve the values associated with value labels.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
# import SPSS data set
# mydat <- read_spss("my_spss_data.sav")

# retrieve variable labels
# mydat.var <- get_label(mydat)

# retrieve value labels
# mydat.val <- get_labels(mydat)

data(efc)
get_labels(efc$e42dep)

# simple barplot
barplot(table(efc$e42dep))
# get value labels to annotate barplot
barplot(table(efc$e42dep),
        names.arg = get_labels(efc$e42dep),
        main = get_label(efc$e42dep))

# include associated values
get_labels(efc$e42dep, include.values = "as.name")

# include associated values
get_labels(efc$e42dep, include.values = "as.prefix")

# get labels from multiple variables
get_labels(list(efc$e42dep, efc$e16sex, efc$e15relat))


# create a dummy factor
f1 <- factor(c("hi", "low", "mid"))
# search for label attributes only
get_labels(f1, attr.only = TRUE)
# search for factor levels as well
get_labels(f1)

# same for character vectors
c1 <- c("higher", "lower", "mid")
# search for label attributes only
get_labels(c1, attr.only = TRUE)
# search for string values as well
get_labels(c1)


# create vector
x <- c(1, 2, 3, 2, 4, NA)
# add less labels than values
x <- set_labels(x, labels = c("yes", "maybe", "no"), force.values = FALSE)
# get labels for labelled values only
get_labels(x)
# get labels for all values
get_labels(x, include.non.labelled = TRUE)


# get labels, including tagged NA values
library(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_labels(x, include.values = "n", drop.na = FALSE)


# create vector with unused labels
data(efc)
efc$e42dep <- set_labels(
  efc$e42dep,
  labels = c("independent" = 1, "dependent" = 4, "not used" = 5)
)
get_labels(efc$e42dep)
get_labels(efc$e42dep, drop.unused = TRUE)
get_labels(efc$e42dep, include.non.labelled = TRUE, drop.unused = TRUE)


Search within the sjmisc package
Search all R packages, documentation and source code

Questions? Problems? Suggestions? or email at ian@mutexlabs.com.

Please suggest features or report bugs with the GitHub issue tracker.

All documentation is copyright its authors; we didn't write any of that.