clqms-fe1/docs/test-types-reference.md

📋 Test Types & Reference Types Guide

Quick Overview: This guide helps you understand the different types of tests and how to display them in the frontend.

---

🎯 What Are Test Types?

Think of test types as "categories" that determine how a test behaves and what information it needs.

Quick Reference Card

┌─────────────┬────────────────────────────┬────────────────────────┐
│ Type        │ Use This For...            │ Example                │
├─────────────┼────────────────────────────┼────────────────────────┤
│ TEST        │ Standard lab tests         │ Blood Glucose, CBC     │
│ PARAM       │ Components of a test       │ WBC count (in CBC)     │
│ CALC        │ Formula-based results      │ BMI, eGFR              │
│ GROUP       │ Panels/batteries           │ Lipid Panel, CMP       │
└─────────────┴────────────────────────────┴────────────────────────┘

---

🧪 Detailed Test Types

1. TEST - Standard Laboratory Test

Icon: 🧫 Color: Blue

Use this for regular tests that have:

• Reference ranges (normal values)
• Units (mg/dL, mmol/L, etc.)
• Collection requirements

Example: Blood Glucose, Hemoglobin, Cholesterol

What to Display:

• Test code and name
• Reference range
• Units
• Collection instructions
• Expected turnaround time

---

2. PARAM - Parameter

Icon: 📊 Color: Light Blue

Use this for individual components within a larger test.

Example:

• Complete Blood Count (GROUP) contains:
  • WBC (PARAM)
  • RBC (PARAM)
  • Hemoglobin (PARAM)

What to Display:

• Same as TEST, but shown indented under parent
• Often part of a GROUP

---

3. CALC - Calculated Test

Icon: 🧮 Color: Purple

Use this for tests computed from other test results using formulas.

Example:

• BMI (calculated from height & weight)
• eGFR (calculated from creatinine, age, etc.)

What to Display:

• Formula description
• Input parameters (which tests feed into this)
• Result value
• Reference range (if applicable)

Special Fields:

• FormulaInput - What values go in?
• FormulaCode - How is it calculated?

---

4. GROUP - Group Test (Panel/Battery)

Icon: 📦 Color: Green

Use this to bundle multiple related tests together.

Example:

• Lipid Panel (GROUP) contains:
  • Total Cholesterol (PARAM)
  • HDL (PARAM)
  • LDL (PARAM)
  • Triglycerides (PARAM)

What to Display:

• Group name
• List of member tests
• Individual results for each member

Structure:

📦 Lipid Panel (GROUP)
   ├── Total Cholesterol (PARAM): 180 mg/dL
   ├── HDL (PARAM): 55 mg/dL
   ├── LDL (PARAM): 110 mg/dL
   └── Triglycerides (PARAM): 150 mg/dL

---

📐 Reference Types Explained

Reference types tell you how to interpret the results - what "normal" looks like.

Choose Your Reference Type:

                    ┌──────────────────────┐
                    │   Reference Type?    │
                    └──────────┬───────────┘
                               │
           ┌───────────────────┼───────────────────┐
           │                   │                   │
      Numbers?             Text values?        Threshold?
           │                   │                   │
    ┌──────▼──────┐     ┌──────▼──────┐     ┌──────▼──────┐
    │    NMRC     │     │    TEXT     │     │    THOLD    │
    │   (Numeric) │     │    (Text)   │     │ (Threshold) │
    └──────┬──────┘     └──────┬──────┘     └──────┬──────┘
           │                   │                   │
    ┌──────▼──────┐     ┌──────▼──────┐     ┌──────▼──────┐
    │   RANGE     │     │    Free     │     │  Positive/  │
    │ (Min-Max)   │     │    Text     │     │  Negative   │
    │   OR        │     │     OR      │     │   OR        │
    │  THOLD      │     │   VSET      │     │  < > =      │
    │ (Threshold) │     │ (Dropdown)  │     │  cutoff     │
    └─────────────┘     └─────────────┘     └─────────────┘

