docs(mimic-iv): no official itemid→LOINC map (#1972)

.github/workflows/lint_sqlfluff.yml

@@ -1,11 +1,17 @@
 name: SQLFluff
 
+# Lints changed mimic-iv/concepts/*.sql on pull requests and posts GitHub
+# annotations. Fork PRs skip Annotate — GITHUB_TOKEN cannot create check runs
+# from forks (Resource not accessible by integration / 403).
 on:
   - pull_request
 
 jobs:
   lint-mimic-iv:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      checks: write
     steps:
       - name: checkout
         uses: actions/checkout@v7
@@ -35,8 +41,14 @@ jobs:
         shell: bash
         run: sqlfluff lint --format github-annotation --annotation-level failure --nofail ${{ steps.get_files_to_lint.outputs.lintees }} > annotations.json
       - name: Annotate
+        # Same-repo PRs only: fork tokens get 403 creating check runs, and
+        # ignore-unauthorized-error does not treat that as unauthorized.
+        if: >
+          steps.get_files_to_lint.outputs.lintees != '' &&
+          github.event.pull_request.head.repo.full_name == github.repository
         uses: yuzutech/annotations-action@v0.6.0
         with:
           repo-token: "${{ secrets.GITHUB_TOKEN }}"
           title: "SQLFluff Lint"
-          input: "./annotations.json"
+          input: "./annotations.json"
+          ignore-unauthorized-error: true

README.md

@@ -114,3 +114,7 @@ By committing your code to the [MIMIC Code Repository](https://github.com/mit-lc
 ### Coding style
 
 Please refer to the [style guide](https://github.com/MIT-LCP/mimic-code/blob/main/styleguide.md) for guidelines on formatting your code for the repository.
+
+### MIMIC-IV notes
+
+- [itemid → LOINC](mimic-iv/docs/LOINC_MAPPING.md)

mimic-iv/README.md

@@ -105,4 +105,8 @@ mimic_utils convert_folder mimic-iv/concepts mimic-iv/concepts_duckdb --destinat
 
 # To PostgreSQL:
 mimic_utils convert_folder mimic-iv/concepts mimic-iv/concepts_postgres --destination_dialect postgres
-```
+```
+
+## Terminology / LOINC
+
+There is no official MIMIC-IV itemid→LOINC map here — see [docs/LOINC_MAPPING.md](docs/LOINC_MAPPING.md).

mimic-iv/concepts/documentation/README.md

@@ -0,0 +1,4 @@
+# Documentation helper queries
+
+Ad-hoc SQL that illustrates known data quirks. These are **not** part of the
+official derived concept build — run them against a local or BigQuery copy.

mimic-iv/concepts/documentation/chartevents_item_sample.sql

@@ -0,0 +1,8 @@
+-- Sample ICU d_items labels (vitals/scores) for manual terminology review (#1972).
+
+SELECT itemid, label, abbreviation, linksto, category
+FROM icu.d_items
+WHERE LOWER(label) LIKE '%spo2%'
+   OR LOWER(label) LIKE '%o2 saturation%'
+ORDER BY itemid
+LIMIT 50;

mimic-iv/concepts/documentation/labitems_label_sample.sql

@@ -0,0 +1,8 @@
+-- Sample d_labitems labels for cohorts that need a manual LOINC review (#1972).
+-- There is no LOINC column in MIMIC-IV dictionaries.
+
+SELECT itemid, label, fluid, category
+FROM hosp.d_labitems
+WHERE LOWER(label) LIKE '%creatinine%'
+ORDER BY itemid
+LIMIT 50;

mimic-iv/docs/LOINC_MAPPING.md

@@ -0,0 +1,47 @@
+# MIMIC-IV itemid → LOINC mapping
+
+There is **no official, complete MIMIC-IV `itemid` → LOINC map** in this
+repository or on PhysioNet as a maintained product.
+
+See [issue #1972](https://github.com/MIT-LCP/mimic-code/issues/1972).
+
+## What exists today
+
+| Path | Scope | Caveat |
+|------|-------|--------|
+| `d_items` / `d_labitems` labels | MIMIC-IV dictionaries | Human-readable names, not LOINC |
+| MIMIC-III `conceptid` / community maps | Older releases | Incomplete; IV itemids are a different namespace |
+| OMOP / Athena / manual review | External | Best for modeling when you need LOINC semantics |
+| PhysioNet forum threads | Community | Useful pointers; not version-guaranteed |
+
+A multi-hop IV → III → LOINC conversion is **error-prone**: itemids were
+reassigned across CareVue / MetaVision / IV, and LOINC bindings in older
+helpers were never exhaustive.
+
+## Recommended practice for predictive modeling
+
+1. Prefer **MIMIC-IV `itemid`** (and `d_labitems.label` / `fluid` / `category`)
+   as the primary feature key inside a single MIMIC version.
+2. If LOINC is required for multi-site harmonization, build an explicit map
+   for the **subset of itemids you use**, with manual clinician/terminology
+   review — do not treat a scraped IV→III→LOINC chain as ground truth.
+3. Record the MIMIC version, map provenance, and unmapped rate in the paper
+   or model card.
+
+## What this repository will not add as “official”
+
+A full LOINC crosswalk would need ongoing clinical terminology maintenance
+outside the CSV loaders. Until PhysioNet publishes one, please treat any
+community CSV as **unofficial**.
+
+## Related
+
+- Lab value / unit quirks: `mimic-iv/buildmimic/TABLE_NOTES.md` (when present)
+- Qualitative labs (`NEG`/`POS`): same notes / issue #1938
+
+## What this repository will not change
+
+MIMIC-Code will not ship a silent “official” LOINC column into `d_labitems`
+or rewrite community maps into the PhysioNet loaders. Publish derived maps
+as versioned concepts with explicit provenance if you contribute one.
+