Code Crosswalks and Mappings Between Coding Systems

A code crosswalk (also called a code mapping) is an official or curated translation table that associates codes in one medical coding system with the closest equivalent codes in another. Crosswalks exist because the healthcare data ecosystem spans multiple, independently governed vocabularies — ICD-9-CM for legacy diagnoses, ICD-10-CM for current diagnoses, NDC for drug package identity, RxNorm for drug ingredients, HCPCS/CPT for procedures and administered drugs, and SNOMED CT for clinical concepts — and no single coding system covers all data types or all calendar periods. Real-world evidence (RWE) studies routinely span vocabulary transitions or assemble data from sources that use different systems, making crosswalk literacy a foundational skill.

The inventory of major crosswalks

GEMs — General Equivalence Mappings (CMS/NCHS, ICD-9-CM ↔ ICD-10-CM/PCS). GEMs were developed jointly by CMS and the National Center for Health Statistics to support the October 1, 2015 transition from ICD-9-CM to ICD-10-CM (diagnoses) and ICD-10-PCS (inpatient procedures). Two files exist for each direction: the forward map (ICD-9-CM → ICD-10-CM) and the backward map (ICD-10-CM → ICD-9-CM). Each row carries four critical flags:

1. the approximate flag (0 = exact match, 1 = approximate/best available),
2. the no map flag (code has no usable equivalent),
3. the combination flag (the ICD-9 concept requires multiple ICD-10 codes to fully express), and
4. the scenario/choice list flags that group one-to-many alternatives. A single ICD-9-CM code commonly maps forward to 3–10 ICD-10-CM codes, and many maps carry approximate = 1, meaning granularity was genuinely lost or gained in translation. GEMs were last updated for FY2018; they are officially retired but remain the de facto standard tool for any study spanning the pre- and post-October-2015 period. Researchers must freeze the GEM version and document it, because there will be no future updates to reconcile.

NDC ↔ RxNorm (NLM RxNav API, monthly updates). The National Library of Medicine's RxNorm is the standard for drug ingredient, clinical drug (product), and branded product identity in the United States. The NLM RxNav API resolves an 11-digit NDC (as it appears in a claims or pharmacy dispensing record) to its RxNorm Concept Unique Identifier (RXCUI) at the ingredient or clinical drug level. This mapping is critical for two reasons: NDCs change whenever a manufacturer repackages or reformulates a product (a single ingredient can have hundreds of active NDCs at any moment), and NDC lists therefore rot rapidly; defining drug exposure at the RxNorm ingredient level and resolving NDCs through RxNorm insulates a study from NDC churn. The NLM also maintains historical NDC endpoints for mapping retired codes. The RxNorm mapping is updated monthly; a study using a snapshot must document the snapshot date.

NDC ↔ HCPCS (CMS Average Sales Price Drug Pricing crosswalk, quarterly). Medicare Part B covers many drugs administered in clinical settings and reimburses them under HCPCS Level II J-codes. The CMS publishes quarterly ASP (Average Sales Price) Drug Pricing files that include an NDC-to-HCPCS crosswalk, allowing researchers to recover the drug identity behind a J-code claim. This is essential for medical-benefit drug studies: a claim for J9271 (pembrolizumab) is informative on its own, but the NDC crosswalk confirms the specific product and links back to the RxNorm ingredient for pharmacological classification. The crosswalk also resolves "not otherwise classified" NOC codes (e.g., J3490, J9999), which appear when a drug has no dedicated J-code. Because NDCs change with ASP submission cycles, the specific quarterly file version must be documented.

SNOMED CT ↔ ICD-10-CM (NLM rule-based map, for reimbursement derivation). The NLM maintains a rule-based SNOMED CT–to–ICD-10-CM map that supports translation from clinical documentation systems (which may use SNOMED CT) to reimbursement coding (ICD-10-CM). The map is intentionally lossy: SNOMED CT's clinical granularity (laterality, severity, morphology) cannot always survive the translation to ICD-10-CM's billing categories. Researchers should treat SNOMED↔ICD-10-CM as a triage tool, not a reliable phenotype definition, and re-derive code lists natively in each system whenever possible.

