Title:	Reproducible Open Coding Kit
Version:	0.9.6
Date:	2025-06-11
Maintainer:	Gjalt-Jorn Peters <rock@opens.science>
Description:	The Reproducible Open Coding Kit ('ROCK', and this package, 'rock') was developed to facilitate reproducible and open coding, specifically geared towards qualitative research methods. It was developed to be both human- and machine-readable, in the spirit of MarkDown and 'YAML'. The idea is that this makes it relatively easy to write other functions and packages to process 'ROCK' files. The 'rock' package contains functions for basic coding and analysis, such as collecting and showing coded fragments and prettifying sources, as well as a number of advanced analyses such as the Qualitative Network Approach and Qualitative/Unified Exploration of State Transitions. The 'ROCK' and this 'rock' package are described in the ROCK book (Zörgő & Peters, 2022; https://rockbook.org), in Zörgő & Peters (2024) <doi:10.1080/21642850.2022.2119144> and Peters, Zörgő and van der Maas (2022) <doi:10.31234/osf.io/cvf52>, and more information and tutorials are available at https://rock.science.
BugReports:	https://codeberg.org/R-packages/rock/issues
URL:	https://rock.opens.science
License:	GPL-3
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.3.2
Depends:	R (≥ 4.1)
Imports:	data.tree (≥ 1.1.0), DiagrammeR (≥ 1.0.0), DiagrammeRsvg (≥ 0.1), ggplot2 (≥ 3.2.0), glue (≥ 1.3.0), htmltools (≥ 0.5.0), markdown (≥ 1.1), purrr (≥ 0.2.5), squids (≥ 25.5.3), yaml (≥ 2.2.0), yum (≥ 0.1.0)
Suggests:	covr, googlesheets4, haven (≥ 2.4), justifier (≥ 0.2), knitr, limonaid (≥ 25.5), openxlsx (≥ 4.2), pdftools, pkgdown (≥ 2.0.0), preregr (≥ 0.1.9), readxl, rmarkdown, rvest, rsvg, rstudioapi, striprtf, testthat, writexl, XLConnect, xml2, zip
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2025-06-11 16:47:32 UTC; Gjalt-Jorn Peters
Author:	Gjalt-Jorn Peters [aut, cre, cph], Szilvia Zörgő [aut]
Repository:	CRAN
Date/Publication:	2025-06-13 20:00:06 UTC

rock: A Reproducible Open Coding Kit

Description

This package implements an open standard for working with qualitative data, as such, it has two parts: a file format/convention and this R package that facilitates working with .rock files.

The ROCK File Format

The .rock files are plain text files where a number of conventions are used to add metadata. Normally these are the following conventions:

• The smallest 'codeable unit' is called an utterance, and utterances are separated by newline characters (i.e. every line of the file is an utterance);

• Codes are in between double square brackets: ⁠[[code1]]⁠ and ⁠[[code2]]⁠;

• Hierarchy in inductive code trees can be indicated using the greater than sign (>): ⁠[[parent1>child1]]⁠;

• Utterances can have unique identifiers called 'utterance identifiers' or 'UIDs', which are unique short alphanumeric strings placed in between double square brackets after 'uid:', e.g. ⁠[[uid:73xk2q07]]⁠;

• Deductive code trees can be specified using YAML

The rock R Package Functions

The most important functions are parse_source() to parse one source and parse_sources() to parse multiple sources simultaneously. clean_source() and clean_sources() can be used to clean sources, and prepend_ids_to_source() and prepend_ids_to_sources() can be used to quickly generate UIDs and prepend them to each utterance in a source.

For analysis, create_cooccurrence_matrix(), collapse_occurrences(), and collect_coded_fragments() can be used.

Author(s)

Maintainer: Gjalt-Jorn Peters rock@opens.science (ORCID) [copyright holder]

Authors:

• Szilvia Zörgő (ORCID)

See Also

Useful links:

• https://rock.opens.science

• Report bugs at https://codeberg.org/R-packages/rock/issues

Add HTML tags to a source

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

Apply multiple DiagrammeR global graph attributes

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

Specify that something is a source

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

Conversion between base10 and base30

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

Taking a vector, carry value over ('persistence')

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

Concatenate to screen without spaces

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], "'.");

Check for presence of a package

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

