| Title: | Simple Handling of Labelled Data |
|---|---|
| Description: | Simple handling of survey data. Smart handling of meta-information like e.g. variable-labels value-labels and scale-levels. Easy access and validation of meta-information. Useage of value labels and values respectively for subsetting and recoding data. |
| Authors: | Christof Lewerenz [aut, cre] |
| Maintainer: | Christof Lewerenz <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.0.1 |
| Built: | 2025-02-19 06:30:28 UTC |
| Source: | https://github.com/clewerenz/ilabelled |
evaluate dots argument
.eval_dots_arg(..., flatten = FALSE).eval_dots_arg(..., flatten = FALSE)
... |
dots passed from function input |
flatten |
should lists be flattened |
Make list from dots, unlist and evaluate.
vector
description description
.i_find_in(x, y).i_find_in(x, y)
x |
vector |
y |
vector |
Vector of T/F values with length of x
Find matches (return T/F)
.i_in(x, table).i_in(x, table)
x |
vector or NULL: the values to be matched. Long vectors are supported. |
table |
vector or NULL: the values to be matched against. Long vectors are not supported. |
Vector of T/F values with length of x
all arguments are passed from i_labelled
.init( x, label = NULL, labels = NULL, na_values = NULL, na_range = NULL, scale = NULL, annotation = NULL, wording = NULL, subject = NULL, ... ).init( x, label = NULL, labels = NULL, na_values = NULL, na_range = NULL, scale = NULL, annotation = NULL, wording = NULL, subject = NULL, ... )
x |
vector |
label |
variable label |
labels |
value labels as named vector |
na_values |
missing values (e.g. c(888, 999)) |
na_range |
range of missing values (e.g. c(-9,-1)) |
scale |
scale level (nominal, ordinal, scale) |
annotation |
additional information about variable |
wording |
question text |
subject |
subject |
... |
further attributes passed to class |
x as i_labelled object with attributes applied to it
checks if vector is numeric sequence
.is_sequential(x).is_sequential(x)
x |
vector |
T/F
combine old value labels with new value labels
.merge_labels(old_labs, new_labs).merge_labels(old_labs, new_labs)
old_labs |
named vector |
new_labs |
named vector |
Returns names vector of value labels
contains run-time-tests annotation runs internally
.valid_annotation(x).valid_annotation(x)
x |
character vector or NULL |
T/F
run-time-tests for variable label runs internally
.valid_label(x).valid_label(x)
x |
vector |
T/F
contains several run-time-tests for value labels runs internally
.valid_labels(x).valid_labels(x)
x |
named vector c(label = value) |
No return value. Aborts process when run-time-tests fail.
validate missing values/range - intern
.valid_missing(x).valid_missing(x)
x |
vector |
T/F
run-time-tests for scale level runs internally
.valid_scale(x).valid_scale(x)
x |
vector |
T/F
contains run-time-tests subject runs internally
.valid_subject(x).valid_subject(x)
x |
character vector or NULL |
T/F
contains run-time-tests wording runs internally
.valid_wording(x).valid_wording(x)
x |
character vector or NULL |
T/F
subsetting vectors of class i_labelled
## S3 method for class 'i_labelled' x[...]## S3 method for class 'i_labelled' x[...]
x |
vector of class i_labelled |
... |
not used |
Subset of x
subsetting vectors of class i_labelled
## S3 method for class 'i_labelled' x[[...]]## S3 method for class 'i_labelled' x[[...]]
x |
vector of class i_labelled |
... |
not used |
Subset of x
coerce to i_labelled class
as.i_labelled(x, ...)as.i_labelled(x, ...)
x |
vector |
... |
attributes passed to class |
vector of class i_labelled
generic for %in%
x %in% tablex %in% table
x |
vector or NULL: the values to be matched. Long vectors are supported. |
table |
vector or NULL: the values to be matched against. Long vectors are not supported. |
T/F
add annotation to i_labelled object
can be used to store additional information about a variable
i_annotation(x, annotation, overwrite = FALSE)i_annotation(x, annotation, overwrite = FALSE)
x |
vector |
annotation |
variable label as string or NULL (NULL will remove label) |
overwrite |
overwrite existing annotation and replace with new annotation |
x with annotation applied
make character from i_labelled
i_as_character( x, missing_to_na = FALSE, require_all_labels = FALSE, keep_attributes = FALSE )i_as_character( x, missing_to_na = FALSE, require_all_labels = FALSE, keep_attributes = FALSE )
x |
vector |
missing_to_na |
as missing declared values will become NA |
require_all_labels |
process will be interrupted, when not all values have valid labels |
keep_attributes |
should attributes be preserved |
character vector
make factor from i_labelled
i_as_factor( x, missing_to_na = FALSE, require_all_labels = FALSE, keep_attributes = FALSE )i_as_factor( x, missing_to_na = FALSE, require_all_labels = FALSE, keep_attributes = FALSE )
x |
vector |
missing_to_na |
as missing declared values will become NA |
require_all_labels |
process will be interrupted, when not all values have valid labels |
keep_attributes |
should attributes be preserved |
vector of class factor
make numeric from i_labelled
i_as_numeric(x, missing_to_na = FALSE, keep_attributes = FALSE)i_as_numeric(x, missing_to_na = FALSE, keep_attributes = FALSE)
x |
vector |
missing_to_na |
as missing declared values will become NA |
keep_attributes |
should attributes be preserved |
numeric vector
Check for required value labels in set of variables
i_assert_labels(x, labels, info = NULL, verbose = TRUE)i_assert_labels(x, labels, info = NULL, verbose = TRUE)
x |
data.frame |
labels |
character vector |
info |
string with info message (purpose of assertion) - optional |
verbose |
return TRUE when assertion is successful |
No return value (exept when verbose = T). Aborts process when test not valid.
copy meta information from one variable to another
i_copy(to, from, what = "all", overwrite = TRUE, ...)i_copy(to, from, what = "all", overwrite = TRUE, ...)
to |
vector |
from |
vector |
what |
character vector describing which attributes are copied. When 'all' (default), all attributes are copied. |
overwrite |
overwrite existing attributes when present in attributes of from. |
... |
further attributes passed to structure |
Returns 'to' with attributes copied from 'from'
return annotation as character vector applied to vector return list when applied to data.frame
i_get_annotation(x)i_get_annotation(x)
x |
vector or data.frame |
returns annotation
return all variable names by subjects
one, several, or all subjects can be looked up
i_get_equal_subject(x, subject = NULL)i_get_equal_subject(x, subject = NULL)
x |
data.frame |
subject |
one or more subjects as character vector. when NULL return all variable names by all subjects in data |
named list or NA. return named list with one list entry for each subject. when no subject in data or no match for subjects, return NA.
return all variable names by wordings
one, several, or all wordings can be looked up
i_get_equal_wording(x, wording = NULL)i_get_equal_wording(x, wording = NULL)
x |
data.frame |
wording |
one or more wordings as character vector. when NULL return all variable names by all wordings in data |
named list or NA. return named list with one list entry for each wording. when no wording in data or no match for wordings, return NA.
return variable label when applied to vector return list when applied to data.frame
i_get_label(x)i_get_label(x)
x |
vector or data.frame |
variable label
return labels when applied to vector return list when applied to data.frame
i_get_labels(x)i_get_labels(x)
x |
vector or data.frame |
values and value labels as data.frame
return missing range when applied to vector return list when applied to data.frame
i_get_na_range(x)i_get_na_range(x)
x |
vector or data.frame |
return missing range
return missing values when applied to vector return list when applied to data.frame
i_get_na_values(x)i_get_na_values(x)
x |
vector or data.frame |
return missing values
return scale level when applied to vector return list when applied to data.frame
i_get_scale(x)i_get_scale(x)
x |
vector or data.frame |
returns scale level
return subject as character vector applied to vector return list when applied to data.frame
i_get_subject(x)i_get_subject(x)
x |
vector or data.frame |
returns subject
return wording as character vector applied to vector return list when applied to data.frame
i_get_wording(x)i_get_wording(x)
x |
vector or data.frame |
returns wording
set variable label
i_label(x, label)i_label(x, label)
x |
vector |
label |
variable label as string or NULL (NULL will remove label) |
x with variable label applied
class constructor
i_labelled( x, label = NULL, labels = NULL, na_values = NULL, na_range = NULL, scale = NULL, annotation = NULL, wording = NULL, subject = NULL, ... )i_labelled( x, label = NULL, labels = NULL, na_values = NULL, na_range = NULL, scale = NULL, annotation = NULL, wording = NULL, subject = NULL, ... )
x |
vector or data.frame |
label |
variable label |
labels |
value labels as named vector (e.g. c("A"=1, "B"=2) or setNames(c(1,2), c("A","B"))) |
na_values |
missing values (e.g. c(888, 999)) |
na_range |
range of missing values as vector length 2 (e.g. c(-9,-1)) |
scale |
scale level (nominal, ordinal, scale) |
annotation |
additional information about variable |
wording |
question text |
subject |
subject |
... |
further attributes passed to class |
vector or data.frame
set value labels
i_labels(x, ..., overwrite = FALSE)i_labels(x, ..., overwrite = FALSE)
x |
vector |
... |
set labels for values (e.g. label_of_choice = 1 or "Label of Choice" = 1); remove single label with NULL = value (e.g. NULL = 1); removes all value labels when only NULL (e.g. i_label(x, NULL)) |
overwrite |
when TRUE, all existing labels are dropped and replaced with the new ones |
In order to assign a specific label to multiple values a named list can also be provided to ... (e.g. list(missing = -9:-1, valid = 1:3))
A named vector can also be provided (e.g. setNames(c(1,2), c("A","B")))
returns x with value labels applied
all values declared as missing will be recoded as NA
i_missing_to_na(x, remove_missing_labels = FALSE)i_missing_to_na(x, remove_missing_labels = FALSE)
x |
vector or data.frame |
remove_missing_labels |
remove values labels from values which are declared as missing |
Returns x with missing values coerced to NA
define which values will be handled as missing values
i_na_range(x, values)i_na_range(x, values)
x |
vector |
values |
vector with missing range e.g. c(-9:-1) or NULL (NULL will remove all missing values) |
Returns x with missing range set
define which values will be handled as missing values
i_na_values(x, values, sort = TRUE, desc = FALSE)i_na_values(x, values, sort = TRUE, desc = FALSE)
x |
vector |
values |
vector with missing values e.g. c(888,999) or NULL (NULL will remove all missing values) |
sort |
sort values |
desc |
sort values in descending order |
Returns x with missing values set
print annotation
i_print_annotation(x)i_print_annotation(x)
x |
vector |
No return value. Print annotation attribute to console
print attributes
i_print_attributes(x, exclude = NULL)i_print_attributes(x, exclude = NULL)
x |
vector |
exclude |
character vector with attribute names not taken into account |
No return value. Print attributes to console
print variable label
i_print_label(x)i_print_label(x)
x |
vector |
No return value. Print variable label to console
print value labels
i_print_labels(x)i_print_labels(x)
x |
vector |
No return value. Print labels to console
print missing range
i_print_na_range(x)i_print_na_range(x)
x |
vector |
No return value. Print na range to console
print missing values
i_print_na_values(x)i_print_na_values(x)
x |
vector |
No return value. Print na values to console
print scale level
i_print_scale(x)i_print_scale(x)
x |
vector |
No return value. Print scale level to console
print subject
i_print_subject(x)i_print_subject(x)
x |
vector |
No return value. Print subject attribute to console
print wording
i_print_wording(x)i_print_wording(x)
x |
vector |
No return value. Print wording attribute to console
Returns a vector object of class i_labelled
i_recode( x, ..., label = NULL, na_values = NULL, na_range = NULL, scale = NULL, annotation = NULL, wording = NULL, subject = NULL, copy = NULL, keep_labels = FALSE )i_recode( x, ..., label = NULL, na_values = NULL, na_range = NULL, scale = NULL, annotation = NULL, wording = NULL, subject = NULL, copy = NULL, keep_labels = FALSE )
x |
vector or data.frame |
... |
formula for recoding of values. See examples. |
label |
variable label |
na_values |
a vector with missing values |
na_range |
a vector for missing range |
scale |
scale level (nominal, ordinal, metric) |
annotation |
addition information about variable |
wording |
question text |
subject |
subject |
copy |
When applied to vector: T/F. When applied to a data.frame: a variable from x. Copy the values of an existing variable or x before recoding values according to ... |
keep_labels |
keep value labels from origin vector when copy TRUE or variable from x |
Can be applied to either vector or data.frame. When x is data.frame the formula passed to ... is different from when it is applied to single vector. When function is applied to a data.frame, multiple conditions on multiple variables are possible (e.g when variable X is equal to this, do that; when variable Y is not equal to this, do that, etc.). See examples for further clarification.
You can recode directly via value labels by using
Returns i_labelled vector with values defined by formula and information given to function.
# When applied to a single vector: # keep in mind that when function is applied to vector, instead of a column use x myVector <- i_labelled(1:4, labels = c("A" = 1, "B" = 2, "C" = 3, "D" = 4)) i_recode(x = myVector, "AB" = 1 ~ x %in% c("A", "B"), "CD" = 2 ~ x == c(3, 4)) # When applied to data.frame (multiple conditions) myData <- data.frame( V1 = i_labelled(1:3, labels = c("A" = 1, "B" = 2, "C" = 3)), V2 = i_labelled(c(2:3,-9)) ) i_recode(x = myData, A = 1 ~ V1 %in% c("A", "B"), 2 ~ "V2" == 3, "C" = 999 ~ V2 == -9)# When applied to a single vector: # keep in mind that when function is applied to vector, instead of a column use x myVector <- i_labelled(1:4, labels = c("A" = 1, "B" = 2, "C" = 3, "D" = 4)) i_recode(x = myVector, "AB" = 1 ~ x %in% c("A", "B"), "CD" = 2 ~ x == c(3, 4)) # When applied to data.frame (multiple conditions) myData <- data.frame( V1 = i_labelled(1:3, labels = c("A" = 1, "B" = 2, "C" = 3)), V2 = i_labelled(c(2:3,-9)) ) i_recode(x = myData, A = 1 ~ V1 %in% c("A", "B"), 2 ~ "V2" == 3, "C" = 999 ~ V2 == -9)
remove annotation label from variable keep other attributes
i_remove_annotation(x)i_remove_annotation(x)
x |
vector or data.frame |
Returns x without annotation
remove variable label keep other attributes
i_remove_label(x)i_remove_label(x)
x |
vector or data.frame |
Returns x without variable label
remove all value labels keep other attributes
i_remove_labels(x)i_remove_labels(x)
x |
vector or data.frame |
Returns x without value labels
remove values labels from values which are declared as missing
i_remove_missing_labels(x)i_remove_missing_labels(x)
x |
vector or data.frame |
Returns x without missing labels
remove na range (information which values should be handled as missing) keep other attributes
i_remove_na_range(x)i_remove_na_range(x)
x |
vector or data.frame |
Returns x without na-range
remove na values (information which values should be handled as missing) keep other attributes
i_remove_na_values(x)i_remove_na_values(x)
x |
vector or data.frame |
Returns x without na-values
remove scale label from variable keep other attributes
i_remove_scale(x)i_remove_scale(x)
x |
vector or data.frame |
Returns x without scale level
remove subject label from variable keep other attributes
i_remove_subject(x)i_remove_subject(x)
x |
vector or data.frame |
Returns x without subject
remove wording label from variable keep other attributes
i_remove_wording(x)i_remove_wording(x)
x |
vector or data.frame |
Returns x without wording
set scale level
i_scale(x, scale = NULL)i_scale(x, scale = NULL)
x |
vector |
scale |
scale level (nominal, ordinal, scale) as string or NULL (NULL will remove scale level) |
Returns x with scale label set
sort value labels by values or by labels
i_sort_labels(x, by = "values", decreasing = FALSE)i_sort_labels(x, by = "values", decreasing = FALSE)
x |
vector or data.frame |
by |
either values or labels |
decreasing |
sort decreasing |
Returns x with sorted value labels
add subject to i_labelled object
i_subject(x, subject)i_subject(x, subject)
x |
vector |
subject |
variable label as string or NULL (NULL will remove label) |
x with subject applied
wrapper for base::table
convert i_labelled objects to base class and pass to table function
i_table(..., missing_to_na = TRUE, as_factor = TRUE, table_args = NULL)i_table(..., missing_to_na = TRUE, as_factor = TRUE, table_args = NULL)
... |
one or more atomic vectors or one data.frame |
missing_to_na |
make as missing declared values NA |
as_factor |
make labelled data factor before pass to table |
table_args |
arguments of base::table as named list |
returns a contingency table, an object of class "table"
set.seed(1234) a <- sample(c(1:3, NA), 10, replace = TRUE) b <- i_labelled(sample(c(1:3, NA), 10, replace = TRUE), labels = c("A" = 1, "B" = 2, "C" = 3)) c <- factor(sample(c("X", "Y", "Z", NA), 10, replace = TRUE)) df <- data.frame(a, b, c) i_table(a, b) i_table(df, table_args = list(useNA = "ifany"))set.seed(1234) a <- sample(c(1:3, NA), 10, replace = TRUE) b <- i_labelled(sample(c(1:3, NA), 10, replace = TRUE), labels = c("A" = 1, "B" = 2, "C" = 3)) c <- factor(sample(c("X", "Y", "Z", NA), 10, replace = TRUE)) df <- data.frame(a, b, c) i_table(a, b) i_table(df, table_args = list(useNA = "ifany"))
- when value labels for all values are available will return factor
- when value labels are missing will unclass i_labelled
- remove class i_labelled and return variable as base R class
i_to_base_class( x, missing_to_na = TRUE, as_factor = TRUE, keep_attributes = FALSE )i_to_base_class( x, missing_to_na = TRUE, as_factor = TRUE, keep_attributes = FALSE )
x |
vector or data.frame |
missing_to_na |
missing values will become regular NA |
as_factor |
convert to factor when value labels are available |
keep_attributes |
should attributes be preserved |
Returns x coerced to R base class
unclass variables
i_unclass(x, keep_attributes = FALSE)i_unclass(x, keep_attributes = FALSE)
x |
vector or data.frame |
keep_attributes |
should attributes be preserved |
x unclassed
returns boolean when applied to vector
returns a named list when applied to data.frame
i_valid_annotation(x)i_valid_annotation(x)
x |
vector or data.frame |
T/F
returns boolean when applied to vector
returns a named list when applied to data.frame
i_valid_label(x)i_valid_label(x)
x |
vector or data.frame |
T/F
returns boolean when applied to vector
returns a named list when applied to data.frame
i_valid_labels(x)i_valid_labels(x)
x |
vector or data.frame |
No return value. Aborts process when run-time-tests fail
returns boolean when applied to vector
returns a named list when applied to data.frame
i_valid_scale(x)i_valid_scale(x)
x |
vector or data.frame |
T/F
returns boolean when applied to vector
returns a named list when applied to data.frame
i_valid_subject(x)i_valid_subject(x)
x |
vector or data.frame |
T/F
returns boolean when applied to vector
returns a named list when applied to data.frame
i_valid_wording(x)i_valid_wording(x)
x |
vector or data.frame |
T/F
add wording to i_labelled object
can be used to store question text
i_wording(x, wording)i_wording(x, wording)
x |
vector |
wording |
variable label as string or NULL (NULL will remove label) |
x with wording applied
Check if vector contains decimal values
is_decimal(x)is_decimal(x)
x |
numeric vector |
T/F
check for class i_labelled
is.i_labelled(x)is.i_labelled(x)
x |
vector of class i_labelled |
T/F
custom print method for i_labelled
## S3 method for class 'i_labelled' print(x, ...)## S3 method for class 'i_labelled' print(x, ...)
x |
vector of class i_labelled |
... |
not used |
No return value. Print object data and information to console