Py-Span-Task is a simple application for testing working memory span.
- June 28, 2022
- Fixed a bug that cause the GUI to get stuck on the first page.
- February 19, 2021
- Migrated the code from Python 2 to Python 3. Thanks to Brad Buran (@bburan) for this contribution.
- March 12, 2019:
-
- Added a Russian operation span task (contributed by Anna Laurinavichyute).
- March 03, 2019:
-
- Added three tests for Czech (contributed by Jan Chromý and the ERCEL Lab).
- July 14, 2017:
-
- Switch to fullscreen on start-up.
- Prevent users from accidentally focusing the text field when it’s not needed. (Focusing the text field previously got the program stuck as it was impossible to escape the text field.)
- May 28, 2016:
-
- Allow sloppy spelling in Spanish operation span task. If people ignore the accents on words, their responses are still counted as correct. However, other one-letter typos are also accepted.
- Improved instructions in Spanish operation span task.
- June 1, 2015:
-
- Added a Japanese operation span task (contributed by Kentaro Nakatani).
- Added a German reading span task and a German operation span task (contributed by Paul Metzner).
- More robust handling of Unicode and UTF-8-encoded materials.
- Working memory score (partial credit unit score) is calculated and stored in results file.
- Important settings are stored in the results file.
- Added detailed documentation (see below).
- Runs on Linux, OSX, Windows.
- Follows the recommendations given in Conway, Kane, Bunting, Hambrick, Wilhelm, & Engle (Psychonomic Bulletin & Review, 2005).
- Performs operation and reading span tests.
- Is highly configurable.
- Supports non-western scripts via Unicode and UTF-8.
- Computes partial credit unit scores.
- Saves a protocol of the test procedure in a simple text file that can be loaded in R, Excel, SPSS, …
- Includes an R script for calculating a range of other measures.
Py-Span-Task is written in Python 3 and uses the TK-toolkit for graphical user interfaces. On Linux and OS X systems, the necessary software for running Py-Span-Task should already be installed. Running Py-Span-Task on Windows may require installing Python 3 (which usually includes the TK-toolkit).
Here’s is a list of tests that are currently available. Please note that neither the authors of py-span-task nor the authors of the tests will be liable for any damages or incorrect results. See the license terms for details.
| Language | Type | Target items | Source |
|---|---|---|---|
| Czech | operation span | consonants | Jan Chromý and the ERCEL Lab |
| Czech | reading span | consonants | Jan Chromý and the ERCEL Lab |
| Czech | reading span | words | Jan Chromý and the ERCEL Lab |
| English | operation span | consonants | Cyrus Shaoul |
| German | operation span | consonants | Paul Metzner |
| German | reading span | words | Paul Metzner |
| Japanese | operation span | consonants | Kentaro Nakatani |
| Russian | operation span | consonants | Anna Laurinavichyute |
| Spanish | operation span | words | von der Malsburg & Vasishth, 2013 |
This software and the included tests are released under the terms of the GNU General Public License, version 2, or later versions of the license. Before using the software please take a moment to read the license terms.
- Current version (.zip)
To run a test, open a terminal, enter the directory containing pyspantask.py and the configuration file of the test, and execute the following command:
python pyspantask.py configuration.pyThe test will prompt for a subject id and conduct some sanity checks on the test materials. For example, it will check whether there are enough target items and whether they are sufficiently different to be uniquely identified when sloppy spelling is tolerated.
The test runs in full screen. Nonetheless it may be necessary to click on it with the mouse to make it receive keyboard presses. The test can be aborted at any time using the escape key.
- Welcome screen
- Instructions 1
- Familiarization with verification task, e.g., checking of simply equations or sentences for well-formedness. Feedback is given and the time that it takes the participant to do the task is measured.
- Instructions 2
- Familiarization with the full task, i.e. verification task plus memory task. Instead of feedback a memory item is shown after each verification item and participants have to enter the memory items at the end of each trial. If the participant is too slow, there will be a time-out. The time-out is calculated for each participant individually based on how fast they were in the first familiarization phase.
- Instructions 3, usually just announce the start of the main test
- Main test, same as in second familiarization phase but long
The structure is fixed but many details can be configured (see below).
The configuration file is a Python file that sets a number of settings described below. As an example, see the configuration of the Spanish operation span task included in this repository. When you save the configuration file, make sure you save it in UTF-8 encoding. This way special non-ASCII characters are correctly processed and displayed.
Apart from the configuration file, a task consists of a file containing the “target items” (the items that the participants have to memorize) and a file containing the “processing items”, i.e. the items used in the distractor task (equations or sentences or …). Here is the target items file of the Spanish operation span task and here is the processing items file.
All settings below are mandatory. There are no default values.
fontsize = 22fontname = "Helvetica"File containing the items for the processing task (also called the verification task or distractor task).
processing_items_file = "operations.txt"Format of the file: One item per line. A sentence in case of a reading span task, an equation in the case of a operation span task. First the item, then a delimiting tab, and then the correct answer for the verification task (y or n). Examples:
The queen of England is smoking secretly. y ( 1 * 2 ) + 1 = 3 y
Make sure that your editor stores tabs as real tabs and does not expand them to spaces.
The file containing the items that the participants have to memorize. In this file, there’s one item per line. Items can be letters, digits or sentences – almost any string is ok. Note that the test is case insensitive. The target items will be displayed as they are stored in this file, but when they are compared with user input the case will be ignored.
target_items_file = "target_words_spanish.txt"Possible responses and their respective keys: Before the colon is the response as indicated in the file with the processing items (processing_items_file). After the colon you can specify the key on the keyboard that the participants should use to indicate that response.
responses = {
'y':'j',
'n':'f'
}Text shown at the beginning of the test.
welcome_text = """¡Bienvenido!"""Text shown on page two. Should give an explanation of the first round of practice trials. In this phase only processing items are shown and there is no memory task. The reaction time of the participants is measures to calculate a timeout after which trials are aborted if no response was given. This allows every participant to work at their own pace. People who are really good at checking equations will not have extra time to rehearse memory items.
instructions1 = """En este test, debe indicar …"""Whether or not minor typos are tolerated when people enter recalled items. If set to True, the entered item is counted as correct if there’s at most one of the following types of typos: omission of a caracter, addition of a character, substitution of a character. NOTE: Don’t use this if your target items are very short, e.g. single digits, because by substitution every digit can be turned into the correct one.
allow_sloppy_spelling = FalseNumber of processing items for the first practice phase. Don’t set this number too low. The reaction times are measured during these practice trials and the mean + time_out_factor * SD is used as timeout during the actual test.
practice_processing_items = 2The factor multiplied with the standard deviation plus the mean reaction time for the practice trials is the timeout, i.e. the time after which the presentation of the processing item is interrupted and the response is counted as wrong.
time_out_factor = 2.5Text shown when a participant took too much time to judge a processing item.
time_out_message = """¡Demasiado lento!"""When first exposed to the task, participants often take much longer than later. Therefore, it’s advisable to measure processing time only after a number of practice trials. This variable controls when the measurements start.
measure_time_after_trial = 3If the order of recalled items does not matter, set this to False. If recalled items should be entered in the order in which they were presented, set this to True. Items that are correctly recalled but in the wrong position will then not count towards the score.
heed_order = FalseThis controls the order in which target items are presented. Either the list of items is shuffled and then each element is presented one after the other. When the list is finished it is shuffled again and the process starts all over. Set pseudo_random_targets to True to get this behavior. If set to False, items are drawn randomly from the set of all items. The crucial difference is that an item can appear in two consecutive trials then. If there are only a few target items, say the digits from 0 to 9, then true random selection is preferable. Otherwise, people can easily guess: if they saw 1, 3, 5, 7, 9 in the last trial, they can guess that in the next they will see 0, 2, 4, 6, 8. If the number of target item is large, shuffled presentation is better, because it avoids repetitions.
pseudo_random_targets = TrueText shown after the first practice phase. Introduces the combined task with processing items and target items for memorization. This phase gives participants a feeling for the timeout and gives them a chance to ask question before the main test begins.
instructions2 = """En la segunda parte, …"""In each trial, a number of processing and target items are shown. This variable specifies which numbers of items are presented, in the example below, either two or four. The order of the numbers doesn’t matter.
practice_levels = (2, 4)Number of trials in the second practice phase per level. In the present example, there would be 6 practice trials because there are 2 levels (2 and 4) and 3 trials per level.
practice_items_per_level = 3Response given in the second practice phase if a processing items was correctly judged. (No feedback will be given during the main experiment.)
practice_correct_response = """¡Muy bien!"""Response given in the second practice phase if a processing items was incorrectly judged. (No feedback will be given during the main experiment.)
practice_incorrect_response = """¡Lo siento, incorrecto!"""Summary presented when the second practice phase is finished.
practice_summary = """De %(total)s operaciones, ha obtenido %(correct)s
respuestas correctas.
Presione la barra espaciadora para continuar."""This text appear after the familiarization period (phase two) and prepares participants for the main test.
instructions3 = """En este momento ya debe …"""The levels of memory load that are tested in the main test. The same as practice_levels. Order doesn’t matter.
levels = (2, 3, 4, 5, 6)Number of trials per level in the main test. Like practice_items_per_level.
items_per_level = 1Text shown before each trial.
next_message = """Cuando esté preparado, sitúe los dedos índice sobre las teclas marcadas y presione la barra espaciadora con el dedo pulgar para continuar."""Text shown when the main test is finished.
finished_message = """¡Bien hecho!
Presione la barra espaciadora para continuar."""Specifies how the target items will be displayed (in milliseconds).
target_display_time = 1000Specifies how long the feedback (correct or wrong) will be displayed during the practice trials.
response_display_time = 1000Text shown after at the end of the test.
good_bye_text = """¡Gracias por su colaboración!"""The results will be stored in a file whose name consists of the subject id and the suffix .tsv. The format of the results file is tab-separated-values and can be read by statistical software such as GNU R and spreadsheet applications such as LibreOffice Calc.
A sample output file from the Japanese operation span task can be found here.
In GNU R, the following command can be used to read a results file:
d <- read.table("subject1.tsv", sep="\t", head=T, as.is=T)
head(d)| phase | set.id | num.items | correctly.recalled | correctly.verified | mean.rt | max.rt | presented.items | recalled.items |
|---|---|---|---|---|---|---|---|---|
| practice | 1 | 2 | 2 | 1 | 790 | 917 | z r | z r |
| practice | 2 | 3 | 1 | 1 | 1056 | 1544 | b t r | t |
| practice | 3 | 3 | 3 | 1 | 607 | 1061 | n b h | n b h |
| practice | 4 | 2 | 2 | 1 | 415 | 581 | v b | v b |
| test | 1 | 6 | 5 | 4 | 452 | 569 | c x z l v t | c x z v l t |
| test | 2 | 3 | 1 | 1 | 800 | 1544 | z y x | x |
However, this repository also includes an R function that reads the data and calculates the usual working memory scores (described in Conway et al., 2005).
source("calculate_wmscores.R")
wm.scores("subject1.tsv")| wmc | pcu | anu | pcl | anl | accuracy |
|---|---|---|---|---|---|
| 0 | 0.729 | 0.333 | 0.722 | 0.315 | 0.556 |
To process the data of all subjects in an experiment, you can use the following code:
source("calculate_wmscores.R")
file.names <- list.files("/path/to/results.files/", "subject.*.tsv")
d <- data.frame(t(sapply(file.names, wm.scores)))
d$subject <- file.names
head(d)wmc pcu anu pcl anl accuracy 005.tsv 4 0.8740000 0.60 0.84 0.49 0.87 006.tsv 2 0.7786667 0.40 0.73 0.27 0.86 007.tsv 2 0.7493333 0.44 0.70 0.34 0.87 008.tsv 2 0.7046667 0.28 0.67 0.18 0.75 009.tsv 4 0.9540000 0.76 0.94 0.68 0.81
See the manual of list.files for details.
We wrote the first version of Py-Span-Task in 2010. Since then, researchers in a number of labs have successfully used this software to obtain working memory scores. The software can thus be considered to be relatively reliable and ready for production use.
Operation and reading span tests play an important role in our research area. Applications for testing working memory span were already available, however, running them required expensive software licenses. Since these memory tests are actually relatively simple, we decided to write our own software. Apart from saving money another benefit is that we know exactly what the software is doing and that we can fix it ourselves when something doesn’t work as it is supposed to. Since we publish the code for our test software, other researchers can also check how exactly we obtained our data.
Yes, everybody is invited to freely use our software. We provide material for different operation and reading span tests in several languages. You can use, modify, and improve this material if you want. Note, however, that we can’t take any responsibility for the correctness of the software or its results (see the license terms for details).
If you use our software in your research, we would appreciate if you could acknowledge that in your publications.
- von der Malsburg, T. (2015). Py-Span-Task -- A software for testing working memory span. doi: 10.5281/zenodo.18238
Below is a BibTeX entry:
@misc{Malsburg2015,
author = {von der Malsburg, Titus},
title = {{Py-Span-Task -- A Software for Testing Working Memory Span}},
month = jun,
year = 2015,
doi = {10.5281/zenodo.18238},
url = {http://dx.doi.org/10.5281/zenodo.18238}
}
Yes, feel free to do so. If you modify the test software or the test material, please consider sharing these changes with us so that we may integrate them in our version. If you create new test materials, or if you translate one of our tests into another language, we would also be happy to integrate these materials in our repository. Your contribution will be duly acknowledged on this page.
Yes, it does, provided that your configuration files and test materials are saved with the appropriate character encoding (UTF-8) and provided that you are using a font that supports these scripts. On OS X and modern Linux distributions, the default encoding scheme is UTF-8, so it should work out of the box. As far as I know, Windows does not use UTF-8 as its default encoding scheme. Therefore you have to make sure to select UTF-8 when you save the material in your text editor. Create a new entry in the issue tracker in case you run into problems.
If you find bugs in the software, or errors in the material, please let us know and we try to fix them. To report a problem, please use the issue tracker.
Py-Span-Task was originally written by Titus von der Malsburg during his dissertation project at the University of Potsdam. Paul Metzner and Bruno Nicenboim made various contributions in the form of suggestions for improvements, code, and test materials. Kentaro Nakatani contributed the Japanese operation span task, Jan Chomý the three Czech tests, and Anna Laurinavichyute the Russian test. Brad Buran migrated the code from Python 2 to Python 3.