Atlas mapping method¶

This page describes how the correspondence between the Catalog and the Cognitive Atlas was established, so that a reader can judge how much weight each mapping carries. The row-by-row results are on the task mapping and process mapping pages, and The Catalog vs the Atlas says what they add up to. The mappings live in four tab-separated tables under data/mappings/, one row per entity with a unique key, so that any view can be generated from them.

Source data¶

Every figure derives from a byte-exact archive of the Atlas REST API, taken in a single snapshot covering both layers in full: 857 tasks and 918 concepts, with the detail record for each. Pulling the concept endpoint directly matters, because a harvest taken from the task endpoint alone reaches a concept only when some task asserts it, which hides about half the concept layer.

What a match type means¶

Match type	Meaning
`exact`	The same paradigm or construct, under the same or an aliased name
`close`	The same family, but the Atlas entry is a variant, is broader, or is narrower
`related`	The Atlas has entries in the same area but none that corresponds
`none`	Nothing in the Atlas corresponds

close and related carry real information and should not be read as weak versions of exact. close says a counterpart exists but its boundaries differ, so a researcher looking for the canonical paradigm will find something usable. related says the search will turn up neighbours only.

Matching at two levels¶

The Atlas frequently registers a specific implementation as its own entry rather than recording it under the parent paradigm: eight separate Stroop entries, eight n-back, six fluency. Many of those correspond not to a task in the Catalog but to a named variation of one.

Each mapping row therefore records whether it resolves to a task or to a variation.

Mapped to	Atlas entries
A HED task	163
A named variation of a HED task	20

Variations are addressed by a stable identifier of the form hedvar_<parent slug>__<variation slug>, for example hedvar_stroop_color_word__counting_stroop. The prefix types the identifier the same way hedtsk_ marks a task and hed_ marks a process. The identifier is what makes a variation referenceable: without one, a reference would have to name the variation, and would break silently if that name were edited. The generator fails if a mapping row names a variation that does not exist, or one whose parent task disagrees with the row.

How the tables were built¶

Candidate matches come from normalized name and alias comparison, with an exact task-name match taking precedence over a variation-name match. That precedence is not cosmetic: the Atlas entry 2-stage decision task matches the Two-Stage Decision Task by name while also matching a variation listed under another task, and only the first reading is correct.

Automated matching decides nothing on its own. On this data it produces false positives and false negatives in both directions. Judgment-of-Learning matched Judgment of Line Orientation because both abbreviate to “JOL”. Heartbeat Detection matched visual pursuit/tracking. Trail Making matched nothing although the Atlas carries Trail Making Test A and B. Every row was therefore checked against the archived Atlas record before being accepted.

What is verified¶

Table	Rows	State
`hed_task_to_atlas.tsv`	103	Every row checked against the archived Atlas record
`atlas_task_to_hed.tsv`	857	Every row assigned a match type; every matched row checked
`hed_process_to_atlas.tsv`	172	Every row checked against the archived concept definition
`atlas_concept_to_hed.tsv`	918	Every row assigned a match type

Two things in these tables are not hand-checked. The scope_class on an unmatched Atlas task is derived from its name by rule. And the none verdicts on the reverse tables assert only that no counterpart exists in the Catalog’s 103 tasks and 172 processes, which is the expected answer for most of an 857-entry and 918-concept corpus.

Reproducing the tables¶

python src/fetch_cog_data.py        # refresh the API archive in .cog_data/
python src/build_atlas_maps.py      # refresh the mapping tables

The second command is non-destructive. It never overwrites a match type, a mapped id, or a curator note. It refreshes the descriptive columns, re-deriving them from whichever id the curator chose rather than from the automated candidate, and reports entities that have appeared in or disappeared from the Atlas since the last run. Running it twice leaves the tables byte-identical.