{"id":26681322,"url":"https://github.com/thesimonho/cognitive-battery","last_synced_at":"2025-04-12T12:35:00.319Z","repository":{"id":114864356,"uuid":"45780937","full_name":"thesimonho/cognitive-battery","owner":"thesimonho","description":"Battery of standard cognitive psychology tasks","archived":false,"fork":false,"pushed_at":"2019-10-17T23:18:40.000Z","size":650,"stargazers_count":43,"open_issues_count":10,"forks_count":12,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-02T13:02:09.941Z","etag":null,"topics":["attention","battery","cognition","cognitive-science","experiment","mental-rotations-task","psychology","psychology-experiments","pygame","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thesimonho.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2015-11-08T13:10:29.000Z","updated_at":"2025-02-23T11:10:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"770cf630-7d0d-44e8-bef6-8a69e14f0217","html_url":"https://github.com/thesimonho/cognitive-battery","commit_stats":null,"previous_names":["thesimonho/cognitive-battery"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thesimonho%2Fcognitive-battery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thesimonho%2Fcognitive-battery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thesimonho%2Fcognitive-battery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thesimonho%2Fcognitive-battery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thesimonho","download_url":"https://codeload.github.com/thesimonho/cognitive-battery/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248567046,"owners_count":21125771,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["attention","battery","cognition","cognitive-science","experiment","mental-rotations-task","psychology","psychology-experiments","pygame","python"],"created_at":"2025-03-26T07:15:20.906Z","updated_at":"2025-04-12T12:35:00.276Z","avatar_url":"https://github.com/thesimonho.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"**[Requirements](#requirements)** |\n**[Usage](#usage)** |\n**[Included Tasks](#included-tasks)** |\n**[Contribution](#contribution)** |\n**[Getting Help](#getting-help)** |\n**[TODO](#todo)** |\n**[Changelog](#changelog)**\n\n# Cognitive Battery\n\n[![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/cognitive-battery/Lobby)\n\n\u003cimg align=\"left\" src=\"images/icon.png\"\u003e\n\nA Python based battery of common cognitive psychology tasks. Designed to be \nmodular as each task is contained within a single Python script/module, the \nresults of which are returned as a dataframe for saving.\n\nPull requests are welcome! Please see the [contribution](#contribution) \nnotes below.\n\n\u003cbr\u003e\n\n![Battery loading screen](images/battery_screenshot.png)\n![Mental rotation task screenshot](images/mrt_screenshot.png)\n\nThe battery was originally designed for a resolution of 1280x1024,\nbut it should work with most resolutions.\n\nSome tasks contain copyrighted images (e.g. Mental Rotations Task, Raven's \nProgressive Matrices) that I cannot include in this repo. In case you have \naccess to the original images, I have included an explanation of how to \nname/format those items to work with this battery.\n\n**Note**: I created this project as I needed to get some tasks up and \nrunning quickly for an experiment. Everything is fully functional as it stands,\nbut I will be refactoring much of the code over time to clean things up.\nThis will include things like code reduction, better handling of different\nscreen resolutions, and improved logic.\n\n## Requirements\n\nCurrent, 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.\n\nYou will need to have the following dependencies installed to run the battery,\nmost of which are just Python modules:\n\n* **Windows 7+**\n  - This battery may work on OSX and Linux, but has only been tested on \n  Windows so far.\n* **Python 3.x**\n  - The easiest way to install Python is using the \n  [Anaconda](https://www.continuum.io/downloads) distribution as it also \n  includes most of the other dependencies listed below\n  - Older versions of the battery (v1-2) are still runnable using Python 2.\n* **Pandas**\n  - Included with Anaconda. Otherwise, install using pip (`pip install pandas`)\n* **Numpy**\n  - Included with Anaconda. Otherwise, install using pip (`pip install numpy`)\n* **PyQt5**\n  - Included with Anaconda. Alternatively, full release (including QT designer)\n   downloadable from the\n   [PyQT website](https://www.riverbankcomputing.com/software/pyqt/download5)\n  - **Note**: Cognitive Battery version 1.x uses PyQt4. However, version 2.x onwards uses PyQt5\n* **Pygame**\n  - Install using pip (`pip install pygame`)\n  - Alternatively, downloadable from the\n  [Pygame website](http://www.pygame.org/download.shtml)\n\n## Usage\n\nUsing the battery is as simple as running the `run_battery.py` file. This \ncan either be done using the command line (navigate to the directory and type\n`python run_battery.py`), or running it from IDLE.\n\nIn 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.\n\nOn the task selection screen, all sections are currently mandatory, although some\n may be irrelevant for your particular experiment. You can place arbitrary \n values in the irrelevant fields.\n\nSelect the tasks you want to include by using the checkboxes. The order of \ntask administration can be set using the `Up` and `Down` buttons. \nAlternatively, you can set a random order using the checkbox.\n\nThe task results are saved in the `/data` directory of your project directory (specified in the project manager). Each participant's data\n is saved as an Excel file, where each task is saved to a separate sheet.\n\nIf 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.\n\n## Included Tasks\n\nInformation about the tasks can be found [here](tasks/README.md).\n\nCurrently implemented tasks:\n\n* **Attention Network Test (ANT)**\n  - Based on the original version by\n  [Fan et al. (2002)](http://www.mitpressjournals.org/doi/abs/10.1162/089892902317361886#.VlEwI9irSHs)\n* **Digit Span (backwards)**\n  - Based on the version used by\n  [Berman et al. (2008)](http://pss.sagepub.com/content/19/12/1207) and\n  [Bourrier (2015)](https://open.library.ubc.ca/cIRcle/collections/ubctheses/24/items/1.0166677)\n* **Eriksen Flanker Task**\n  - Based on the compatible and incompatible versions by [Hillman et al. (2006)](http://psycnet.apa.org/record/2006-20659-003) and \n  [Pontifex et al. (2011)](https://www.ncbi.nlm.nih.gov/pubmed/20521857)\n* **Mental Rotation Task**\n  - Based on the redrawn version by\n  [Peters et al. (1995)](http://www.ncbi.nlm.nih.gov/pubmed/7546667)\n* **Raven's Progressive Matrices**\n  - Based on the second set of matrices used in the\n  [Wechsler Adult Intelligence Scale](https://en.wikipedia.org/wiki/Wechsler_Adult_Intelligence_Scale#WAIS-IV)\n* **Sternberg Task**\n  - Based on the original task by [Sternberg (1966)](https://www.ncbi.nlm.nih.gov/pubmed/5939936),\n   with trial count and set sizes from [Martins et al. (2012)](http://www.sciencedirect.com/science/article/pii/S1469029212001380)\n* **Sustained Attention to Response Task (SART)**\n  - Based on the original version by\n  [Robertson et al. (1997)](http://www.sciencedirect.com/science/article/pii/S0028393297000158)\n\n## Contribution\n\n**Note**: I intend to majorly streamline this process in future releases, \nhopefully automating the importing/running/saving of tasks.\n\nEach new task you want to add will need to be programmed as a Python module.\n\nCreate a class in the module that contains a `run()` method. This method \nshould contain the main sequence of your task and needs to return a Pandas \ndataframe object. Your class should also accept a pygame screen and\nbackground object.\n\nAn instance of the class is spawned in `run_battery.py`, near the end of the \n`start()` method. Your class's `run()` method is invoked after, and the \nreturned dataframe is saved to file.\n\nYou'll then need to update the QT Designer UI file \n(`/designer/ui/battery_window_qt.ui`) by adding your task to the list. \nRebuild using the included `convertUI.bat` script.\n\n**Note**: It is better to modify the UI file using QT Designer and then \nrebuild, rather than directly editing the generated Python file\n(`battery_window_qt.py`), because:\n\n- Your changes will be included in the UI file in case anyone wants to use \nQT Designer to make changes later\n- Any changes you make will be lost whenever anyone builds from the UI file\n\nIn summary:\n\n1. Program a separate `.py` module for your task\n2. Include a `run()` method in your class that contains your task sequence \nand returns a Pandas dataframe\n3. Import this module in `run_battery.py`\n4. Spawn a new instance of your class in `run_battery.py` in the `start()` \nmethod\n5. Invoke your `run()` method and save the returned dataframe to a file\n6. Update the QT Designer UI file and rebuild using the conversion script\n\nConsider making a pull request and please include a journal reference for any\nnew tasks you add.\n\n## Getting Help\nYou're encouraged to post questions as an [issue](https://github.com/sho-87/cognitive-battery/issues) in this repo, or get live help on [Gitter](https://gitter.im/cognitive-battery/Lobby).\n\n## TODO\n\nIn no particular order...\n\n**General**\n- Create an analysis tool for summarizing/aggregating participant data for\nthe different battery tasks. The goal is to output summary data that is ready\nfor statistics\n- Compile an executable binary version of the entire battery\n    - This will make it possible run the battery without dealing with Python\n     module installation\n- Cross-platform support (OSX and Debian based GNU/Linux)\n- **Major** code cleanup across the board\n\n**Tasks**\n- Improve support for different screen resolutions\n- Streamline the process of adding new tasks\n    - Automatically import all task modules\n    - Automatically handle task running/saving\n    - No longer need to edit the main battery file to add your own tasks\n- Save subject data to non-proprietary file format instead of Excel\n    - Likely to be CSV, but open to suggestions\n- Add more tasks...\n\n## Changelog\n\nYou can view the change log/release notes [here](CHANGELOG.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthesimonho%2Fcognitive-battery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthesimonho%2Fcognitive-battery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthesimonho%2Fcognitive-battery/lists"}