CPT/HCPCS ↔ SNOMED CT and ICD-10-PCS ↔ SNOMED CT (partial maps). Partial procedure maps exist between CPT and SNOMED CT and between ICD-10-PCS and SNOMED CT, but coverage is incomplete and maintained by different organizations on different schedules. These are useful for concept-level harmonization across datasets but require the same caveat: verify coverage fractions before relying on them.

UMLS Metathesaurus as the CUI-level hub. The NLM Unified Medical Language System (UMLS) integrates more than 200 biomedical vocabularies under a single Concept Unique Identifier (CUI), enabling lookup from any supported source system to any other. The Metathesaurus connects ICD-9-CM, ICD-10-CM, SNOMED CT, RxNorm, LOINC, MeSH, and many others under one roof. UMLS requires a free UMLS Metathesaurus License; it is not public-domain. The breadth makes it the most comprehensive single hub, but its mappings vary in source and quality — some are algorithmically generated and should be reviewed for the specific concept.

OMOP CONCEPT_RELATIONSHIP "Maps to" as the operational crosswalk hub. Within the OMOP Common Data Model, the CONCEPT_RELATIONSHIP table stores the "Maps to" relationship that connects every source code (ICD-9-CM, ICD-10-CM, NDC, CPT, HCPCS, SNOMED CT) to its standard concept. This is a continuously maintained, versioned crosswalk hub — the OHDSI community updates it regularly, and new vocabulary versions are released quarterly. Researchers using OMOP inherit the crosswalk automatically through the ETL, but must still document the vocabulary version used (it is stored in the VOCABULARY table) and understand that source codes without a "Maps to" relationship fall to concept_id = 0 (unmapped) and are invisible to standard-concept queries.

The methodological core: crosswalks are approximations, not identities

Every crosswalk changes the measurement. This is the most important principle of crosswalk methodology, and the one most frequently violated. The specific failure modes are:

• One-to-many inflation. When a single ICD-9-CM code maps forward to multiple ICD-10-CM codes, applying the GEM mechanically to expand a code list inflates the code count. If an analyst counts diagnosis codes or trends in code frequency, the ICD-10 transition will appear to generate more diagnoses — not because disease incidence changed, but because each ICD-9 concept now has more granular children. This is a cartographic artifact, not a clinical signal, and it is one of the primary drivers of apparent trend discontinuities at 2015-10-01.

• Granularity loss on backward maps. When translating from ICD-10-CM (more granular) backward to ICD-9-CM (less granular), multiple distinct ICD-10-CM codes often collapse onto a single ICD-9-CM code. Information is irreversibly lost.

• Asymmetry: forward ∘ backward ≠ identity. Applying the forward map and then the backward map does not return the original code set. This is not a defect in the GEMs; it is a logical consequence of the coding system transition — the two systems have different granularity and different clinical partitions. Researchers who assume round-trip equivalence will produce incorrect overlap analyses.

• Version drift. Crosswalks are updated on different schedules (GEMs: frozen at FY2018; ASP crosswalk: quarterly; RxNorm: monthly; OMOP vocabularies: quarterly). A study that runs across multiple vocabulary update cycles may apply different translations to different time periods, introducing a time-varying mapping artifact unless the researcher pins a single snapshot and documents it.

• Approximate flag is the norm, not the exception. In the forward GEM for ICD-9-CM to ICD-10-CM, the majority of entries carry approximate = 1, meaning the mapping is the best available, not a true clinical equivalence. Treating approximate = 0 (exact) rows as high-confidence and approximate = 1 rows as requiring clinical review is the standard practice.

Best practice: map the concept, not the code list

The gold standard is to re-derive the code list natively in each coding system — starting from the clinical concept, asking a subject-matter expert to curate the relevant codes independently in ICD-9-CM and in ICD-10-CM — rather than mechanically translating the ICD-9 list forward. Use the GEM as a first-pass triage tool to identify candidate codes in the target system, then clinician-review the candidate set. For transition-spanning trends, run ITS (interrupted time series) diagnostics at 2015-10-01 to distinguish cartographic from biological discontinuities.

