HyperpolarizationDecayKineticsMonitor
Hyperpolarization Decay Kinetics Monitor
instrumental Hyperpolarized Xenon RPH Xe-129 medical gases CSV→JSON URS & FS rule-based
Open selectionUtility description: Hyperpolarization Decay Kinetics Monitor
Hyperpolarization Decay Kinetics Monitor — Xe-129 Hyperpolarization Decay Kinetics Monitor
ℹ️ Utility analyzes spin polarization lifetime (T1):
• Measured T1 calculation
• Remaining signal life prediction
• Anomalous decay detection (O2 impurities, bad vials)
⚠️ CRITICAL: Polarization lives for minutes/hours!
If T1 drops faster than normal, image will be unreadable.
Usage:
HyperpolarizationDecayKineticsMonitor.exe → demo mode (console output)
HyperpolarizationDecayKineticsMonitor.exe input.csv output.json → evaluate your data
Input format:
BatchNumber,ProductName,Initial_Pol_Percent,Start_Time_H,Current_Pol_Percent,Elapsed_Time_H,O2_ppm,Wall_Factor,Min_Acceptable_Pol,Expected_T1_H
Example:
XE-T1-2026-001,HP-Xe-129,40.0,0.0,25.0,1.5,10.0,0.95,5.0,2.5
— WHY IS THIS NEEDED?
Decay kinetics control is critical for HP-MRI logistics:
• Hyperpolarized Xe-129 is not eternal; it returns to thermal equilibrium
• This process time is characterized by T1 constant (Spin-Lattice Relaxation Time)
• T1 strongly depends on paramagnetic impurities (oxygen) and vial wall quality
• If T1 is too short, gas "dies" before reaching patient's lungs
• Utility allows predicting if signal will be sufficient for scanning in 30-60 minutes
⚠️ CRITICAL:
• Measured T1 must match theoretical for given mixture (±20%)
• Oxygen presence >50 ppm drastically reduces T1
• Poor anti-relaxation vial coating accelerates decay
• Remaining lifetime must be sufficient for transport and administration
Key features:
• Exponential approximation of decay curve
• "Remaining shelf life" of polarization calculation in minutes
• Rapid decay cause diagnostics (O2 vs Walls)
• Support for various isotopic mixtures
Critical parameters:
• Measured T1: ≥80% of Expected T1
• Current Polarization: ≥5% (approximate detection threshold)
• Remaining Life: ≥15 min
💡 Usage tips:
1. Measure polarization immediately after exiting spinner (t=0) and before patient administration
2. Use data to calibrate gas delivery models
3. If low T1 observed, check vial seal and gas purity
4. Store vials in magnetic field (even weak) to extend T1
5. Account for temperature: heating accelerates relaxation
⚠️ Note: Unlike standard drugs where shelf life is measured in years, here it is measured in hours. The utility turns physical parameter T1 into a practical tool for medical study planning.input.csv
BatchNumber,ProductName,Initial_Pol_Percent,Start_Time_H,Current_Pol_Percent,Elapsed_Time_H,O2_ppm,Wall_Factor,Min_Acceptable_Pol,Expected_T1_H XE-T1-2026-001,HP-Xe-129 (Good Vial),40.0,0.0,25.0,1.5,10.0,0.95,5.0,2.5 XE-T1-2026-002,HP-Xe-129 (Bad Coating),40.0,0.0,10.0,1.5,10.0,0.5,5.0,2.5 XE-T1-2026-003,HP-Xe-129 (O2 Leak),40.0,0.0,15.0,1.0,500.0,0.95,5.0,2.5
URS & FS — user requirements and functional specification
URS & FS — User Requirements and Functional Specification
This document defines the controlled interface and behaviour of HyperpolarizationDecayKineticsMonitor for “Hyperpolarization Decay Kinetics Monitor”. Limits from the source description are an initial configuration and shall be reconciled with the approved specification, study protocol, equipment instructions and local SOPs before production use.
Domain constraints and critical parameters
- Measured T1: ≥80% of Expected T1
- Current Polarization: ≥5% (approximate detection threshold)
- Remaining Life: ≥15 min
URS — User Requirements Specification
| ID | Requirement | Criticality | Acceptance criterion |
|---|---|---|---|
| URS-001 | The utility shall accept input.csv with the exact headers defined by the data contract. | High | The file is processed without manual header renaming. |
| URS-002 | The utility shall perform a deterministic assessment for “Hyperpolarization Decay Kinetics Monitor”. | High | PASS / WARNING / FAIL is produced for each row. |
| URS-003 | Required fields, types, ranges, units and data consistency shall be validated before domain rules. | High | Schema errors are separated from nonconformities. |
| URS-004 | Critical limits from the description and approved local configuration shall create a critical finding. | High | A critical rule violation results in FAIL. |
| URS-005 | The result shall be written to machine-readable output.json. | High | JSON contains source values, checks, warnings and failures. |
| URS-006 | The conformity decision shall not use machine learning. | Medium | The result is reproducible from explicit rules and inputs. |
| URS-007 | Traceability of batch, source file, rule version and final status shall be retained. | High | QA/QC can reproduce the decision. |
| URS-008 | The utility shall have exactly one primary portal tag: instrumental. | Medium | The other api / instrumental / medical_devices tags are absent. |
| URS-009 | Documentation shall support IQ/OQ/PQ or equivalent CSA/CSV verification. | Medium | The contract, test scenarios and change-control rules are supplied with the utility. |
input.csv data contract
| # | Field | Type | Unit | Sample | Purpose |
|---|---|---|---|---|---|
| 1 | BatchNumber | string | as specified | XE-T1-2026-001 | Batch/lot identifier for traceability. |
| 2 | ProductName | string | as specified | HP-Xe-129 (Good Vial) | Name of the controlled product, gas, procedure or equipment. |
| 3 | Initial_Pol_Percent | decimal | % | 40.0 | Xe-129 hyperpolarization level, loss or target parameter. |
| 4 | Start_Time_H | decimal | h | 0.0 | Time parameter for processing, relaxation, pumping or examination. |
| 5 | Current_Pol_Percent | decimal | % | 25.0 | Xe-129 hyperpolarization level, loss or target parameter. |
| 6 | Elapsed_Time_H | decimal | h | 1.5 | Time parameter for processing, relaxation, pumping or examination. |
| 7 | O2_ppm | decimal | ppm | 10.0 | Oxygen concentration or flow; a breathing-mixture safety and/or polarization-retention parameter. |
| 8 | Wall_Factor | decimal | as specified | 0.95 | Controlled input.csv field: Wall Factor. |
| 9 | Min_Acceptable_Pol | decimal | as specified | 5.0 | Xe-129 hyperpolarization level, loss or target parameter. |
| 10 | Expected_T1_H | decimal | h | 2.5 | Longitudinal relaxation time or its target/predicted value. |
BatchNumber,ProductName,Initial_Pol_Percent,Start_Time_H,Current_Pol_Percent,Elapsed_Time_H,O2_ppm,Wall_Factor,Min_Acceptable_Pol,Expected_T1_H XE-T1-2026-001,HP-Xe-129 (Good Vial),40.0,0.0,25.0,1.5,10.0,0.95,5.0,2.5 XE-T1-2026-002,HP-Xe-129 (Bad Coating),40.0,0.0,10.0,1.5,10.0,0.5,5.0,2.5 XE-T1-2026-003,HP-Xe-129 (O2 Leak),40.0,0.0,15.0,1.0,500.0,0.95,5.0,2.5
FS — Functional Specification
| ID | Function | Implementation |
|---|---|---|
| FS-001 | CLI execution | HyperpolarizationDecayKineticsMonitor.exe supports demo mode and input.csv output.json mode. |
| FS-002 | CSV import | Read UTF-8 CSV and validate header, column count and order. |
| FS-003 | Schema validation | Validate required values, empties, types and basic plausibility. |
| FS-004 | Domain rule engine | Apply explicit rules for “Hyperpolarization Decay Kinetics Monitor” and locally approved limits. |
| FS-005 | Status aggregation | FAIL for a critical finding; WARNING for a non-critical deviation; PASS for conformity. |
| FS-006 | JSON export | Write source values, applied rules, statuses, warnings, failures and configuration version. |
| FS-007 | Audit support | Retain a result structure suitable for review, investigation, IQ/OQ and change control. |
| FS-008 | Integration contract | LIMS/ELN/MES or an instrument wrapper creates CSV; the utility returns JSON. |
output.json example
{
"utilityId": "hyperpolarization-decay-kinetics-monitor",
"primaryTag": "instrumental",
"overallStatus": "PASS|WARNING|FAIL",
"sourceFile": "input.csv",
"checks": [
{
"parameter": "BatchNumber",
"value": "XE-T1-2026-001",
"status": "PASS|WARNING|FAIL",
"message": "Rule-based check result"
},
{
"parameter": "ProductName",
"value": "HP-Xe-129 (Good Vial)",
"status": "PASS|WARNING|FAIL",
"message": "Rule-based check result"
},
{
"parameter": "Initial_Pol_Percent",
"value": "40.0",
"status": "PASS|WARNING|FAIL",
"message": "Rule-based check result"
},
{
"parameter": "Start_Time_H",
"value": "0.0",
"status": "PASS|WARNING|FAIL",
"message": "Rule-based check result"
},
{
"parameter": "Current_Pol_Percent",
"value": "25.0",
"status": "PASS|WARNING|FAIL",
"message": "Rule-based check result"
},
{
"parameter": "Elapsed_Time_H",
"value": "1.5",
"status": "PASS|WARNING|FAIL",
"message": "Rule-based check result"
},
{
"parameter": "O2_ppm",
"value": "10.0",
"status": "PASS|WARNING|FAIL",
"message": "Rule-based check result"
},
{
"parameter": "Wall_Factor",
"value": "0.95",
"status": "PASS|WARNING|FAIL",
"message": "Rule-based check result"
}
],
"warnings": [],
"criticalFindings": []
}
OQ/PQ test scenarios
| ID | Scenario | Expected result |
|---|---|---|
| OQ-001 | Valid example row | PASS or an allowed WARNING under local rules. |
| OQ-002 | Required column missing | Schema error; domain checks do not mask it. |
| OQ-003 | Non-numeric value in numeric field | Type-conversion error. |
| OQ-004 | Critical parameter outside its limit | FAIL and a critical finding. |
| OQ-005 | Boundary value | The result follows the configured ≤ / ≥ / < / > operator. |
| PQ-001 | Real site data | Agreed QA/QC review retaining CSV, JSON, version and checksum. |
QA/QC and change control
- Do not change column names without updating the validator, documentation and test set.
- Retain input.csv, output.json, executable version, rule version and checksums.
- Before production use, verify local limits and execute IQ/OQ/PQ or equivalent CSA.
- Changes affecting patient safety, dosimetry, gas composition, polarization or equipment require documented impact assessment.
Included in packages
Rph Hyperpolarized Xenon Lifecycle QC Suite
29 utilities for the hyperpolarized xenon lifecycle: isotope composition and gas purity, SEOP and polarization, T1/storage/transport, safe blending and delivery, MRI/SPECT QC, dosimetry, scavenging, recovery and recycling.
OpenRPH isotope family: xenon and gas tracers
Xe-127, Xe-129 and Xe-133 for ventilation, hyperpolarized imaging, gas QC and safety.
OpenRPH organ/system: hepatobiliary and GI
HIDA, mebrofenin, gallbladder, gastric emptying, GI transit, bleeding and liver/spleen imaging.
OpenRPH organ/system: pulmonary and ventilation
Lung perfusion, MAA, V/Q, aerosol, xenon ventilation, shunt and pulmonary dosimetry.
OpenRPH use case: xenon, ventilation and medical gases
Xe-129, Xe-133, Xe-127, hyperpolarization, SEOP, T1, mixing, scavenging, transport, recovery and ventilation imaging.
OpenRPH workflow: dosimetry and therapy planning
Activity planning, absorbed dose, organ dose, lung shunt, preplanning and therapy verification.
OpenRPH workflow: imaging QC and quantitative interpretation
Acquisition, uptake, clearance, perfusion, transit, ejection fraction, segmentation and quantitative imaging.
OpenRPH workflow: product release QC
Assay, purity, sterility, endotoxins, pH, impurities, appearance and batch-release checks.
OpenRPH workflow: stability, storage, decay and waste
Kinetic stability, shelf life, decay correction, expiry, storage, trend and radioactive waste.
Open