Terminal
Terminal/Skill
Guidance on choosing and mapping clinical terminologies such as MedDRA, ICD-10, SNOMED CT, and LOINC for adverse event coding and grouping.
By Amazon Web Services
Works with
npx skills add awslabs/hcls-agent-skills --skill clinical-data-standardsThis skill teaches the agent how to reason about clinical terminology systems — MedDRA, ICD-10, SNOMED CT, and LOINC — and the decisions involved in coding, grouping, and mapping clinical data. It does not generate pipeline code; it provides the domain knowledge needed to make correct coding and aggregation choices before any analysis begins.
Getting terminology wrong has direct consequences: miscoded adverse events hide safety signals, wrong ICD-10 granularity inflates or deflates prevalence estimates, and incorrect LOINC assignments break lab result interoperability. This skill encodes the rules, hierarchies, and decision frameworks that prevent those errors.
Invoke this skill when the user:
The agent should respond by:
MedDRA (Medical Dictionary for Regulatory Activities) is the standard for coding adverse events, medical history, and indications in clinical trials and pharmacovigilance.
| Level | Abbreviation | Count (~v26) | Purpose |
|---|---|---|---|
| System Organ Class | SOC | ~27 | Broadest grouping (e.g., "Cardiac disorders") |
| High Level Group Term | HLGT | ~337 | Groups related HLTs within a SOC |
| High Level Term | HLT | ~1,740 | Groups related PTs by anatomy/mechanism |
| Preferred Term | PT | ~24,000 | Standard reportable term — the workhorse |
| Lowest Level Term | LLT | ~83,000 | Verbatim-level synonyms mapping to one PT |
Verbatim AE text (from CRF)
│
▼
LLT (closest match to verbatim)
│
▼
PT (standard reportable term — one LLT maps to exactly one PT)
│
▼
HLT → HLGT → SOC (for grouping and display)
Rules:
| Scenario | Recommended level | Rationale |
|---|---|---|
| Standard AE frequency table (CSR) | PT within SOC | Regulatory expectation (ICH E3) |
| Signal detection across rare events | HLT or HLGT | Individual PTs too sparse; grouping reveals patterns |
| Standardized MedDRA Queries (SMQs) | SMQ (pre-defined) | Curated term groups for known safety topics (e.g., "Hepatic disorders") |
| High-level safety overview | SOC | Executive summary, not for detailed analysis |
Start
│
├── Is this a standard CSR AE table?
│ └── Code at LLT → report at PT within primary SOC.
│
├── Are you looking for a safety signal across related terms?
│ ├── Does an SMQ exist for the topic?
│ │ └── Yes → Use the SMQ (narrow or broad scope as appropriate).
│ └── No SMQ → Aggregate at HLT. Document the grouping rationale.
│
├── Are individual PTs too rare to detect a signal?
│ └── Consider HLT or HLGT grouping, but report both grouped
│ and individual PT counts for transparency.
│
└── Executive safety summary only?
└── SOC-level counts are acceptable, with PT detail available on request.
ICD-10 (International Classification of Diseases, 10th Revision) is the standard for diagnosis coding in claims, EHR, and epidemiological studies.
Chapter (I–XXII)
└── Block (e.g., E10–E14: Diabetes mellitus)
└── Category — 3 characters (e.g., E11: Type 2 diabetes)
└── Subcategory — 4–7 characters (e.g., E11.6: With complications)
└── Extension (e.g., E11.65: With hyperglycemia)
| Level | Example | Granularity |
|---|---|---|
| Chapter | Chapter IV: Endocrine diseases | Too broad for most analyses |
| Block | E10–E14 | Disease family grouping |
| 3-character category | E11 | Disease entity (Type 2 DM) |
| 4-character subcategory | E11.6 | Complication type |
| Full code | E11.65 | Specific manifestation |
The choice of granularity depends on the analysis goal:
| Analysis type | Recommended level | Example |
|---|---|---|
| Population prevalence study | 3-character category | E11 (all Type 2 DM) |
| Comorbidity index (Charlson, Elixhauser) | 3-character or block | Pre-defined code lists per condition |
| Specific outcome study | Full code (4–7 char) | E11.65 (hyperglycemia specifically) |
| Claims-based cohort definition | 3-character + exclusions | E11.* excluding E11.0 (with coma) |
| Cross-country comparison | Block level | ICD-10 blocks are more stable across national modifications |
Start
│
├── Are you estimating disease prevalence or incidence?
│ └── 3-character category. Captures all subtypes.
│ Add block-level grouping if comparing across disease families.
│
├── Are you defining a specific clinical outcome?
│ └── Full code (4+ characters). Be explicit about which
│ manifestations qualify. Document inclusion/exclusion codes.
│
├── Are you building a comorbidity score?
│ └── Use the published code lists (Charlson/Elixhauser).
│ Do not invent your own groupings.
│
├── Are you comparing across countries or ICD-10 modifications?
│ └── Block level. National modifications (ICD-10-CM, ICD-10-GM)
│ diverge at the subcategory level.
│
└── Are you mapping from another system (MedDRA, SNOMED CT)?
└── Map to 3-character first, then refine to subcategory
only if the source system provides sufficient specificity.
SNOMED CT (Systematized Nomenclature of Medicine — Clinical Terms) is the most comprehensive clinical terminology, used for clinical findings, procedures, substances, body structures, and organisms.
| Relationship | Meaning | Example |
|---|---|---|
| IS-A | Subsumption hierarchy | "Acute myocardial infarction" IS-A "Myocardial infarction" |
| Finding site | Where the finding is located | "Pneumonia" → finding site → "Lung structure" |
| Causative agent | What causes the condition | "Aspirin-induced asthma" → causative agent → "Aspirin" |
| Associated morphology | Structural change | "Adenocarcinoma of lung" → morphology → "Adenocarcinoma" |
| Method | How a procedure is performed | "Laparoscopic cholecystectomy" → method → "Laparoscopic approach" |
| Use case | Preferred system | Rationale |
|---|---|---|
| Clinical documentation in EHR | SNOMED CT | Rich concept model, supports clinical detail |
| Billing and claims | ICD-10 | Required by payers |
| Adverse event reporting | MedDRA | Regulatory requirement |
| Lab test ordering/results | LOINC | Standard for lab interoperability |
| Drug coding | RxNorm (US) / SNOMED CT | RxNorm for prescribing; SNOMED CT for substances |
LOINC (Logical Observation Identifiers Names and Codes) is the standard for identifying laboratory tests and clinical observations.
Every LOINC code is defined by six axes:
| Axis | Description | Example (Glucose, fasting, serum) |
|---|---|---|
| Component | What is measured | Glucose |
| Property | Type of measurement | MCnc (mass concentration) |
| Timing | Point vs over time | Pt (point in time) |
| System | Specimen type | Ser/Plas (serum or plasma) |
| Scale | Quantitative, ordinal, etc. | Qn (quantitative) |
| Method | How measured (optional) | — |
LOINC panels group related tests ordered together:
| Panel | LOINC code | Contains |
|---|---|---|
| CBC with differential | 57021-8 | WBC, RBC, Hgb, Hct, MCV, MCH, MCHC, Plt, differential |
| Basic Metabolic Panel | 51990-0 | Glucose, BUN, Creatinine, Na, K, Cl, CO2, Ca |
| Comprehensive Metabolic Panel | 24323-8 | BMP + albumin, bilirubin, ALP, ALT, AST, total protein |
| Lipid Panel | 24331-1 | Total cholesterol, HDL, LDL (calc), triglycerides |
| Hepatic Function Panel | 24325-3 | Albumin, bilirubin (total/direct), ALP, ALT, AST, total protein |
Mapping between terminology systems is necessary but error-prone. Follow these rules:
| Scenario | Approach |
|---|---|
| AE term to diagnosis code | Map PT → ICD-10 3-character category. Refine to subcategory only if the PT provides sufficient specificity. |
| Medical history coding | Map at PT level; ICD-10 subcategory when the verbatim text supports it. |
| Concomitant conditions | Use the official MedDRA-to-ICD crosswalk where available. |
Rules:
Start
│
├── Source is verbatim AE text?
│ └── Code to MedDRA (LLT → PT). Map to ICD-10 only if
│ the downstream system requires it.
│
├── Source is EHR diagnosis (free text or local code)?
│ ├── US system → Map to ICD-10-CM (billing) and SNOMED CT (clinical).
│ └── Non-US → Map to ICD-10-WHO or national modification.
│
├── Source is lab result?
│ └── Map to LOINC. Match all six axes. Use panel codes for orders.
│
├── Need to cross-walk between MedDRA and SNOMED CT?
│ └── Go through ICD-10 as an intermediary (MedDRA → ICD-10 → SNOMED CT)
│ or use UMLS concept mappings. Direct MedDRA ↔ SNOMED CT maps
│ are not officially maintained.
│
└── Building a research dataset combining claims + EHR + trial data?
└── Define a canonical code system for each data element.
Map all sources to the canonical. Document every mapping
decision and version. Accept that some mappings are lossy.
| Standard | Required system | Context |
|---|---|---|
| ICH E2B(R3) | MedDRA | Individual Case Safety Reports (ICSRs) |
| ICH E3 | MedDRA | Clinical Study Reports — AE tables at PT within SOC |
| US claims (CMS) | ICD-10-CM, CPT, HCPCS | Billing and reimbursement |
| US EHR (ONC) | SNOMED CT, LOINC, RxNorm | Meaningful Use / Promoting Interoperability |
| CDISC SDTM | MedDRA (AE domain), dictionaries per domain | Clinical trial data submission to FDA |
| OMOP CDM | SNOMED CT (conditions), LOINC (measurements), RxNorm (drugs) | Observational research |
Wrong: Coding adverse events directly to PT, skipping the LLT layer Right: Always code verbatim text to LLT first, then let the hierarchy derive the PT Why: The LLT layer captures synonyms and spelling variants — skipping it risks inconsistent coding when different verbatim texts describe the same concept
Wrong: Using secondary SOC for AE frequency tables Right: Always use the primary SOC for frequency tables unless the protocol explicitly specifies otherwise Why: Multi-axial PTs appear under multiple SOCs — mixing primary and secondary inflates apparent AE counts and confuses signal detection
Wrong: Aggregating at HLT level without documenting justification Right: Only aggregate above PT when individual terms are too sparse for signal detection; always show both grouped and ungrouped PT counts Why: HLT grouping hides individual PT signals that may represent distinct safety concerns
Wrong: Applying ICD-10-CM codes in a non-US context Right: Specify which ICD-10 modification you are using; use ICD-10-WHO or the appropriate national modification for non-US data Why: ICD-10-CM extensions (laterality, encounter type) do not exist in ICD-10-WHO — codes may be invalid or misinterpreted
Wrong: Grouping ICD-10 at 3-character level for specific outcome studies Right: Use full codes (4+ characters) when the outcome is a specific manifestation; document inclusion/exclusion codes explicitly Why: E11 includes all Type 2 DM complications — if the outcome is "Type 2 DM with hyperglycemia," only E11.65 is correct
Wrong: Reversing the SNOMED CT → ICD-10 map to create an ICD-10 → SNOMED CT crosswalk Right: Use a dedicated reverse crosswalk or UMLS CUI-based mappings; never invert the forward map Why: The forward map is many-to-one — reversing it creates ambiguous one-to-many mappings without the map rules to resolve them
Wrong: Matching LOINC codes by component name alone Right: Verify all six LOINC axes (component, property, timing, system, scale, method) match the local test definition Why: Two LOINC codes can share the same component but differ in system (serum vs urine), property, or scale — partial matching produces wrong assignments
Wrong: Using deprecated LOINC codes without checking status Right: Always check the LOINC STATUS field and replace deprecated codes with their active successors Why: Deprecated codes break interoperability and may not be recognized by receiving systems
Wrong: Creating ad hoc terminology crosswalks instead of using official maps Right: Use curated maps from SNOMED International, NLM, or MSSO; document the map version used Why: Ad hoc mappings introduce inconsistencies, are not reproducible, and diverge from regulatory expectations
Wrong: Ignoring MedDRA version differences when combining data across studies Right: Document the MedDRA version used for each study; reconcile terms that were added, merged, or deprecated across versions Why: PTs are added, merged, and deprecated across versions — a term valid in v25 may be deprecated in v26, causing data loss or miscounting
Wrong: Confusing LOINC panel codes with component codes when storing results Right: Use the panel code for the order and individual component LOINC codes for each result within the panel Why: Storing a glucose result under the CBC panel code is semantically wrong and breaks downstream aggregation and interoperability
Wrong: Mapping MedDRA directly to SNOMED CT without an intermediary Right: Use ICD-10 as an intermediary (MedDRA → ICD-10 → SNOMED CT) or use UMLS CUI-based mappings; document the mapping path Why: No official direct MedDRA ↔ SNOMED CT crosswalk exists — direct mapping produces unvalidated, irreproducible results