Licensing and public-domain status

• GEMs (ICD-9-CM ↔ ICD-10-CM/PCS): public domain, freely downloadable from CMS.
• CMS ASP NDC-HCPCS crosswalk: public domain, freely downloadable from CMS.
• NLM RxNav / RxNorm API: public domain for the API and underlying data.
• UMLS Metathesaurus: requires a free UMLS Metathesaurus License (NLM sign-up).
• SNOMED CT: requires a NRC (National Release Center) license in the US; obtained free through NLM for most research uses.

Pros, cons, and trade-offs — specific and comparative

• Crosswalk (mechanical translation) vs concept re-derivation (native curation): Mechanical translation via GEMs is fast and reproducible, and it produces a code list that can be traced to an official table. Cost: it inherits all GEM approximations and one-to-many expansions, and it can include codes that a clinician familiar with the target system would exclude and miss codes the GEM did not capture. Prefer concept re-derivation for the final, study-grade code list; use the crosswalk as triage. The GEM-first-then-clinician-review workflow is the standard recommended by AHIMA and OHDSI.

• Pinned crosswalk snapshot vs live API: Using a live RxNorm or OMOP vocabulary API at query time ensures the latest mappings but means the study results may change if the API is called at different times. For reproducible research, pin and archive the crosswalk snapshot with a date stamp. Prefer a pinned snapshot for published research. The OMOP versioned vocabulary download (available from the Athena portal) is the standard mechanism for this in OMOP studies.

• GEMs vs OMOP "Maps to" for ICD-9/ICD-10 bridging: GEMs operate at the raw ICD code level; OMOP "Maps to" operates at the standard concept level (SNOMED for conditions, RxNorm for drugs) and abstracts away the ICD version. For network studies using OMOP, the "Maps to" relationships are preferred because they are vocabulary-version-agnostic. For studies on raw claims not in OMOP, GEMs are the correct tool. Prefer OMOP "Maps to" when the data are in OMOP-CDM; prefer GEMs when working directly with ICD claims.

When NOT to use — and when it is actively misleading or dangerous

• As a substitute for clinical concept re-derivation. Applying the GEM forward map to generate an ICD-10-CM code list and treating the output as a validated phenotype is misleading. The GEM was designed for billing and administrative continuity, not for research phenotyping. The one-to-many expansions and approximate flags mean that a researcher who trusts the GEM output without clinical review will include codes that are clinically irrelevant and miss others that are clinically central.

• For trend analysis without ITS diagnostics. Using a crosswalk to translate a code list and then measuring trends across the transition without testing for a cartographic discontinuity at 2015-10-01 is actively misleading. The coding transition itself introduces apparent level changes and slope breaks in virtually every ICD-based condition series; reporting these as clinical trends is incorrect.

• When the approximate flag is ignored. Selecting only the zero-flag rows from the GEM (exact matches) and discarding approximate rows will silently exclude the majority of the mapping — most ICD-9 concepts have no exact ICD-10 equivalent. Ignoring the flag entirely and treating all rows as equivalent is also wrong because it obscures the uncertainty.

• When version drift is ignored. Applying a quarterly ASP crosswalk from a different quarter than the study period, or applying the FY2016 GEM to FY2018 data, introduces uncontrolled mapping variation. For regulatory submissions (FDA, payer dossiers), the crosswalk version must be documented and justified.

• For MA-only or capitated data. If the claims data derive from capitated arrangements that do not produce adjudicated ICD codes (e.g., Medicare Advantage encounter data with systematically missing diagnoses), no crosswalk can recover what was never coded. Restrict to FFS-observable person-time before applying any ICD-based crosswalk.

Data-source operational depth