Get an item in a specific language

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.

Create a heatmap showing issues with items

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

Import a Narrative Response Model specification

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.

Cleaning & editing sources

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

Convert a character vector into an utterance vector

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

Replace code identifiers with their full paths

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.

Get a vector to find the full paths based on the leaf code identifier

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

Code frequencies separate by a variable

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

Create a frequency histogram for codes

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

Add one or more codes to one or more sources

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

Import a code book specification from a spreadsheet

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, ];
}

Convert a codebook specification to PDF

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

Convenience function to get a list of all available coding schemes

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

Collapse the occurrences in utterances into groups

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

Create an overview of coded fragments

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

Vector compression helper functions

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

Confidence intervals for proportions, vectorized over all arguments

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 rock@opens.science

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

Conveniently convert vectors to numeric

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

Convert 'rectangular' or spreadsheet-format data to one or more sources

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

Count code occurrences

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

Create a coding scheme

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.

Create a co-occurrence matrix

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

Create HTML fragment with CSS styling

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.

Convert a document (.docx, .pdf, .odt, .rtf, or .html) to a plain text file

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

An very rudimentary example codebook specification

Description

This is a simple and relatively short codebook specification.

Usage

exampleCodebook_1

Format

An example of a codebook specification

Expand categorical attribute variables to a series of dichotomous variables

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

Exporting tables to HTML

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

Export a ROCK project to a single ROCKproject file

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

Export codes to a plain text file

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

Export the fully merged code tree(s)

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

Export a merged source data frame

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.

Export parsed sources to HTML or Markdown

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

Extract the codings by each coder using the coderId

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.

Extract the UIDs (or SQUIDs) from a vector

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

Convert a (pre)registration form to an R Markdown template

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

Generate a TSSID

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

Generate utterance identifiers (UIDs)

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

Generic underlying recoding function

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.

Get the code identifiers a code's descendents

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)

Get the code identifiers from QNA codings

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

Return all values from a nested list in a dataframe

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

Create a filter to select utterances in a source

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.

Get the state transition data frame

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

Get the Dot code for a state transition graph

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

Get the state transition table

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

Get utterances and codes from source

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

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

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

Print a heading

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"

Make a vector of strings into headings

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"

Generic convenience function to create a heatmap

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

Import a ROCK project from a ROCKproject file

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

Import a source from Google Documents

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;
}

Read sources from a directory, parse them, and show coded fragments and code tree

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

Load a source from a file or a string

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

Make a ROCK project configuration file

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

Masking sources

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

Match the corresponding indices of (YAML) delimiters in a sequential list

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

Merge source files by different coders

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.

Convert a number to a date using Excel's system

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

Options for the rock package

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

Padd a character vector

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

Parsing sources

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, ...)

Arguments

Value

For rock::parse_source(), an object of class rock_parsedSource; for rock::parse_sources(), an object of class rock_parsedSources. These objects contain the original source(s) as well as the final data frame with utterances and codes, as well as the code structures.

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

### Show inductive code tree for the codes
### extracted with the regular expression specified with
### the name 'codes':
parsedExample$inductiveCodeTrees$codes;

### If you want `rock` to be chatty, use:
parsedExample <- rock::parse_source(exampleFile,
                                    silent=FALSE);

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

### Show combined inductive code tree for the codes
### extracted with the regular expression specified with
### the name 'codes':
parsedExamples$inductiveCodeTrees$codes;

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

Parsing sources separately for each coder

Description

Parsing sources separately for each coder

Usage

parse_source_by_coderId(
  input,
  ignoreOddDelimiters = FALSE,
  postponeDeductiveTreeBuilding = TRUE,
  rlWarn = rock::opts$get(rlWarn),
  encoding = "UTF-8",
  silent = TRUE
)

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

Arguments

Value

For rock::parse_source_by_coderId(), an object of class rock_parsedSource; for rock::parse_sources_by_coderId(), an object of class rock_parsedSources. These objects contain the original source(s) as well as the final data frame with utterances and codes, as well as the code structures.

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_by_coderId(exampleFile);

Create an ENA network out of one or more parsed sources

Description

Create an ENA network out of one or more parsed sources

Usage

parsed_sources_to_ena_network(
  x,
  unitCols,
  conversationCols = "originalSource",
  codes = x$convenience$codingLeaves,
  metadata = x$convenience$attributesVars
)

