Purpose

Define user requirements for a standalone FUZKK utility that accepts laboratory CSV data, evaluates the records using limits embedded in code, and produces LabWare-compatible JSON.

Scope

The utility is intended for preliminary QC/QA review, integration testing, LIMS/LabWare flow and evidence-trail preparation. Final release decisions remain under the laboratory's validated procedure and responsible personnel.

Users

QC analyst, QA reviewer, CSV/validation engineer, LIMS/LabWare integration engineer, responsible laboratory specialist.

User requirements

1. The utility shall run without arguments and print its self-description, a built-in input.csv example from GetDemoData(), and demo evaluation for the embedded records.
2. The utility shall run with two arguments: input.csv output.json.
3. The utility shall not read input.csv and shall not write output.json when started without arguments.
4. CSV numeric values shall be parsed using CultureInfo.InvariantCulture.
5. Output shall be generated as LabWare-compatible JSON with Header, Samples, Results, Status, StatusCode, ErrorMessage, Description and DescriptionEN.
6. For PASS records, ErrorMessage shall be an empty string.
7. Embedded limits shall follow this priority: Ph. Eur. → British Pharmacopoeia / UK implementation → EAEU / regional requirements → EMA/ICH/EU guidance → USP fallback.
8. If an exact monograph is not known, strict standard API limits are used where applicable: assay 98–102%, total impurities ≤1.0%, individual impurity ≤0.5%.
9. For biologics and mAb-like products, aggregation, sterility and endotoxin checks shall be included where relevant to the utility purpose.
10. If a parameter may arrive in different units, the unit shall be represented as a separate input field or explicitly reflected in the input.csv field name.

Input CSV

BatchNumber,ProductName,ReferencePatternId,Cosine_Similarity,Correlation_Coefficient,Euclidean_Distance_Normalized,Common_Peaks_Count,Required_Marker_Peaks,Detected_Marker_Peaks,Max_RT_Drift_Min
TCM-FP-2026-001,Panax Notoginseng Extract,REF-PN-001,0.985,0.992,0.05,12,5,5,0.2
TCM-FP-2026-002,Astragalus Root,REF-AR-002,0.960,0.985,0.08,10,4,4,0.3
TCM-FP-2026-003,Ginseng Powder,REF-GP-003,0.850,0.900,0.25,6,5,3,0.8

input.csv fields

Utility description

Herbal Chromatographic Fingerprint Analyzer — Herbal Chromatographic Fingerprint Analyzer

Herbal Chromatographic Fingerprint Analyzer — Herbal Chromatographic Fingerprint Analyzer

ℹ️ Utility evaluates chromatogram similarity with reference pattern:
• Cosine similarity (≥0.95)
• Correlation coefficient (≥0.98)
• Presence of common and marker peaks
• Retention time stability

⚠️ CRITICAL: Fingerprint is the 'passport' of the herb!
Low similarity indicates species substitution or poor quality.

Usage:
HerbalChromatographicFingerprintAnalyzer.exe → demo mode (console output)
HerbalChromatographicFingerprintAnalyzer.exe input.csv output.json → evaluate your data

Input format:
BatchNumber,ProductName,ReferencePatternId,Cosine_Similarity,Correlation_Coefficient,Euclidean_Distance_Normalized,Common_Peaks_Count,Required_Marker_Peaks,Detected_Marker_Peaks,Max_RT_Drift_Min

Example:
TCM-FP-2026-001,Panax Notoginseng Extract,REF-PN-001,0.985,0.992,0.05,12,5,5,0.2

— WHY IS THIS NEEDED?
Chromatographic fingerprint control is critical for TCM and herbal products (Yunnan Baiyao, Tong Ren Tang):
• Herbs contain hundreds of compounds, and one molecule cannot characterize quality
• "Fingerprint" reflects holistic chemical profile
• Allows detection of adulteration (species substitution)
• Controls raw material stability from different geographic zones and harvests
• Required by pharmacopoeias (ChP, USP) for registration of complex herbal products

⚠️ CRITICAL:
• Cosine similarity ≥0.95 — standard for recognizing batch as identical to reference
• Correlation coefficient ≥0.98 — high linear relationship of profiles
• All marker peaks (characteristic for species) must be present
• Retention time drift ≤0.5 min — guarantee of chromatography correctness
• No extra peaks indicating contaminants