• Claims (FFS commercial / Medicare FFS): ICD-9/ICD-10-CM on the diagnosis fields; NDC on pharmacy claims; HCPCS/CPT on medical claims. Apply GEMs across the 2015 transition; use the ASP crosswalk to resolve J-codes to NDCs; use RxNorm to normalize NDC to ingredient. Failure mode: procedure codes on medical claims may be CPT (AMA-licensed, not in GEMs) — use the partial CPT↔SNOMED map or OMOP "Maps to" if the data are in OMOP. Document whether the study population includes Medicare Advantage spans; the NDC-HCPCS crosswalk is irrelevant for MA claims where drug administration records may be absent.
• EHR: Problem lists and encounter diagnoses may carry ICD-10-CM or SNOMED CT depending on the system and configuration year. The SNOMED↔ICD-10-CM NLM map may be needed to align EHR concepts with claims. Orders and prescriptions may carry local drug codes that require a custom mapping step before RxNorm normalization.
• Registry: Disease-specific registries often use registry-specific codes that require a project-specific crosswalk to standard vocabularies; the GEMs and RxNorm crosswalks do not cover registry-specific coding schemes.
• OMOP-CDM: The ETL handles all source-to-standard mapping through the CONCEPT_RELATIONSHIP "Maps to" table; researchers build concept sets on standard concepts and inherit the crosswalk automatically. The workflow for a transition-spanning study is to verify that the ETL bridged both ICD-9-CM and ICD-10-CM to the same SNOMED CT standard concept and to quantify the concept_id = 0 unmapped fraction on both sides of the transition date.

Decision diagram

flowchart TD
  A[Clinical concept\ne.g. COPD exacerbation] -->|Start here| B[ICD-9-CM code list\npre-Oct 2015]
  A -->|Re-derive natively| C[ICD-10-CM code list\npost-Oct 2015]
  B -->|GEM forward map\napprox flag + 1:many| D[Candidate ICD-10-CM codes\nrequire clinical review]
  D -->|Clinician review\naccept / reject / add| C
  C -->|GEM backward map\ngranularity loss| E[ICD-9-CM round-trip\nNOT equal to B]
  B -->|Study crosses 2015-10-01| F[Transition-spanning analysis]
  C --> F
  F -->|ITS diagnostics at 2015-10-01| G[Cartographic vs biological\ndiscontinuity separated]
  H[NDC on pharmacy claim] -->|RxNorm API\nmonthly snapshot| I[RxNorm RXCUI\ningredient level]
  J[HCPCS J-code on medical claim] -->|CMS ASP crosswalk\nquarterly| K[NDC + drug identity]
  K --> I
  I --> L[Drug exposure defined\nat ingredient level]
  M[OMOP source code\nICD/NDC/CPT] -->|CONCEPT_RELATIONSHIP\nMaps to| N[Standard concept\nSNOMED/RxNorm/LOINC]

Worked example

Scenario

An analyst is building a study on chronic obstructive pulmonary disease (COPD) hospitalizations in US commercial claims. The data span January 2013 through December 2018, which means the cohort crosses the ICD-9-to-ICD-10-CM transition on October 1, 2015. The analyst starts with one representative ICD-9-CM COPD hospitalization code — 491.21 (obstructive chronic bronchitis with acute exacerbation) — and wants to know what the GEM forward map produces and whether applying the backward map would return the starting code.

Dataset

Forward GEM rows for ICD-9-CM 491.21 (obstructive chronic bronchitis with acute exacerbation). Each row is one entry in the CMS FY2018 GEM forward-map file.

FIG. 1 — DESIGN TIMELINE

Steps

Result

Starting from 1 ICD-9-CM code (491.21), the forward GEM produces 2 ICD-10-CM candidate codes (approximate = 1 on both). Backward-mapping J44.1 returns 3 ICD-9-CM codes — 2 more than the original 1. The round trip 1 -> 2 -> 3 demonstrates asymmetry: forward does not equal backward, and neither direction produces cardinality = 1. An analyst who naively counts "codes ever assigned to this condition" across the transition window will see an apparent 2 / 1 = 2.0x code-count multiplication at 2015-10-01 that is entirely cartographic.

Trade-offs

Runnable example