Arguments

Value

The result of a call to rENA::ena.plot.network(), if that is installed.

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

### Add something to indicate which units belong together; normally,
### these would probably be indicated using one of the identifier,
### for example the stanza identifiers, the sid's
nChunks <- nrow(parsedExamples$mergedSourceDf) %/% 10;
parsedExamples$mergedSourceDf$units <-
  c(rep(1:nChunks, each=10), rep(max(nChunks), nrow(parsedExamples$mergedSourceDf) - (10*nChunks)));

### Generate ENA plot

enaPlot <-
  rock::parsed_sources_to_ena_network(parsedExamples,
                                      unitCols='units');

### Show the resulting plot
print(enaPlot);

Prepend lines with one or more class instance identifiers to one or more sources

Description

These functions add lines with class instance identifiers to the beginning of one or more sources that were read with one of the loading_sources functions.

Usage

prepend_ciids_to_source(
  input,
  ciids,
  output = NULL,
  allOnOneLine = FALSE,
  designationSymbol = "=",
  preventOverwriting = rock::opts$get("preventOverwriting"),
  rlWarn = rock::opts$get(rlWarn),
  encoding = rock::opts$get("encoding"),
  silent = rock::opts$get("silent")
)

prepend_ciids_to_sources(
  input,
  ciids,
  output = NULL,
  outputPrefix = "",
  outputSuffix = "_coded",
  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);

### Add a coder identifier
loadedExample <-
  rock::prepend_ciids_to_source(
    loadedExample,
    c("codeId" = "iz0dn96")
  );

### Show lines 1-5
cat(loadedExample[1:5]);

Prepending unique utterance identifiers

Description

This function prepends unique utterance identifiers to each utterance (line) in a source. Note that you'll probably want to clean the sources using clean_sources() first.

Usage

prepend_ids_to_source(
  input,
  output = NULL,
  origin = Sys.time(),
  follow = NULL,
  followBy = NULL,
  rlWarn = rock::opts$get(rlWarn),
  preventOverwriting = rock::opts$get(preventOverwriting),
  encoding = rock::opts$get(encoding),
  silent = rock::opts$get(silent)
)

prepend_ids_to_sources(
  input,
  output = NULL,
  outputPrefix = "",
  outputSuffix = "_withUIDs",
  origin = Sys.time(),
  follow = NULL,
  followBy = NULL,
  uidSpacing = NULL,
  preventOverwriting = rock::opts$get(preventOverwriting),
  encoding = rock::opts$get(encoding),
  silent = rock::opts$get(silent)
)

Arguments

Value

The source with prepended uids, either invisible (if output if specified) or visibly (if not).

Examples

### Simple example
rock::prepend_ids_to_source(
  "brief\nexample\nsource"
);

### Example including fake YAML fragments
longerExampleText <-
  c(
    "---",
    "First YAML fragment",
    "---",
    "So this is an utterance (i.e. outside of YAML)",
    "This, too.",
    "---",
    "Second fragment",
    "---",
    "Another real utterance outside of YAML",
    "Another one outside",
    "Last 'real utterance'"
  );

rock::prepend_ids_to_source(
  longerExampleText
);

Prepend a line with a TSSID to a source

Description

This function adds a line with a TSSID (a time-stamped source identifier) to the beginning of a source that was read with one of the loading_sources functions. When combined with UIDs, TSSIDs are virtually unique references to a specific data fragment.

Usage

prepend_tssid_to_source(
  input,
  moment = format(Sys.time(), "%Y-%m-%d %H:%M"),
  output = NULL,
  designationSymbol = "=",
  preventOverwriting = rock::opts$get("preventOverwriting"),
  rlWarn = rock::opts$get(rlWarn),
  encoding = rock::opts$get("encoding"),
  silent = rock::opts$get("silent")
)

Arguments

Details

TSSIDs are a date and time in the UTC timezone, consisting of eight digits (four for the year, two for the month, and two for the day), a T, four digits (two for the hour and two for the minute), and a Z (to designate that the time is specified in the UTC timezone). TSSIDs are valid ISO8601 standard date/times.

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

### Add a coder identifier
loadedExample <-
  rock::prepend_tssid_to_source(
    loadedExample,
    moment = "2025-05-28 11:30 CEST"
  );

