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

```javascript
// 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

```javascript
// 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

```javascript
// 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

```javascript
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

```javascript
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

```javascript
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

```javascript
// 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

```javascript
// 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`