URS & FS — User Requirements and Functional Specification
This document defines the controlled interface, validation behaviour and expected output of NIR_Blend_Uniformity_Checker. The document is intended to reside inside the utility folder together with input.csv and the description file. Expected executable: NIR_Blend_Uniformity_Checker.exe.
Purpose: the utility performs deterministic verification of QC input data against approved limits, generates machine-readable output.json, and supports QC/QA review, LIMS/ELN/MES integration and CSV/CSA preparation.
Scope
| Utility class | IR spectroscopy / InfraLUM |
| Main object/method | Assessment of Blend Homogeneity via Near-Infrared Spectroscopy |
| Input | input.csv with a fixed header and controlled data types. |
| Output | output.json with PASS, WARNING, FAIL statuses, detailed checks and critical findings. |
| Exclusions | The utility does not replace the approved specification, analytical procedure, OOS/OOT investigation or Qualified Person / QA release decision. |
Domain limits and critical parameters
Key fragments from the source description are listed below. Before production use, limits shall be verified against the approved specification, registration dossier, current pharmacopoeial edition and local SOPs.
- • Mean API Content: 95.0–105.0%
- • Relative Standard Deviation (RSD): ≤5.0%
- • Maximum single point deviation: ≤10.0%
- • Minimum number of scans/samples: ≥30
- ⚠️ CRITICAL: RSD >5.0% → blend is non-homogeneous! Risk of segregation during tableting.
- NIR_Blend_Uniformity_Checker.exe input.csv output.json → evaluate your data
- BatchNumber,MeanContentPercent,StdDevPercent,NumberOfScans,MaxDeviationPercent,RSD_Percent
- • NIR allows in-line or at-line analysis without sampling (non-destructive).
- • Scanning multiple points (mapping) provides a statistically significant picture of API distribution.
- • Early detection of non-uniformity prevents scrapping the entire tablet batch.
- • Compliance with ASTM E2709 / ASTM E2810 and USP <1033>.
- ⚠️ CRITICAL:
- • RSD ≤5.0% — generally accepted criterion for good homogeneity in dry blends.
- • Mean content must match formulation (Target 100%).
- • Maximum Deviation (Max Dev) shows the worst point in the blender. If high, local segregation exists.
- • Number of scans (N) ≥30 is necessary for representativeness across the blender volume.
Pharmacopoeial and regulatory references found in the description
| # | Source | Note |
|---|
| 1 | USP <1033> | Used as a source/context reference from the description; the current edition must be verified before implementation. |
Production data flow
| Step | Responsible object | Description | Control |
| 1 | LIMS/ELN/MES or QC analyst | Creates input.csv with measured values and batch identifier. | Header, mandatory-field and unit checks. |
| 2 | NIR_Blend_Uniformity_Checker | Loads CSV, converts data types, applies domain rules and produces the result. | Deterministic rules; no ML/probabilistic conformance decision. |
| 3 | QC reviewer / QA | Reviews output.json, warnings, critical deviations and source values. | Review, deviation investigation and data-trail retention. |
| 4 | Archive / eQMS | Retains input, output, utility version, documentation and checksum. | Data integrity: ALCOA+, reproducibility and change control. |
URS — User Requirements Specification
| ID | Requirement | Criticality | Acceptance criterion |
| URS-001 | The utility shall be supplied with NIR_Blend_Uniformity_Checker.documentation.html in the same folder as the description and sample input.csv. | Medium | The documentation file exists in the NIR_Blend_Uniformity_Checker folder and opens locally in a browser. |
| URS-002 | The utility shall accept input.csv with the exact headers defined in the data contract. | High | A CSV file with the correct header is processed without manual editing. |
| URS-003 | The utility shall validate mandatory fields, column count, data types and basic plausibility of values. | High | Schema and conversion errors are explicitly reported. |
| URS-004 | The utility shall evaluate each critical and non-critical QC parameter against approved limits. | High | Each checked parameter receives a status and explanatory message. |
| URS-005 | The utility shall produce a final record/batch status: PASS, WARNING or FAIL. | High | A critical deviation causes FAIL; a non-critical deviation causes WARNING. |
| URS-006 | The utility shall generate output.json suitable for LIMS/ELN/MES integration and QA/QC review. | High | JSON contains source values, rules, statuses, warnings and critical findings. |
| URS-007 | The utility shall preserve traceability between batch identifier, input values, applied rules and final status. | High | The output contains the batch/row identifier and list of checked parameters. |
| URS-008 | The utility shall not use machine learning or probabilistic interpretation for conformance decisions. | Medium | The result is reproducible and based on explicit rules, thresholds and input values. |
| URS-009 | The utility shall support the CLI scenario: NIR_Blend_Uniformity_Checker.exe input.csv output.json. | High | With valid arguments, output.json is created; on error, a diagnostic message is returned. |
| URS-010 | The documentation shall support IQ/OQ/PQ or equivalent CSV/CSA verification. | Medium | The document contains URS, FS, CSV contract, rules, test scenarios and traceability. |
| URS-011 | The utility shall distinguish data errors, method warnings and critical specification failures. | High | output.json provides separate structures/fields for errors, warnings and critical findings. |
| URS-012 | The utility shall support archival retention of unchanged input and output data. | Medium | input.csv and output.json can be retained as a batch record or OQ/PQ evidence. |
input.csv contract
| # | Field | Type | Sample | Purpose |
| 1 | BatchNumber | string | BLEND-NIR-2026-001 | Batch or lot identifier used for traceability. |
| 2 | Mean% | decimal | 100.2 | Controlled input parameter used by the deterministic QC rules. |
| 3 | StdDev | decimal | 1.5 | Controlled input parameter used by the deterministic QC rules. |
| 4 | N | decimal | 60 | Controlled input parameter used by the deterministic QC rules. |
| 5 | MaxDev | decimal | 4.5 | Controlled input parameter used by the deterministic QC rules. |
| 6 | RSD% | decimal | 1.5 | Precision/repeatability parameter. |
BatchNumber,Mean%,StdDev,N,MaxDev,RSD%
BLEND-NIR-2026-001,100.2,1.5,60,4.5,1.5
BLEND-NIR-2026-002,99.8,2.1,45,6.2,2.1
BLEND-FAIL-2026-003,101.0,6.5,30,18.0,6.5
Input validation rules
| ID | Field | Type | Check | Criticality |
| VR-001 | BatchNumber | string | not empty; unique within file where applicable | Medium |
| VR-002 | Mean% | decimal | parse as invariant decimal; finite value; no NaN/Infinity; evaluate against approved numerical limit | Medium |
| VR-003 | StdDev | decimal | parse as invariant decimal; finite value; no NaN/Infinity; evaluate against approved numerical limit | Medium |
| VR-004 | N | decimal | parse as invariant decimal; finite value; no NaN/Infinity; evaluate against approved numerical limit | Medium |
| VR-005 | MaxDev | decimal | parse as invariant decimal; finite value; no NaN/Infinity; evaluate against approved numerical limit | Medium |
| VR-006 | RSD% | decimal | parse as invariant decimal; finite value; no NaN/Infinity; evaluate against approved numerical limit | Medium |
FS — Functional Specification
| ID | Function | Implementation | URS link |
| FS-001 | Local HTML documentation | Provide a bilingual NIR_Blend_Uniformity_Checker.documentation.html file with RU/EN switch, source description, URS, FS, contracts and tests. | URS-001, URS-010 |
| FS-002 | CSV import | Read input.csv in UTF-8/CSV-compatible format and identify the header row and data records. | URS-002, URS-009 |
| FS-003 | Schema validation | Compare actual columns against the expected contract; missing key fields are recorded as schema errors. | URS-002, URS-003 |
| FS-004 | Type conversion | Convert decimal, flag/boolean and controlled string values. Invalid values are recorded at row and field level. | URS-003 |
| FS-005 | Domain rule engine | Apply rules for NIR Blend Uniformity Checker, including critical limits from the description and approved specification. | URS-004, URS-008 |
| FS-006 | Status aggregation | Aggregate parameter statuses: FAIL for critical failure, WARNING for non-critical deviation, PASS for conformance. | URS-005, URS-011 |
| FS-007 | JSON export | Write output.json with utility identifier, source values, check results, warnings and critical findings. | URS-006, URS-007 |
| FS-008 | Error handling | Separate execution errors, schema errors, conversion errors and domain-limit failures. | URS-003, URS-011 |
| FS-009 | Audit support | Keep result structure suitable for review, OOS/OOT investigation, calculation reproduction and inspection discussion. | URS-007, URS-012 |
| FS-010 | Integration contract | Support the standard scenario: LIMS/ELN/MES creates input.csv, the utility returns output.json, and the portal displays description and documentation. | URS-006, URS-009 |
| FS-011 | Configuration/change control | Any change to limits, column names or rule logic requires versioning, review, regression tests and documentation update. | URS-010, URS-012 |
| FS-012 | Data integrity | Do not modify the source input.csv; save results separately in output.json for archival retention. | URS-007, URS-012 |
Example output.json structure
{
"utilityId": "nir-blend-uniformity-checker",
"utilityName": "NIR_Blend_Uniformity_Checker",
"object": "NIR Blend Uniformity Checker",
"overallStatus": "PASS|WARNING|FAIL",
"sourceFile": "input.csv",
"recordCount": 3,
"checks": [
{
"parameter": "BatchNumber",
"value": "BLEND-NIR-2026-001",
"status": "PASS|WARNING|FAIL",
"message": "Rule-based check result",
"ruleReference": "VR-001"
},
{
"parameter": "Mean%",
"value": "100.2",
"status": "PASS|WARNING|FAIL",
"message": "Rule-based check result",
"ruleReference": "VR-002"
},
{
"parameter": "StdDev",
"value": "1.5",
"status": "PASS|WARNING|FAIL",
"message": "Rule-based check result",
"ruleReference": "VR-003"
},
{
"parameter": "N",
"value": "60",
"status": "PASS|WARNING|FAIL",
"message": "Rule-based check result",
"ruleReference": "VR-004"
},
{
"parameter": "MaxDev",
"value": "4.5",
"status": "PASS|WARNING|FAIL",
"message": "Rule-based check result",
"ruleReference": "VR-005"
},
{
"parameter": "RSD%",
"value": "1.5",
"status": "PASS|WARNING|FAIL",
"message": "Rule-based check result",
"ruleReference": "VR-006"
}
],
"criticalFindings": [],
"warnings": [],
"metadata": {
"executionMode": "CLI",
"interface": "CSV to JSON",
"documentationFile": "NIR_Blend_Uniformity_Checker.documentation.html"
}
}
Traceability matrix URS → FS → OQ/PQ
| URS | FS | Verification | Expected result |
| URS-001 | FS-001 | Check that NIR_Blend_Uniformity_Checker.documentation.html exists in the utility folder. | The file exists, opens, and the RU/EN switch works. |
| URS-002/003 | FS-002/003/004 | Run the utility with a correct CSV, a CSV missing a mandatory column and a CSV with an invalid data type. | Correct CSV is processed; schema and type errors are explicit. |
| URS-004/005 | FS-005/006 | Submit values within limits, at warning level and beyond a critical limit. | PASS, WARNING and FAIL are produced according to rules. |
| URS-006/007 | FS-007/009/012 | Verify output.json structure and batch traceability. | JSON contains batch identifier, values, rules, statuses and critical findings. |
| URS-008 | FS-005 | Repeat execution with the same input.csv. | The result is identical; no probabilistic behaviour is present. |
| URS-009/010/012 | FS-010/011/012 | Execute the CLI scenario and archive input/output/version. | Artefacts are suitable for OQ/PQ and change-control records. |
OQ/PQ test scenarios
| ID | Scenario | Input data | Expected result |
| OQ-001 | Positive path | Sample CSV with valid values. | output.json is created; final status is PASS or acceptable WARNING according to rules. |
| OQ-002 | Mandatory column missing | Remove one key column from the header. | Schema error; the row shall not be treated as passed. |
| OQ-003 | Invalid type | Put text into a numeric field. | Type-conversion error with field and row identification. |
| OQ-004 | Critical limit | Critical parameter value outside the approved limit. | FAIL and an entry in criticalFindings. |
| OQ-005 | Warning | Non-critical deviation or unknown controlled category. | WARNING without hiding the source value. |
| PQ-001 | User real batch | Real input.csv from the QC process. | Reviewed result with input.csv, output.json, version and checksum retained. |
QA/QC, CSV/CSA and change control
- Do not rename columns without updating the validator, test set and documentation.
- Retain
input.csv, output.json, executable version, checksum and a copy of the documentation.
- Before production use, perform IQ/OQ/PQ or equivalent risk-based CSV/CSA verification.
- Critical limits shall be approved by the process owner and verified against the registration dossier, pharmacopoeia and local SOPs.
- Any change to rules, thresholds or status interpretation shall go through change control and regression testing.