recode: Recoding nominal data

Description Usage Arguments Details Value Author(s) References See Also


Nominal data (‘categorical data’) are data that consist of attributes, and each attribute consists of various discrete values (‘types’). The different values that are distinguished in comparative linguistics are mostly open to debate, and different scholars like to make different decisions as to the definition of values. The recode function allows for an easy and transparent way to specify a recoding of an existing dataset.





a data frame with nominal data, attributes as columns, observations as rows.


a recoding data structure, specifying the decisions of the recoding. It can also be a path to a file containing the specifications in YAML format. See Details.


a list of attributes to be recoded. Vectors (as elements of the list) are possible to specify combinations of attributes to be recoded as a single complex attribute.


file in which the recoding should be written.


the recoding template is by default written to a file in YAML format. When yaml=FALSE, the template is not converted to YAML, but returned inside R as a nested list.


Recoding nominal data is normally considered too complex to be performed purely within R. It is possible to do it completely within R, but it is proposed here to use an external YAML document to specify the decisions that are taken in the recoding. The typical process of recoding will be to use write.recoding.template to prepare a skeleton that allows for quick and easy YAML-specification of a recoding. Or a YAML-recoding is written manually using various shortcuts (see below), and read.recoding is used to turn it into a full-fledged recoding that can also be used to document the decisions made. The function recode then combines the original data with the recoding, and produces a recoded dataframe.

The recoding data structure in the YAML document basically consists of a list of recodings, each of which describes a new attribute, based on one or more attributes from the original data. Each new attribute is described by:

For writing recodings by hand, there are various shortcuts allowed:

A minimal recoding consist thus of a specification of recodingOf and link. Without link nothing will be recoded. Omitting recodingOf will lead to an error.

There is a vignette available with detailed information about the process of recoding, check recoding nominal data.


recode returns a data frame with the recoded attributes

write.recoding.template by default (when yaml=TRUE) writes a YAML structure to the specified file. When yaml=FALSE the same structure is returned inside R as a nested list.

read.recoding either reads a recoding from file, or a list structure within R, and cleans up all the shortcuts used. The output is by default a list structure to be used in recode, though it is also possible to write the result to a YAML-file (when file is specified). When data is specified, the output will be embelished with all the original names from the original data, which makes for an even better documentation of the recoding.

expandValues is an internal help function to show the various value-combinations when combining attributes.


Michael Cysouw


Cysouw, Michael, Jeffrey Craig Good, Mihai Albu and Hans-Jörg Bibiko. 2005. Can GOLD "cope" with WALS? Retrofitting an ontology onto the World Atlas of Language Structures. Proceedings of E-MELD Workshop 2005,

See Also

The World Atlas of Language Structure (WALS) contains typical data that most people would very much like to recode before using for further analysis. See Cysouw et al. 2005 for a discussion of various issues surrounding the WALS data.

cysouw/qlcRecode documentation built on May 14, 2019, 1:41 p.m.