"""
Code Crosswalk Utilities — GEM expansion + ASP NDC-HCPCS join
=============================================================
Applies the CMS FY2018 GEM forward map to an ICD-9-CM code list,
reports one-to-many expansion and approximate flags, then demonstrates
backward-map asymmetry. Includes an ASP NDC-HCPCS J-code resolver.

Input files (public domain, download from CMS GEMs archive and ASP pages):
  gem_forward.tsv  — CMS 2018 ICD-9-CM to ICD-10-CM GEM forward map
  gem_backward.tsv — CMS 2018 ICD-10-CM to ICD-9-CM GEM backward map
  asp_crosswalk.csv — CMS quarterly ASP NDC-HCPCS crosswalk
"""
import pandas as pd
from pathlib import Path


def load_gem(path: str | Path) -> pd.DataFrame:
    """Load a CMS GEM flat file (space-delimited, no header).

    Columns (per CMS format): source_code, target_code,
    approximate, no_map, combination, scenario, choice_list.
    """
    cols = [
        "source_code", "target_code",
        "approximate", "no_map", "combination",
        "scenario", "choice_list",
    ]
    df = pd.read_csv(
        path, sep=r"\s+", header=None, names=cols,
        dtype=str
    )
    # Convert flag columns to int for filtering
    for c in ["approximate", "no_map", "combination", "scenario", "choice_list"]:
        df[c] = pd.to_numeric(df[c], errors="coerce").fillna(0).astype(int)
    return df


def apply_forward_gem(
    code_list: list[str],
    gem_forward: pd.DataFrame,
    include_approximate: bool = True,
) -> pd.DataFrame:
    """Expand an ICD-9-CM code list via the GEM forward map.

    Returns all matching rows, with one_to_many_count added.
    include_approximate=False restricts to exact matches only
    (WARNING: drops the majority of rows — use for triage only).
    """
    df = gem_forward[gem_forward["source_code"].isin(code_list)].copy()
    if not include_approximate:
        df = df[df["approximate"] == 0]

    # Count how many ICD-10 targets each ICD-9 source maps to
    counts = (
        df[df["no_map"] == 0]
        .groupby("source_code")["target_code"]
        .count()
        .rename("one_to_many_count")
    )
    df = df.merge(counts, on="source_code", how="left")

    no_map_codes = df[df["no_map"] == 1]["source_code"].unique()
    if len(no_map_codes):
        print(
            f"WARNING: {len(no_map_codes)} code(s) have no_map=1 "
            f"(no GEM equivalent): {list(no_map_codes)}"
        )
    return df


def check_roundtrip_asymmetry(
    source_codes: list[str],
    gem_forward: pd.DataFrame,
    gem_backward: pd.DataFrame,
) -> dict:
    """Apply forward then backward and report asymmetry.

    Returns dict with original code count, forward count, roundtrip count.
    A round-trip that does NOT return the original set demonstrates asymmetry.
    """
    # Forward: ICD-9 -> ICD-10
    fwd = apply_forward_gem(source_codes, gem_forward)
    icd10_codes = fwd[fwd["no_map"] == 0]["target_code"].unique().tolist()

    # Backward: ICD-10 -> ICD-9
    bwd = gem_backward[gem_backward["source_code"].isin(icd10_codes)]
    icd9_roundtrip = bwd["target_code"].unique().tolist()

    original_set = set(source_codes)
    roundtrip_set = set(icd9_roundtrip)
    added = roundtrip_set - original_set
    lost = original_set - roundtrip_set

    return {
        "original_codes": source_codes,
        "original_count": len(source_codes),
        "icd10_forward_codes": icd10_codes,
        "icd10_forward_count": len(icd10_codes),
        "icd9_roundtrip_codes": icd9_roundtrip,
        "icd9_roundtrip_count": len(icd9_roundtrip),
        "codes_added_by_roundtrip": sorted(added),
        "codes_lost_by_roundtrip": sorted(lost),
        "is_symmetric": original_set == roundtrip_set,
    }


def load_asp_crosswalk(path: str | Path) -> pd.DataFrame:
    """Load the CMS quarterly ASP NDC-HCPCS crosswalk CSV.

    CMS publishes these as CSV/Excel; key columns: HCPCS_CD, NDC, LONG_DESC.
    Adjust column names to match the actual file header.
    """
    df = pd.read_csv(path, dtype=str)
    # Normalize column names to lowercase, strip spaces
    df.columns = [c.strip().lower().replace(" ", "_") for c in df.columns]
    return df