### Show the first line
cat(loadedExample[1]);

Efficiently preprocess data

Description

Efficiently preprocess data

Usage

preprocess_source(
  input,
  output = NULL,
  clean = TRUE,
  cleaningArgs = NULL,
  wordwrap = TRUE,
  wrappingArgs = NULL,
  prependUIDs = TRUE,
  UIDArgs = NULL,
  preventOverwriting = rock::opts$get("preventOverwriting"),
  encoding = rock::opts$get("encoding"),
  rlWarn = rock::opts$get("rlWarn"),
  silent = rock::opts$get("silent")
)

Arguments

Value

The preprocessed source as character vector.

Examples

exampleText <-
  paste0(
    "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."
  );

### Show example text
cat(exampleText);

### Show preprocessed example text
rock::preprocess_source(
  exampleText
);

Initialize a (pre)registration

Description

To initialize a (pre)registration, pass 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

prereg_initialize(x, initialText = "Unspecified")

Arguments

Details

For an introduction to working with {preregr} (pre)registrations, see the "Specifying preregistration content" vignette.

Value

The empty (pre)registration specification.

Examples

rock::prereg_initialize(
  "preregQE_v0_95"
);

Prettify a source in HTML

Description

This function adds HTML tags to a source to allow pretty printing/viewing. For an example, visit https://rock.opens.science/articles/rock.html.

Usage

prettify_source(
  x,
  heading = NULL,
  headingLevel = 2,
  add_html_tags = TRUE,
  output = NULL,
  outputViewer = "viewer",
  template = "default",
  includeCSS = TRUE,
  preserveSpaces = TRUE,
  includeBootstrap = rock::opts$get("includeBootstrap"),
  preventOverwriting = rock::opts$get(preventOverwriting),
  silent = rock::opts$get(silent)
)

Arguments

Value

A character vector with the prettified source

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

### Prettify source; if using RStudio, by default the
### prettified source is shown in the viewer. You can
### view the output of this example in the "rock" vignette
### at https://rock.opens.science/articles/rock.html
rock::prettify_source(
  exampleFile
);

Plot the graphs in a list of graphs

Description

Plot the graphs in a list of graphs

Usage

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

Arguments

Value

x, invisibly

Convert a QNA network to Linear Topic Map format

Description

