recode_addChildCodes {rock}

Add child codes under a parent code

Description

This function conditionally adds new child codes under a code. Where recode_split() removes the original code (splitting it into the new codes), this function retains the original, adding the new codes as sub-codes.

Usage

recode_addChildCodes(
  input,
  codes,
  childCodes,
  filter = TRUE,
  output = NULL,
  filenameRegex = ".*",
  outputPrefix = "",
  outputSuffix = "_rcAdded",
  decisionLabel = NULL,
  justification = NULL,
  justificationFile = NULL,
  preventOverwriting = rock::opts$get("preventOverwriting"),
  encoding = rock::opts$get("encoding"),
  silent = rock::opts$get("silent")
)

Arguments

input

One of 1) a character string specifying the path to a file with a source; 2) an object with a loaded source as produced by a call to load_source(); 3) a character string specifying the path to a directory containing one or more sources; 4) or an object with a list of loaded sources as produced by a call to load_sources().

codes

A single character value with the code to add the child codes to.

childCodes

A named list with specifying when to add which child code. Each element of this list is a filtering criterion that will be passed on to get_source_filter() to create the actual filter that will be applied. The name of each element is the code that will be applied to utterances matching that filter. When calling recode_addChildCodes() for a single source, instead of passing the filtering criterion, it is also possible to pass a filter (i.e. the result of the call to get_source_filter()), which allows more finegrained control. Note that these 'child code filters' and the corresponding codes are processed sequentially in the order specified in childCodes. Any utterances coded with the code specified in codes that do not match with any of the 'child code filters' specified as the childCodes elements will remain unchanged. To create a catch-all ('else') category, pass ".*" or TRUE as a filter (see the example).

filter

Optionally, a filter to apply to specify a subset of the source(s) to process (see get_source_filter()).

output

If specified, the recoded source(s) will be written here.

filenameRegex

Only process files matching this regular expression.

outputPrefix, outputSuffix

The prefix and suffix to add to the filenames when writing the processed files to disk, in case multiple sources are passed as input.

decisionLabel

A description of the (recoding) decision that was taken.

justification

The justification for this action.

justificationFile

If specified, the justification is appended to this file. If not, it is saved to the justifier::workspace(). This can then be saved or displayed at the end of the R Markdown file or R script using justifier::save_workspace().

preventOverwriting

Whether to prevent overwriting existing files when writing the files to output.

encoding

The encoding to use.

silent

Whether to be chatty or quiet.

Value

Invisibly, the changed source(s) or source(s) object.

Examples

### Get path to example source
examplePath <-
  system.file("extdata", package="rock");

### Get a path to one example file
exampleFile <-
  file.path(examplePath, "example-1.rock");

### Load example source
loadedExampleSource <- rock::load_source(exampleFile);

### Split a code into two codes, showing progress (the backticks are
### used to be able to specify a name that starts with an underscore)
recoded_source <-
  rock::recode_addChildCodes(
    loadedExampleSource,
    codes="childCode1",
    childCodes = list(
      `_and_` = " and ",
      `_book_` = "book",
      `_else_` = TRUE
    ),
    silent=FALSE
  );