sho-87 / cognitive-battery

Battery of standard cognitive psychology tasks
MIT License
36 stars 12 forks source link
attention battery cognition cognitive-science experiment mental-rotations-task psychology psychology-experiments pygame python

Requirements | Usage | Included Tasks | Contribution | Getting Help | TODO | Changelog

Cognitive Battery

Gitter chat

A Python based battery of common cognitive psychology tasks. Designed to be modular as each task is contained within a single Python script/module, the results of which are returned as a dataframe for saving.

Pull requests are welcome! Please see the contribution notes below.


Battery loading screen Mental rotation task screenshot

The battery was originally designed for a resolution of 1280x1024, but it should work with most resolutions.

Some tasks contain copyrighted images (e.g. Mental Rotations Task, Raven's Progressive Matrices) that I cannot include in this repo. In case you have access to the original images, I have included an explanation of how to name/format those items to work with this battery.

Note: I created this project as I needed to get some tasks up and running quickly for an experiment. Everything is fully functional as it stands, but I will be refactoring much of the code over time to clean things up. This will include things like code reduction, better handling of different screen resolutions, and improved logic.

Requirements

Current, and future, versions of the battery use Python 3. Python 2 users can still run v2 of the battery, but will no longer be maintained. Cognitive Battery v3 may still be runnable under Python 2, however, it's not tested or supported, so use at your own risk.

You will need to have the following dependencies installed to run the battery, most of which are just Python modules:

Usage

Using the battery is as simple as running the run_battery.py file. This can either be done using the command line (navigate to the directory and type python run_battery.py), or running it from IDLE.

In the project manager, add a new bookmark indicating the project name and a path to your desired save directory for that project. Adding or deleting a bookmark does not change any files on the filesystem, it's merely a reference to a directory for where data files and settings should be saved for that project. It's safe to delete a project bookmark as it will not delete any currently existing data.

On the task selection screen, all sections are currently mandatory, although some may be irrelevant for your particular experiment. You can place arbitrary values in the irrelevant fields.

Select the tasks you want to include by using the checkboxes. The order of task administration can be set using the Up and Down buttons. Alternatively, you can set a random order using the checkbox.

The task results are saved in the /data directory of your project directory (specified in the project manager). Each participant's data is saved as an Excel file, where each task is saved to a separate sheet.

If you want to reset the settings for a particular project, delete the battery_settings.ini file in the project's directory. A new (default) one will be created when you next load that project.

Included Tasks

Information about the tasks can be found here.

Currently implemented tasks:

Contribution

Note: I intend to majorly streamline this process in future releases, hopefully automating the importing/running/saving of tasks.

Each new task you want to add will need to be programmed as a Python module.

Create a class in the module that contains a run() method. This method should contain the main sequence of your task and needs to return a Pandas dataframe object. Your class should also accept a pygame screen and background object.

An instance of the class is spawned in run_battery.py, near the end of the start() method. Your class's run() method is invoked after, and the returned dataframe is saved to file.

You'll then need to update the QT Designer UI file (/designer/ui/battery_window_qt.ui) by adding your task to the list. Rebuild using the included convertUI.bat script.

Note: It is better to modify the UI file using QT Designer and then rebuild, rather than directly editing the generated Python file (battery_window_qt.py), because:

In summary:

  1. Program a separate .py module for your task
  2. Include a run() method in your class that contains your task sequence and returns a Pandas dataframe
  3. Import this module in run_battery.py
  4. Spawn a new instance of your class in run_battery.py in the start() method
  5. Invoke your run() method and save the returned dataframe to a file
  6. Update the QT Designer UI file and rebuild using the conversion script

Consider making a pull request and please include a journal reference for any new tasks you add.

Getting Help

You're encouraged to post questions as an issue in this repo, or get live help on Gitter.

TODO

In no particular order...

General

Tasks

Changelog

You can view the change log/release notes here