A curated catalog of standard cognitive and behavioral neuroscience tasks and the cognitive processes they engage, developed as part of the HED (Hierarchical Event Descriptors) standardization effort. Its purpose is to provide a controlled vocabulary for tagging datasets with what their participants were asked to do, so that repositories can be searched by task or by process and datasets can be compared across laboratories.
The catalog currently covers 103 tasks in 18 paradigm families, 172 cognitive processes in 19 categories, and 486 task-process links. Each task has a canonical definition, an inclusion test, named variations, verified references and a mapping to the Cognitive Atlas. The catalog is a work in progress; suggestions, corrections and proposals are welcome as GitHub issues.
The catalog is published as a searchable website at https://www.hedtags.org/hed-task/.
| Section | Description |
|---|---|
| Introduction | What the catalog is made of, its identifiers, and where it came from |
| How to use the catalog | Reading a task page, tagging a dataset, proposing a change |
| Tasks | 103 tasks in 18 paradigm families, each with inclusion test, variations and process links |
| Cognitive processes | 172 processes in 19 categories, each with definition, references and linked tasks |
| Task-process links | The whole task-to-process matrix in both directions |
| Methods | Task and process selection criteria; how the Cognitive Atlas mapping was built |
| Cognitive Atlas | What the Atlas contains, how this catalog relates to it, and the row-by-row mapping tables |
hed-task/
|-- src/ # Documentation generators (Python)
| |-- generate_docs.py # Entry point: validates data/ and regenerates docs/source/
| |-- build_atlas_data.py # Recomputes data/atlas_summary.json from the Atlas harvest
| |-- build_atlas_maps.py # Refreshes data/mappings/*.tsv, preserving curation
| |-- fetch_cog_data.py # Rebuilds the Atlas API archive in .cog_data/
| |-- generators/ # One module per page family
|-- data/ # The catalog: task/process JSON, schemas, Atlas mappings, task families
|-- docs/
| |-- source/ # Sphinx source: hand-written narrative pages plus generated catalog pages
| |-- _build/ # Build output (gitignored)
|-- tests/ # Unit tests
|-- pyproject.toml
Two kinds of page live in docs/source/. The narrative pages (landing page, introduction, how to use, the two Cognitive Atlas essays, and the three Methods documents) are hand-written Markdown: edit them directly. The catalog pages (tasks/, processes/, crossref.md, the two Atlas mapping tables, and the table fragments in _generated/) are generated from the JSON and TSV data in data/ by the scripts in src/, and are never edited by hand. Each hand-written page says so in a comment at its top. See Regenerating the site below.
The catalog itself lives in data/: task_details.json, process_details.json, their JSON Schemas, the Cognitive Atlas mapping tables and the paradigm-family tables. It is edited here by pull request; data/README.md says how, and python src/generate_docs.py validates every edit before writing a page. The two JSON files began as a one-time import from the research workspace that found the citations (src/import_catalog.py records that migration).
Prerequisites: Python 3.10 or later.
# Clone and set up
git clone https://github.com/hed-standard/hed-task.git
cd hed-task
python -m venv .venv
# Activate (Windows)
.venv\Scripts\activate
# Activate (Linux / macOS)
source .venv/bin/activate
# Install dependencies
pip install -e ".[dev,docs]"Whenever data/ changes, run both steps. Editing a narrative page needs only step 2.
Step 1 - regenerate the Markdown source:
python src/generate_docs.pyThis validates data/task_details.json and data/process_details.json against their schemas and against each other, then deletes the generated paths under docs/source/ (tasks/, processes/, crossref.md, the two Atlas mapping tables, _generated/), and rewrites them. It never touches a narrative page. It refuses to run, naming the record, if any check fails: unknown process or category ids, a process whose tasks list disagrees with the tasks that name it, a reference role outside the vocabulary, a variation without its derived id, or a task without a family. CI runs the same generation and fails a pull request whose pages are out of date.
atlas_summary.json and mappings/*.tsv are derived from a byte-exact archive of the Cognitive Atlas REST API kept in .cog_data/, which is untracked. Only the derived files are committed, so the docs build never needs the archive. To refresh, run:
python src/fetch_cog_data.py # rebuild .cog_data/ from the Atlas API (resumable)
python src/build_atlas_data.py # recompute data/atlas_summary.json
python src/build_atlas_maps.py # refresh the mapping tables, preserving curationbuild_atlas_data.py and build_atlas_maps.py both take --archive if the archive is not at .cog_data/.
Step 2 - build the HTML:
sphinx-build -b html docs/source docs/_build/htmlThen open docs/_build/html/index.html in a browser to preview. A clean build emits no warnings.
Narrative pages can use a few live counts from the data, written as {{ n_tasks }}, {{ n_processes }}, {{ n_categories }}, {{ n_families }}, {{ n_variations }}, {{ n_links }} or {{ n_linked }}; docs/source/conf.py defines them at build time. A table that follows the data is pulled in from docs/source/_generated/ with an include directive.
Do not run mdformat over docs/source/. It rewrites the generated MyST directives into a form Sphinx cannot parse. The mdformat CI check is scoped to the hand-written Markdown at the repository root for that reason:
python -m mdformat --check --wrap no --number *.mdpython -m unittest discover -s tests -vruff check .
ruff format --check .| Workflow | Trigger | Purpose |
|---|---|---|
docs.yaml |
Push / PR to main |
Build and deploy the site to GitHub Pages |
ruff.yaml |
Push / PR to main |
Lint and format checks |
mdformat.yaml |
Push / PR to main |
Markdown formatting of the root files |
links.yaml |
Push / PR to main |
Broken link detection |
This project is licensed under the MIT License.