Reproducible Open Coding Kit Workshop (2 hour version)
Szilvia Zörgő & Gjalt-Jorn Peters
19:39:59 on 2021-10-31 UTC (UTC+0000)
This so-called R Markdown file accompanies a short Reproducible Open Coding Kit (ROCK) workshop developed by Szilvia Zörgő & Gjalt-Jorn Peters. More details are available below in section Links and resources.
Getting started
RStudio Cloud
The easiest way to get started is to copy this file to an RStudio Cloud project of your own. To do that, first visit the shared RStudio project at https://rstudio.cloud/project/2109292. Note that to view it, you will need to be logged in with an RStudio Cloud (or shinyapps.io) account, so create that first if you don’t have one yet.
Once it has loaded, click “Save a permanent copy” at the top:
Figure 1: A screenshot of RStudio Cloud
This will store the project in your account’s workspace, so you that your changes are preserved and you can always return to it. If you do not save a permanent copy, you will be ejected from the temporary project after a while and will have to start over.
Local RStudio Desktop
If you are already familiar with R, RStudio, and Git, you can also download this project and use your local RStudio Desktop installation. For the URL to the Git repository, see the Appendix.
Exercises
Exercise 1: prepend utterance identifiers (UIDs)
In this exercise you will command the rock package to read the clean sources and prepend uterrance identifiers (UIDs). The relative path to these clean sources from your project’s directory is data/05--clean-sources. This means that the sources are in the the 05--clean-sources directory (or folder) which is itself a subdirectory of the data directory, which sits in the project directory.
We use the here::here() function to conveniently locate the project directory; by passing the names of the subdirectories, it will always build a correct path that allows R (and the rock package) to find the sources on the harddisk.
If you want to have a look at the clean sources beforehand, navigate to the data directory in the file pane in the bottom-right, then open the 05--clean-sources directory, and the click the Facebook_data_cleaned.rock file to open it in RStudio.
After this function, rock::prepend_ids_to_sources(), has read the sources and prepended the UIDs, it will write the sources to the 10--sources-with-UIDs directory, which is also a subdirectory of the data directory. It will add the suffix _with_uids to each file it processed, which is convenient from a data management perspective.
In this exercise, we set the preventOverwriting argument to FALSE so that every time you run this code, new UIDs are designated, allowing you to play around a bit. Normally, you would never do this, because you want utterance identifiers to stay fixed throughout your project once they have been designated (therefore, the default value of the preventOverwriting argument is TRUE, so the rock always protects against overwriting unless your override that manually).
rock::prepend_ids_to_sources(
input = here::here("data", "05--clean-sources"),
output = here::here("data", "10--sources-with-UIDs"),
outputSuffix = "_with_uids",
preventOverwriting = FALSE
);Exercise 2: initial coding with iROCK
Open the iROCK interface at https://i.rock.science:
Figure 2: A screenshot of a fresh instance of iROCK
Click the ‘Sources’ button at the top to load a source. It will show you a dialogue similar to that shown in Figure 3. To load the example source, copy-paste the following URL into the field as shown in Figure 3 and press [ENTER].
Note that if you run MacOS instead of Windows, you have to copy-paste the URLs into your browser, and then store the file locally and upload from there.
- Example source to code: https://rock.science/workshop/2hr/source
Then repeat that to load the example Codes and Section Breaks, this time copy-pasting these two URLs:
- Example deductive codes to use: https://rock.science/workshop/2hr/codes
- Example breaks to use: https://rock.science/workshop/2hr/breaks
Figure 3: A screenshot of a fresh instance of iROCK
When you loaded all three the files into the right place, you should see something similar to what is shown in Figure 4:
Figure 4: A screenshot of iROCK with the example source, codes, and breaks loaded
You can now start coding and segmenting. To use one of the codes or section breaks you loaded, drag them from the right-hand panel and drop them where you want them in the source. If you make a mistake, simply click the section break or code to delete it again.
When you are done coding, you can download the coded source by clicking Download. Normally, it is vital to not forget that. In this workshop, in the next step you will import a pre-coded source, so no harm done if you forget to Download and save your coded source.
Exercise 3: inspect coded sources
Then, we can inspect the coded fragments. Because looking at all the coded fragments is a lot, we’ll just select two codes, ‘religion’ and ‘money’. We’ll also specify that we want to see two utterances of context. This means that we’ll get the two utterances preceding and following each coded utterance. These two arguments are passed in a list that itself is passed as argument fragment_args:
rock::inspect_coded_sources(
path = here::here("data", "20--sources-after-initial-coding"),
fragments_args = list(
codes = "religion|money",
context = 2
)
);Inductive code tree for codes
levelName 1 codes 2 ¦--CONTENT 3 ¦ ¦--money 4 ¦ ¦--politics 5 ¦ °--religion 6 ¦--gratitude 7 ¦--opinion 8 ¦ ¦--agree 9 ¦ °--disagree 10 °--ref_to_science
Collected coded fragments for codes ‘money’ & ‘religion’ with 2 lines of context
money (path: codes>CONTENT>money)
Source: Facebook_data__with-UIDs__after-initial-coding__example.rock
Source: Facebook_data__with-UIDs__after-initial-coding__example.rock
Source: Facebook_data__with-UIDs__after-initial-coding__example.rock
Source: Facebook_data__with-UIDs__after-initial-coding__example.rock
Source: Facebook_data__with-UIDs__after-initial-coding__example.rock
Source: Facebook_data__with-UIDs__after-initial-coding__example.rock
Source: Facebook_data__with-UIDs__after-initial-coding__example.rock
Source: Facebook_data__with-UIDs__after-initial-coding__example.rock
Source: Facebook_data__with-UIDs__after-initial-coding__example.rock
Source: Facebook_data__with-UIDs__after-initial-coding__example.rock
Source: Facebook_data__with-UIDs__after-initial-coding__example.rock
religion (path: codes>CONTENT>religion)
Source: Facebook_data__with-UIDs__after-initial-coding__example.rock
Source: Facebook_data__with-UIDs__after-initial-coding__example.rock
Appendix
Links and resources
This R Markdown file (see R Markdown section below) can be adapted by workshop participants to their own needs. The authors have deposited this file in the public domain: we waive all (copy)rights.
This file is available in a public GitLab repository at https://gitlab.com/sci-ops/rock-workshop-2-hour and can be downloaded from there. A rendered version of this file is hosted by GitLab pages at https://sci-ops.gitlab.io/rock-workshop-2-hour (short url: https://rock.science/workshop/2hr).1
The prezi slides are available here and the PDFs with the Powerpoint slides are available in the GitLab repository. More background information is available in the ROCK book at https://rockbook.org.
Commanding the rock package
To command the rock package (or use other R functionality), you usually use functions. Functions are small programs that do things for you. For them to know what to do, you have to pass so-called arguments or parameters when you call them. If you get everything right, the function will do its job and return its result to you. You will usually want to store that result, so you can do other things with it.
To illustrate this, let us create a simple source using a function. The following command creates a character vector with two elements:
firstSourceBit <-
c("this is the first element",
"this is the second element");We now called a function called c() to combine two elements into a vector (a list of elements). We pass two arguments to this function (the two text strings), and the functions returns the result to us (the vector), which we store in a variable called firstSourceBit with the assignment operator, <-.
If you are viewing the source code of this R Markdown file in RStudio (either Desktop, on your PC, or RStudio Cloud, in a web browser), you can select the three lines with R commands above and copy-paste them into the console in the bottom-left corner to try it out. If instead you are reading the rendered version of this R Markdown file, why not use the link above to open the associated project in RStudio Cloud so you can play along?
We can check that this worked by telling R to display the contents of the firstSourceBit object, simply by specifying its name in the console:
firstSourceBitR then shows its contents, and should show:
[1] "this is the first element" "this is the second element"We can now use another function to combine these two elements into a single character value again, using a so-called ‘newline character’, \n, as separator. The R function to paste several character strings together is called paste(). You usually call it the same way we called the c() function above, by specifying all character strings as separate arguments, but we can also pass them all in a vector: then we pass another argument called collapse to tell paste() the separator it should use when collapsing the vector into a single string:
firstSourceBit_collapsed <-
paste(
firstSourceBit,
collapse = "\n"
);If you let R print the contents of this new object firstSourceBit_collapsed, you see:
[1] "this is the first element\nthis is the second element"Here, R shows the newline character as a newline character (n), instead of as the newline it represents. To force R to display the newline character as a new line, use the cat() command:
cat(firstSourceBit_collapsed);Which should show:
this is the first element
this is the second elementYou now succesfully used your first three functions. Below, as we use the rock package, we will use more functions, usually with more arguments.
R Markdown
This is an R Markdown document. 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.
When you click the Knit button a document will be generated that includes both content as well as the output of any embedded R code chunks within the document. R chunks always start with a line containing three backticks (`) and two accolades ({ and }), with the chunk’s language (usually r), an optional chunk label, and the chunk options in between the accolades. When knitting the R Markdown document, the R chunks are executed and the results are inserted into the final rendered HTML (or PDF, or Word) file.
Installing the rock package
If you want to use the rock R package on your own computer, you will first have to download and install it in R. THe following R chunk contains commands you can use to install the rock package.
### Note the `eval=FALSE` chunk option on the line above; this tells the `knitr`
### package to *not* execute the R code in this chunk. This has been added
### because you normally will not want to reinstall that package *every time*
### you run this script.
### To install the version on R's CRAN repository network, use:
install.packages('rock');
### The next two commands require the `remotes` package to be installed;
### if you don't have that yet, you can install it with:
install.packages('remotes');
### To install the latest version of the package (at your own risk), use:
remotes::install_gitlab("r-packages/rock");
### To install the cutting edge version (at even more of your own risk), use:
remotes::install_gitlab("r-packages/rock@dev");
### Note that because the `install_gitlab()` function comes from a package,
### we tell R from which package to get it using the `::` operator.Note that that page is updated upon rerendering (‘reknitting’, see R Markdown section) of the source file. If you copy this repository yourself and intend to also use GitLab’s continuous integration (CI) functionality, and if you rename the R Markdown file, make sure to also update the CI configuration in the
.gitlab-ci.ymlfile accordingly (specifically, on line 6, replacescripts/rock-workshop-2-hr.htmlwith the new name of the rendered version of this file).↩︎