The Linear Topic Map format, LTM (https://ontopia.net/download/ltm.html), allows specification of networks in a human-readable format.

Usage

qna_to_tlm(
  x,
  topicmapId = "rock_qna_topicmap",
  topicmapTitle = "A ROCK QNA Topic Map"
)

Arguments

Value

If x is a single parsed source: a character vector holding the Linear Topic Map specification; or, if multiple network coding schemes were used in parallel, each in a list. If x contains multiple parseds sources, a list of such objects (i.e., a list of vectors, or a list of lists of vectors).

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

### Convert and show the topic map
cat(
  rock::qna_to_tlm(
    qnaExample
  ),
  sep="\n"
);

Qualitative/Unified Exploration of State Transitions

Description

Qualitative/Unified Exploration of State Transitions

Usage

quest(
  x,
  rawClassIdentifierCol = "state_raw",
  labelFun = base::round,
  labelFunArgs = list(digits = 2)
)

Arguments

Value

A DiagrammeR::grViz() object, which will print to show the QUEST 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 a QUEST graph
rock::quest(
  parsedExample
);

Bind lots of dataframes together rowwise

Description

Bind lots of dataframes together rowwise

Usage

rbind_df_list(x)

Arguments

Value

A dataframe

Examples

rbind_df_list(list(Orange, mtcars, ChickWeight));

Simple alternative for rbind.fill or bind_rows

Description

Simple alternative for rbind.fill or bind_rows

Usage

rbind_dfs(x, y, clearRowNames = TRUE)

Arguments

Value

The merged dataframe

Examples

rbind_dfs(Orange, mtcars);

Convenience function to read spreadsheet-like files

Description

Currently reads spreadsheets from Google Sheets or from xlsx, csv, or sav files.

Usage

read_spreadsheet(
  x,
  sheet = NULL,
  columnDictionary = NULL,
  localBackup = NULL,
  exportGoogleSheet = FALSE,
  flattenSingleDf = FALSE,
  xlsxPkg = c("rw_xl", "openxlsx", "XLConnect"),
  failQuietly = FALSE,
  silent = rock::opts$get("silent")
)

Arguments

Value

A list of dataframes, or, if only one data frame was loaded and flattenSingleDf is TRUE, a data frame.

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
  ROCK_codebook <-
    read_spreadsheet(
      paste0(
        "https://docs.google.com/spreadsheets/d/",
        "1gVx5uhYzqcTH6Jq7AYmsLvHSBaYaT-23c7ZhZF4jmps"
      )
    );

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

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

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

Remove one or more codes

Description

These functions remove one or more codes from a source, and make it easy to justify that decision.

Usage

recode_delete(
  input,
  codes,
  filter = TRUE,
  output = NULL,
  filenameRegex = ".*",
  outputPrefix = "",
  outputSuffix = "_rcDeleted",
  childrenReplaceParents = TRUE,
  recursiveDeletion = FALSE,
  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.

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::load_source(exampleFile);

### Delete two codes, moving children to the codes' parents
recoded_source <-
  rock::recode_delete(
    loadedExample,
    codes=c("childCode2", "childCode1"),
    silent=FALSE
  );

### Process an entire directory
list_of_recoded_sources <-
  rock::recode_delete(
    examplePath,
    codes=c("childCode2", "childCode1"),
    silent=FALSE
  );

Merge two or more codes

Description

This function merges two or more codes into one.

Usage

recode_merge(
  input,
  codes,
  mergeToCode,
  filter = TRUE,
  output = NULL,
  filenameRegex = ".*",
  outputPrefix = "",
  outputSuffix = "_rcMerged",
  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 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
loadedExample <- rock::load_source(exampleFile);

### Move two codes to a new parent, showing progress
recoded_source <-
  rock::recode_merge(
    loadedExample,
    codes=c("childCode2", "grandchildCode2"),
    mergeToCode="mergedCode",
    silent=FALSE
  );

Move one or more codes to a different parent

Description

These functions move a code to a different parent (and therefore, ancestry) in one or more sources.

Usage

recode_move(
  input,
  codes,
  newAncestry,
  filter = TRUE,
  output = NULL,
  filenameRegex = ".*",
  outputPrefix = "",
  outputSuffix = "_rcMoved",
  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 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
loadedExample <- rock::load_source(exampleFile);

### Move two codes to a new parent, showing progress
recoded_source <-
  rock::recode_move(
    loadedExample,
    codes=c("childCode2", "childCode1"),
    newAncestry = "parentCode2",
    silent=FALSE
  );

Rename one or more codes

Description

These functions rename one or more codes in one or more sources.

Usage

recode_rename(
  input,
  codes,
  filter = TRUE,
  output = NULL,
  filenameRegex = ".*",
  outputPrefix = "",
  outputSuffix = "_rcRenamed",
  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 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
loadedExample <- rock::load_source(exampleFile);

### Move two codes to a new parent, showing progress
recoded_source <-
  rock::recode_rename(
    loadedExample,
    codes=c(childCode2 = "grownUpCode2",
            grandchildCode2 = "almostChildCode2"),
    silent=FALSE
  );

Split a code into multiple codes

Description

This function conditionally splits a code into multiple codes. Note that you may want to use recode_addChildCodes() instead to not lose the original coding.

Usage

recode_split(
  input,
  codes,
  splitToCodes,
  filter = TRUE,
  output = NULL,
  filenameRegex = ".*",
  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 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
loadedExample <- rock::load_source(exampleFile);

### Split a code into two codes, showing progress
recoded_source <-
  rock::recode_split(
    loadedExample,
    codes="childCode1",
    splitToCodes = list(
      and_REPLACED = " and ",
      book_REPLACED = "book",
      else_REPLACED = TRUE
    ),
    silent=FALSE
  );

Repeat a string a number of times

Description

Repeat a string a number of times

Usage

repeatStr(n = 1, str = " ")

Arguments

Value

A character vector of length 1.

Examples

### 10 spaces:
repStr(10);

### Three euro symbols:
repStr("\u20ac", 3);

Show all coded fragments

Description

Show all coded fragments

Usage

resultsOverview_allCodedFragments(
  x,
  root = "codes",
  context = 0,
  heading = NULL,
  headingLevel = 2,
  add_html_tags = TRUE,
  cleanUtterances = FALSE,
  output = NULL,
  outputViewer = "viewer",
  template = "default",
  includeCSS = TRUE,
  includeBootstrap = rock::opts$get("includeBootstrap"),
  preventOverwriting = rock::opts$get(preventOverwriting),
  silent = rock::opts$get(silent)
)

Arguments

Value

Invisibly, the coded fragments in a character vector.

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

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

Get the roots from a vector with code paths

Description

Get the roots from a vector with code paths

Usage

root_from_codePaths(x)

Arguments

Value

A vector with the root of each element.

Examples

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

Create a source with items to code for Response Process Evaluation

Description

This function creates a plain text file, a .rock source, that can be coded when conducting Response Process Evaluation.

Usage

rpe_create_source_with_items(
  data,
  iterationId,
  batchId,
  populationId,
  itemVarNames,
  metaquestionIdentifiers,
  metaquestionVarNames,
  itemContents,
  metaquestionContents,
  coderId,
  caseIds = NULL,
  outputFile = NULL,
  preventOverwriting = rock::opts$get("preventOverwriting"),
  encoding = rock::opts$get("encoding"),
  silent = rock::opts$get("silent")
)

Arguments

Value

The created source, as a character vector (invisibly);

Save your justifications to a file

Description

When conducting analyses, you make many choices that ideally, you document and justify. This function saves stored justifications to a file.

Usage

save_workspace(
  file = rock::opts$get("justificationFile"),
  encoding = rock::opts$get("encoding"),
  append = FALSE,
  preventOverwriting = rock::opts$get("preventOverwriting"),
  silent = rock::opts$get("silent")
)

Arguments

Value

The result of a call to justifier::export_justification().

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::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_split(
    loadedExample,
    codes="childCode1",
    splitToCodes = list(
      `_and_` = " and ",
      `_book_` = "book",
      `_else_` = TRUE
    ),
    silent=FALSE,
    justification = "Because this seems like a good idea"
  );

### Save this workspace to a file
temporaryFilename <- tempfile();
rock::save_workspace(file = temporaryFilename);

Show a table with all attributes in the RStudio viewer and/or console

Description

Show a table with all attributes in the RStudio viewer and/or console

Usage

show_attribute_table(
  x,
  output = rock::opts$get("tableOutput"),
  tableOutputCSS = rock::opts$get("tableOutputCSS")
)

Arguments

Value

x, invisibly, unless being knitted into R Markdown, in which case a knitr::asis_output()-wrapped character vector is returned.

Show the fully merged code tree(s)

Description

Show the fully merged code tree(s)

Usage

show_fullyMergedCodeTrees(x)

Arguments

Value

The result of a call to DiagrammeR::render_graph().

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 merged code tree
show_fullyMergedCodeTrees(loadedExample);

Show the inductive code tree(s)

Description

This function shows one or more inductive code trees.

Usage

show_inductive_code_tree(
  x,
  codes = ".*",
  output = "both",
  headingLevel = 3,
  nodeStyle = list(shape = "box", fontname = "Arial"),
  edgeStyle = list(arrowhead = "none"),
  graphStyle = list(rankdir = "LR")
)

Arguments

Value

x, invisibly, unless being knitted into R Markdown, in which case a knitr::asis_output()-wrapped character vector is returned.

Soft Non-numeric Occurrence Estimation (SNOE) plot

Description

Soft Non-numeric Occurrence Estimation (SNOE) plot

Usage

snoe_plot(
  x,
  codes = ".*",
  matchRegexAgainstPaths = TRUE,
  estimateWithin = NULL,
  title = "SNOE plot",
  ggplot2Theme = ggplot2::theme_minimal(),
  greyScale = FALSE,
  colors = c("#0072B2", "#C0C0C0"),
  greyScaleColors = c("#808080", "#C0C0C0"),
  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-3.rock");

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

### Show code occurrence estimates
rock::snoe_plot(
  loadedExample
);

### Load two example sources
loadedExamples <- rock::parse_sources(
  examplePath,
  regex = "example-[34].rock"
);

rock::snoe_plot(
  loadedExamples
);

Split long lines

Description

This function splits long lines at a given number of characters, keeping words intact. It's basically a wrapper around strwrap().

Usage

split_long_lines(
  x,
  length = 60,
  collapseResult = FALSE,
  splitString = rock::opts$get("utteranceMarker")
)

Arguments

Value

A character vector.

Examples

cat(
  rock::split_long_lines(
    paste0(
      "Lorem ipsum dolor sit amet, consectetur adipiscing elit. ",
      "Vestibulum et dictum urna. Donec neque nunc, lacinia vitae ",
      "varius vitae, pretium quis nibh. Aliquam pulvinar, lacus ",
      "sed varius vulputate, justo nibh blandit quam, ",
      "nec sollicitudin velit augue eget erat."
    )
  )
);

Strip the root from a code path

Description

This function strips the root (just the first element) from a code path, using the codeTreeMarker stored in the opts object as marker.

Usage

stripCodePathRoot(x)

Arguments

Value

The modified vector of code paths.

Examples

stripCodePathRoot("codes>reason>parent_feels");

Synchronize multiple streams

Description

This function maps the codes from multiple streams onto a primary stream.

Usage

sync_streams(
  x,
  primaryStream,
  columns = NULL,
  anchorsCol = rock::opts$get("anchorsCol"),
  sourceId = rock::opts$get("sourceId"),
  streamId = rock::opts$get("streamId"),
  prependStreamIdToColName = FALSE,
  appendStreamIdToColName = TRUE,
  sep = " ",
  fill = TRUE,
  paddingValue = NA,
  neverFill = grep("_raw$", names(x$qdt), value = TRUE),
  compressFun = NULL,
  compressFunPart = NULL,
  expandFun = NULL,
  carryOverAnchors = FALSE,
  colNameGlue = rock::opts$get("colNameGlue"),
  silent = rock::opts$get("silent")
)

Arguments

Value

The object with parsd sources, x, with the synchronization results added in the ⁠$syncResults⁠ subobject.

Examples

### Get a directory with example sources
examplePath <-
  file.path(
    system.file(package="rock"),
    'extdata',
    'streams'
  );

### Parse the sources
parsedSources <- rock::parse_sources(
  examplePath
);

### Add a dataframe, syncing all streams to primary stream !
parsedSources <- rock::sync_streams(
  parsedSources,
  primaryStream = "streamA",
  columns = c("Code1", "Code2", "Code3"),
  prependStreamIdToColName = TRUE
);

### Look at two examples
parsedSources$syncResults$qdt[
  ,
  c("streamB_Code3_streamB", "streamC_Code1_streamC")
];

Sync (expand or compress) a vector

Description

Sync (expand or compress) a vector

Usage

sync_vector(
  x,
  newLength,
  sep = " ",
  fill = TRUE,
  compressFun = NULL,
  expandFun = NULL,
  compressFunPart = NULL,
  silent = rock::opts$get("silent")
)

Arguments

Value

The synced vector

Examples

rock::sync_vector(letters[1:10], 15);
rock::sync_vector(letters[1:10], 5);

Compress a vector or data frame

Description

Compress a vector or data frame

Usage

syncing_df_compress(
  x,
  newLength,
  sep = " ",
  compressFun = NULL,
  compressFunPart = NULL,
  silent = rock::opts$get("silent")
)

syncing_vector_compress(
  x,
  newLength,
  sep = " ",
  compressFun = NULL,
  compressFunPart = NULL,
  silent = rock::opts$get("silent")
)

Arguments

Value

The compressed vector or data frame

Examples

rock::syncing_vector_compress(
  1:10,
  3
);

rock::syncing_df_compress(
  mtcars[, 1:4],
  6
);

rock::syncing_df_compress(
  mtcars[, 1:4],
  6,
  compressFunPart = mean
);

Expand a vector or data frame

Description

Expand a vector or data frame

Usage

syncing_df_expand(
  x,
  newLength,
  fill = TRUE,
  neverFill = NULL,
  paddingValue = NA,
  expandFun = NULL,
  silent = rock::opts$get("silent")
)

syncing_vector_expand(
  x,
  newLength,
  fill = TRUE,
  paddingValue = NA,
  expandFun = NULL,
  silent = rock::opts$get("silent")
)

Arguments

Value

The expanded vector

Examples

rock::syncing_vector_expand(letters[1:10], 15);
rock::syncing_vector_expand(letters[1:10], 15, fill=FALSE);

Create a templated report for cognitive interviews

Description

Use this function to export a templated report for cognitive interviews. To embed it in an R Markdown file, use !!! CREATE rock::knit_codebook() !!!

Usage

template_ci_heatmap_1_to_pdf(
  x,
  file,
  title = "Cognitive Interview: Heatmap and Coded Fragments",
  author = NULL,
  caption = "Heatmap",
  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 CI
examplePath <- file.path(system.file(package="rock"), 'extdata');
parsedCI <- parse_source(file.path(examplePath,
                                   "ci_example_1.rock"));

rock::template_ci_heatmap_1_to_pdf(
  parsedCI,
  file = tmpFile
);

Convert a codebook specification to PDF

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

template_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 codebook
data("exampleCodebook_1", package = "rock");

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

Easily parse a vector into a character value

Description

Easily parse a vector into a character value

Usage

vecTxt(
  vector,
  delimiter = ", ",
  useQuote = "",
  firstDelimiter = NULL,
  lastDelimiter = " & ",
  firstElements = 0,
  lastElements = 1,
  lastHasPrecedence = TRUE
)

vecTxtQ(vector, useQuote = "'", ...)

Arguments

Value

A character vector of length 1.

Examples

vecTxtQ(names(mtcars));

Wordwrapping a source

Description

This function wordwraps a source.

Usage

wordwrap_source(
  input,
  output = NULL,
  length = 40,
  removeNewlines = FALSE,
  removeTrailingNewlines = TRUE,
  rlWarn = rock::opts$get(rlWarn),
  preventOverwriting = rock::opts$get("preventOverwriting"),
  encoding = rock::opts$get(encoding),
  silent = rock::opts$get(silent),
  utteranceMarker = rock::opts$get("utteranceMarker")
)

Arguments

Value

A character vector.

Examples

exampleText <-
  paste0(
    "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."
  );

### Show example text
cat(exampleText);

### Show preprocessed example text
cat(
  paste0(
    rock::wordwrap_source(
      exampleText
    ),
    collapse = "\n"
  )
);

Wrap all elements in a vector

Description

Wrap all elements in a vector

Usage

wrapVector(x, width = 0.9 * getOption("width"), sep = "\n", ...)

Arguments

Value

A character vector

Examples

res <- wrapVector(
  c(
    "This is a sentence ready for wrapping",
    "So is this one, although it's a bit longer"
  ),
  width = 10
);

print(res);
cat(res, sep="\n");

Write a source to a file

Description

These functions write one or more source(s) from memory (as loaded by load_source() or load_sources() to a file.

Usage

write_source(
  x,
  output,
  encoding = rock::opts$get("encoding"),
  preventOverwriting = rock::opts$get("preventOverwriting"),
  silent = rock::opts$get("silent")
)

write_sources(
  x,
  output,
  filenamePrefix = "",
  filenameSuffix = "_written",
  recursive = TRUE,
  encoding = rock::opts$get("encoding"),
  preventOverwriting = rock::opts$get("preventOverwriting"),
  silent = rock::opts$get("silent")
)

Arguments

Value

Invisibly, the input (x), to enable chaining in pipes.

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

### Get a temporary file to write to
tempFile <- tempfile(fileext = ".rock")

### For R versions below 4.1
loadedSource <-
  rock::load_source(exampleFile);

loadedSource <-
  rock::code_source(
    loadedSource,
    c("Lorem Ipsum" = "lorumIpsum")
  );

rock::write_source(
  loadedSource,
  tempFile
);

### From R 4.1 onwards, you can also chain
### these commands using the pipe operator.
###
### Note that that means that this example
### will not run if you have a previous
### version of R.
loadedSource <-

  rock::load_source(exampleFile) |>

  rock::code_source(c("Lorem Ipsum" = "lorumIpsum")) |>

  rock::write_source(tempFile);

Get indices of YAML delimiters

Description

Get indices of YAML delimiters

Usage

yaml_delimiter_indices(x)

Arguments

Value

A numeric vector.

Examples

yaml_delimiter_indices(
  c("not here",
    "---",
    "above this one",
    "but nothing here",
    "below this one, too",
    "---")
);
### [1] 2 6