Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 48 additions & 9 deletions .claude/skills/pro-marker-species-support/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,21 +118,60 @@ own discipline here.

## Step 4 — write the row

Append to `reports/pro_marker_species_support.tsv`
(tab-separated, one row per pair):
`reports/pro_marker_species_support.tsv` has one row per directly asserted
(CL term, PRO marker) pair for every CL term in
`mappings/curated_mappings.tsv` (87 pairs as of 2026-09-28). The question is
Dr. Diehl's: **is each marker, as CL asserts it, valid in human, mouse, or
both?**

**Never edit the first 10 (legacy) columns** of an existing row. They record
the original human-only check from issue #11. All new work goes in the 7
columns after them. **Where the new columns disagree with the legacy
`species_support` value, the new columns take precedence** (e.g. plasmablast
"lacks CD138", where the legacy value still says `human`).

| Column | Meaning |
|---|---|
| `cl_id`, `cl_label`, `pr_id`, `pr_label`, `cd_synonym` | From `get_scoped_pairs()` — don't hand-retype these, pull them programmatically to avoid transcription errors (a real bug caught during the first run: hand-typed PR labels didn't match `cl_pro_relationships.tsv`). |
| `species_support` | `human` / `mouse` / `both` / `insufficient_evidence`. |
| `evidence_source` | `m2_literature_report` / `citation_traversal` / `europepmc_search` / `none`. |
| `citation` | Author/year/PMID/DOI, plus a trailing `-- ` caveat clause when the quote's context doesn't exactly match the pair's cell type/subset (e.g. a naive-T marker's only evidence coming from a Treg paper) — say so rather than let the row imply a cleaner match than it is. |
| `quote` | The verbatim substring itself. |
| `source_ref` | `literature/evidence.tsv#<evidence_id>` for M2 reuse (older rows cite `archive/2026-09_literature_narratives/<file>.md`), an EuropePMC article URL for a fresh search, or `reports/citation_traversal/<run_id>/` for a traversal — or, for `insufficient_evidence`, a one-line note on what was tried. |
| `cl_id`, `cl_label`, `pr_id`, `pr_label`, `cd_synonym` | From `cl_pro_relationships.tsv` — pull them programmatically, don't retype them. |
| `species_support`, `evidence_source`, `citation`, `quote`, `source_ref` | **Legacy** (issue #11 human-only check). Read-only. |
| `species_scope` | `human`, `mouse`, `both` or `unresolved` (blank = not yet assessed). |
| `human_citation`, `human_quote` | Citation (author, year, PMID, PMCID) and an exact quote for the human side. |
| `mouse_citation`, `mouse_quote` | The same for mouse. |
| `note` | Free text explaining the verdict, e.g. "not tested in mouse, no reagent", "ortholog exists but not expressed", "contradicted in mouse", or "species from PRO label". |
| `checked_on` | Date the row was last assessed. |

Rules for `species_scope`:

- **Judge against the assertion as CL states it.** For a negative pair
("lacks CD14"), evidence that the marker is absent in a species *supports*
it.
- `both` only when **both** species have an exact quote supporting the
assertion.
- `human` / `mouse` when that species is supported and the other is
contradicted by a quote (e.g. mouse NK cells are not classified by CD56).
- `unresolved` whenever a species has no evidence, only "not tested", or
conflicting evidence. Explain which in `note`. **Never treat "not tested in
mouse" as human-only.**
- Pairs whose PRO label is species-qualified, e.g. "(human)", get
`species_scope = human` and the note "species from PRO label".
- **Human-specific CL terms** (label ending ", human", e.g. CL:0000938): the
mouse question doesn't apply. Set `species_scope = human` when the human
side is supported by a verified quote, otherwise `unresolved`, and start
`note` with "CL term is human-specific; mouse not applicable".
- An existing mouse ortholog (Alliance of Genome Resources / MGI) is **not**
evidence that a marker works in mouse. It may go in `note` with its record
ID; mouse support needs literature.
- Every quote is checked word for word against the paper's Europe PMC full
text (as `soulcap-evidence verify` does) before it is written. If none can
be verified, leave the quote blank and say so in `note`.

Evidence sources, in order: references in `literature/reviews/` (Dr. Diehl's
first); verified rows of `literature/evidence.tsv`; then open-access
literature via `soulcap-europepmc` / Europe PMC full text.

## Step 5 — flag real findings

If a `species_support` result is genuinely surprising (e.g. a marker CL
If a `species_scope` result is genuinely surprising (e.g. a marker CL
implicitly treats as pan-species turns out to only have mouse evidence, or a
whole marker cluster comes back `insufficient_evidence` the way monocyte
subset markers did), log it the same way other literature/CL gaps from this
Expand Down
2 changes: 1 addition & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ pages hold the full detail.
| [pipeline.md](pipeline.md) | Each pipeline stage and its command: sheet sync, CL→PRO axioms, candidate matching, OAK lexical search, SSSOM export, ROBOT QC |
| [marker_resolution.md](marker_resolution.md) | Token → PRO resolution rules, policies, lexical cache |
| [matching_and_evaluation.md](matching_and_evaluation.md) | Audit dashboard, matcher evaluation, regression triage and follow-up |
| [planning/](planning/) | Sprint backlog and semester plan (hand-maintained); agenda for the [12 Oct 2026 meeting](planning/2026-10-12_meeting_summary.md) |
| [planning/](planning/) | Sprint backlog and semester plan (hand-maintained); agenda for the [12 Oct 2026 meeting](planning/2026-10-12_meeting_summary.md); [human/mouse marker pilot summary](planning/2026-10-02_diehl_summary.md) for Dr. Diehl |

Related specs that live at the top level: [MARKER_SYNTAX.md](../MARKER_SYNTAX.md)
(marker expression grammar) and [ROADMAP.md](../ROADMAP.md) (milestones).
Expand Down
76 changes: 76 additions & 0 deletions docs/planning/2026-10-02_diehl_summary.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# Human vs mouse validity of CL markers: pilot summary for 2 October 2026

For Dr. Diehl. Your request from 28 September, a pilot on 3 CL terms, and
three questions before the rest is done.

## The task and how it's done

For every CL term a SOULCAP cell type maps to, each PRO marker CL asserts
directly (87 pairs) is checked: **is the assertion, as CL states it, valid in
human, mouse, or both?** For a negative assertion such as "lacks CD14",
absence in a species counts as support.

- Each species needs its own **exact quote**, checked word for word against
the paper's full text in Europe PMC. Nothing is inferred from a marker's name
or from memory.
- `both` requires a supporting quote for each species. "Not tested in mouse"
gives `unresolved`, never "human only". An existing mouse ortholog is not
counted as evidence.
- Results are in `reports/pro_marker_species_support.tsv` (new columns
`species_scope`, `human_*`, `mouse_*`, `note`). The original human-only
check is kept unchanged alongside.

## Pilot: 3 CL terms, 10 pairs

| CL term: assertion | Human | Mouse | Scope |
|---|---|---|---|
| NK cell (CL:0000623): lacks CD20 | Supported | No evidence found | unresolved |
| NK cell: lacks CD14 | Supported | No evidence found | unresolved |
| Plasmablast (CL:0000980): CD38 high | Supported | No evidence found | unresolved |
| Plasmablast: CD27 high | Supported | No evidence found | unresolved |
| Plasmablast: lacks CD20 | Supported | No evidence found | unresolved |
| Plasmablast: lacks CD138 | Conflicting | **Contradicted** | unresolved |
| CD56-bright NK, human (CL:0000938): CD56 high | Supported | Contradicted | **human** |
| CD56-bright NK: lacks CD16 | Supported | Not applicable | **human** |
| CD56-bright NK: lacks HLA-DRA | **Not supported** | Not applicable | unresolved |
| CD56-bright NK: CD84 positive | No evidence found | Not applicable | unresolved |

Also, 10 pairs whose PRO term is itself human-specific, e.g. "(human)" in the
label, are marked `human` from the label.

## Three notable findings

1. **CD56 is the clearest human-only marker.** "Because mice lack CD56, murine
NK cell subsets are classified using alternative markers, particularly CD27
and Mac-1." (PMID 41898531). The mouse gene *Ncam1* exists (MGI:97281), but
it isn't used for NK cells.
2. **Plasmablast "lacks CD138" doesn't hold in mouse and is disputed in
human.** Mouse: "plasmablasts as B220+CD138+" (PMID 42774878). Human:
"short-lived plasmablasts (CD19+CD138++ or CD19+CD27+CD38++)"
(PMID 41771939).
3. **CD56-bright NK "lacks HLA-DRA" isn't well supported even in human:** "the
proportion of HLA-DR+CD56bright cells ex vivo" (PMID 42450353). PRO notes
the mouse counterpart is H2-Ea.

Findings 2 and 3 are logged as unfiled candidates in
`reports/cl_term_issues.md`.

## Questions for you

a. **Can you share your references?** They'll be used first, before any new
searching (they go in `literature/reviews/`).

b. **Negative lineage markers.** For assertions like "lacks CD14 / CD19 / CD20"
on non-myeloid or non-B cells, will you accept `both` on biological
grounds, or require a quote for each species? The mouse literature rarely
states these absences, so requiring quotes leaves most of them
`unresolved`.

c. **Human-specific CL terms.** For terms like CL:0000938 ("…, human"), is
"mouse not applicable", scoped `human` when the human side is supported,
the right rule?

## Remaining scope

**67 pairs on 30 CL terms**, waiting for your answers. Four of those pairs
already have a corrected human quote; their mouse side is still to do.
2 changes: 1 addition & 1 deletion reports/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ These are generated, but they are inputs to other code and need network access
|---|---|---|---|
| [gaps.tsv](gaps.tsv) | Cases with no good CL match, CL/marker conflicts, CL axiom gaps, or sheet data problems. Filed as GitHub issues by the `gap-issue-filing` skill | Hand-maintained | Curated |
| [cl_term_issues.md](cl_term_issues.md) | Proposed Cell Ontology corrections found during mapping | Hand-maintained | Curated |
| [pro_marker_species_support.tsv](pro_marker_species_support.tsv) | Whether literature supports each CL PRO marker as human, mouse, or both (issue #11) | `pro-marker-species-support` skill, quotes verified verbatim | Curated |
| [pro_marker_species_support.tsv](pro_marker_species_support.tsv) | For every directly asserted PRO marker on a mapped CL term (87 pairs): is the assertion valid in human, mouse, or both? The first 10 columns are the original human-only check (issue #11, read-only); `species_scope`, `human_*`/`mouse_*` citation and quote, `note` and `checked_on` hold the human/mouse assessment (Dr. Diehl's request, 2026-09-28; pilot on 3 CL terms so far). Where they disagree with the legacy `species_support`, the new columns take precedence | `pro-marker-species-support` skill; every quote checked against the paper's full text | Curated |

## Not tracked

Expand Down
38 changes: 38 additions & 0 deletions reports/cl_term_issues.md
Original file line number Diff line number Diff line change
Expand Up @@ -185,6 +185,44 @@ confirmed)? The same question applies to CD57 (HNK-1 epitope, made by
B3GAT1, PR:000001440): CL has one such axiom, CL:4033092 "CD57-positive
enterocyte" `expresses` PR:000001440.

### Plasmablast "lacks CD138" — CL:0000980, PR:000001935 (syndecan-1)

**Status:** candidate — not filed

CL asserts CL:0000980 "plasmablast" `lacks_plasma_membrane_part`
PR:000001935 "syndecan-1" (CD138). Found during the human/mouse marker
review (2026-09-28; row in
[pro_marker_species_support.tsv](pro_marker_species_support.tsv)). Both
quotes were checked word for word against the Europe PMC full text:

- **Contradicted in mouse:** "plasmablasts as B220+CD138+" (PMID 42774878;
PMC13594723, 2026).
- **Conflicting in human:** one human scheme defines plasmablasts as CD138++:
"short-lived plasmablasts (CD19+CD138++ or CD19+CD27+CD38++)" (PMID
41771939; PMC13066544, 2026). The earlier human quote supporting the
assertion (Woodruff 2020 gating labels) could not be verified.

**Question for review:** should this axiom be removed, weakened (e.g. "low"),
or restricted to human?

### CD56-bright NK "lacks HLA-DRA" — CL:0000938, PR:000002015

**Status:** candidate — not filed

CL asserts CL:0000938 "CD16-negative, CD56-bright natural killer cell, human"
`lacks_plasma_membrane_part` PR:000002015 "MHC class II histocompatibility
antigen alpha chain DRA". Human evidence reports HLA-DR+ CD56-bright cells:
"the proportion of HLA-DR+CD56bright cells ex vivo" (PMID 42450353;
PMC13362507, 2026; checked word for word against the full text). The
supporting quote from the earlier check (Rebuffet 2024) concerns a different
NK cluster (NK3B) and does not address CD56-bright cells.

**Question for review:** is "lacks HLA-DRA" right for resting CD56-bright NK
cells, with HLA-DR appearing only on an activated subset, or should the axiom
be dropped? This is also Dr. Diehl's example of HLA-DRA as a human-only proxy
for MHC class II: PRO notes "The mouse ortholog is called H2-Ea"
(PR:000002015, OLS4).

---

## Resolved issues
Expand Down
Loading
Loading