Get and install the library

We developed a simple R package called PsyToolkit

Here is how you can install it. You only need to do this one time in your R console. This package will be regularly improved, please make sure to follow PsyToolkit on BlueSky where this will be announced.

Latest update: Version 1.0.1 on the 9th of May 2025.

install.packages("https://us.psytoolkit.org/R/PsyToolkit_1.0.1.tar.gz", repos = NULL, type = "source")
Make sure to subscribe to the BlueSky PsyToolkit channel to learn about any updates in this package. Click here to go to PsyToolkit’s BlueSky channel

After installing this, you can now load the library

library(PsyToolkit)
Note the capitals P and T in the library name

YouTube tutorial about this package

Get and install the demo data set

The PsyToolkit R library does not come with demo data. But the examples below use the demo dataset. Here is how to download and install it.

Step 1: Download the zipped data files from here: https://us.psytoolkit.org/R/PsyToolkitDemoData.zip

Step 2: It is a zip file. You need to unzip it on your system and store in a folder where you want to run your test R functions.

The folder contains the same data as you would download from a PsyToolkit survey in your own PsyToolkit account.

Quick overview

The following essential functions are provided

Function name What it does

psytkReadData()

reads in the whole survey structure and all data files

psytkParseSurvey()

reads in the whole survey structure, but not the data

psytkReport()

reports the data read in

The following functions pre-process/summarise experiment data into participant level data

psytkExtractNum()

Extract an average number based on a condition for each participant

psytkExtractPerc()

Extract a percentage based on a condition for each participant

psytkExtractCount()

Extract a count based on a condition for each participant

psytkExtractTail()

Extract a number from last line of a participant’s data file

The following functions come in the package but are mostly just support functions

round0p()

calculates percentage based on count and total and rounds to whole number

catn()

exactly as the standard function cat() but with a line break

hr()

outputs a horizontal line ----------------

reportRange()

reports a vector’s numerical range with the word to in between

psytkReadTable

reads in a text file, can read csv data, and fills unequal numbers of colums

Example of reading in survey data

Step 1: Download your data

To get your own PsyToolkit survey data:

  1. go to your PsyToolkit account.

  2. go to your survey of interest

  3. go to the prepare/download section

  4. prepare your data and refresh page

  5. download the data (this is zip file)

  6. unzip the data file in your data subfolder

  7. check if the data subfolder contains at least the following:

    • a file called survey.txt

    • a folder called survey_data

Now you are set up to start working with the PsyToolkit R library.

In these examples we will work with the demo data, see above how to download it. You can use these data to learn how to run the functions.

Step 2: Set up files

Make sure you have a folder in which you analyze your data. Here you will have your R scripts and one subfolder. For example PsyToolkitDemoData.

Again, for this we assume you have an R project folder called PsyToolkitDemoData which again contains the unzipped PsyToolkit survey (and possibly experiment) data. Of course, your extracted PsyToolkit file has a different name. For the examples below, we assume it is called PsyToolkitDemoData. Of course, you can rename your folder into this as well.

Step 3: Read in data

Now run simply this in R.

Make sure you are in the correct working directory. How to get there will depend on what sort of R interface you use. 
library(PsyToolkit) (1)
d = psytkReadData("PsyToolkitDemoData")  (2)
1 Load the library (you only need to do that once)
2 The variable d will now hold all information about the survey and its data

Step 4: Get overview

Now that your data are read in, you most likely first want to check how many data files you have. For this, call the following function:

psytkReport( d )

Step 5: Questionnaire data

In PsyToolkit, you always have questionnaire data. Only if you embedded experiments, you will also have experiment data. There are different ways to analyze these.

Questionnaire data are the answers or scores on your standard questions, such as "How old are you" and the personality scale questions (e.g., TIPI).

The function psytkReport( data ) gives you an overview of the basic descriptive statistics of these data. But you can get more indepth analyzes by accessing the individual answers for each participant.

THIS NEEDS TO BE ADDED TO DOCUMENTATION

Experiment data

If you have embedded one or more experiments in your PsyToolkit survey, they create experiment data. In the example data set, we have three experiments.

The PsyToolkit R library provides several functions to pre-process these data.

For each experiment, you have one R dataframe with one row for each trial. For example, if you embedded an experiment called "Stroop" and your surveydata has the variable name d (as in the above examples), then your Stroop data is a data frame that can be viewed as follows:

d$expData.Stroop

That is, there is a set of data in d$expData in your data and the specific names of the experiments follow after a "."

If you have another experiment called "search", then that can be shown as follows:

d$expData.search

Of course, for a detailed analysis, you will need to get your data in a simpler format to work on. For this we have the functions:

  • psytkExtractNum()

  • psytkExtractPerc()

  • psytkExtractCount()

  • psytkExtractTail()

These functions will extract just one number for each partcipant, such as the mean reaction time in congruent or incongruent Stroop trials.

If you have completed your survey (with or without experiments), you can use our PsyToolkit R code to quickly and easily read in all data. The R code can be downloaded (see link toward end of this document).

What do PsyToolkit datafiles actually look like?

You can skip this, but if interested, here is the information.

All PsyToolkit data files are simple textfiles that you can open with any text editor or Word. This makes allows you to process it in in any programming language you like. Here we use R, which is ideal for statistical coding.

The basic idea of PsyToolkit data is that all data is stored in a survey participant data file (starting with "s" followed by a long unique identifier string) and optionally additional files for each embedded experiment. Thus, for a survey with one experiment, each participant has a survey data files as well as one experiment data file.

Survey data files

For each participant, there is one survey data file (and if you use experiments, with an additional data file for each experiment in your survey).

Survey data file names start with the letter "s", followed by a long alphanumerical string, followed by the extension "txt". For example:

s.05060a15-d2be-4ed2-a026-73bd684b4772.txt

The long string is called a Unique Universal Identifcation (UUID). Each participant has such a file. If the participant completed the survey, the last line will be something like this (starting with the word "end"; the rest is the date in year, month, day, hour, minute format)

end 2024-07-02-14-26

The file starts with some information about the computer and time on the participant’s computer. Then for each question (starting with a line starting with "l:" followed by a space and the label name), there are several lines with the type of question. Importantly, there is the answer (a:) and a score line (s:). Some questions will have more than one "a:" line.

You do not need to fully understand this, because the R code takes care of reading these files in.

Experiment data files

Experiment data files start with the name of the experiment, followed by the date and then the UUID of the participant. The UUID is important, it is the only way of matching the experiment file to the participant.

The information in the experiment file is simply what you chose to save via the "save" lines in your PsyToolkit experiment code.