Key features:
• Similarity metrics calculation (Cosine, Pearson, Euclidean)
• Specific marker peak presence check
• Chromatographic system stability assessment
• Support for various detection types (DAD, ELSD, MS)

Critical parameters:
• Cosine Similarity: ≥0.95
• Correlation Coefficient: ≥0.98
• Marker peaks: 100% presence
• RT Drift: ≤0.5 min

💡 Usage tips:
1. Use standardized extraction and chromatography conditions
2. Perform baseline alignment before similarity calculation
3. For complex mixtures, use multi-wavelength detection (DAD)
4. Create library of reference fingerprints for each raw material supplier
5. Combine fingerprint analysis with quantitative determination of main markers

⚠️ Note: Unlike synthetic drugs where impurities are regulated individually, in herbs the overall balance of components is important. Change in ratio of even minor peaks may indicate change in growing or harvesting conditions, affecting therapeutic efficacy. The utility helps preserve this integrity.

Traceability and limitations

• The URS is used as the source document for functional specification, CSV review and later validation work.
• This document does not replace an approved pharmacopoeial monograph, validated analytical method or internal product specification.
• For product-specific limits, the approved customer specification takes priority.

The functional specification describes the behaviour of the standalone FUZKK console utility, input-data format, evaluation algorithm and output JSON structure.

Functional flow

1. Main() checks the number of arguments.
2. If no arguments are provided: PrintHello() prints the description and built-in input.csv example, then RunDemoEvaluation() executes Evaluate() over GetDemoData() and prints demo JSON.
3. If two arguments are provided: RunWithFiles(input.csv, output.json) reads CSV, evaluates each record and writes LabWare-compatible JSON.
4. LoadData() uses CultureInfo.InvariantCulture and shall not be called in no-arguments mode.
5. Evaluate() returns a named tuple with BatchNumber, ProductName, Parameters, CriticalFailCount, WarningCount, Recommendation and RecommendationEN.
6. GetIssues() builds messages for ErrorMessage in WARNING/FAIL cases.

Evaluation rules

• PASS: CriticalFailCount = 0 and WarningCount = 0.
• WARNING: CriticalFailCount = 0 and WarningCount > 0.
• FAIL: CriticalFailCount > 0.
• ERROR: exception during reading or processing.
• ErrorMessage remains empty for PASS.
• Limits are embedded in Program.cs; no external limit configuration is required.

Input and fields

BatchNumber,ProductName,ReferencePatternId,Cosine_Similarity,Correlation_Coefficient,Euclidean_Distance_Normalized,Common_Peaks_Count,Required_Marker_Peaks,Detected_Marker_Peaks,Max_RT_Drift_Min
TCM-FP-2026-001,Panax Notoginseng Extract,REF-PN-001,0.985,0.992,0.05,12,5,5,0.2
TCM-FP-2026-002,Astragalus Root,REF-AR-002,0.960,0.985,0.08,10,4,4,0.3
TCM-FP-2026-003,Ginseng Powder,REF-GP-003,0.850,0.900,0.25,6,5,3,0.8

Output JSON

{
  "Header": {
    "UtilityName": "Herbal_Chromatographic_Fingerprint_Analyzer",
    "Version": "1.0.0",
    "Timestamp": "UTC",
    "InstrumentID": "FUZKK-QC-WORKSTATION",
    "OperatorID": "Admin"
  },
  "Samples": [
    {
      "SampleID": "from BatchNumber",
      "BatchNumber": "from CSV",
      "ProductName": "from CSV",
      "TestName": "utility-specific test",
      "AnalysisCode": "utility-specific code",
      "Status": "PASS | WARNING | FAIL | ERROR",
      "StatusCode": "1 | 2 | 0 | -1",
      "ErrorMessage": "",
      "Description": "Russian recommendation",
      "DescriptionEN": "English recommendation",
      "Results": [
        {
          "ParameterName": "parameter",
          "ResultValue": 0.0,
          "UnitOfMeasure": "unit",
          "SpecificationLimit": "limit",
          "IsWithinSpec": true
        }
      ]
    }
  ]
}