Why Harmonization Is More Than Renaming
Two reference atlases may describe related cell populations with different names, or use the same name for categories at different levels of detail. A label such as “regulatory T cell” may be a distinct category in one atlas but included within a broad “CD4 T cell” category in another. Replacing names with a common spelling does not resolve this mismatch: the labels must refer to compatible biological categories before they can be compared or combined.
Harmonization creates a shared vocabulary and records how each atlas’s labels relate to it. The goal is not to make every atlas appear equally detailed. It is to use consistent meanings while retaining distinctions when the available annotations support them. The earlier material on choosing label granularity with cell ontologies provides the context for selecting a useful level of detail.
An ontology can help by representing categories and their relations. For example, an “is a” relation may state that a regulatory T cell is a kind of CD4 T cell. A source label can therefore be equivalent to a target label, narrower than it, broader than it, or not reliably related to it. The target vocabulary need not contain every ontology term: it should contain the categories needed for the intended comparison, with definitions that can be applied consistently.
Rules for Building a Crosswalk
Begin with the label definitions and identifiers used by each atlas, not only their displayed names. Check the ontology identifier, definition, parent category, synonyms, and any atlas-specific annotation notes. A shared word is not proof of shared meaning, and different words can refer to the same category. When an atlas provides only a name and no reliable definition, treat that missing information as uncertainty in the mapping rather than assuming equivalence.
For a source label \(l\) and target label \(t\), a direct mapping is defensible when the populations described by \(l\) fit the definition of \(t\). If \(t\) is broader, mapping to it is an explicit aggregation. If \(t\) is narrower, the source label alone does not justify assigning its cells to \(t\): doing so would split a broad category without evidence about which cells belong to which subcategory. This rule concerns the meaning of the labels; any separate cell-level classification procedure is a different task.
For each atlas, record label names, definitions, ontology identifiers where available, and the number of cells bearing each label.
Set its intended level of detail for the comparison. Prefer categories whose definitions can be applied consistently to every atlas being compared.
Mark each mapping as equivalent, aggregated to a broader category, or unresolved. Record the evidence and any distinctions lost.
Check coverage, aggregation, unresolved labels, and whether any source category has been mapped to a target more specific than its definition supports.
A useful formalization makes the information loss explicit. Let \(L\) be the set of source labels and \(T\) the shared vocabulary. A crosswalk \(g\) assigns a target label to each mapped source label. If \(g(l_1)=g(l_2)\) for two distinct source labels, their distinction is lost in the harmonized data. If the distinction is supported and relevant, the target vocabulary should retain it. If the distinction cannot be represented consistently across atlases, aggregation may be necessary, but it should be recorded as such.
This follows directly from the mapping: after both labels are replaced by the same target value, the original label cannot be recovered from that value. In particular, a many-to-one mapping is not a neutral spelling change. It is a loss of label-level information, even if it is the most defensible choice for cross-atlas comparability.
Worked Example: Reconciling Equivalent Names Without Losing a Subtype
Suppose two hypothetical atlases use these labels and counts. Atlas A records “CD4 T cell” for 120 cells and “Treg” for 30. Atlas B records “CD4+ T lymphocyte” for 80 and “regulatory T cell” for 20. After reviewing the atlas definitions, assume “CD4 T cell” and “CD4+ T lymphocyte” refer to the same broad category, while both Treg labels refer to the same narrower regulatory category.
Use the shared vocabulary \(\{\text{CD4 T cell}, \text{regulatory T cell}\}\), with regulatory T cell defined as a subtype of CD4 T cell. Map “CD4+ T lymphocyte” to “CD4 T cell” as an equivalent-name mapping, and map “Treg” to “regulatory T cell.” Apply the same two mappings to the corresponding labels in Atlas B.
The harmonized counts are 120 broad CD4 T cells and 30 regulatory T cells from Atlas A, and 80 broad CD4 T cells and 20 regulatory T cells from Atlas B. The pooled counts are therefore \(120+80=200\) broad CD4 T cells and \(30+20=50\) regulatory T cells. The subtype remains identifiable because it has its own target label; it is not absorbed into the broader category. These pooled counts describe the labels after harmonization, not a claim that the two atlases sampled comparable populations in equal proportions.
Worked Example: Choosing a Common Level When One Atlas Is Broader
Consider two hypothetical atlases. Atlas A labels 60 cells “classical monocyte” and 40 “nonclassical monocyte.” Atlas B labels 100 cells “monocyte” and provides no subcategory labels. Assume the definitions establish that both Atlas A categories are monocyte subtypes and that Atlas B’s label includes both.
If the goal is a directly comparable category in both atlases, choose “monocyte” as the shared target. Map both Atlas A labels to “monocyte” and map Atlas B’s label to “monocyte.” Atlas A contributes \(60+40=100\) cells to the target, and Atlas B contributes 100; there are 200 harmonized monocytes in total.
This aggregation removes the classical-versus-nonclassical distinction for all 100 Atlas A cells, so the fraction of Atlas A cells whose subtype distinction is lost is \(100/100=1\), or 100%. Across both atlases, the fraction of cells originating in a source category with a finer label than the shared target is \(100/200=0.5\), or 50%. These figures describe the consequences of the chosen mapping; they do not show that the underlying biological subtypes are absent from Atlas B. If the analysis requires subtype-level comparisons, Atlas B’s broad label cannot be split using this crosswalk alone.
Coverage, Aggregation, and Unresolved Labels
A crosswalk should report how much of each atlas it maps and how much detail it removes. Let \(n_l\) be the number of cells with source label \(l\). The cell-weighted mapping coverage is the number of cells with mapped labels divided by the total number of cells considered. It is useful to report this separately from the fraction of source label categories mapped: mapping many rare labels may give high category coverage but low cell coverage, or the reverse.
Here \(L\) is the set of source labels under review and \(M\subseteq L\) is the set assigned a target. Coverage is not a measure of mapping correctness. A high value can coexist with incorrect assignments, so unresolved labels and aggregation decisions should also be visible in the report.
Worked Example: Quantifying an Unresolved Mapping
In a hypothetical atlas of 200 cells, 110 are labelled “fibroblast,” 50 “pericyte,” and 40 “activated stromal.” The first two labels have definitions that match target categories in the shared vocabulary. The definition of “activated stromal” is too broad to determine whether those cells belong in the fibroblast or pericyte category. No broader stromal target is included in the vocabulary.
Map the first two labels and mark “activated stromal” unresolved. The mapped cell count is \(110+50=160\), so cell-weighted coverage is \(160/200=0.8\), or 80%. The remaining \(40/200=0.2\), or 20%, is unresolved. There are three source categories and two map to targets, so category-level coverage is \(2/3\), or about 66.7%. Reporting both values makes clear that two-thirds of the label types account for four-fifths of the cells.
The 40 unresolved cells should not be divided between fibroblast and pericyte merely to obtain complete coverage. If a defensible broad stromal target is later added and the source definition fits it, mapping to that broader category could be considered and documented as aggregation. Otherwise, preserving the unresolved status is more informative than asserting an unsupported match.
Diagnostics and Alternative Approaches
Review the crosswalk at both the label and cell levels. A practical audit asks whether every source label has a documented status; whether any target is narrower than its source; whether several distinct source labels collapse to one target; and whether the collapse is intentional. Check cell counts after mapping: unexpected zero-count targets, abrupt changes in category proportions, or one source label dominating a target can expose a coding error or a misunderstood definition. These signals prompt review but do not, by themselves, prove a mapping is wrong.
There are two common alternatives to a carefully documented crosswalk, and both have narrower uses. Exact string matching is fast and can identify identical names, but misses synonyms and cannot detect different meanings attached to the same name. Automated lexical similarity can suggest candidate matches for manual review; it cannot establish that two labels describe equivalent populations. Ontology-based mapping uses identifiers and parent–child relations to make the semantics more explicit, but it still requires checking the atlas’s actual definitions and annotation conventions. No matching method removes the need to decide whether aggregation is acceptable for the intended comparison.
A frequent pitfall is reasoning, “Both labels contain ‘monocyte,’ so they can be replaced with the same most specific target.” This mistakes shared wording for equivalent specificity. If one source label covers all monocytes and the proposed target means only classical monocytes, the mapping asserts a distinction the source annotation does not provide. The correction is to map to a supported broader category, retain an unresolved status, or use additional justified evidence in a separate analysis—not to infer a subtype from the name.
Check Your Understanding
Answer each question, then compare your reasoning with the solutions.
- Atlas A uses “B cell” and Atlas B uses “B lymphocyte.” What information should be checked before treating these as equivalent?
- An atlas labels cells “dendritic cell,” while the shared vocabulary includes “conventional dendritic cell.” Can the broad source label be mapped to that narrower target on the label name alone?
- Of 500 cells, 425 have source labels mapped to the shared vocabulary. Calculate cell-weighted coverage and state one thing it does not establish.
- Two source categories, with 18 and 32 cells, are intentionally combined into one target category. How many cells lose their source-label distinction, and why should this be recorded?
Solutions. (1) Check definitions, ontology identifiers, synonyms, and atlas-specific annotation conventions; the similar names alone do not establish equivalent meanings. (2) No. A broad source category does not justify assigning all its cells to a narrower subtype. Map to a compatible broader target or leave it unresolved unless independent, justified evidence supports finer classification. (3) Coverage is \(425/500=0.85\), or 85%. This does not establish that the 425 mappings are correct. (4) \(18+32=50\) cells lose their distinction because both source labels become one target; recording this makes the deliberate information loss and its scope auditable.