Add comprehensive test types and reference types documentation
- Document TEST, PARAM, CALC, and GROUP test type categories - Include usage examples and frontend display guidance - Provide quick reference card for developers - Covers standard lab tests, components, calculations, and panels
This commit is contained in:
parent
46e52b124b
commit
ac0ffb679a
434
docs/test-types-reference.md
Normal file
434
docs/test-types-reference.md
Normal file
@ -0,0 +1,434 @@
|
||||
# 📋 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 │
|
||||
│ TITLE │ Section headers │ "Hematology Results" │
|
||||
└─────────────┴────────────────────────────┴────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. TITLE - Section Header
|
||||
**Icon**: 📌 **Color**: Gray
|
||||
|
||||
Use this for organizing tests into sections on reports.
|
||||
|
||||
**Example**: "Hematology", "Chemistry", "Urinalysis"
|
||||
|
||||
**What to Display**:
|
||||
- Just the title text
|
||||
- No results or values
|
||||
- Used for organization only
|
||||
|
||||
---
|
||||
|
||||
## 📐 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 |
|
||||
| TITLE | `#666666` | `#F5F5F5` | Section headers |
|
||||
|
||||
### Icons
|
||||
|
||||
| Type | Icon | Unicode |
|
||||
|------|------|---------|
|
||||
| TEST | 🧫 | `\u{1F9EB}` |
|
||||
| PARAM | 📊 | `\u{1F4CA}` |
|
||||
| CALC | 🧮 | `\u{1F9EE}` |
|
||||
| GROUP | 📦 | `\u{1F4E6}` |
|
||||
| TITLE | 📌 | `\u{1F4CC}` |
|
||||
|
||||
---
|
||||
|
||||
## 🔌 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, TITLE
|
||||
├── 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
|
||||
- [ ] Show TITLE tests as section headers
|
||||
- [ ] 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`
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user