This R Markdown file accompanies the two-day workshop for Simple Qualitative Administration For File Organization and Development (SQAFFOLD) created by Szilvia Zörgő and the Reproducible Open Coding Kit (ROCK) developed by Gjalt-Jorn Peters and Szilvia Zörgő. The script below integrates the directory structure and functionality of the R package {rock}. For more ROCK functions and materials, see: https://rock.science. Below “{rock}” is used to refer to the R package, “ROCK” refers to the standard or to both the R package and the standard simultaneously.
| Resource type | URL |
|---|---|
| Open Science Framework repository | https://osf.io/knwg9 |
| SQAFFOLD Website | https://www.sqaffold.org |
| ROCK Website | https://rock.science |
| Git repository | https://gitlab.com/sqaffold/2-day-workshop |
| License | CC0 1.0 Universal |
| Rendered version of script | https://sqaffold.gitlab.io/2-day-workshop |
| SQAFFOLD Main repository | https://gitlab.com/sqaffold/sqaffold-main |
| Posit Cloud project for workshop | https://posit.cloud/content/7313968 |
SQAFFOLD is a directory system, which aims to facilitate the organization of materials generated in qualitative or unified research projects. The subdirectories can be flexibly rearranged or extended to suit your current project. SQAFFOLD also contains plain text files: some are empty, to be filled with project content (if it makes sense for your project); other plain text files contain ideas, tools, links to resources that may be useful in various stages of your research process.
Through {rock} functionality, SQAFFOLD also has the potential to be used for various tasks within a qualitative or unified research project, such as cleaning qualitative data, adding unique utterance identifiers to data segments, coding and segmenting data, and tabularizing them. To access these functions, you need to use the R script below.
The script below, as the entire directory structure, houses workshop
materials and various resources. During the workshop, we will be drawing
on these resources and discussing aspects of qualitative/unified
research. I suggest you work directly in the SQAFFOLD you downloaded to
your computer at the beginning of the workshop. If you want to use
SQAFFOLD for a later project, you can just download it again from https://www.sqaffold.org.
To employ the script below, you need to download R and RStudio; some guidance on that is available here: https://sci-ops.gitlab.io/rockbook/rock-tutorial.html.
If you do not want to work locally, you can use Posit Cloud (formerly: RStudio Cloud; https://posit.cloud) by creating an account and uploading SQAFFOLD as a zip file. In this case, you do not need to download anything R-related.
Markdown is a simple formatting syntax for authoring HTML, PDF, and MS Word documents. For more details on using R Markdown see http://rmarkdown.rstudio.com.
The script below contains R commands (in the gray sections called “chunks”), which can be run individually by pressing the green “play button” in the chunk’s upper right corner. Note, you will only see this option if you open the script in RStudio; otherwise, this file, like every other file in SQAFFOLD, merely contains plain text.
Below are some basic {rock} functions you can run from SQAFFOLD. To access full {rock} functionality, see: https://rock.opens.science. SQAFFOLD Main and Modified SQAFFOLD (for this workshop) integrate Git as well (see e.g., files with the .git extension), which is a repository and version control system. For setting up a Gitlab repository, see: https://sci-ops.gitlab.io/rockbook/rock-tutorial.html#setting-up-the-basics. You do not need to use Git in order for SQAFFOLD or {rock} functionality to work, but it is a best practice.
Run this chunk every time you start a session! The
chunk below will install all R packages needed to run the commands in
the script. To be sure you are up-to-date, run this chunk every time you
wish to use the script. This chunk also contains the specifications for
persistent identifiers (see: https://sci-ops.gitlab.io/rockbook/rock-tutorial.html#designate-your-persistent-ids);
if you have any other persistent IDs apart from the ones listed, you can
add those here. Lastly, this chunk contains the paths to subdirectories,
which {rock} commands will consider input and output destinations. Run
it by clicking on the green play button in the top right corner of the
chunk.
To run commands when knitting this script, change “eval
= FALSE” to “eval = TRUE” in the knitr options!
### package installs and updates
packagesToCheck <- c("rock", "here", "knitr", "writexl");
for (currentPkg in packagesToCheck) {
if (!requireNamespace(currentPkg, quietly = TRUE)) {
install.packages(currentPkg, repos="http://cran.rstudio.com");
}
}
knitr::opts_chunk$set(
echo = TRUE,
eval = FALSE,
comment = ""
);
rock::opts$set(
silent = TRUE,
idRegexes = list(
cid = "\\[\\[cid[=:]([a-zA-Z][a-zA-Z0-9_]*)\\]\\]",
coderId = "\\[\\[coderid[=:]([a-zA-Z][a-zA-Z0-9_]*)\\]\\]"
),
sectionRegexes = list(
sectionBreak = "---<<([a-zA-Z][a-zA-Z0-9_]*)>>---"
),
persistentIds = c("cid", "coderId")
);
### Set paths for later
basePath <- here::here();
dataPath <- file.path(basePath, "data");
scriptsPath <- file.path(basePath, "scripts");
resultsPath <- file.path(basePath, "results");Your data in raw form is in the “000—raw-data” subdirectory located within the data directory. The same data has been put into separate plain text files based on speaker, and placed into the “010—raw-sources” subdirectory . Your data should be in plain text files from here on; these are referred to as “sources”. For more on preparing data, see: https://sci-ops.gitlab.io/rockbook/rock-tutorial.html#data-preparation.
There is also a list of attributes of your data providers (in the
data directory). These have been specified according to the ROCK
standard. For more on this format, see: https://sci-ops.gitlab.io/rockbook/rock-tutorial.html#designate-your-attributes.
Qualitative data is often “messy”, but you can use this command to help you clean them in several respects. To view these aspects, type “?rock::clean_sources” into the console and hit enter. Most importantly, the cleaning command places each of the sentences in your data on a new line. Since coding with iROCK (see below) is performed per line of data, this act of segmentation is a necessary step when working with the ROCK. But your data does not need to be segmented based on sentences. The smallest codable pieces can be anything from a paragraph to an entire transcript. The {rock} package recognizes newline characters as indicators of segmentation, so if you do not want to code sentence-by-sentence, you can place your chosen segments on new lines manually or change the default options in the R package. Note, this act of segmentation refers to the lowest level (on which you will code); you can also add higher levels of segmentation (e.g., delimiting topics), by adding section breaks. For more on section breaks, see: https://sci-ops.gitlab.io/rockbook/rock-tutorial.html#coding-and-segmentation. The chunk below will write the cleaned sources found in “010—raw-sources” into the subdirectory “020—cleaned-sources”.
rock::clean_sources(
input = file.path(dataPath, "010---raw-sources"),
output = file.path(dataPath, "020---cleaned-sources")
);If it makes sense for your project, you may choose to add a unique identifier to each line of data (lines from here on are referred to as “utterances”). With this unique utterance identifier (uid), you will be able to locate or refer to any specific utterance in your dataset. Furthermore, if multiple coders are employing different codes (or coding schemes) to code the data, you may want to merge those different versions of the coded sources into a source that contains all codes applied by the various researchers; this merging takes place based on uids. To view more on uids, type “?rock::prepend_ids_to_sources” into the console and hit enter. The chunk below will write the sources with uids into the subdirectory “030—sources-with-uids”.
rock::prepend_ids_to_sources(
input = file.path(dataPath, "020---cleaned-sources"),
output = file.path(dataPath, "030---sources-with-uids")
);If you’d like to code your data manually, you can use a rudimentary graphical user interface called iROCK (available at: https://i.rock.science). This interface allows you to upload your codes, section breaks (for higher levels of segmentation), and your sources, and then drag and drop codes/section breaks into the data. Please remember to download your work once you have finished coding. More information on iROCK is available here: https://sci-ops.gitlab.io/rockbook/rock-tutorial.html#coding-and-segmentation.
Note, your codes and section breaks need to be in a specific format if you wish to upload them as a list. If you want to generate them via the interface inductively, then iROCK places those into the specified format automatically. Once you have coded and downloaded your sources, in order for the commands below to work, you need to modify the name of the sources to include a “slug”. You may have noticed that the above commands (cleaning and adding uids) have also placed a slug on the name of your sources. After coding, rename sources to include the slug: “_coded”; for example: “002_Source_cleaned_withUIDs_coded”. (You may also use a different slug, but then remember to change the code in the script as well!)
If you’d like to employ automated coding and/or you want to use
{rock} recode functions, please refer to: https://rock.opens.science and https://rock.science.
If multiple coders are applying different codes or coding schemes to the same dataset, or if a single coder is applying different codes in different rounds of coding, then merging coded sources may be useful. Merging means that you combine different coded versions of the same source into a “master” source that contains all applied codes. Merging is made possible via unique utterance identifiers (uids).
Before running the command, make sure that the input directory (where the sources to be merged are located) is indeed “041—coded-sources-for-merging” and that the output directory (where the merged sources should be written) is the same. If these do not correspond to your wishes, you can modify them within the chunk. A good practice is to create a “slug” for each coded version of the sources, for example, “_coder1” and “_coder2”. You will have to choose a version of the coded source to be the foundation upon which the other versions are merged (indicated by “primarySourcesRegex” in the code below). For example, the command below says that all versions of each source should be “collapsed” onto the version with the slug: “_coder1”. The command below will write the merged sources into the same directory as where it found them, resulting in a merged version for each source that you placed into that directory.
rock::merge_sources(input = here::here("data",
"041---coded-sources-for-merging"),
output = "same",
primarySourcesPath = here::here("data",
"041---coded-sources-for-merging"),
primarySourcesRegex = "_coder1\\.rock");Run this chunk every session during which you want to employ the functionality below (e.g., inspecting fragments, code frequencies, heatmaps)! This command will assemble all your coded sources (and persistent IDs and attributes, if you have specified these), into an R object that can be employed to run analyses and other commands below. The chunk below will use the coded sources (and if applicable, the YAML fragments) to parse your sources. The regex (regular expression) specified for retrieving those sources is set to “_coded”, the slug specified in the previous step (manual coding); please modify this regex in the chunk below if your slug is different.
Note, if you have used the merge sources command above, and you want to work with your merged sources regarding the commands below (code tree, heat map, code frequencies, etc.), then you should change the slug specified as the regex from “_coded” to “_merged”.
dat <-
rock::parse_sources(
dataPath,
regex = "_coded|attributes"
);The command below allows you to collect and inspect all coded fragments within your dataset, by code. The context is set to “2”, which means that you will see two lines of data prior to the coded line, and two lines subsequent to it. Feel free to change this number if you wish to see more/less lines of context. If you wish to only inspect a certain code or codes, use the command under the heading “Inspect coded fragments for specific code(s)”.
rock::collect_coded_fragments(
dat,
context = 2
);If you’d like to collect and inspect coded fragments for only certain codes, you can use the command below by changing the code labels “CodeA” and “CodeB” to the codes you’d like to inspect. If you’d only like to see fragments for a single code, just delete the “|CodeB”, and leave “CodeA” in the chunk. If you’d like to add codes to the list, use the pipe and add the code label(s), e.g.: “CodeA|CodeB|CodeC”. Again, you can modify the amount of context you wish to have around the coded utterance by changing “2” to any other number. The chunk below will show you coded utterances for all specified codes.
rock::inspect_coded_sources(
path = here::here("data", "040---coded-sources"),
fragments_args = list(
codes = "CodeA|CodeB",
context = 2
)
);This command prints all attributes listed in the case-attributes.rock file into tabular format.
rock::show_attribute_table(dat)Based on your codes, {rock} can create a code tree, provided your codes are specified according to the ROCK standard; they can be flat or hierarchical. For more on these specifications, please see: https://sci-ops.gitlab.io/rockbook/rock-tutorial.html#designate-your-codes-and-section-breaks.
rock::show_fullyMergedCodeTrees(dat)This command will allow you to see a bar chart of the code frequencies within the various sources they were applied. The command also produces a legend at the bottom of the visual to help identify the sources based on color.
rock::code_freq_hist(
dat
);Code co-occurrences can be visualized with a heatmap. This representation will use colors to indicate the code co-occurrence frequencies. Co-occurrences are defined as two or more codes occurring on the same line of data (utterance). The console will also show you the co-occurrence matrix from which the visualization was generated.
rock::create_cooccurrence_matrix(
dat,
plotHeatmap = TRUE);This command will enable a tabularized version of your dataset, which for example, can be employed to further process your data with software such as Epistemic Network Analysis (https://www.epistemicnetwork.org), or “merely” represent your coded data in a single file. In this dataset, rows are constituted by utterances, columns by variables and data. The file will be an Excel called “mergedSourceDf” located in the results subdirectory.
Provided you have added attributes, those will also be included. To make sure you are complying with the ROCK standard (which is necessary for the command to work), please see: https://sci-ops.gitlab.io/rockbook/rock-tutorial.html#rock-tutorial.
Beware, when re-generating the qualitative data table the {rock} default is to prevent overwriting, so either allow overwrite within the script, or delete the old excel before you run this chunk.
rock::export_mergedSourceDf_to_xlsx(
dat,
file.path(resultsPath,
"mergedSourceDf.xlsx")
);This command will create a state transition network (STN) from a specified source. In the chunk below, we specify the subdirectory “045—coded-sources_states” (containing three sources labeled with states), and the file “Source_01.txt” for the command to generate the STN.
### Get a path to one example file
exampleFile <-
file.path(dataPath, "045---coded-sources-states", "Source_01.txt");
### 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);As with the SQAFFOLD in general, this script can be (and should be!) tailored to your specific project. In its final state, it is not meant as a collection of actions you can perform on your data, but as a record of what you have actually done. If you, for example, have not looked at code frequencies, because it did not make sense in your project, or if you have not tabularized your data, it is recommended that you delete those chunks from the script.
Congruently, the descriptions above each command in the script are meant to guide your work and facilitate a general understanding of the functions; these can be deleted or modified to reflect a more specific application of the commands, or to elaborate on your process. Also, the information at the very top of the script (with author names, title, etc) should also be modified to reflect your project’s information.
Once you have added these details, you can make this script public to increase the transparency and confirmability of your coding and analytic process. The script will let your audience know what steps you went through to prepare, code, segment, analyze, and visualize your data. It is a helpful supplement to understanding your project, and it is a great way to adhere to Open Science principles.
The following workshops can be taken autonomously, based on the provided instructions and materials:
One-hour SQAFFOLD workshop: https://sqaffold.gitlab.io/1-hour-workshop
Two-hour
ROCK workshop: https://sci-ops.gitlab.io/rock-workshop-2-hour
For more on ROCK terminology, see: https://sci-ops.gitlab.io/rockbook/vocab.html.
SQAFFOLD and its one-hour workshop are licensed under CC0 1.0 Universal (public domain), which means you can employ them and modify them without having to cite the author. If you do wish to cite SQAFFOLD, you can do so as such:
Zörgő, S. (2023, August 9). SQAFFOLD. Retrieved from osf.io/zerwu
For other formats, see the citation bar of the OSF project: https://osf.io/zerwu
The Reproducible Open Coding Kit (ROCK) standard is licensed under CC0 1.0 Universal. The {rock} R package is licensed under a GNU General Public License; for more see: https://rock.science.
ROCK citation: Gjalt-Jorn Ygram Peters and Szilvia Zörgő (2023). rock: Reproducible Open Coding Kit. R package version 0.7.1. https://rock.opens.science
For more on ROCK materials licensing and citation, please see: https://rock.opens.science/authors.html#citation.
For more on licensing in general, see: https://creativecommons.org/choose and https://how-to-open.science/share/licenses.
Thank you for considering to use SQAFFOLD and ROCK for your
qualitative or unified project. If you have any questions or would like
to make suggestions on how to improve these resources, feel free to
write to: info@rock.science.