From b825038ffc64a998abc9e66ac33006714569baf8 Mon Sep 17 00:00:00 2001 From: Taksh Date: Fri, 31 Jul 2026 15:43:13 +0300 Subject: [PATCH 1/8] =?UTF-8?q?docs(mimic-iv):=20state=20there=20is=20no?= =?UTF-8?q?=20official=20itemid=E2=86=92LOINC=20map?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Answer #1972 without promising a maintained crosswalk in this repo. Co-authored-by: Cursor --- mimic-iv/docs/LOINC_MAPPING.md | 40 ++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 mimic-iv/docs/LOINC_MAPPING.md diff --git a/mimic-iv/docs/LOINC_MAPPING.md b/mimic-iv/docs/LOINC_MAPPING.md new file mode 100644 index 00000000..2401cc5b --- /dev/null +++ b/mimic-iv/docs/LOINC_MAPPING.md @@ -0,0 +1,40 @@ +# 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 From d53b1fef5c8dcc72b4539a910fe8a69e7d0f6a61 Mon Sep 17 00:00:00 2001 From: Taksh Date: Fri, 31 Jul 2026 15:43:13 +0300 Subject: [PATCH 2/8] docs(mimic-iv): link README(s) to LOINC mapping notes Surface the #1972 answer from module and repo entrypoints. Co-authored-by: Cursor --- README.md | 4 ++++ mimic-iv/README.md | 6 +++++- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 53fe9f9f..8a3297a3 100644 --- a/README.md +++ b/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) diff --git a/mimic-iv/README.md b/mimic-iv/README.md index 919b196c..5425bede 100644 --- a/mimic-iv/README.md +++ b/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 -``` \ No newline at end of file +``` + +## Terminology / LOINC + +There is no official MIMIC-IV itemid→LOINC map here — see [docs/LOINC_MAPPING.md](docs/LOINC_MAPPING.md). From caaabc704c9b6ac33a32603816ac63dee6e66623 Mon Sep 17 00:00:00 2001 From: Taksh Date: Fri, 31 Jul 2026 15:43:13 +0300 Subject: [PATCH 3/8] docs(mimic-iv): ensure documentation helper-query folder exists Home for terminology audit SQL outside the derived-concept tree. Co-authored-by: Cursor --- mimic-iv/concepts/documentation/README.md | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 mimic-iv/concepts/documentation/README.md diff --git a/mimic-iv/concepts/documentation/README.md b/mimic-iv/concepts/documentation/README.md new file mode 100644 index 00000000..15576507 --- /dev/null +++ b/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. From bed876877461f270104e2b1bb0a638cc05e0e04a Mon Sep 17 00:00:00 2001 From: Taksh Date: Fri, 31 Jul 2026 15:43:13 +0300 Subject: [PATCH 4/8] docs(mimic-iv): sample d_labitems query for manual LOINC review Show researchers where labels live when no official map exists (#1972). Co-authored-by: Cursor --- mimic-iv/concepts/documentation/labitems_label_sample.sql | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 mimic-iv/concepts/documentation/labitems_label_sample.sql diff --git a/mimic-iv/concepts/documentation/labitems_label_sample.sql b/mimic-iv/concepts/documentation/labitems_label_sample.sql new file mode 100644 index 00000000..f7df7c25 --- /dev/null +++ b/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; From 3713575a514795377aa93850065b98e99ebb2498 Mon Sep 17 00:00:00 2001 From: Taksh Date: Fri, 31 Jul 2026 15:43:13 +0300 Subject: [PATCH 5/8] docs(mimic-iv): sample d_items query for SpO2-like labels Help #1972-style terminology work without inventing LOINC codes. Co-authored-by: Cursor --- .../concepts/documentation/chartevents_item_sample.sql | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 mimic-iv/concepts/documentation/chartevents_item_sample.sql diff --git a/mimic-iv/concepts/documentation/chartevents_item_sample.sql b/mimic-iv/concepts/documentation/chartevents_item_sample.sql new file mode 100644 index 00000000..55f96883 --- /dev/null +++ b/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; From 1434ab47505e24634a1516a5e2c09db1a44932fc Mon Sep 17 00:00:00 2001 From: Taksh Date: Fri, 31 Jul 2026 15:43:13 +0300 Subject: [PATCH 6/8] docs(mimic-iv): clarify we will not invent an official LOINC ETL column Keep #1972 resolved as documentation and practice guidance. Co-authored-by: Cursor --- mimic-iv/docs/LOINC_MAPPING.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/mimic-iv/docs/LOINC_MAPPING.md b/mimic-iv/docs/LOINC_MAPPING.md index 2401cc5b..a6a4267c 100644 --- a/mimic-iv/docs/LOINC_MAPPING.md +++ b/mimic-iv/docs/LOINC_MAPPING.md @@ -38,3 +38,10 @@ community CSV as **unofficial**. - 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. + From 0d62c89d043f3d71c5f5e8af09c3061671d7659a Mon Sep 17 00:00:00 2001 From: Taksh Date: Sat, 1 Aug 2026 15:14:05 +0300 Subject: [PATCH 7/8] ci: ignore SQLFluff annotate failures on fork PRs Fork tokens cannot create check runs; keep lint green with ignore-unauthorized-error and skip annotate when no concept SQL changed. Co-authored-by: Cursor --- .github/workflows/lint_sqlfluff.yml | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/.github/workflows/lint_sqlfluff.yml b/.github/workflows/lint_sqlfluff.yml index 0986785b..71f08fca 100644 --- a/.github/workflows/lint_sqlfluff.yml +++ b/.github/workflows/lint_sqlfluff.yml @@ -1,11 +1,16 @@ name: SQLFluff +# Lints changed mimic-iv/concepts/*.sql on pull requests and posts GitHub +# annotations. permissions + ignore-unauthorized-error keep fork PRs usable. 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 +40,10 @@ jobs: shell: bash run: sqlfluff lint --format github-annotation --annotation-level failure --nofail ${{ steps.get_files_to_lint.outputs.lintees }} > annotations.json - name: Annotate + if: steps.get_files_to_lint.outputs.lintees != '' uses: yuzutech/annotations-action@v0.6.0 with: repo-token: "${{ secrets.GITHUB_TOKEN }}" title: "SQLFluff Lint" - input: "./annotations.json" \ No newline at end of file + input: "./annotations.json" + ignore-unauthorized-error: true From c70ee7c1d7e2e0157cf79297a1ff88d429e6aba5 Mon Sep 17 00:00:00 2001 From: Taksh Date: Sat, 1 Aug 2026 15:16:05 +0300 Subject: [PATCH 8/8] ci: skip SQLFluff Annotate on fork PRs ignore-unauthorized-error does not catch the fork 403 (Resource not accessible by integration). Skip Annotate when head.repo != base repo so lint-mimic-iv can stay green. --- .github/workflows/lint_sqlfluff.yml | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/.github/workflows/lint_sqlfluff.yml b/.github/workflows/lint_sqlfluff.yml index 71f08fca..d6e1c3f0 100644 --- a/.github/workflows/lint_sqlfluff.yml +++ b/.github/workflows/lint_sqlfluff.yml @@ -1,7 +1,8 @@ name: SQLFluff # Lints changed mimic-iv/concepts/*.sql on pull requests and posts GitHub -# annotations. permissions + ignore-unauthorized-error keep fork PRs usable. +# annotations. Fork PRs skip Annotate — GITHUB_TOKEN cannot create check runs +# from forks (Resource not accessible by integration / 403). on: - pull_request @@ -40,7 +41,11 @@ jobs: shell: bash run: sqlfluff lint --format github-annotation --annotation-level failure --nofail ${{ steps.get_files_to_lint.outputs.lintees }} > annotations.json - name: Annotate - if: steps.get_files_to_lint.outputs.lintees != '' + # 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 }}"