map_values: Map values or names

Description Usage Arguments Details Value See Also Examples

Description

Map values using a character vector, a function or an expression, or use a character vector or a function for recursively mapping list names, or mapping the colnames and rownames attributes of a data frame or matrix.

Usage

 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
74
75
76
77
78
79
80
81
82
83
  ## S4 method for signature 'ANY,character'
map_names(object, mapping) 
  ## S4 method for signature 'ANY,function'
map_names(object, mapping, ...) 
  ## S4 method for signature 'ANY,missing'
map_names(object) 
  ## S4 method for signature 'array,character'
map_names(object, mapping) 
  ## S4 method for signature 'array,function'
map_names(object, mapping, ...) 
  ## S4 method for signature 'array,missing'
map_names(object) 
  ## S4 method for signature 'data.frame,character'
map_names(object, mapping) 
  ## S4 method for signature 'data.frame,function'
map_names(object, mapping, ...)
  ## S4 method for signature 'data.frame,missing'
map_names(object) 
  ## S4 method for signature 'list,character'
map_names(object, mapping) 
  ## S4 method for signature 'list,function'
map_names(object, mapping, ...) 
  ## S4 method for signature 'list,missing'
map_names(object) 

  ## S4 method for signature 'NULL,character'
map_values(object, mapping) 
  ## S4 method for signature 'NULL,function'
map_values(object, mapping, ...) 
  ## S4 method for signature 'NULL,missing'
map_values(object, mapping) 
  ## S4 method for signature 'array,character'
map_values(object, mapping, coerce = TRUE)
  ## S4 method for signature 'array,function'
map_values(object, mapping, ...) 
  ## S4 method for signature 'array,missing'
map_values(object, coerce = TRUE) 
  ## S4 method for signature 'character,NULL'
map_values(object, mapping) 
  ## S4 method for signature 'character,character'
map_values(object, mapping) 
  ## S4 method for signature 'character,function'
map_values(object, mapping, ...)
  ## S4 method for signature 'character,missing'
map_values(object) 
  ## S4 method for signature 'character,numeric'
map_values(object, mapping, ...)
  ## S4 method for signature 'data.frame,NULL'
map_values(object, mapping, coerce = character(), ...)
  ## S4 method for signature 'data.frame,character'
map_values(object, mapping, coerce = character())
  ## S4 method for signature 'data.frame,function'
map_values(object, mapping, coerce = character(), ...)
  ## S4 method for signature 'data.frame,list'
map_values(object, mapping) 
  ## S4 method for signature 'data.frame,missing'
map_values(object, coerce = character())
  ## S4 method for signature 'factor,character'
map_values(object, mapping) 
  ## S4 method for signature 'factor,function'
map_values(object, mapping, ...)
  ## S4 method for signature 'factor,missing'
map_values(object) 
  ## S4 method for signature 'factor,numeric'
map_values(object, mapping, ...)
  ## S4 method for signature 'list,NULL'
map_values(object, mapping, coerce = character())
  ## S4 method for signature 'list,character'
map_values(object, mapping, coerce = character())
  ## S4 method for signature 'list,expression'
map_values(object, mapping, coerce = parent.frame())
  ## S4 method for signature 'list,function'
map_values(object, mapping, coerce = character(), ...)
  ## S4 method for signature 'list,missing'
map_values(object, mapping, coerce = character())
  ## S4 method for signature 'logical,NULL'
map_values(object, mapping) 
  ## S4 method for signature 'logical,function'
map_values(object, mapping, ...)
  ## S4 method for signature 'logical,missing'
map_values(object) 
  ## S4 method for signature 'logical,vector'
map_values(object, mapping) 

Arguments

object

When mapping values, a list (may be nested), data frame or character vector. If it has names, they are preserved. NULL can also be given and yields NULL or an empty named character vector (if mapping is missing). object may also be an array (which includes matrices).

