getCodebook: Extract metadata information

In DDIwR: DDI with R

Extract metadata information

Description

Extract a list containing the variable labels, value labels and any available information about missing values.

Usage

getCodebook(from = NULL, encoding = "auto", ignore = NULL, ...)

Arguments

from	A path to a file, or a data frame object
encoding	The character encoding used to read a file
ignore	Character, ignore DDI elements when reading from an XML file
...	Additional arguments for this function (internal use only)

Details

This function extracts the metadata from an R dataset, or alternatively it can read an XML file containing a DDI Codebook version 1.2.2, 2.5 or 2.6, or an SPSS or Stata file and returns a list containing the variable labels, value labels and information about the missing values.

If the input is a dataset, it will extract the variable level metadata (labels, missing values etc.). From a DDI XML file, it will import all metadata elements, the most expensive being the data description.

It additionally attempts to automatically detect a type for each variable:

cat:	categorical variable using numeric values
catchar:	categorical variable using character values
catnum:	categorical variable for which numerical summaries
	can be calculated (ex. a 0...10 Likert response scale)
num:	numerical
numcat:	numerical variable with few enough values (ex. number of children)
	for which a table of frequencies is possible in addition to frequencies

Apart from utf8, other encodings might be necessary when reading from SPSS or DDI XML files, for instance latin1 or windows-1252, and it also accepts bytes for multi-byte encodings. To use the one specified in the file, set encoding = NULL. The default is encoding = "auto", which tries to detect the encoding automatically.

For the moment, only DDI Codebook is supported, but DDI Lifecycle is planned to be implemented.

Value

An R list roughly equivalent to a DDI Codebook, containing all variables, their corresponding variable labels and value labels, and (if applicable) missing values if imported and found.

Author(s)

Adrian Dusa

Examples

x <- data.frame(
    A = declared(
        c(1:5, -92),
        labels = c(Good = 1, Bad = 5, NR = -92),
        na_values = -92
    ),
    C = declared(
        c(1, -91, 3:5, -92),
        labels = c(DK = -91, NR = -92),
        na_values = c(-91, -92)
    )
)

getCodebook(from = x)

DDIwR documentation built on Aug. 22, 2026, 9:07 a.m.