Package 'rock'

Description

This function adds HTML tags to a source to allow pretty printing/viewing.

Usage

add_html_tags(
  x,
  context = NULL,
  codeClass = rock::opts$get("codeClass"),
  codeValueClass = rock::opts$get("codeValueClass"),
  networkCodeClass = rock::opts$get("networkCodeClass"),
  idClass = rock::opts$get("idClass"),
  sectionClass = rock::opts$get("sectionClass"),
  uidClass = rock::opts$get("uidClass"),
  contextClass = rock::opts$get("contextClass"),
  rockLineClass = rock::opts$get("rockLineClass"),
  utteranceClass = rock::opts$get("utteranceClass"),
  codingClass = rock::opts$get("codingClass"),
  commentClass = rock::opts$get("commentClass"),
  yamlClass = rock::opts$get("yamlClass")
)

Arguments

Value

The character vector with the replacements made.

Examples

### Add tags to a mini example source
add_html_tags("[[cid=participant1]]
This is something this participant may have said.
Just like this. [[thisIsACode]]
---paragraph-break---
And another utterance.");

Description

Apply multiple DiagrammeR global graph attributes

Usage

apply_graph_theme(graph, ...)

Arguments

Value

The DiagrammeR::DiagrammeR graph.

Examples

### Create an example source
exampleSource <- '
---
codes:
  -
    id: parentCode
    label: Parent code
    children:
      -
        id: childCode1
      -
        id: childCode2
  -
    id: childCode3
    label: Child Code
    parentId: parentCode
    children: [grandChild1, grandChild2]
---
';

### Parse it
parsedSource <-
  rock::parse_source(
    text = exampleSource
  );

### Extract the deductive code tree from
### the parsed source
deductiveCodeTree <-
  parsedSource$deductiveCodeTrees;

### Convert it to a DiagrammeR graph
miniGraph <-
  data.tree::ToDiagrammeRGraph(
    deductiveCodeTree
  );

### Show the graph
DiagrammeR::render_graph(
  miniGraph
);

### Apply a "theme" (three attributes)
miniGraph_themed <-
  rock::apply_graph_theme(
    miniGraph,
    c("rankdir", "TB", "graph"),
    c("shape", "square", "node"),
    c("style", "solid", "node"),
    c("fontname", "Arial", "node"),
    c("fontcolor", "#0000BB", "node"),
    c("color", "#BB0000", "node")
  );

### Show the updated graph
DiagrammeR::render_graph(
  miniGraph_themed
);

Description

This function converts an object to a character vector and marks it as a ROCK source.

Usage

as.rock_source(x)

Arguments

Value

A character vector with class rock_source.

Examples

exampleROCK <-
  rock::as.rock_source(c(
    "Some example text,",
    "and some more.       [[look_a_code]]",
    "And the end."));

### This can then be processed by other {rock}
### functions, for example:
rock::prettify_source(
  exampleROCK
);

Description

Note: this function is deprecated; use this function in the {squids} package!

Usage

base30toNumeric(x)

numericToBase30(x)

Arguments

Details

The conversion functions from base10 to base30 and vice versa are used by the generate_uids() functions.

The symbols to represent the 'base 30' system are the 0-9 followed by the alphabet without vowels but including the y (see squids::squids-package).

Value

The converted vector (numeric for base30toNumeric, character for numericToBase30).

Examples

rock::numericToBase30(
  654321
);
rock::base30toNumeric(
  rock::numericToBase30(
    654321
  )
);

Description

This function takes a value, and then replaces empty elements (NA or zero-length character values) with the last non-empty preceding element it encountered.

Usage

carry_over_values(x, noId = "no_id")

Arguments

Value

The vector with the carries over elements

Examples

rock::carry_over_values(
  c(
    NA, NA, 3, NA, NA, 7, NA, NA
  )
);

Description

The cat0 function is to cat what paste0 is to paste; it simply makes concatenating many strings without a separator easier.

Usage

cat0(..., sep = "")

Arguments

Value

Nothing (invisible NULL, like cat).

Examples

cat0("The first variable is '", names(mtcars)[1], "'.");

Description

This function efficiently checks for the presence of a package without loading it (unlike library() or require(). This is useful to force yourself to use the package::function syntax for addressing functions; you can make sure required packages are installed, but their namespace won't attach to the search path.

Usage

checkPkgs(
  ...,
  install = FALSE,
  load = FALSE,
  repos = "https://cran.rstudio.com"
)

Arguments

Value

Invisibly, a vector of the available packages.

Examples

rock::checkPkgs('base');

### Require a specific version
rock::checkPkgs(rock = "0.9.1");

### This will show the error message
tryCatch(
  rock::checkPkgs(
    base = "99",
    stats = "42.5",
    rock = 2000
  ),
  error = print
);

Description

This function takes a Narrative Response Model specification as used in NRM-based cognitive interviews, and composes an item based on the specified template for that item, the specified stimuli, and the requested language.

Usage

ci_get_item(nrm_spec, item_id, language)

Arguments

Value

A character value with the item.

Description

When conducting cognitive interviews, it can be useful to quickly inspect the code distributions for each item. These heatmaps facilitate that process.

Usage

ci_heatmap(
  x,
  nrmSpec = NULL,
  language = nrmSpec$defaultLanguage,
  wrapLabels = 80,
  itemOrder = NULL,
  itemLabels = NULL,
  itemIdentifier = "uiid",
  codingScheme = "peterson",
  itemlab = NULL,
  codelab = NULL,
  freqlab = "Count",
  plotTitle = "Cognitive Interview Heatmap",
  fillScale = ggplot2::scale_fill_viridis_c(),
  theme = ggplot2::theme_minimal()
)

Arguments

Value

The heatmap as a ggplot2 plot.

Examples

examplePath <- file.path(system.file(package="rock"), 'extdata');
parsedCI <- rock::parse_source(
  file.path(examplePath,
            "ci_example_1.rock")
);

rock::ci_heatmap(parsedCI,
                 codingScheme = "peterson");

Description

Narrative Response Models are a description of the theory of how a measurement instrument that measures a psychological construct works, geared towards conducting cognitive interviews to verify the validity of that measurement instrument. One a Narrative Response Model has been imported, it can be used to generate interview schemes, overview of each item's narrative response model, and combined with coded cognitive interview notes or transcripts.

Usage

ci_import_nrm_spec(
  x,
  read_ss_args = list(exportGoogleSheet = TRUE),
  defaultLanguage = NULL,
  silent = rock::opts$get("silent")
)

## S3 method for class 'rock_ci_nrm'
print(x, ...)

Arguments

Value

A rock_ci_nrm object.

Description

These functions can be used to 'clean' one or more sources or perform search and replace taks. Cleaning consists of two operations: splitting the source at utterance markers, and conducting search and replaces using regular expressions.

Usage

clean_source(
  input,
  output = NULL,
  replacementsPre = rock::opts$get("replacementsPre"),
  replacementsPost = rock::opts$get("replacementsPost"),
  extraReplacementsPre = NULL,
  extraReplacementsPost = NULL,
  removeNewlines = FALSE,
  removeTrailingNewlines = TRUE,
  rlWarn = rock::opts$get(rlWarn),
  utteranceSplits = rock::opts$get("utteranceSplits"),
  preventOverwriting = rock::opts$get("preventOverwriting"),
  encoding = rock::opts$get("encoding"),
  silent = rock::opts$get("silent")
)

clean_sources(
  input,
  output,
  outputPrefix = "",
  outputSuffix = "_cleaned",
  recursive = TRUE,
  filenameRegex = ".*",
  replacementsPre = rock::opts$get(replacementsPre),
  replacementsPost = rock::opts$get(replacementsPost),
  extraReplacementsPre = NULL,
  extraReplacementsPost = NULL,
  removeNewlines = FALSE,
  utteranceSplits = rock::opts$get(utteranceSplits),
  preventOverwriting = rock::opts$get(preventOverwriting),
  encoding = rock::opts$get(encoding),
  silent = rock::opts$get(silent)
)

search_and_replace_in_source(
  input,
  replacements = NULL,
  output = NULL,
  preventOverwriting = TRUE,
  encoding = "UTF-8",
  rlWarn = rock::opts$get(rlWarn),
  silent = FALSE
)

search_and_replace_in_sources(
  input,
  output,
  replacements = NULL,
  outputPrefix = "",
  outputSuffix = "_postReplacing",
  preventOverwriting = rock::opts$get("preventOverwriting"),
  recursive = TRUE,
  filenameRegex = ".*",
  encoding = rock::opts$get("encoding"),
  silent = rock::opts$get("silent")
)

Arguments

Details

The cleaning functions, when called with their default arguments, will do the following:

• Double periods (..) will be replaced with single periods (.)

• Four or more periods (... or .....) will be replaced with three periods

• Three or more newline characters will be replaced by one newline character (which will become more, if the sentence before that character marks the end of an utterance)

• All sentences will become separate utterances (in a semi-smart manner; specifically, breaks in speaking, if represented by three periods, are not considered sentence ends, wheread ellipses ("…" or unicode 2026, see the example) are.

• If there are comma's without a space following them, a space will be inserted.

Value

A character vector for clean_source, or a list of character vectors, for clean_sources.

Examples

exampleSource <-
"Do you like icecream?


Well, that depends\u2026 Sometimes, when it's..... Nice. Then I do,
but otherwise... not really, actually."

### Default settings:
cat(clean_source(exampleSource));

### First remove existing newlines:
cat(clean_source(exampleSource,
                 removeNewlines=TRUE));

### Example with a YAML fragment
exampleWithYAML <-
c(
  "Do you like icecream?",
  "",
  "",
  "Well, that depends\u2026 Sometimes, when it's..... Nice.",
  "Then I do,",
  "but otherwise... not really, actually.",
  "",
  "---",
  "This acts as some YAML. So this won't be split.",
  "Not real YAML, mind... It just has the delimiters, really.",
  "---",
  "This is an utterance again."
);

cat(
  rock::clean_source(
    exampleWithYAML
  ),
  sep="\n"
);

exampleSource <-
"Do you like icecream?


Well, that depends\u2026 Sometimes, when it's..... Nice. Then I do,
but otherwise... not really, actually."

### Simple text replacements:
cat(search_and_replace_in_source(exampleSource,
                                 replacements=list(c("\u2026", "..."),
                                                   c("Nice", "Great"))));

### Using a regular expression to capitalize all words following
### a period:
cat(search_and_replace_in_source(exampleSource,
                                 replacements=list(c("\\.(\\s*)([a-z])", ".\\1\\U\\2"))));

Description

Utterance vectors are split by the utterance marker. Note that if x has more than one element, the separate elements will remain separate.

Usage

cleaned_source_to_utterance_vector(
  x,
  utteranceMarker = rock::opts$get("utteranceMarker"),
  fixed = FALSE,
  perl = TRUE
)

Arguments

Value

A character vector with separate utterances, split by utteranceMarker.

Examples

cleaned_source_to_utterance_vector("first\nsecond\nthird");

Description

Code frequencies separate by a variable

Usage

code_freq_by(x, by, codes = ".*", returnTidyDf = FALSE)

Arguments

Value

A data frame with the code frequencies

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
loadedExample <- rock::parse_source(exampleFile);

### Show code frequencies
code_freq_by(loadedExample, "nestingLevel");

Description

Create a frequency histogram for codes

Usage

code_freq_hist(
  x,
  codes = ".*",
  sortByFreq = "decreasing",
  forceRootStripping = FALSE,
  trimSourceIdentifiers = 20,
  ggplot2Theme = ggplot2::theme(legend.position = "bottom"),
  silent = rock::opts$get("silent")
)

Arguments

Value

a ggplot2::ggplot().

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
loadedExample <- rock::parse_source(exampleFile);

### Show code frequencies
code_freq_hist(loadedExample);

Description

These functions add codes to one or more sources that were read with one of the loading_sources functions.

Usage

code_source(
  input,
  codes,
  indices = NULL,
  output = NULL,
  decisionLabel = NULL,
  justification = NULL,
  justificationFile = NULL,
  preventOverwriting = rock::opts$get("preventOverwriting"),
  rlWarn = rock::opts$get(rlWarn),
  encoding = rock::opts$get("encoding"),
  silent = rock::opts$get("silent")
)

code_sources(
  input,
  codes,
  output = NULL,
  indices = NULL,
  outputPrefix = "",
  outputSuffix = "_coded",
  decisionLabel = NULL,
  justification = NULL,
  justificationFile = NULL,
  recursive = TRUE,
  filenameRegex = ".*",
  preventOverwriting = rock::opts$get("preventOverwriting"),
  encoding = rock::opts$get("encoding"),
  silent = rock::opts$get("silent")
)

Arguments

Value

Invisibly, the coded source 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");

### Parse single example source
loadedExample <- rock::load_source(exampleFile);

### Show line 71
cat(loadedExample[71]);

### Specify the rules to code all utterances
### containing "Ipsum" with the code 'ipsum' and
### all utterances containing the code
codeSpecs <-
  c("(?i)ipsum" = "ipsum",
    "BC|AD|\\d\\d\\d\\ds" = "timeRef");

### Apply rules
codedExample <- code_source(loadedExample,
                            codeSpecs);

### Show line 71
cat(codedExample[71]);

### Also add code "foo" to utterances with code 'ipsum'
moreCodedExample <- code_source(codedExample,
                                c("[[ipsum]]" = "foo"));

### Show line 71
cat(moreCodedExample[71]);

### Use the 'indices' argument to add the code 'bar' to
### line 71
overCodedExample <- code_source(moreCodedExample,
                                "bar",
                                indices=71);

cat(overCodedExample[71]);

Description

Import a code book specification from a spreadsheet

Usage

codebook_fromSpreadsheet(
  x,
  localBackup = NULL,
  exportGoogleSheet = TRUE,
  xlsxPkg = c("rw_xl", "openxlsx", "XLConnect"),
  silent = rock::opts$get("silent")
)

Arguments

Value

The code book specification as a rock code book object

Examples

### Note that this will require an active
### internet connection! This if statement
### checks for that.

if (tryCatch({readLines("https://google.com",n=1); TRUE}, error=function(x) FALSE)) {

  ### Read the example ROCK codebook
  gs_url <- paste0(
    "https://docs.google.com/spreadsheets/d/",
    "1gVx5uhYzqcTH6Jq7AYmsLvHSBaYaT-23c7ZhZF4jmps"
  );
  ROCK_codebook <- rock::codebook_fromSpreadsheet(gs_url);

  ### Show a bit
  ROCK_codebook$metadata[1:3, ];
}

Description

Use this function to export your codebook specification to a PDF file. To embed it in an R Markdown file, use !!! CREATE rock::knit_codebook() !!!

Usage

codebook_to_pdf(
  x,
  file,
  author = NULL,
  headingLevel = 1,
  silent = rock::opts$get("silent")
)

Arguments

Value

x, invisibly

Examples

### Use a temporary file to write to
tmpFile <- tempfile(fileext = ".pdf");

### Load an example (pre)registration specification
data("exampleCodebook_1", package = "rock");

rock::codebook_to_pdf(
  exampleCodebook_1,
  file = tmpFile
);

Description

This function replaces the column names in the mergedSourceDf data frame in a rock_parsedSource or rock_parsedSources object with the full paths to those code identifiers.

Usage

codeIds_to_codePaths(
  x,
  stripRootsFromCodePaths = rock::opts$get("stripRootsFromCodePaths")
)

Arguments

Value

An adapted rock_parsedSource or rock_parsedSources object.

Description

This function names a vector with the leaf code using the codeTreeMarker stored in the opts object as marker.

Usage

codePaths_to_namedVector(x)

Arguments

Value

The named vector of code paths.

Examples

codePaths_to_namedVector(
  c("codes>reason>parent_feels",
    "codes>reason>child_feels")
);

Description

Convenience function to get a list of all available coding schemes

Usage

codingSchemes_get_all()

Value

A list of all available coding schemes

Examples

rock::codingSchemes_get_all();

Description

This function collapses all occurrences into groups sharing the same identifier, by default the stanzaId identifier (⁠[[sid=..]]⁠).

Usage

collapse_occurrences(
  parsedSource,
  collapseBy = "stanzaId",
  columns = NULL,
  logical = FALSE
)

Arguments

Value

A dataframe with one row for each value of of collapseBy and columns for collapseBy and each of the columns, with in the cells the counts (if logical is FALSE) or TRUE or FALSE (if logical is TRUE).

Examples

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

### Parse example source
parsedExample <-
  rock::parse_source(exampleFile);

### Collapse logically, using a code (either occurring or not):
collapsedExample <-
  rock::collapse_occurrences(parsedExample,
                             collapseBy = 'childCode1');

### Show result: only two rows left after collapsing,
### because 'childCode1' is either 0 or 1:
collapsedExample;

### Collapse using weights (i.e. count codes in each segment):
collapsedExample <-
  rock::collapse_occurrences(parsedExample,
                             collapseBy = 'childCode1',
                             logical=FALSE);

Description

Collect all coded utterances and optionally add some context (utterances before and utterances after) to create an overview of all coded fragments per code.

Usage

collect_coded_fragments(
  x,
  codes = ".*",
  context = 0,
  includeDescendents = FALSE,
  attributes = NULL,
  heading = NULL,
  headingLevel = 3,
  add_html_tags = TRUE,
  cleanUtterances = FALSE,
  omitEmptyCodes = TRUE,
  output = NULL,
  outputViewer = "viewer",
  template = "default",
  rawResult = FALSE,
  includeCSS = TRUE,
  preserveSpaces = TRUE,
  codeHeadingFormatting = rock::opts$get("codeHeadingFormatting"),
  codeHeadingFormatting_html = rock::opts$get("codeHeadingFormatting_html"),
  includeBootstrap = rock::opts$get("includeBootstrap"),
  preventOverwriting = rock::opts$get("preventOverwriting"),
  silent = rock::opts$get("silent")
)

Arguments

Details

By default, the output is optimized for inclusion in an R Markdown document. To optimize output for the R console or a plain text file, without any HTML codes, set add_html_tags to FALSE, and potentially set cleanUtterances to only return the utterances, without the codes.

Value

Either a list of character vectors, or a single character value.

Examples

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

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

### Parse single example source
parsedExample <-
  rock::parse_source(
    exampleFile
  );

### Show organised coded fragments in Markdown
cat(
  rock::collect_coded_fragments(
    parsedExample
  )
);

### Only for the codes containing 'Code2', with
### 2 lines of context (both ways)
cat(
  rock::collect_coded_fragments(
    parsedExample,
    'Code2',
    context = 2
  )
);

### Parse multiple example sources
### Load two example sources
parsedExamples <- rock::parse_sources(
  examplePath,
  regex = "example-[1234].rock"
);

cat(
  rock::collect_coded_fragments(
    parsedExamples,
    '[cC]ode2',
    context = 2
  )
);

Description

These functions can help when compressing vectors. They always compress their input (x) into a single element by various means.

Usage

compress_with_sum(x)

compress_with_or(x)

Arguments

Details

compress_with_sum computes the sum of the elements, doing its best to convert all input values to numeric values. compress_with_or returns 0 if all elements are FALSE, 0, NA or empty character values (""), and 1 otherwise.

Value

The compressed element

Examples

rock::compress_with_sum(c(1, '1', 0));
rock::compress_with_or(c(1, '1', 0));
rock::compress_with_or(c(0, '', 0, FALSE));

Description

This function simply computes confidence intervals for proportions.

Usage

confIntProp(x, n, conf.level = 0.95, plot = FALSE)

Arguments

Details

This function is the adapted source code of binom.test(). It uses pbeta(), with some lines of code taken from the binom.test() source. Specifically, the count for the low category is specified as first 'shape argument' to pbeta(), and the total count (either the sum of the count for the low category and the count for the high category, or the total number of cases if compareHiToLo is FALSE) minus the count for the low category as the second 'shape argument'.

Value

The confidence interval bounds in a twodimensional matrix, with the first column containing the lower bound and the second column containing the upper bound.

Author(s)

Unknown (see binom.test(); adapted by Gjalt-Jorn Peters)

Maintainer: Gjalt-Jorn Peters [email protected]

See Also

binom.test()

Examples

### Simple case
  rock::confIntProp(84, 200);

  ### Using vectors
  rock::confIntProp(c(2,3), c(10, 20), conf.level=c(.90, .95, .99));

Description

These functions first import data from a 'data format', such as spreadsheets in .xlsx format, comma-separated values files (.csv), or SPSS data files (.sav). You can also just use R data frames (imported however you want). These functions then use the columns you specified to convert these data to one (oneFile=TRUE) or more (oneFile=FALSE) rock source file(s), optionally including class instance identifiers (such as case identifiers to identify participants, or location identifiers, or moment identifiers, etc) and using those to link the utterances to attributes from columns you specified. You can also precode the utterances with codes you specify (if you ever would want to for some reason).

Usage

convert_df_to_source(
  data,
  output = NULL,
  omit_empty_rows = TRUE,
  cols_to_utterances = NULL,
  cols_to_ciids = NULL,
  cols_to_codes = NULL,
  cols_to_attributes = NULL,
  utterance_classId = NULL,
  utterance_comments = NULL,
  commentPrefix = ifelse(prependUIDs, repStr("#", 16), repStr("#", 3)),
  oneFile = TRUE,
  cols_to_sourceFilename = cols_to_ciids,
  cols_in_sourceFilename_sep = "_is_",
  sourceFilename_prefix = "source_",
  sourceFilename_suffix = "",
  ciid_labels = NULL,
  ciid_separator = "=",
  attributesFile = NULL,
  clean = TRUE,
  cleaningArgs = NULL,
  wordwrap = TRUE,
  wrappingArgs = NULL,
  prependUIDs = TRUE,
  UIDArgs = NULL,
  preventOverwriting = rock::opts$get(preventOverwriting),
  encoding = rock::opts$get(encoding),
  silent = rock::opts$get(silent)
)

convert_csv_to_source(
  file,
  importArgs = NULL,
  omit_empty_rows = TRUE,
  output = NULL,
  cols_to_utterances = NULL,
  cols_to_ciids = NULL,
  cols_to_codes = NULL,
  cols_to_attributes = NULL,
  oneFile = TRUE,
  cols_to_sourceFilename = cols_to_ciids,
  cols_in_sourceFilename_sep = "=",
  sourceFilename_prefix = "source_",
  sourceFilename_suffix = "",
  ciid_labels = NULL,
  ciid_separator = "=",
  attributesFile = NULL,
  preventOverwriting = rock::opts$get(preventOverwriting),
  encoding = rock::opts$get(encoding),
  silent = rock::opts$get(silent)
)

convert_csv2_to_source(
  file,
  importArgs = NULL,
  omit_empty_rows = TRUE,
  output = NULL,
  cols_to_utterances = NULL,
  cols_to_ciids = NULL,
  cols_to_codes = NULL,
  cols_to_attributes = NULL,
  oneFile = TRUE,
  cols_to_sourceFilename = cols_to_ciids,
  cols_in_sourceFilename_sep = "=",
  sourceFilename_prefix = "source_",
  sourceFilename_suffix = "",
  ciid_labels = NULL,
  ciid_separator = "=",
  attributesFile = NULL,
  preventOverwriting = rock::opts$get(preventOverwriting),
  encoding = rock::opts$get(encoding),
  silent = rock::opts$get(silent)
)

convert_xlsx_to_source(
  file,
  importArgs = list(),
  omit_empty_rows = TRUE,
  output = NULL,
  cols_to_utterances = NULL,
  cols_to_ciids = NULL,
  cols_to_codes = NULL,
  cols_to_attributes = NULL,
  oneFile = TRUE,
  cols_to_sourceFilename = cols_to_ciids,
  cols_in_sourceFilename_sep = "=",
  sourceFilename_prefix = "source_",
  sourceFilename_suffix = "",
  ciid_labels = NULL,
  ciid_separator = "=",
  attributesFile = NULL,
  preventOverwriting = rock::opts$get(preventOverwriting),
  encoding = rock::opts$get(encoding),
  silent = rock::opts$get(silent)
)

convert_sav_to_source(
  file,
  importArgs = NULL,
  omit_empty_rows = TRUE,
  output = NULL,
  cols_to_utterances = NULL,
  cols_to_ciids = NULL,
  cols_to_codes = NULL,
  cols_to_attributes = NULL,
  oneFile = TRUE,
  cols_to_sourceFilename = cols_to_ciids,
  cols_in_sourceFilename_sep = "=",
  sourceFilename_prefix = "source_",
  sourceFilename_suffix = "",
  ciid_labels = NULL,
  ciid_separator = "=",
  attributesFile = NULL,
  preventOverwriting = rock::opts$get(preventOverwriting),
  encoding = rock::opts$get(encoding),
  silent = rock::opts$get(silent)
)

Arguments

Value

A source as a character vector.

Examples

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

### Get a path to file with example data frame
exampleFile <-
  file.path(examplePath, "spreadsheet-import-test.csv");

### Read data into a data frame
dat <-
  read.csv(exampleFile);

### Convert data frame to a source
source_from_df <-
  convert_df_to_source(
    dat,
    cols_to_utterances = c("open_question_1",
                           "open_question_2"),
    cols_to_ciids = c(cid = "id"),
    cols_to_attributes = c("age", "gender"),
    cols_to_codes = c("code_1", "code_2"),
    ciid_labels = c(cid = "caseId")
 );

### Show the result
cat(
  source_from_df,
  sep = "\n"
);

Description

Tries to 'smartly' convert factor and character vectors to numeric.

Usage

convertToNumeric(vector, byFactorLabel = FALSE)

Arguments

Value

The converted vector.

Examples

rock::convertToNumeric(as.character(1:8));

Description

Count code occurrences

Usage

count_occurrences(x, codes = ".*", matchRegexAgainstPaths = TRUE)

Arguments

Value

A data.frame().

Examples

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

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

### Load example source
loadedExample <- rock::parse_source(exampleFile);

### Show code occurrences
rock::count_occurrences(
  loadedExample
);

Description

This function can be used to specify a coding scheme that can then be used in analysis.

Usage

create_codingScheme(
  id,
  label,
  codes,
  codingInstructions = NULL,
  description = "",
  source = ""
)

codingScheme_peterson

codingScheme_levine

codingScheme_willis

Arguments

Format

An object of class rock_codingScheme of length 5.

An object of class rock_codingScheme of length 5.

An object of class rock_codingScheme of length 5.

Details

A number of coding schemes for cognitive interviews are provided:

codingScheme_peterson

Coding scheme from Peterson, Peterson & Powell, 2017

codingScheme_levine

Coding scheme from Levine, Fowler & Brown, 2005

codingScheme_willis

Coding scheme from Willis, 1999

Value

The coding scheme object.

Description

This function creates a co-occurrence matrix based on one or more coded sources. Optionally, it plots a heatmap, simply by calling the stats::heatmap() function on that matrix.

Usage

create_cooccurrence_matrix(
  x,
  codes = x$convenience$codingLeaves,
  plotHeatmap = FALSE
)

Arguments

Value

The co-occurrence matrix; a matrix.

Examples

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

### Parse a selection of example sources in that directory
parsedExamples <-
  rock::parse_sources(
    examplePath,
    regex = "(test|example)(.txt|.rock)"
  );

### Create cooccurrence matrix
rock::create_cooccurrence_matrix(parsedExamples);

Description

Create HTML fragment with CSS styling

Usage

css(
  template = "default",
  includeBootstrap = rock::opts$get("includeBootstrap")
)

Arguments

Value

A character vector with the HTML fragment.

Description

This used to be a thin wrapper around textreadr::read_document() that also writes the result to output, doing its best to correctly write UTF-8 (based on the approach recommended in this blog post). However, textreadr was archived from CRAN. It now directly wraps the functions that textreadr wraps: pdftools::pdf_text(), striprtf::read_rtf, and it uses xml2 to import .docx and .odt files, and rvest to import .html files, using the code from the textreadr package.

Usage

doc_to_txt(
  input,
  output = NULL,
  encoding = rock::opts$get("encoding"),
  newExt = NULL,
  preventOverwriting = rock::opts$get("preventOverwriting"),
  silent = rock::opts$get("silent")
)

Arguments

Value

The converted source, as a character vector.

Examples

### This example requires the {xml2} package
if (requireNamespace("xml2", quietly = TRUE)) {
  print(
    rock::doc_to_txt(
      input = system.file(
        "extdata/doc-to-test.docx", package="rock"
      )
    )
  );
}

Description

This is a simple and relatively short codebook specification.

Usage

exampleCodebook_1

Format

An example of a codebook specification

Description

Expand categorical attribute variables to a series of dichotomous variables

Usage

expand_attributes(
  data,
  attributes,
  valueLabels = NULL,
  prefix = "",
  glue = "__",
  suffix = "",
  falseValue = 0,
  trueValue = 1,
  valueFirst = TRUE,
  append = TRUE
)

Arguments

Value

A data.frame

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");

### Parse single example source
parsedExample <- rock::parse_source(exampleFile);

### Create a categorical attribute column
parsedExample$qdt$age_group <-
  c(rep(c("<18", "18-30", "31-60", ">60"),
        each=19),
    rep(c("<18", ">60"),
        time = c(3, 4)));

### Expand to four logical columns
parsedExample$qdt <-
  rock::expand_attributes(
    parsedExample$qdt,
    "age_group",
    valueLabels =
      c(
        "<18" = "youngest",
        "18-30" = "youngish",
        "31-60" = "oldish",
        ">60" = "oldest"
       ),
    valueFirst = FALSE
);

### Show some of the result
table(parsedExample$qdt$age_group,
      parsedExample$qdt$age_group__youngest);
table(parsedExample$qdt$age_group,
      parsedExample$qdt$age_group__oldish);

Description

These function can be used to convert one or more parsed sources to HTML, or to convert all sources to tabbed sections in Markdown.

Usage

export_codes_to_txt(
  input,
  output = NULL,
  codeTree = "fullyMergedCodeTrees",
  codingScheme = "codes",
  regex = ".*",
  onlyChildrenOf = NULL,
  leavesOnly = TRUE,
  includePath = TRUE,
  preventOverwriting = rock::opts$get(preventOverwriting),
  encoding = rock::opts$get(encoding),
  silent = rock::opts$get(silent)
)

Arguments

Value

A character vector.

Examples

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

### Parse a selection of example sources in that directory
parsedExamples <-
  rock::parse_sources(
    examplePath,
    regex = "(test|example)(.txt|.rock)"
  );

### Show results of exporting the codes
rock::export_codes_to_txt(parsedExamples);

### Only show select a narrow set of codes
rock::export_codes_to_txt(
  parsedExamples,
  leavesOnly=TRUE,
  includePath=FALSE,
  onlyChildrenOf = "inductFather",
  regex="3|5"
);

Description

Export the fully merged code tree(s)

Usage

export_fullyMergedCodeTrees(x, file)

Arguments

Value

Invisibly, NULL.

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
loadedExample <- rock::parse_source(exampleFile);

tempFile <- tempfile(fileext = ".svg");

### Export merged code tree
export_fullyMergedCodeTrees(
  loadedExample,
  tempFile
);

Description

Export a merged source data frame

Usage

export_mergedSourceDf_to_csv(
  x,
  file,
  exportArgs = list(fileEncoding = rock::opts$get("encoding")),
  preventOverwriting = rock::opts$get("preventOverwriting"),
  silent = rock::opts$get("silent")
)

export_mergedSourceDf_to_csv2(
  x,
  file,
  exportArgs = list(fileEncoding = rock::opts$get("encoding")),
  preventOverwriting = rock::opts$get("preventOverwriting"),
  silent = rock::opts$get("silent")
)

export_mergedSourceDf_to_xlsx(
  x,
  file,
  exportArgs = NULL,
  preventOverwriting = rock::opts$get("preventOverwriting"),
  silent = rock::opts$get("silent")
)

export_mergedSourceDf_to_sav(
  x,
  file,
  exportArgs = NULL,
  preventOverwriting = rock::opts$get("preventOverwriting"),
  silent = rock::opts$get("silent")
)

Arguments

Value

Silently, the object with parsed sources.

Description

Export a ROCK project to a single ROCKproject file

Usage

export_ROCKproject(
  output,
  path = ".",
  config = NULL,
  includeRegex = NULL,
  excludeRegex = NULL,
  createDirs = FALSE,
  preventOverwriting = TRUE,
  forceBaseZip = FALSE,
  silent = rock::opts$get("silent")
)

Arguments

Value

Invisibly, output.

Examples

### Get path to example project
examplePath <-
  system.file(
    "ROCKprojects",
    "exportable-ROCKproject-1",
    package="rock"
  );

### Get a temporary filename to write to
projectFilename <-
  tempfile(
    fileext = ".ROCKproject"
  );

### Export it
rock::export_ROCKproject(
  path = examplePath,
  output = projectFilename,
  silent = FALSE
);

Description

These function can be used to convert one or more parsed sources to HTML, or to convert all sources to tabbed sections in Markdown.

Usage

export_to_html(
  input,
  output = NULL,
  template = "default",
  fragment = FALSE,
  preventOverwriting = rock::opts$get(preventOverwriting),
  encoding = rock::opts$get(encoding),
  silent = rock::opts$get(silent)
)

export_to_markdown(
  input,
  heading = "Sources",
  headingLevel = 2,
  template = "default",
  silent = rock::opts$get(silent)
)

Arguments

Value

A character vector or a list of character vectors.

Examples

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

### Parse a selection of example sources in that directory
parsedExamples <- rock::parse_sources(
  examplePath,
  regex = "(test|example)(.txt|.rock)"
);

### Export results to a temporary directory
tmpDir <- tempdir(check = TRUE);
prettySources <-
  export_to_html(input = parsedExamples,
                 output = tmpDir);

### Show first one
print(prettySources[[1]]);

Description

This function exports data frames or matrices to HTML, sending output to one or more of the console, viewer, and one or more files.

Usage

exportToHTML(
  input,
  output = rock::opts$get("tableOutput"),
  tableOutputCSS = rock::opts$get("tableOutputCSS")
)

Arguments

Value

Invisibly, the (potentially concatenated) input as character vector.

Examples

exportToHTML(mtcars[1:5, 1:5]);

Description

Extract the codings by each coder using the coderId

Usage

extract_codings_by_coderId(
  input,
  recursive = TRUE,
  filenameRegex = ".*",
  postponeDeductiveTreeBuilding = TRUE,
  ignoreOddDelimiters = FALSE,
  encoding = rock::opts$get(encoding),
  silent = rock::opts$get(silent)
)

Arguments

Value

An object with the read sources.

Description

Extract the UIDs (or SQUIDs) from a vector

Usage

extract_uids(x, returnSQUIDs = FALSE)

Arguments

Value

A vector with (SQ)UIDs

Examples

exampleText <- c(
  "Lorem ipsum dolor sit amet, consectetur",
  "adipiscing elit. Nunc non commodo ex,",
  "ac varius mi. Praesent feugiat nunc",
  "eget urna euismod lobortis. Sed",
  "hendrerit suscipit nisl, ac tempus",
  "magna porta et. Quisque libero massa,",
  "tempus vel tristique lacinia, tristique",
  "in nulla. Nam cursus enim dui, non",
  "ornare est tempor eu. Vivamus et massa",
  "consectetur, tristique magna eget,",
  "viverra elit."
);

withUIDs <-
  rock::prepend_ids_to_source(
    exampleText
  );

rock::extract_uids(
  withUIDs
);

Description

This function creates an R Markdown template from a {preregr} (pre)registrations form specification. Pass it the URL to a Google Sheet holding the (pre)registration form specification (in {preregr} format), see the "Creating a form from a spreadsheet" vignette), the path to a file with a spreadsheet holding such a specification, or a loaded or imported {preregr} (pre)registration form.

Usage

form_to_rmd_template(
  x,
  file = NULL,
  title = NULL,
  author = NULL,
  date = "`r format(Sys.time(), \"%H:%M:%S on %Y-%m-%d %Z (UTC%z)\")`",
  output = "html_document",
  yaml = list(title = title, author = author, date = date, output = output),
  includeYAML = TRUE,
  chunkOpts = "echo=FALSE, results='hide'",
  justify = FALSE,
  headingLevel = 1,
  showSpecification = FALSE,
  preventOverwriting = rock::opts$get("preventOverwriting"),
  silent = rock::opts$get("silent")
)

Arguments

Value

x, invisibly

Examples

newForm <-
  preregr::form_create(
    title = "Example form",
    version = "0.1.0"
  );

preregr::form_to_rmd_template(
  newForm
);

Description

A TSSID is a Timestamped Source Identifier. It is a practically unique identifier for a source, conventionally the time and date the source was produced (e.g. when the data were collected, for example the time and date of an interview) in the UTC timezone and in ISO 8601 standard format.

Usage

generate_tssid(x = Sys.time(), addDelimiters = FALSE, designationSymbol = "=")

Arguments

Value

The tssid

Examples

rock::generate_tssid();

Description

This function generates utterance identifiers. Utterance identifiers are Short Quasi-Unique Identifiers (SQUIDs) generated using the squids::squids() function.

Usage

generate_uids(x, origin = Sys.time(), follow = NULL, followBy = NULL)

Arguments

Value

A vector of UIDs.

Examples

### Produce and store five UIDs
fiveUIDs <-
  rock::generate_uids(5);

### Look at them
fiveUIDs;

### Use a specific origin to be able to reproduce
### a set of UIDs later (e.g. in a script)
uidOrigin <-
  as.POSIXct("2025-05-21 21:53:25 CEST");

rock::generate_uids(
  5,
  origin = uidOrigin
);

### Produce five more UIDs to show
### their 'progression'
rock::generate_uids(5);

### Produce a set of five UIDs that follow
### the first set of five UIDs
rock::generate_uids(
  5,
  follow = fiveUIDs
);

### Follow with a 'distance' of 5 utterances
rock::generate_uids(
  5,
  follow = fiveUIDs,
  followBy = 5
);

Description

This function contains the general set of actions that are always used when recoding a source (e.g. check the input, document the justification, etc). Users should normally never call this function.

Usage

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

Arguments

Value

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

Description

Get the code identifiers of all children, or all descendents (i.e. including grand-children, grand-grand-children, etc) of a code with a given identifier.

Usage

get_childCodeIds(
  x,
  parentCodeId,
  returnNodes = FALSE,
  includeParentCode = FALSE
)

get_descendentCodeIds(x, parentCodeId, includeParentCode = FALSE)

Arguments

Value

A character vector with code identifiers (or a list of nodes)

Description

Get the code identifiers from QNA codings

Usage

get_codeIds_from_qna_codings(
  x,
  within = "network",
  return = "all",
  includeUIDs = TRUE
)

Arguments

Value

A character vector or data frame

Examples

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

### Read a souce coded with the Qualitative Network Approach
qnaExample <-
  rock::parse_source(
    file.path(
      examplePath,
      "network-example-1.rock"
    )
  );

rock::get_codeIds_from_qna_codings(
  qnaExample
);

Description

Return all values from a nested list in a dataframe

Usage

get_dataframe_from_nested_list(x, nestingIn = "children")

Arguments

Value

A dataframe

Examples

nestedList <-
  list(
    id = "x",
    value = "value for x",
    children = list(
      list(
        id = "y",
        value = "value for y"
      ),
      list(
        id = "z",
        value = "value for z"
      )
    )
  );
str(nestedList);
get_dataframe_from_nested_list(nestedList);

Description

This function takes a character vector with regular expressions, a numeric vector with numeric indices, or a logical vector that is either as long as the source or has length 1; and then always returns a logical vector of the same length as the source.

Usage

get_source_filter(
  source,
  filter,
  ignore.case = TRUE,
  invert = FALSE,
  perl = TRUE,
  ...
)

Arguments

Value

A logical vector of the same length as the source.

Description

Get the state transition data frame

Usage

get_state_transition_df(x)

Arguments

Value

A dataframe with columns fromState, toState, and nrOfTransitions.

Examples

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

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

### Parse single example source
parsedExample <- rock::parse_source(exampleFile);

### Show the state transition probabilities
exampleTable <- rock::get_state_transition_table(
  parsedExample
);

exampleStateDf <- rock::get_state_transition_df(
  exampleTable
);

Description

Get the Dot code for a state transition graph

Usage

get_state_transition_dot(
  x,
  labelFun = base::round,
  labelFunArgs = list(digits = 2)
)

Arguments

Value

The Dot code for a state transition graph.

Examples

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

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

### Parse single example source
parsedExample <- rock::parse_source(exampleFile);

### Show the state transition probabilities
exampleTable <- rock::get_state_transition_table(
  parsedExample
);

exampleStateDf <- rock::get_state_transition_df(
  exampleTable
);

exampleDotCode <- rock::get_state_transition_dot(
  exampleStateDf
);

DiagrammeR::grViz(exampleDotCode);

Description

Get the state transition table

Usage

get_state_transition_table(x, rawClassIdentifierCol = "state_raw")

Arguments

Value

A table, with the 'from' states as rows and the 'to' states as columns

Examples

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

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

### Parse single example source
parsedExample <- rock::parse_source(exampleFile);

### Show the state transition probabilities
rock::get_state_transition_table(
  parsedExample
);

Description

This is a convenience function to use when displaying a source. It returns an object with the raw and clean utterances in a source, as well as the utterance identifiers and a list with vectors of the codes for each utterance.

Usage

get_utterances_and_codes_from_source(x, ...)

Arguments

Value

A list containing ⁠$utterances_raw⁠, ⁠$utterances_clean⁠, ⁠$uids$⁠, ⁠$codeMatches⁠, and ⁠$codesPerUtterance⁠.

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");

### Parse single example source
res <-
  rock::get_utterances_and_codes_from_source(
    exampleFile
  );

Description

Return one or more values from a nested list in a list of vectors

Usage

get_vectors_from_nested_list(x, valuesIn = NULL, nestingIn = "children")

Arguments

Value

A list of vectors.

Examples

nestedList <-
  list(
    id = "x",
    value = "value for x",
    children = list(
      list(
        id = "y",
        value = "value for y"
      ),
      list(
        id = "z",
        value = "value for z"
      )
    )
  );
str(nestedList);
get_vectors_from_nested_list(
  nestedList,
  c("id", "value")
);

Description

This is just a convenience function to print a markdown or HTML heading at a given 'depth'.

Usage

heading(
  ...,
  headingLevel = rock::opts$get("defaultHeadingLevel"),
  output = "markdown",
  cat = TRUE
)

Arguments

Value

The heading, invisibly.

Examples

heading("Hello ", "World", headingLevel=5);
### This produces: "\n\n##### Hello World\n\n"

Description

This is just a convenience function to convert a vector of strings into markdown or HTML headings at a given 'depth'.

Usage

heading_vector(
  x,
  headingLevel = rock::opts$get("defaultHeadingLevel"),
  output = "markdown",
  cat = FALSE
)

Arguments

Value

The heading, invisibly.

Examples

rock::heading_vector(c("Hello ", "World"), headingLevel=5);
### This produces: "\n\n##### Hello\n\n" and
### "\n\n##### World\n\n"

Description

Generic convenience function to create a heatmap

Usage

heatmap_basic(
  data,
  x,
  y,
  fill,
  xLab = x,
  yLab = y,
  fillLab = fill,
  plotTitle = "Heatmap",
  fillScale = ggplot2::scale_fill_viridis_c(),
  theme = ggplot2::theme_minimal()
)

Arguments

Value

The heatmap, as a ggplot2 object.

Examples

rock::heatmap_basic(mtcars, 'am', 'cyl', 'mpg');

Description

Import a ROCK project from a ROCKproject file

Usage

import_ROCKproject(
  input,
  path = ".",
  createDirs = FALSE,
  preventOverwriting = TRUE,
  forceBaseZip = FALSE,
  silent = rock::opts$get(silent)
)

Arguments

Value

Invisibly, output.

Examples

### Get path to example project
exampleProjectFile <-
  system.file(
    "ROCKprojects",
    "example1.ROCKproject",
    package="rock"
  );

### Get a temporary directory to write to
temporaryDir <-
  tempdir();

### Import the project
rock::import_ROCKproject(
  input = exampleProjectFile,
  path = temporaryDir,
  silent = FALSE
);

Description

Import a source from Google Documents

Usage

import_source_from_gDocs(x, localFile = NULL)

Arguments

Value

The source contents.

Examples

### Note that this will require an active
### internet connection! This if statement
### checks for that.

if (tryCatch({readLines("https://google.com",n=1); TRUE}, error=function(x) FALSE)) {

  gDocs_url <-
    paste0(
      "https://docs.google.com/document/d/",
      "1iACYjV7DdCjOmfgX6KEMtCcCjuuXD3iuikTSGWtsK84",
      "/edit?usp=sharing"
    );

  ### Import the source
  exampleSource <-
    import_source_from_gDocs(
      gDocs_url
    );

  ### Show the downloaded file:
  exampleSource;

  ### Parse the source:
  parsedExampleSource <-
    rock::parse_source(
      exampleSource
    );

  ### Imported; the comments are gone:
  parsedExampleSource$qdt$utterances_raw;
}

Description

This function combines successive calls to parse_sources(), collect_coded_fragments() and show_inductive_code_tree().

Usage

inspect_coded_sources(
  path,
  parse_args = list(extension = "rock|dct", regex = NULL, recursive = TRUE,
    ignoreOddDelimiters = FALSE, encoding = rock::opts$get("encoding"), silent =
    rock::opts$get("silent")),
  fragments_args = list(codes = ".*", context = 0),
  inductive_tree_args = list(codes = ".*", output = "both", headingLevel = 3),
  deductive_tree_args = list()
)

Arguments

Value

The parsedSources object.

Examples

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

### Inspect a selection of example sources - this takes too long
### to test, so hence the 'donttest' directive.

rock::inspect_coded_sources(
  examplePath,
  parse_args = list(regex = "test(.txt|.rock)")
);

Description

These functions load one or more source(s) from a file or a string and store it in memory for further processing. Note that you'll probably want to clean the sources first, using one of the clean_sources() functions, and you'll probably want to add utterance identifiers to each utterance using one of the prepending_uids() functions.

Usage

load_source(
  input,
  encoding = rock::opts$get("encoding"),
  silent = rock::opts$get("silent"),
  rlWarn = rock::opts$get(rlWarn),
  diligentWarnings = rock::opts$get("diligentWarnings")
)

load_sources(
  input,
  filenameRegex = ".*",
  ignoreRegex = NULL,
  recursive = TRUE,
  full.names = FALSE,
  encoding = rock::opts$get("encoding"),
  silent = rock::opts$get("silent")
)

Arguments

Value

Invisibly, an R character vector of classes rock_source and character.

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");

### Parse single example source
loadedSource <- rock::load_source(exampleFile);

Description

This function creates a ROCK project configuration file in the YAML format. See the Details section for more information.

Usage

make_ROCKproject_config(
  project = list(title = "Default title", authors = "Authors", authorIds = NULL, version
    = "1.0", ROCK_version = "1.0", ROCK_project_version = "1.0", date_created =
    format(Sys.time(), "%Y-%m-%d %H:%M:%S %Z"), date_modified = format(Sys.time(),
    "%Y-%m-%d %H:%M:%S %Z")),
  codebook = list(urcid = "", embedded = NULL, local = ""),
  sources = list(extension = ".rock", regex = NULL, dirsToIncludeRegex = "data/",
    recursive = TRUE, dirsToExcludeRegex = NULL, filesToIncludeRegex = NULL,
    filesToExcludeRegex = NULL),
  workflow = list(pipeline = NULL, actions = NULL),
  extra = NULL,
  path = NULL
)

Arguments

Details

For more information about the ROCK project configuration file format, see the ROCKproject-format vignette. You can view this from R using:

vignette("ROCKproject-format", package="rock");

You can also visit it at https://rock.opens.science/articles/ROCKproject-format.html.

Value

A list with the passed configuration in a list called ⁠$input⁠, and as YAML in a character vector called ⁠$yaml⁠.

Examples

### To get the default configuration,
### just pass no arguments:
defaultConfig <-
  rock::make_ROCKproject_config();

### You can then extract the object with settings
config <- defaultConfig$input;

### Edit some of them
config$project$title <- "Some new title";

### Call the function again with the new arguments
myConfig <-
  rock::make_ROCKproject_config(
    project = config$project,
    codebook = config$codebook,
    sources = config$sources,
    workflow = config$workflow,
    extra = config$extra
  );

### View the result
cat(myConfig$yaml);

Description

These functions can be used to mask a set of utterances or one or more sources.

Usage

mask_source(
  input,
  output = NULL,
  proportionToMask = 1,
  preventOverwriting = rock::opts$get(preventOverwriting),
  encoding = rock::opts$get(encoding),
  rlWarn = rock::opts$get(rlWarn),
  maskRegex = "[[:alnum:]]",
  maskChar = "X",
  perl = TRUE,
  silent = rock::opts$get(silent)
)

mask_sources(
  input,
  output,
  proportionToMask = 1,
  outputPrefix = "",
  outputSuffix = "_masked",
  maskRegex = "[[:alnum:]]",
  maskChar = "X",
  perl = TRUE,
  recursive = TRUE,
  filenameRegex = ".*",
  filenameReplacement = c("_PRIVATE_", "_public_"),
  preventOverwriting = rock::opts$get(preventOverwriting),
  encoding = rock::opts$get(encoding),
  silent = rock::opts$get(silent)
)

mask_utterances(
  input,
  proportionToMask = 1,
  maskRegex = "[[:alnum:]]",
  maskChar = "X",
  perl = TRUE
)

Arguments

Value

A character vector for mask_utterance and mask_source, or a list of character vectors, for mask_sources.

Examples

### Mask text but not the codes
rock::mask_utterances(
  paste0(
    "Lorem ipsum dolor sit amet, consectetur adipiscing ",
    "elit. [[expAttitude_expectation_73dnt5z1>earplugsFeelUnpleasant]]"
  )
)

Description

This is just a convenience function that takes a vector of deliminaters and returns a list of delimiter pairs.

Usage

match_consecutive_delimiters(
  x,
  errorOnInvalidX = FALSE,
  errorOnOdd = FALSE,
  onOddIgnoreFirst = FALSE
)

Arguments

Value

A list where each element is a two-element vector with the two consecutive delimiters

Examples

rock::match_consecutive_delimiters(
  c(1, 3, 5, 10, 19, 25, 30, 70)
);

exampleText <- c(
  "some text",
  "delimiter",
  "more text",
  "delimiter",
  "filler text",
  "intentionally left blank",
  "delimiter",
  "final text",
  "delimiter"
);

rock::match_consecutive_delimiters(
  grep(
    "delimiter",
    exampleText
  )
);

Description

This function takes sets of sources and merges them using the utterance identifiers (UIDs) to match them.

Usage

merge_sources(
  input,
  output,
  outputPrefix = "",
  outputSuffix = "_merged",
  primarySourcesRegex = ".*",
  primarySourcesIgnoreRegex = outputSuffix,
  primarySourcesPath = input,
  recursive = TRUE,
  primarySourcesRecursive = recursive,
  filenameRegex = ".*",
  primarySourcesFileList = NULL,
  sourcesFileList = NULL,
  postponeDeductiveTreeBuilding = TRUE,
  ignoreOddDelimiters = FALSE,
  preventOverwriting = rock::opts$get(preventOverwriting),
  encoding = rock::opts$get(encoding),
  silent = rock::opts$get(silent),
  inheritSilence = FALSE
)

Arguments

Value

Invisibly, a list of the parsed, primary, and merged sources.

Description

Convert a number to a date using Excel's system

Usage

number_as_xl_date(x)

Arguments

Value

The date(s)

Examples

preregr::number_as_xl_date(44113);

Description

The rock::opts object contains three functions to set, get, and reset options used by the rock package. Use rock::opts$set to set options, rock::opts$get to get options, or rock::opts$reset to reset specific or all options to their default values.

Usage

opts

Format

An object of class list of length 4.

Details

It is normally not necessary to get or set rock options. The defaults implement the Reproducible Open Coding Kit (ROCK) standard, and deviating from these defaults therefore means the processed sources and codes are not compatible and cannot be processed by other software that implements the ROCK. Still, in some cases this degree of customization might be desirable.

The following arguments can be passed:

...

For rock::opts$set, the dots can be used to specify the options to set, in the format option = value, for example, utteranceMarker = "\n". For rock::opts$reset, a list of options to be reset can be passed.

option

For rock::opts$set, the name of the option to set.

default

For rock::opts$get, the default value to return if the option has not been manually specified.

Some of the options that can be set (see rock::opts$defaults for the full list):

codeRegexes

A named character vector with one or more regular expressions that specify how to extract the codes (that were used to code the sources). These regular expressions must each contain one capturing group to capture the codes.

idRegexes

A named character vector with one or more regular expressions that specify how to extract the different types of identifiers. These regular expressions must each contain one capturing group to capture the identifiers.

sectionRegexes

A named character vector with one or more regular expressions that specify how to extract the different types of sections.

autoGenerateIds

The names of the idRegexes that, if missing, should receive autogenerated identifiers (which consist of 'autogenerated_' followed by an incrementing number).

noCodes

This regular expression is matched with all codes after they have been extracted using the codeRegexes regular expression (i.e. they're matched against the codes themselves without, for example, the square brackets in the default code regex). Any codes matching this noCodes regular expression will be ignored, i.e., removed from the list of codes.

inductiveCodingHierarchyMarker

For inductive coding, this marker is used to indicate hierarchical relationships between codes. The code at the left hand side of this marker will be considered the parent code of the code on the right hand side. More than two levels can be specified in one code (for example, if the inductiveCodingHierarchyMarker is '>', the code ⁠grandparent>child>grandchild⁠ would indicate codes at three levels.

attributeContainers

The name of YAML fragments containing case attributes (e.g. metadata, demographic variables, quantitative data about cases, etc).

codesContainers

The name of YAML fragments containing (parts of) deductive coding trees.

delimiterRegEx

The regular expression that is used to extract the YAML fragments.

codeDelimiters

A character vector of two elements specifying the opening and closing delimiters of codes (conform the default ROCK convention, two square brackets). The square brackets will be escaped; other characters will not, but will be used as-is.

ignoreRegex

The regular expression that is used to delete lines before any other processing. This can be used to enable adding comments to sources, which are then ignored during analysis.

includeBootstrap

Whether to include the default bootstrap CSS.

utteranceMarker

How to specify breaks between utterances in the source(s). The ROCK convention is to use a newline (⁠\\n⁠).

coderId

A regular expression specifying the coder identifier, specified similarly to the codeRegexes.

idForOmittedCoderIds

The identifier to use for utterances that do not have a coder id (i.e. utterance that occur in a source that does not specify a coder id, or above the line where a coder id is specified).

Examples

### Get the default utteranceMarker
rock::opts$get(utteranceMarker);

### Set it to a custom version, so that every line starts with a pipe
rock::opts$set(utteranceMarker = "\n|");

### Check that it worked
rock::opts$get(utteranceMarker);

### Reset this option to its default value
rock::opts$reset(utteranceMarker);

### Check that the reset worked, too
rock::opts$get(utteranceMarker);

Description

Padd a character vector

Usage

padString(x, width, padding = " ")

Arguments

Value

x with padding appended to each element

Examples

padString(
  c("One",
    "Two",
    "Three"
  ),
  width = 7
);

Description

These function parse one (parse_source) or more (parse_sources) sources and the contained identifiers, sections, and codes.

Usage

parse_source(
  text,
  file,
  utteranceLabelRegexes = NULL,
  ignoreOddDelimiters = FALSE,
  checkClassInstanceIds = rock::opts$get(checkClassInstanceIds),
  postponeDeductiveTreeBuilding = FALSE,
  filesWithYAML = NULL,
  mergeAttributes = TRUE,
  removeSectionBreakRows = rock::opts$get("removeSectionBreakRows"),
  removeIdentifierRows = rock::opts$get("removeIdentifierRows"),
  removeEmptyRows = rock::opts$get("removeEmptyRows"),
  suppressDuplicateInstanceWarnings = rock::opts$get("suppressDuplicateInstanceWarnings"),
  rlWarn = rock::opts$get("rlWarn"),
  encoding = rock::opts$get("encoding"),
  silent = rock::opts$get("silent")
)

## S3 method for class 'rock_parsedSource'
print(x, prefix = "### ", ...)

parse_sources(
  path,
  extension = "rock|dct",
  regex = NULL,
  recursive = TRUE,
  removeSectionBreakRows = rock::opts$get("removeSectionBreakRows"),
  removeIdentifierRows = rock::opts$get("removeIdentifierRows"),
  removeEmptyRows = rock::opts$get("removeEmptyRows"),
  suppressDuplicateInstanceWarnings = rock::opts$get("suppressDuplicateInstanceWarnings"),
  filesWithYAML = NULL,
  ignoreOddDelimiters = FALSE,
  checkClassInstanceIds = rock::opts$get("checkClassInstanceIds"),
  mergeInductiveTrees = FALSE,
  encoding = rock::opts$get("encoding"),
  silent = rock::opts$get("silent")
)

## S3 method for class 'rock_parsedSources'
print(x, prefix = "### ", ...)

## S3 method for class 'rock_parsedSources'
plot(x, ...)