Reference Type Details

Type	Visual	Example
NMRC - Numeric Range	70 - 100 mg/dL	Blood glucose: 70-100 mg/dL
TEXT - Text Value	"Normal" or "Positive"	Urinalysis: "Clear", "Cloudy"
THOLD - Threshold	> 60 or < 5.5	eGFR: > 60 (normal)
VSET - Value Set	Dropdown options	Organism: [E.coli, Staph, etc.]

---

🎨 Frontend Display Patterns

Pattern 1: Test List View

// When showing a list of tests
function renderTestCard(test) {
  const typeIcon = getIcon(test.TestType);
  const typeColor = getColor(test.TestType);
  
  return `
    <div class="test-card ${typeColor}">
      <span class="icon">${typeIcon}</span>
      <h3>${test.TestSiteName}</h3>
      <span class="badge">${test.TestTypeLabel}</span>
      <code>${test.TestSiteCode}</code>
    </div>
  `;
}

Pattern 2: Reference Range Display

// Show reference range based on type
function renderReferenceRange(test) {
  switch(test.RefType) {
    case 'NMRC':
      return `${test.MinValue} - ${test.MaxValue} ${test.Unit}`;
    
    case 'TEXT':
      return test.ReferenceText || 'See report';
    
    case 'THOLD':
      return `${test.ThresholdOperator} ${test.ThresholdValue}`;
    
    case 'VSET':
      return 'Select from list';
  }
}

Pattern 3: Group Test Expansion

// Expandable group test
function renderGroupTest(test) {
  return `
    <div class="group-test">
      <button onclick="toggleGroup(${test.TestSiteID})">
        📦 ${test.TestSiteName} (${test.testdefgrp.length} tests)
      </button>
      <div class="members" id="group-${test.TestSiteID}">
        ${test.testdefgrp.map(member => renderTestRow(member)).join('')}
      </div>
    </div>
  `;
}

---

🗂️ Data Structure Visualization

Test Hierarchy

┌─────────────────────────────────────────────────────────┐
│                    TEST DEFINITION                       │
├─────────────────────────────────────────────────────────┤
│  TestSiteID: 12345                                       │
│  TestSiteCode: GLUC                                     │
│  TestSiteName: Glucose                                   │
│  TestType: TEST                                          │
├─────────────────────────────────────────────────────────┤
│  📎 Additional Info (loaded based on TestType):         │
│                                                          │
│  ┌──────────────────────────────────────────────┐       │
│  │   TestDefTech (for TEST/PARAM)                │       │
│  │   - DisciplineID, DepartmentID                │       │
│  │   - ResultType, RefType                       │       │
│  │   - Unit, Method, ExpectedTAT                 │       │
│  └──────────────────────────────────────────────┘       │
│                                                          │
│  ┌──────────────────────────────────────────────┐       │
│  │   TestDefCal (for CALC)                       │       │
│  │   - FormulaInput, FormulaCode               │       │
│  │   - RefType, Unit, Decimal                  │       │
│  └──────────────────────────────────────────────┘       │
│                                                          │
│  ┌──────────────────────────────────────────────┐       │
│  │   TestDefGrp (for GROUP)                      │       │
│  │   - Array of member tests                    │       │
│  └──────────────────────────────────────────────┘       │
│                                                          │
│  ┌──────────────────────────────────────────────┐       │
│  │   TestMap (for ALL types)                     │       │
│  │   - Mapping to external systems              │       │
│  └──────────────────────────────────────────────┘       │
└─────────────────────────────────────────────────────────┘

---

💡 Common Scenarios

Scenario 1: Creating a Simple Test

Need: Add "Hemoglobin" test Choose: TEST type with NMRC reference

