TcmDnaBarcodingAuthenticityQualityChecker
Tcm Dna Barcoding Authenticity
ℹ️ Утилита выполняет ДНК-идентификацию согласно ChP General Chapter 9107, USP <561>, WHO Guidelines on Quality Control of Herbal Materials и стандартам CBOL Plant Working Group:
КАЧЕСТВО ДНК И ПЦР:
• DNA Concentration ≥ 10 ng/µL: Достаточность матрицы для амплификации.
• A260/A280 Ratio 1.7–2.1: Чистота ДНК от белков и РНК.
• Mean Phred Score ≥ 30: Качество секвенирования (Q30 = 99.9% точность чтения оснований).
• Sequence Length: Соответствие ожидаемой длине баркода (ITS2 ~400–500 bp, rbcL ~550 bp, matK ~800 bp, psbA-trnH ~300–450 bp).
• PCR Amplification Success: ⛔ Неудача ПЦР = невозможность идентификации; требуется повторная экстракция или mini-barcode.
BLAST-ИДЕНТИФИКАЦИЯ:
• Identity ≥ 98%: Порог подтверждения вида для ITS2 (для rbcL/matK может быть ≥97%).
• Query Coverage ≥ 90%: Полнота выравнивания запроса с референсной последовательностью.
• E-value ≤ 1e-50: Статистическая значимость совпадения; исключает случайные хиты.
• Species Match: Совпадение топ-хита с заявленным латинским названием.
• ⚠ Mismatch = возможная подмена вида (например, Stephania tetrandra → Aristolochia fangchi).
BARCODE GAP ANALYSIS:
• K2P Intraspecific Distance ≤ 0.01: Генетическое расстояние внутри вида (конспецифичные референсы).
• K2P Nearest Neighbor ≥ 0.02: Расстояние до ближайшего гетероспецифичного вида.
• Barcode Gap Present: Intra < Inter — обязательное условие надежной дискриминации видов.
• Отсутствие barcode gap = маркер не обладает достаточной разрешающей способностью для данного таксона; требуется альтернативный маркер.
ДЕТЕКЦИЯ СМЕСЕЙ ВИДОВ (NGS МЕТАБАКОДИРОВАНИЕ):
• Mixed Species Detected: Наличие нескольких таксонов в одном образце.
• Secondary Species Read %: Доля прочтений, принадлежащих вторичному виду.
• Contamination Threshold ≥ 5%: Порог объявления о фальсификации/контаминации.
• Trace levels (<5%) документируются как предупреждение, но не являются основанием для отказа партии.
• Species Count: Общее число детектированных видов в образце.
КАЧЕСТВО РЕФЕРЕНСНОЙ БАЗЫ ДАННЫХ:
• Reference Sequences Available ≥ 3: Минимальное число референсов для статистической надежности идентификации.
• Voucher Specimen Confirmed: Привязка референсной последовательности к гербарному ваучерному образцу — золотой стандарт таксономической достоверности.
• База без ваучеров = риск ошибочной таксономии в референсе и ложной идентификации.
• Поддерживаемые базы: GenBank, BOLD, TCM-ID, внутренние курируемые библиотеки.
⚠️ ВАЖНО:
• ITS2 — основной баркод для ТКМ согласно ChP 9107; rbcL и matK — вспомогательные маркеры.
• Для переработанного сырья (экстракты, порошки, гранулы) используйте короткие маркеры (mini-barcodes <200 bp).
• Подмена Fang_Ji (Stephania tetrandra) на Guang_Fang_Ji (Aristolochia fangchi) детектируется однозначно по ITS2.
• NGS-метабакодирование выявляет многокомпонентные смеси и микроконтаминации, которые пропускает секвенирование по Сэнгеру.
• Отсутствие barcode gap требует переключения на альтернативный маркер; принудительная идентификация без gap недопустима.
• Референсная база должна быть курируемой; GenBank содержит до 10% ошибочно идентифицированных записей.
• ДНК деградирует в обработанном сырье; отрицательный результат ПЦР ≠ отсутствие целевого вида (возможна деградация).
• Всегда включайте no-template control (NTC) для детекции лабораторной контаминации.
Использование:
TcmDnaBarcodingAuthenticityQualityChecker.exe → демо-режим (вывод в консоль)
TcmDnaBarcodingAuthenticityQualityChecker.exe input.csv output.json → оценка ваших данных
📍 Область применения:
• Входной контроль сырья ТКМ: Верификация видовой принадлежности при приемке.
• Расследование подмен: Молекулярное подтверждение фальсификации (особенно для токсичных подмен).
• Экспортный контроль: Соответствие требованиям импортеров (EU/US/Japan/Korea).
• Фармакопейный контроль: Выполнение требований ChP General Chapter 9107.
• Биобанкинг и эталонные коллекции: Верификация аутентичности референсных образцов.
• Научные исследования: Таксономическая верификация собранных образцов.
💡 Советы:
1. Multi-Marker Strategy: Используйте комбинацию ITS2 + psbA-trnH для сложных таксонов (Panax, Lycium, Angelica).
2. Curated Internal Database: Создайте внутреннюю базу с ваучерными образцами для критических и высокорисковых видов.
3. Negative Controls: Всегда включайте NTC и extraction blank для детекции контаминации реагентов и лаборатории.
4. Degraded DNA Protocol: Для экстрактов и старых образцов заранее подготовьте праймеры на mini-barcodes (<200 bp).
5. Threshold Validation: Валидируйте пороги идентичности и K2P дистанций отдельно для каждого маркера и таксона.
6. Regular DB Updates: Обновляйте референсную базу ежеквартально; таксономия растений активно пересматривается.
⚠️ Примечание: Утилита оценивает МОЛЕКУЛЯРНУЮ ПОДЛИННОСТЬ ВИДА. Она не заменяет химический анализ (маркерные соединения, fingerprinting) или токсикологический скрининг (аристолохиевые кислоты, ПА, тяжелые металлы). Статус SPECIES_CONFIRMED подтверждает видовую принадлежность, но не гарантирует качество, безопасность или эффективность сырья. CLOSE_MATCH требует дополнительного анализа (второй маркер, морфология, химия). MIXED_SPECIES указывает на фальсификацию, контаминацию или ошибку сбора; партия должна быть карантинизирована до выяснения причин.
input.csv
SampleID,DeclaredHerbName,DeclaredLatinName,PartUsed,BarcodeMarker,SequencingMethod,SequenceLength_bp,ExpectedMinLength_bp,ExpectedMaxLength_bp,MeanPhredScore,MinAcceptablePhredScore,DnaConcentration_ng_uL,MinDnaConcentration_ng_uL,A260_A280_Ratio,PcrAmplification_Success,TopHit_Species,TopHit_Accession,Identity_Percent,MinIdentityForConfirmation_Percent,QueryCoverage_Percent,MinQueryCoverage_Percent,E_Value,MaxE_Value,TotalHits_AboveThreshold,K2P_Distance_Intraspecific,K2P_Distance_NearestNeighbor,MaxIntraspecific_K2P,MinInterspecific_K2P,BarcodeGap_Present,MixedSpecies_Detected,SpeciesCount_Detected,DominantSpecies_ReadPercent,SecondarySpecies_ReadPercent,SecondarySpecies_Name,ContaminationThreshold_Percent,ReferenceDatabase,DatabaseVersion,ReferenceSequences_Available,VoucherSpecimen_Confirmed TCM-DNA-2026-001,Ren_Shen,Panax_ginseng,Root,ITS2,Sanger,462,400,500,38.5,30,45.0,10,1.85,true,Panax_ginseng,JX967890,99.8,98,100,90,1e-180,1e-50,12,0.002,0.035,0.01,0.02,true,false,1,100,0,,5.0,TCM_ID,v3.2,45,true TCM-DNA-2026-002,Fang_Ji,Stephania_tetrandra,Root,ITS2,Sanger,448,400,500,35.2,30,22.0,10,1.92,true,Aristolochia_fangchi,KF234567,99.5,98,99,90,1e-175,1e-50,8,0.001,0.042,0.01,0.02,true,false,1,100,0,,5.0,GenBank,2026.05,28,true TCM-DNA-2026-003,Gou_Qi_Zi,Lycium_barbarum,Fruit,psbA_trnH,NGS_Metabarcoding,380,300,450,32.0,30,15.0,10,1.78,true,Lycium_barbarum,MH123456,99.2,98,98,90,1e-150,1e-50,15,0.003,0.018,0.01,0.02,true,true,3,82.5,12.3,Lycium_chinense,5.0,BOLD,2026.04,32,true
TcmDnaBarcodingAuthenticityQualityChecker — URS & FS
TCM DNA Barcoding Authenticity Quality Checker
TCM DNA Barcoding Authenticity Quality Checker
1. Назначение документа
Документ описывает пользовательские требования (URS) и функциональную спецификацию (FS) для утилиты TcmDnaBarcodingAuthenticityQualityChecker. Утилита предназначена для детерминированной проверки данных input.csv, формирования структурированного результата output.json и поддержки прослеживаемого QA/QC review.
Документ является проектной URS/FS-основой для CSV/CSA, IQ/OQ/PQ и дальнейшей валидации в контексте конкретной лабораторной процедуры.
2. Исходное описание утилиты
3. URS — пользовательские требования
3.1 Цель и область применения
Система должна принимать табличные результаты лабораторного контроля, выполнять проверку по заранее заданным критериям и возвращать понятный статус по каждой серии/записи: Pass, Review или Fail.
3.2 Нормативная / методическая база
В исходном описании и правилах утилиты используются следующие ориентиры: ChP, USP, EP, WHO, CBOL. Финальные лимиты должны быть подтверждены утверждённой спецификацией, монографией, SOP или протоколом трансфера метода.
3.3 Ключевые QC-проверки
- DNA Concentration ≥ 10 ng/µL: Достаточность матрицы для амплификации.
- A260/A280 Ratio 1.7–2.1: Чистота ДНК от белков и РНК.
- Mean Phred Score ≥ 30: Качество секвенирования (Q30 = 99.9% точность чтения оснований).
- Sequence Length: Соответствие ожидаемой длине баркода (ITS2 ~400–500 bp, rbcL ~550 bp, matK ~800 bp, psbA-trnH ~300–450 bp).
- PCR Amplification Success: ⛔ Неудача ПЦР = невозможность идентификации; требуется повторная экстракция или mini-barcode.
- Identity ≥ 98%: Порог подтверждения вида для ITS2 (для rbcL/matK может быть ≥97%).
- Query Coverage ≥ 90%: Полнота выравнивания запроса с референсной последовательностью.
- E-value ≤ 1e-50: Статистическая значимость совпадения; исключает случайные хиты.
3.4 Пользователи
- QC analyst — подготовка и загрузка
input.csv. - QA/QC reviewer — проверка результата и отклонений.
- CSV/validation specialist — подтверждение пригодности утилиты.
- System owner — управление версией, доступом и изменениями.
3.5 Требования к данным и Data Integrity
- каждая строка CSV должна быть прослеживаемой к серии, образцу или измерению;
- исходные значения не должны изменяться утилитой;
- расчёты должны быть воспроизводимыми при повторном запуске;
- любое отклонение должно сохраняться как структурированное finding с указанием поля и правила;
- ручное изменение итогового статуса вне QA-процесса не допускается.
4. FS — функциональная спецификация
4.1 Поток обработки
- Проверить наличие и кодировку
input.csv. - Проверить заголовки, обязательные поля и типы данных.
- Нормализовать числовые и булевы значения без изменения исходного следа.
- Выбрать набор правил по категории продукта/типа, если он предусмотрен.
- Сравнить значения с лимитами и вычислить derived metrics.
- Сформировать запись результата по каждой строке.
- Сохранить
output.jsonс общей сводкой, findings и traceability.
4.2 CSV-схема
| № | Поле CSV | Тип | Обяз. | Назначение |
|---|---|---|---|---|
| 1 | SampleID | string | Да | Входной атрибут для детерминированной оценки правил и прослеживаемости результата. |
| 2 | DeclaredHerbName | string | Да | Идентичность продукта, препарата или образца. |
| 3 | DeclaredLatinName | string | Да | Идентичность продукта, препарата или образца. |
| 4 | PartUsed | string | Да | Входной атрибут для детерминированной оценки правил и прослеживаемости результата. |
| 5 | BarcodeMarker | string | Да | Входной атрибут для детерминированной оценки правил и прослеживаемости результата. |
| 6 | SequencingMethod | string | Да | Метаданные аналитического метода или условий анализа. |
| 7 | SequenceLength_bp | integer | Да | Входной атрибут для детерминированной оценки правил и прослеживаемости результата. |
| 8 | ExpectedMinLength_bp | integer | Да | Входной атрибут для детерминированной оценки правил и прослеживаемости результата. |
| 9 | ExpectedMaxLength_bp | integer | Да | Входной атрибут для детерминированной оценки правил и прослеживаемости результата. |
| 10 | MeanPhredScore | decimal | Да | Показатель pH для контроля качества и совместимости матрицы. |
| 11 | MinAcceptablePhredScore | integer | Да | Показатель pH для контроля качества и совместимости матрицы. |
| 12 | DnaConcentration_ng_uL | decimal | Да | Измеренный аналитический результат для сравнения с критерием приемлемости. |
| 13 | MinDnaConcentration_ng_uL | integer | Да | Измеренный аналитический результат для сравнения с критерием приемлемости. |
| 14 | A260_A280_Ratio | decimal | Да | Измеренный аналитический результат для сравнения с критерием приемлемости. |
| 15 | PcrAmplification_Success | boolean | Да | Входной атрибут для детерминированной оценки правил и прослеживаемости результата. |
| 16 | TopHit_Species | string | Да | Показатель pH для контроля качества и совместимости матрицы. |
| 17 | TopHit_Accession | string | Да | Показатель pH для контроля качества и совместимости матрицы. |
| 18 | Identity_Percent | decimal | Да | Измеренный аналитический результат для сравнения с критерием приемлемости. |
| 19 | MinIdentityForConfirmation_Percent | integer | Да | Измеренный аналитический результат для сравнения с критерием приемлемости. |
| 20 | QueryCoverage_Percent | integer | Да | Измеренный аналитический результат для сравнения с критерием приемлемости. |
| 21 | MinQueryCoverage_Percent | integer | Да | Измеренный аналитический результат для сравнения с критерием приемлемости. |
| 22 | E_Value | decimal | Да | Измеренный аналитический результат для сравнения с критерием приемлемости. |
| 23 | MaxE_Value | decimal | Да | Измеренный аналитический результат для сравнения с критерием приемлемости. |
| 24 | TotalHits_AboveThreshold | integer | Да | Входной атрибут для детерминированной оценки правил и прослеживаемости результата. |
| 25 | K2P_Distance_Intraspecific | decimal | Да | Входной атрибут для детерминированной оценки правил и прослеживаемости результата. |
| 26 | K2P_Distance_NearestNeighbor | decimal | Да | Входной атрибут для детерминированной оценки правил и прослеживаемости результата. |
| 27 | MaxIntraspecific_K2P | decimal | Да | Входной атрибут для детерминированной оценки правил и прослеживаемости результата. |
| 28 | MinInterspecific_K2P | decimal | Да | Входной атрибут для детерминированной оценки правил и прослеживаемости результата. |
| 29 | BarcodeGap_Present | boolean | Да | Бинарный признак обнаружения для правил нулевой толерантности или предупреждений. |
| 30 | MixedSpecies_Detected | boolean | Да | Бинарный признак обнаружения для правил нулевой толерантности или предупреждений. |
| 31 | SpeciesCount_Detected | integer | Да | Бинарный признак обнаружения для правил нулевой толерантности или предупреждений. |
| 32 | DominantSpecies_ReadPercent | decimal | Да | Измеренный аналитический результат для сравнения с критерием приемлемости. |
| 33 | SecondarySpecies_ReadPercent | decimal | Да | Измеренный аналитический результат для сравнения с критерием приемлемости. |
| 34 | SecondarySpecies_Name | string | Да | Идентичность продукта, препарата или образца. |
| 35 | ContaminationThreshold_Percent | decimal | Да | Измеренный аналитический результат для сравнения с критерием приемлемости. |
| 36 | ReferenceDatabase | string | Да | Входной атрибут для детерминированной оценки правил и прослеживаемости результата. |
| 37 | DatabaseVersion | string | Да | Входной атрибут для детерминированной оценки правил и прослеживаемости результата. |
| 38 | ReferenceSequences_Available | integer | Да | Входной атрибут для детерминированной оценки правил и прослеживаемости результата. |
| 39 | VoucherSpecimen_Confirmed | boolean | Да | Входной атрибут для детерминированной оценки правил и прослеживаемости результата. |
4.3 Пример входных данных
| SampleID | DeclaredHerbName | DeclaredLatinName | PartUsed | BarcodeMarker | SequencingMethod | SequenceLength_bp | ExpectedMinLength_bp | ExpectedMaxLength_bp | MeanPhredScore | MinAcceptablePhredScore | DnaConcentration_ng_uL | MinDnaConcentration_ng_uL | A260_A280_Ratio | PcrAmplification_Success | TopHit_Species | TopHit_Accession | Identity_Percent | MinIdentityForConfirmation_Percent | QueryCoverage_Percent | MinQueryCoverage_Percent | E_Value | MaxE_Value | TotalHits_AboveThreshold | K2P_Distance_Intraspecific | K2P_Distance_NearestNeighbor | MaxIntraspecific_K2P | MinInterspecific_K2P | BarcodeGap_Present | MixedSpecies_Detected | SpeciesCount_Detected | DominantSpecies_ReadPercent | SecondarySpecies_ReadPercent | SecondarySpecies_Name | ContaminationThreshold_Percent | ReferenceDatabase | DatabaseVersion | ReferenceSequences_Available | VoucherSpecimen_Confirmed |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| TCM-DNA-2026-001 | Ren_Shen | Panax_ginseng | Root | ITS2 | Sanger | 462 | 400 | 500 | 38.5 | 30 | 45.0 | 10 | 1.85 | true | Panax_ginseng | JX967890 | 99.8 | 98 | 100 | 90 | 1e-180 | 1e-50 | 12 | 0.002 | 0.035 | 0.01 | 0.02 | true | false | 1 | 100 | 0 | 5.0 | TCM_ID | v3.2 | 45 | true | |
| TCM-DNA-2026-002 | Fang_Ji | Stephania_tetrandra | Root | ITS2 | Sanger | 448 | 400 | 500 | 35.2 | 30 | 22.0 | 10 | 1.92 | true | Aristolochia_fangchi | KF234567 | 99.5 | 98 | 99 | 90 | 1e-175 | 1e-50 | 8 | 0.001 | 0.042 | 0.01 | 0.02 | true | false | 1 | 100 | 0 | 5.0 | GenBank | 2026.05 | 28 | true | |
| TCM-DNA-2026-003 | Gou_Qi_Zi | Lycium_barbarum | Fruit | psbA_trnH | NGS_Metabarcoding | 380 | 300 | 450 | 32.0 | 30 | 15.0 | 10 | 1.78 | true | Lycium_barbarum | MH123456 | 99.2 | 98 | 98 | 90 | 1e-150 | 1e-50 | 15 | 0.003 | 0.018 | 0.01 | 0.02 | true | true | 3 | 82.5 | 12.3 | Lycium_chinense | 5.0 | BOLD | 2026.04 | 32 | true |
4.4 Выходной JSON
{
"utility": "TcmDnaBarcodingAuthenticityQualityChecker",
"runId": "urn:fuzkk:run:example",
"sourceFile": "input.csv",
"recordsProcessed": 3,
"overallStatus": "Pass / Review / Fail",
"records": [
{
"recordId": "TCM-DNA-2026-001",
"status": "Pass / Review / Fail",
"criticalFindings": [],
"warnings": [],
"evaluatedRules": [
"Configured acceptance criteria from the utility rule set"
],
"inputTrace": {
"SampleID": "TCM-DNA-2026-001",
"DeclaredHerbName": "Ren_Shen",
"DeclaredLatinName": "Panax_ginseng",
"PartUsed": "Root",
"BarcodeMarker": "ITS2",
"SequencingMethod": "Sanger",
"SequenceLength_bp": "462",
"ExpectedMinLength_bp": "400"
}
}
],
"dataIntegrity": {
"deterministicEvaluation": true,
"sourceRowTraceability": true,
"manualOverrideAllowed": false
}
}
5. Трассировка URS → FS → тесты
| URS | FS-механизм | Проверка |
|---|---|---|
| Загрузка корректного input.csv | CSV parser + schema validator | OQ: валидный/невалидный CSV |
| Детерминированная оценка лимитов | Rule engine с фиксированной конфигурацией | OQ: граничные значения и known expected results |
| Статусы Pass/Review/Fail | Status aggregator по findings | OQ/PQ: образцы с проходными и провальными сериями |
| Прослеживаемость к исходной строке | inputTrace + recordId | PQ: сверка output.json с исходным CSV |
| Поддержка QA review | структурированные findings и warnings | PQ: review сценарии и deviation handling |
6. CSV/CSA и валидационный подход
IQ
- проверка версии утилиты;
- проверка расположения исполняемого файла;
- проверка шаблона CSV;
- контроль прав доступа.
OQ
- проверка обязательных полей;
- проверка типов данных;
- проверка граничных значений;
- проверка zero-tolerance правил.
PQ
- прогоны на реальных/репрезентативных данных;
- сверка с ручным расчётом;
- подтверждение QA review workflow.
Change control
- версионирование лимитов;
- impact assessment при изменении правил;
- регрессия после обновления.
1. Document purpose
This document defines user requirements (URS) and functional specification (FS) for TcmDnaBarcodingAuthenticityQualityChecker. The utility is intended to evaluate input.csv data deterministically, generate structured output.json output and support traceable QA/QC review.
This document is a project-level URS/FS baseline for CSV/CSA, IQ/OQ/PQ and further validation under an approved laboratory procedure.
2. Source utility description
3. URS — user requirements
3.1 Intended use and scope
The system shall accept tabular laboratory QC results, evaluate them against configured acceptance criteria and return a clear status for each batch or record: Pass, Review or Fail.
3.2 Regulatory / methodological basis
The source description and utility rules refer to the following framework: ChP, USP, EP, WHO, CBOL. Final acceptance limits shall be confirmed by the approved specification, pharmacopoeial monograph, SOP or method-transfer protocol.
3.3 Key QC checks
- TCM raw material incoming inspection: Species verification upon receipt.
- Adulteration investigations: Molecular confirmation of substitution (especially toxic substitutions).
- Export control: Compliance with importer requirements (EU/US/Japan/Korea).
- Pharmacopoeial compliance: Fulfillment of ChP General Chapter 9107 requirements.
- Biobanking and reference collections: Authentication of voucher specimens.
- Research: Taxonomic verification of field-collected samples.
3.4 Users
- QC analyst — prepares and loads
input.csv. - QA/QC reviewer — reviews output, findings and deviations.
- CSV/validation specialist — confirms fitness for intended use.
- System owner — controls versioning, access and change management.
3.5 Data and data-integrity requirements
- each CSV row shall be traceable to a batch, sample or analytical measurement;
- source values shall not be modified by the utility;
- calculations shall be reproducible on repeated execution;
- each deviation shall be captured as a structured finding with field and rule references;
- manual override of the final status outside QA process is not allowed.
4. FS — functional specification
4.1 Processing flow
- Verify presence and encoding of
input.csv. - Validate headers, mandatory fields and data types.
- Normalize numeric and boolean values while preserving the source trace.
- Select an adaptive rule set by product/category type, where applicable.
- Compare values with limits and compute derived metrics.
- Create a result record for each input row.
- Write
output.jsonwith summary, findings and traceability.
4.2 CSV schema
| # | CSV field | Type | Req. | Purpose |
|---|---|---|---|---|
| 1 | SampleID | string | Yes | Input attribute required for deterministic rule evaluation and output traceability. |
| 2 | DeclaredHerbName | string | Yes | Product, preparation or sample identity. |
| 3 | DeclaredLatinName | string | Yes | Product, preparation or sample identity. |
| 4 | PartUsed | string | Yes | Input attribute required for deterministic rule evaluation and output traceability. |
| 5 | BarcodeMarker | string | Yes | Input attribute required for deterministic rule evaluation and output traceability. |
| 6 | SequencingMethod | string | Yes | Analytical method / condition metadata required for technical review. |
| 7 | SequenceLength_bp | integer | Yes | Input attribute required for deterministic rule evaluation and output traceability. |
| 8 | ExpectedMinLength_bp | integer | Yes | Input attribute required for deterministic rule evaluation and output traceability. |
| 9 | ExpectedMaxLength_bp | integer | Yes | Input attribute required for deterministic rule evaluation and output traceability. |
| 10 | MeanPhredScore | decimal | Yes | pH-related measurement used for quality and matrix compatibility control. |
| 11 | MinAcceptablePhredScore | integer | Yes | pH-related measurement used for quality and matrix compatibility control. |
| 12 | DnaConcentration_ng_uL | decimal | Yes | Measured analytical result compared with the configured acceptance criterion. |
| 13 | MinDnaConcentration_ng_uL | integer | Yes | Measured analytical result compared with the configured acceptance criterion. |
| 14 | A260_A280_Ratio | decimal | Yes | Measured analytical result compared with the configured acceptance criterion. |
| 15 | PcrAmplification_Success | boolean | Yes | Input attribute required for deterministic rule evaluation and output traceability. |
| 16 | TopHit_Species | string | Yes | pH-related measurement used for quality and matrix compatibility control. |
| 17 | TopHit_Accession | string | Yes | pH-related measurement used for quality and matrix compatibility control. |
| 18 | Identity_Percent | decimal | Yes | Measured analytical result compared with the configured acceptance criterion. |
| 19 | MinIdentityForConfirmation_Percent | integer | Yes | Measured analytical result compared with the configured acceptance criterion. |
| 20 | QueryCoverage_Percent | integer | Yes | Measured analytical result compared with the configured acceptance criterion. |
| 21 | MinQueryCoverage_Percent | integer | Yes | Measured analytical result compared with the configured acceptance criterion. |
| 22 | E_Value | decimal | Yes | Measured analytical result compared with the configured acceptance criterion. |
| 23 | MaxE_Value | decimal | Yes | Measured analytical result compared with the configured acceptance criterion. |
| 24 | TotalHits_AboveThreshold | integer | Yes | Input attribute required for deterministic rule evaluation and output traceability. |
| 25 | K2P_Distance_Intraspecific | decimal | Yes | Input attribute required for deterministic rule evaluation and output traceability. |
| 26 | K2P_Distance_NearestNeighbor | decimal | Yes | Input attribute required for deterministic rule evaluation and output traceability. |
| 27 | MaxIntraspecific_K2P | decimal | Yes | Input attribute required for deterministic rule evaluation and output traceability. |
| 28 | MinInterspecific_K2P | decimal | Yes | Input attribute required for deterministic rule evaluation and output traceability. |
| 29 | BarcodeGap_Present | boolean | Yes | Binary detection flag used for zero-tolerance or warning rules. |
| 30 | MixedSpecies_Detected | boolean | Yes | Binary detection flag used for zero-tolerance or warning rules. |
| 31 | SpeciesCount_Detected | integer | Yes | Binary detection flag used for zero-tolerance or warning rules. |
| 32 | DominantSpecies_ReadPercent | decimal | Yes | Measured analytical result compared with the configured acceptance criterion. |
| 33 | SecondarySpecies_ReadPercent | decimal | Yes | Measured analytical result compared with the configured acceptance criterion. |
| 34 | SecondarySpecies_Name | string | Yes | Product, preparation or sample identity. |
| 35 | ContaminationThreshold_Percent | decimal | Yes | Measured analytical result compared with the configured acceptance criterion. |
| 36 | ReferenceDatabase | string | Yes | Input attribute required for deterministic rule evaluation and output traceability. |
| 37 | DatabaseVersion | string | Yes | Input attribute required for deterministic rule evaluation and output traceability. |
| 38 | ReferenceSequences_Available | integer | Yes | Input attribute required for deterministic rule evaluation and output traceability. |
| 39 | VoucherSpecimen_Confirmed | boolean | Yes | Input attribute required for deterministic rule evaluation and output traceability. |
4.3 Input data example
| SampleID | DeclaredHerbName | DeclaredLatinName | PartUsed | BarcodeMarker | SequencingMethod | SequenceLength_bp | ExpectedMinLength_bp | ExpectedMaxLength_bp | MeanPhredScore | MinAcceptablePhredScore | DnaConcentration_ng_uL | MinDnaConcentration_ng_uL | A260_A280_Ratio | PcrAmplification_Success | TopHit_Species | TopHit_Accession | Identity_Percent | MinIdentityForConfirmation_Percent | QueryCoverage_Percent | MinQueryCoverage_Percent | E_Value | MaxE_Value | TotalHits_AboveThreshold | K2P_Distance_Intraspecific | K2P_Distance_NearestNeighbor | MaxIntraspecific_K2P | MinInterspecific_K2P | BarcodeGap_Present | MixedSpecies_Detected | SpeciesCount_Detected | DominantSpecies_ReadPercent | SecondarySpecies_ReadPercent | SecondarySpecies_Name | ContaminationThreshold_Percent | ReferenceDatabase | DatabaseVersion | ReferenceSequences_Available | VoucherSpecimen_Confirmed |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| TCM-DNA-2026-001 | Ren_Shen | Panax_ginseng | Root | ITS2 | Sanger | 462 | 400 | 500 | 38.5 | 30 | 45.0 | 10 | 1.85 | true | Panax_ginseng | JX967890 | 99.8 | 98 | 100 | 90 | 1e-180 | 1e-50 | 12 | 0.002 | 0.035 | 0.01 | 0.02 | true | false | 1 | 100 | 0 | 5.0 | TCM_ID | v3.2 | 45 | true | |
| TCM-DNA-2026-002 | Fang_Ji | Stephania_tetrandra | Root | ITS2 | Sanger | 448 | 400 | 500 | 35.2 | 30 | 22.0 | 10 | 1.92 | true | Aristolochia_fangchi | KF234567 | 99.5 | 98 | 99 | 90 | 1e-175 | 1e-50 | 8 | 0.001 | 0.042 | 0.01 | 0.02 | true | false | 1 | 100 | 0 | 5.0 | GenBank | 2026.05 | 28 | true | |
| TCM-DNA-2026-003 | Gou_Qi_Zi | Lycium_barbarum | Fruit | psbA_trnH | NGS_Metabarcoding | 380 | 300 | 450 | 32.0 | 30 | 15.0 | 10 | 1.78 | true | Lycium_barbarum | MH123456 | 99.2 | 98 | 98 | 90 | 1e-150 | 1e-50 | 15 | 0.003 | 0.018 | 0.01 | 0.02 | true | true | 3 | 82.5 | 12.3 | Lycium_chinense | 5.0 | BOLD | 2026.04 | 32 | true |
4.4 Output JSON
{
"utility": "TcmDnaBarcodingAuthenticityQualityChecker",
"runId": "urn:fuzkk:run:example",
"sourceFile": "input.csv",
"recordsProcessed": 3,
"overallStatus": "Pass / Review / Fail",
"records": [
{
"recordId": "TCM-DNA-2026-001",
"status": "Pass / Review / Fail",
"criticalFindings": [],
"warnings": [],
"evaluatedRules": [
"Configured acceptance criteria from the utility rule set"
],
"inputTrace": {
"SampleID": "TCM-DNA-2026-001",
"DeclaredHerbName": "Ren_Shen",
"DeclaredLatinName": "Panax_ginseng",
"PartUsed": "Root",
"BarcodeMarker": "ITS2",
"SequencingMethod": "Sanger",
"SequenceLength_bp": "462",
"ExpectedMinLength_bp": "400"
}
}
],
"dataIntegrity": {
"deterministicEvaluation": true,
"sourceRowTraceability": true,
"manualOverrideAllowed": false
}
}
5. Traceability URS → FS → tests
| URS | FS mechanism | Test evidence |
|---|---|---|
| Load valid input.csv | CSV parser + schema validator | OQ: valid/invalid CSV cases |
| Deterministic limit evaluation | Rule engine with fixed configuration | OQ: boundary values and known expected results |
| Pass/Review/Fail statuses | Status aggregator based on findings | OQ/PQ: passing and failing representative batches |
| Traceability to source row | inputTrace + recordId | PQ: output.json reconciliation to source CSV |
| QA review support | structured findings and warnings | PQ: review and deviation-handling scenarios |
6. CSV/CSA and validation approach
IQ
- utility version check;
- executable location check;
- CSV template check;
- access-right verification.
OQ
- mandatory field checks;
- data type checks;
- boundary-value checks;
- zero-tolerance rule checks.
PQ
- runs on real or representative data;
- comparison with manual calculation;
- confirmation of QA review workflow.
Change control
- rule and limit versioning;
- impact assessment for rule changes;
- regression after updates.
Входит в пакеты
Традиционная китайская медицина (ТКМ)
Пакет QC-утилит для ТКМ: botanical identity, fingerprint consistency, marker compounds, decoction pieces, Paozhi processing, pesticides, mycotoxins, heavy metals, sulfur fumigation, microbial limits and adulteration screening.
Открыть