When mapping names, object can be any R object. The default method applies the mapping to the ‘names’ attribute. The behaviour is special for lists, which are traversed recursively to also consider contained lists with names. Data frames and array objects (that is, including matrices) are also treated specially because the dimnames attribute, not the ‘names’ attribute is considered.

mapping

When mapping values, a character vector, function, expression, numeric scalar, list, NULL or missing.

  • If a character vector, used as a mapping from its names to its values. Values from object are searched for in the names attribute of mapping; those found are replaced by the corresponding values of mapping.

  • If mapping is missing, a character vector is returned (sorted and with duplicates removed) whose names are identical to the values. This eases the construction of mapping vectors specific for object. If mapping is missing, the coerce argument must be named. mapping changes its usage if coerce is TRUE.

  • For array objects, if mapping was a function, it would be applied to object after conversion with as.vector, and it would be attempted to add the original attributes (particularly important are ‘dim’ and dimnames back to the result.

  • For array objects, if mapping is the usual character vector, it then is used for mapping the storage.mode, not the class of object.

  • If mapping is an expression, all sub-expressions will be evaluated in object represented as an environment, which after conversion back to a list, is returned.

  • If mapping is NULL and object is a list, all contained objects of zero length are removed recursively.

  • If mapping is a numeric scalar and object is a character vector or factor, a mapping (named character vector) is created that translates groups of similar strings to their most frequent member.

  • If mapping is a list and object is a data frame, the names of mapping specify the columns of object to map. Only factors and character vectors within object are modified, and it is an error if mapping does not list all of them, or has no names at all. Three potential names of mapping are special. . must refer to a named character vector and is used for mapping the column names of object. _, containing a named list, is used for adding columns. / pointing to a character vector provides a set of columns to delete. - provides a named list for deleting rows; the names are the names of the columns and the values the values within that column that indicate the rows to delete. Behaviour is special when mapping is an empty list; in that case, a template for a real mapping list is generated.

When mapping names, a mapping function that takes a character vector as first argument, or character vector used for mapping from its names to its values, or missing. It is guaranteed that NULL input remains NULL, irrespective of the value of mapping.

coerce

The usage of this argument depends on object.

  • A character vector with the names of classes that are coerced to ‘character’ to allow the mapping. Other classes are returned unchanged. Note that the coerced data are not converted back to their original data type. ‘ANY’ can be used to indicate that all classes will be considered.

  • Alternatively, coerce can be TRUE. mapping is then interpreted as a mapping between the names of classes, and as from the methods package is used for conducting the requested coercions. Attempting an undefined coercion will result in an error.

  • For the expression method, an enclosing environment to look up objects that are not found in mapping.

...

Optional further arguments to mapping (if it is a function).

Details

Mapping of ‘character’ data using another ‘character’ vector is possible, as well as recursively applying a mapping function to all ‘character’ values within a list, or non-recursively to a data frame. Optionally other data types are coerced to ‘character’; the remaining ones are returned unchanged. It is also possible to map between classes using coercion functions. For convenience in programming, methods for the ‘NULL’ class are also available.

Mapping of logical vectors using another vector expects (at least) three elements within the mapping vector, i.e. the values to be used for FALSE, NA and TRUE elements in object. Nothing is modified if the mapping is NULL. The default mapping vector c(1L, 2L, 3L) is used if mapping is missing.

In the case of lists, the function passed to map_names is not applied to list elements which are not themselves lists, even if they have a ‘names’ attribute. Such elements and their names, if any, are returned unchanged. If a ‘names’, colnames or rownames attribute is NULL, it is ignored.

Alternatively, instead of mapping the names, collect them and return them as a single character vector, sorted and with duplicates removed. The collected names are added as their own names attribute; this might be useful if the result is later on used for some mapping (using this function or map_values).

The method for a numeric mapping argument and strings or factors as object argument can be used to correct misspellings. It is based on adist from the base package, to which the ... arguments are passed. mapping indicates the maximum string distance allowed when placing strings into the same group. Distances are calculated as output of adist divided by the larger of the two strings length for partial = FALSE (the default) and the smaller one otherwise. ignore.case is TRUE per default, useBytes is FALSE. Clustering is done by single linkage for partial = FALSE, by complete linkage for partial = TRUE. An additional argument exclude, if a non-empty string, is used as a PERL-compatible regular expression to remove strings prior to determining misspellings.

Value

map_values returns a list, data frame, a character or logical vector or NULL.

map_names yields a character vector if mapping is missing, otherwise an R object of the same class than object.

See Also

base::rapply base::list base::as.list methods::as base::class base::storage.mode base::as.vector

Other coding-functions: L, LL, assert, case, check, collect, contains, flatten, listing, must, set, sql, unnest

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
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
## map_values()

# Character/character method
map <- letters
names(map) <- rev(LETTERS)
(x <- map_values(LETTERS, map))
stopifnot(rev(x) == letters)

# Character/missing method
(x <- map_values(letters))
stopifnot(x == letters, names(x) == letters)

# Character/function method
x <- letters[1:4]
names(x) <- LETTERS[1:4]
(y <- map_values(x, function(z) sprintf("%s%s", z, z)))
stopifnot(names(y) == names(x), y != x)

# Character/numeric method
x <- c("car", "cars", "car", "care", " Car")
(y <- map_values(x, 0.25))
stopifnot(length(y) == 3, y == "car")

# List/character method
x <- list(a = 1:8, c = 9, d = 'x')
map <- c(a = "b", e = "f", x = "y")
(y <- map_values(x, map))
stopifnot(identical(x[1:2], y[1:2]), !identical(x[3], y[3]))
(y <- map_values(x, map, coerce = "integer"))
stopifnot(identical(x[2], y[2]), !identical(x[1], y[1]),
  !identical(x[3], y[3]))
(y <- map_values(x, map, coerce = TRUE))
stopifnot(identical(x, y))
(y <- map_values(x, c(numeric = "character"), coerce = TRUE))
stopifnot(identical(x[1], y[1]), !identical(x[2], y[2]),
  identical(x[3], y[3]))

# List/function method
(y <- map_values(x, identity, coerce = "ANY"))
stopifnot(identical(x, y))
(y <- map_values(x, class, coerce = "ANY"))
stopifnot(sapply(y, class) == "character", names(y) == names(x))

# List/missing method
(y <- map_values(x))
stopifnot(y == "x", names(y) == y)
(y <- map_values(x, coerce = "integer"))
stopifnot(length(y) == 9, names(y) == y)
(y <- map_values(x, coerce = c("integer", "numeric")))
stopifnot(length(y) == 10, names(y) == y)
(y <- map_values(x, coerce = "ANY")) # same effect
stopifnot(length(y) == 10, names(y) == y)
(y <- map_values(x, coerce = TRUE))
stopifnot(y == c("character", "integer", "numeric"), names(y) == y)

# List/expression method
(y <- map_values(x, expression(b <- a + c)))
stopifnot(is.list(y), y$b == c(10:17))

# List/expression method applied to a data frame
x <- data.frame(a = 1:5, b = 6:10)
(y <- map_values(x, expression(c <- a + b)))
stopifnot(is.data.frame(y), dim(y) == c(5, 3))

# Data frame/character method
x <- data.frame(a = 1:3, b = letters[1:3])
stopifnot(sapply(x, class) == c("integer", "factor"))
map <- c(a = "A", b = "B", c = "C", `1` = "5")
(y <- map_values(x, map))
stopifnot(identical(x, y))
(y <- map_values(x, map, coerce = "factor"))
stopifnot(!identical(x, y), y[[2]] == c("A", "B", "C"))
(y <- map_values(x, map, coerce = "ANY"))
stopifnot(y[[1]] == c("5", "2", "3"), y[[2]] == c("A", "B", "C"))
(y <- map_values(x, map, coerce = TRUE))
stopifnot(identical(x, y))
map <- c(factor = "character", integer = "complex")
(y <- map_values(x, map, coerce = TRUE))
stopifnot(sapply(y, class) == c("complex", "character"))

# Data frame/function method
(y <- map_values(x, `+`, coerce = "integer", y = 1L))
stopifnot(y$a == x$a + 1L)
(y <- map_values(x, as.character, coerce = "factor"))
stopifnot(sapply(y, class) == c("integer", "character"))

# Data frame/missing method
(y <- map_values(x))
stopifnot(is.character(y), length(y) == 0)
(y <- map_values(x, coerce = "factor"))
stopifnot(is.character(y), y == letters[1:3], names(y) == y)
(y <- map_values(x, coerce = "ANY"))
stopifnot(is.character(y), length(y) == 6, names(y) == y)
(y <- map_values(x, coerce = TRUE))
stopifnot(is.character(y), y == c("factor", "integer"), names(y) == y)

# Matrix/character method
(x <- matrix(1:6, nrow = 2))
(y <- map_values(x, c(integer = "numeric"), coerce = TRUE))
stopifnot(storage.mode(x) != storage.mode(y))
(y <- map_values(x, c(`1` = "7"), coerce = "integer"))
stopifnot(is.character(y), y[-1] == x[-1])

# Matrix/function method
(y <- map_values(x, identity))
stopifnot(identical(x, y))
(y <- map_values(x, `+`, y = 1)) # useless because '+' is directly available
stopifnot(dim(y) == dim(x), y == x + 1)

# Matrix/missing method
(y <- map_values(x))
stopifnot(y == "integer", names(y) == y)
(y <- map_values(x, coerce = "ANY"))
stopifnot(is.character(y), y == 1:6, names(y) == y)

# Factor/function method
x <- as.factor(c("a", "b", "a"))
(y <- map_values(x, toupper))
stopifnot(is.factor(y), y == toupper(x))

# Factor/character method
(y <- map_values(x, c(b = "c", k = "h")))
stopifnot(is.factor(y), levels(y) == c("a", "c"))

# Factor/missing method
(y <- map_values(x))
stopifnot(levels(x) == y, names(y) == y)

## map_names()

# List/function method
x <- list(a = 1:8, c = 9, d = 'x')
map <- function(x) sprintf("%s%s", x, x)
(y <- map_names(x, map))
stopifnot(identical(as.character(x), as.character(y)))
stopifnot(!identical(names(x), names(y)))

# List/character method
x <- list(a = 1:8, c = 9, d = 'x')
map <- c(a = "b", e = "f", x = "y")
(y <- map_names(x, map))
stopifnot(identical(as.character(x), as.character(y)))
stopifnot(!identical(names(x), names(y)))
# compare with the map_values() example

# List/missing method
x <- list(a = 1:8, c = 9, d = 'x')
(y <- map_names(x))
stopifnot(identical(as.vector(y), names(x)))
stopifnot(identical(names(y), names(x)))
# Now a recursive list
x <- list(a = 1:8, c = 9, d = list(d1 = 'x', d2 = 'y'))
(y <- map_names(x))
stopifnot(length(y) > length(names(x)))

# Data frame/function method
x <- data.frame(a = 1:3, b = letters[1:3])
(y <- map_names(x, toupper))
stopifnot(identical(y[[1]], x[[1]]), identical(y[[2]], x[[2]]))
stopifnot(identical(names(y), c("A", "B")))

# Data frame/character method
(y <- map_names(x, c(a = "b", b = "a")))
stopifnot(x == y, names(y) == c("b", "a"))

# Data frame/missing method
(y <- map_names(x))
stopifnot(is.character(y), y == names(y), length(y) == 5)

# Matrix/function method
x <- as.matrix(x)
(y <- map_names(x, toupper))
stopifnot(x == y, toupper(colnames(x)) == colnames(y))

# Matrix/character method
(y <- map_names(x, c(a = "b", b = "a")))
stopifnot(x == y, colnames(y) == c("b", "a"))

# Matrix/missing method
(y <- map_names(x))
stopifnot(y == c("a", "b"), names(y) == y)

pkgutils documentation built on May 2, 2019, 5:49 p.m.