def resolve_jcode_to_ndc(
    claims: pd.DataFrame,
    asp_crosswalk: pd.DataFrame,
    hcpcs_col: str = "hcpcs_cd",
    ndc_col: str = "ndc",
) -> pd.DataFrame:
    """Join ASP crosswalk to medical claims on HCPCS code.

    Recovers drug identity (NDC and long description) for J-codes and NOC codes.
    Returns claims with ndc_from_asp and drug_description columns added.

    Note: multiple NDCs may map to one HCPCS code; the join produces one row per
    NDC match per claim. Deduplicate using claim-level NDC field if available.
    """
    asp_sub = asp_crosswalk[[hcpcs_col, ndc_col, "long_desc"]].rename(
        columns={
            ndc_col: "ndc_from_asp",
            "long_desc": "drug_description_from_asp",
        }
    )
    enriched = claims.merge(asp_sub, on=hcpcs_col, how="left")
    unresolved = enriched["ndc_from_asp"].isna().sum()
    if unresolved:
        print(
            f"INFO: {unresolved} claim rows could not be matched to an NDC "
            f"via the ASP crosswalk (missing HCPCS or new drug not in this quarter)."
        )
    return enriched


# ── Example usage ─────────────────────────────────────────────────────────────
if __name__ == "__main__":
    # Load GEM files (download from CMS GEMs archive)
    # gem_fwd = load_gem("2018_I9gem.txt")
    # gem_bwd = load_gem("2018_I10gem.txt")

    # COPD exacerbation example (see worked_example above)
    copd_icd9 = ["491.21"]

    # Demonstrate forward expansion and asymmetry:
    # result = check_roundtrip_asymmetry(copd_icd9, gem_fwd, gem_bwd)
    # print(result)
    # Expected: original_count=1, icd10_forward_count=2, icd9_roundtrip_count=3
    # is_symmetric=False (round trip 1 -> 2 -> 3, not 1 -> 1 -> 1)

    print("GEM crosswalk utilities loaded. Provide GEM files to run.")

# Code Crosswalk Utilities (R) — GEM + ASP NDC-HCPCS join
# =========================================================
# Applies CMS FY2018 GEM forward map to an ICD-9-CM code list and
# demonstrates backward-map asymmetry. Includes ASP J-code resolver.
#
# Input files (public domain):
#   gem_forward_path — CMS 2018 ICD-9 -> ICD-10-CM GEM (space-delimited, no header)
#   gem_backward_path — CMS 2018 ICD-10-CM -> ICD-9 GEM (space-delimited, no header)
#   asp_crosswalk_path — CMS quarterly ASP NDC-HCPCS crosswalk (CSV)

library(data.table)
library(dplyr)

GEM_COLS <- c("source_code", "target_code",
              "approximate", "no_map", "combination",
              "scenario", "choice_list")

load_gem <- function(path) {
  dt <- fread(path, header = FALSE, col.names = GEM_COLS,
              colClasses = "character")
  flag_cols <- c("approximate", "no_map", "combination", "scenario", "choice_list")
  dt[, (flag_cols) := lapply(.SD, as.integer), .SDcols = flag_cols]
  dt
}

apply_forward_gem <- function(code_list, gem_forward,
                              include_approximate = TRUE) {
  # Expand ICD-9-CM code list via GEM forward map.
  # include_approximate = FALSE restricts to exact matches (WARNING: loses most rows).
  dt <- gem_forward[source_code %in% code_list]
  if (!include_approximate) dt <- dt[approximate == 0]

  # Count how many ICD-10 targets each source maps to (excluding no_map rows)
  counts <- dt[no_map == 0, .(one_to_many_count = .N), by = source_code]
  dt <- merge(dt, counts, by = "source_code", all.x = TRUE)

  no_map_codes <- unique(dt[no_map == 1, source_code])
  if (length(no_map_codes) > 0) {
    warning("no_map=1 (no GEM equivalent): ", paste(no_map_codes, collapse = ", "))
  }
  dt
}