const hemoglobin = {
  TestSiteCode: 'HGB',
  TestSiteName: 'Hemoglobin',
  TestType: 'TEST',
  testdeftech: {
    RefType: 'NMRC',
    Unit: 'g/dL',
    // Reference range: 12-16 g/dL
  }
};

Scenario 2: Creating a Panel

Need: "Complete Blood Count" with multiple components Choose: GROUP type with PARAM children

const cbc = {
  TestSiteCode: 'CBC',
  TestSiteName: 'Complete Blood Count',
  TestType: 'GROUP',
  testdefgrp: [
    { TestSiteCode: 'WBC', TestType: 'PARAM' },
    { TestSiteCode: 'RBC', TestType: 'PARAM' },
    { TestSiteCode: 'HGB', TestType: 'PARAM' },
    { TestSiteCode: 'PLT', TestType: 'PARAM' }
  ]
};

Scenario 3: Calculated Result

Need: BMI from height and weight Choose: CALC type with formula

const bmi = {
  TestSiteCode: 'BMI',
  TestSiteName: 'Body Mass Index',
  TestType: 'CALC',
  testdefcal: {
    FormulaInput: 'HEIGHT,WEIGHT',
    FormulaCode: 'WEIGHT / ((HEIGHT/100) * (HEIGHT/100))',
    RefType: 'NMRC',
    Unit: 'kg/m²'
  }
};

---

🎨 Visual Style Guide

Color Coding

Type	Primary Color	Background	Usage
TEST	#0066CC	#E6F2FF	Main test cards
PARAM	#3399FF	#F0F8FF	Component rows
CALC	#9933CC	#F5E6FF	Calculated fields
GROUP	#00AA44	#E6F9EE	Expandable panels

Icons

Type	Icon	Unicode
TEST	🧫	\u{1F9EB}
PARAM	📊	\u{1F4CA}
CALC	🧮	\u{1F9EE}
GROUP	📦	\u{1F4E6}

---

🔌 Quick API Reference

Fetch Tests

// Get all tests for a site
GET /api/tests?siteId=123

// Get specific test type
GET /api/tests?testType=GROUP

// Search tests
GET /api/tests?search=glucose

// Get single test with details
GET /api/tests/12345

Value Set Helpers

// Get human-readable labels
const labels = {
  testType: valueSet.getLabel('test_type', test.TestType),
  refType: valueSet.getLabel('reference_type', test.RefType),
  resultType: valueSet.getLabel('result_type', test.ResultType)
};

// Get dropdown options
const testTypes = valueSet.get('test_type');
// Returns: [{value: "TEST", label: "Test"}, ...]

---

📚 Value Set File Locations

app/Libraries/Data/
├── test_type.json          # TEST, PARAM, CALC, GROUP
├── reference_type.json     # NMRC, TEXT, THOLD, VSET
├── result_type.json        # NMRIC, RANGE, TEXT, VSET
├── numeric_ref_type.json   # RANGE, THOLD
└── text_ref_type.json      # VSET, TEXT

---

✅ Checklist for Frontend Developers

• Show correct icon for each test type

• Display reference ranges based on RefType

• Handle GROUP tests as expandable panels

• Display CALC formulas when available

• Use ValueSet labels for all coded fields

• Respect VisibleScr/VisibleRpt flags

• Handle soft-deleted tests (EndDate check)

---

🆘 Need Help?

Q: When do I use PARAM vs TEST? A: Use PARAM for sub-components of a GROUP. Use TEST for standalone tests.

Q: What's the difference between NMRC and THOLD? A: NMRC shows a range (70-100). THOLD shows a threshold (> 60 or < 5.5).

Q: Can a GROUP contain other GROUPs? A: Yes! Groups can be nested (though typically only 1-2 levels deep).

Q: How do I know which details to fetch? A: Check TestType first, then look for the corresponding property:

• TEST/PARAM → testdeftech
• CALC → testdefcal
• GROUP → testdefgrp
• All types → testmap