check_roundtrip_asymmetry <- function(source_codes, gem_forward, gem_backward) {
  # Forward: ICD-9 -> ICD-10
  fwd <- apply_forward_gem(source_codes, gem_forward)
  icd10_codes <- unique(fwd[no_map == 0, target_code])

  # Backward: ICD-10 -> ICD-9
  bwd <- gem_backward[source_code %in% icd10_codes]
  icd9_roundtrip <- unique(bwd[, target_code])

  added <- setdiff(icd9_roundtrip, source_codes)
  lost  <- setdiff(source_codes, icd9_roundtrip)

  list(
    original_codes        = source_codes,
    original_count        = length(source_codes),
    icd10_forward_codes   = icd10_codes,
    icd10_forward_count   = length(icd10_codes),
    icd9_roundtrip_codes  = icd9_roundtrip,
    icd9_roundtrip_count  = length(icd9_roundtrip),
    codes_added           = added,
    codes_lost            = lost,
    is_symmetric          = setequal(source_codes, icd9_roundtrip)
  )
}

load_asp_crosswalk <- function(path) {
  dt <- fread(path, colClasses = "character")
  setnames(dt, tolower(gsub(" ", "_", names(dt))))
  dt
}

resolve_jcode_to_ndc <- function(claims_dt, asp_dt,
                                 hcpcs_col = "hcpcs_cd",
                                 ndc_col   = "ndc") {
  # Join ASP crosswalk to medical claims on HCPCS code.
  # Returns claims with ndc_from_asp and drug_description columns added.
  asp_sub <- asp_dt[, .(
    hcpcs_cd        = get(hcpcs_col),
    ndc_from_asp    = get(ndc_col),
    drug_description = long_desc
  )]
  enriched <- merge(claims_dt, asp_sub, by.x = hcpcs_col, by.y = "hcpcs_cd",
                    all.x = TRUE)
  n_unresolved <- sum(is.na(enriched$ndc_from_asp))
  if (n_unresolved > 0)
    message("INFO: ", n_unresolved,
            " claim rows not matched via ASP crosswalk")
  enriched
}

# ── Example usage ──────────────────────────────────────────────────────────────
# gem_fwd <- load_gem("2018_I9gem.txt")
# gem_bwd <- load_gem("2018_I10gem.txt")
#
# copd_icd9 <- "491.21"
# result <- check_roundtrip_asymmetry(copd_icd9, gem_fwd, gem_bwd)
# stopifnot(!result$is_symmetric)  # Asymmetry confirmed: 1 -> 2 -> 3 codes
# cat("Forward count:", result$icd10_forward_count, "\n")
# cat("Roundtrip count:", result$icd9_roundtrip_count, "\n")

Citations

1. [1]Boyd AD, Li JJ, Burton MD, et al. The discriminatory cost of ICD-10-CM transition between clinical specialties: metrics, case study, and mitigating tools. Journal of the American Medical Informatics Association. 2013;20(4):708-717.
2. [2]Slavova S, Costich JF, Luu H, Fields JR. Interrupted time series design to evaluate the effect of the ICD-9-CM to ICD-10-CM coding transition on injury hospitalization trends. Injury Epidemiology. 2018;5(1):34.
3. [3]Liu S, Wei Ma, Moore R. RxNorm: prescription for electronic drug information exchange. IT Professional. 2005;7(5):17-23.

1. [4]Bodenreider O. The Unified Medical Language System (UMLS): integrating biomedical terminology. Nucleic Acids Research. 2004;32(Suppl 1):D267-D270.

1. [5]Centers for Medicare and Medicaid Services. ICD-10-CM and ICD-10-PCS GEM Archive. Baltimore, MD: CMS; FY2018 (last updated). Accessed 2026.
2. [6]National Library of Medicine. Unified Medical Language System (UMLS). Bethesda, MD: NLM. Accessed 2026.
3. [7]Centers for Medicare and Medicaid Services. Medicare Part B Drug Average Sales Price: ASP Pricing Files (NDC-HCPCS Crosswalk). Baltimore, MD: CMS; updated quarterly. Accessed 2026.