TcmDnaBarcodingAuthenticityQualityChecker

Tcm Dna Barcoding Authenticity

TCM Traditional Chinese Medicine Herbal Botanical BHP Chinese Pharmacopoeia CSV→JSON URS & FS
Открыть подборку
TCM DNA Barcoding Authenticity Quality Checker — Молекулярная верификация подлинности сырья ТКМ

ℹ️ Утилита выполняет ДНК-идентификацию согласно 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 Documentation

TcmDnaBarcodingAuthenticityQualityChecker — URS & FS

TCM DNA Barcoding Authenticity Quality Checker

TCM DNA Barcoding Authenticity Quality Checker

FUZKK Pharma Utilities URS / FS / CSV-ready documentation Generated: 2026-06-23 Path: East/tkm/data/apps/TcmDnaBarcodingAuthenticityQualityChecker

1. Назначение документа

Документ описывает пользовательские требования (URS) и функциональную спецификацию (FS) для утилиты TcmDnaBarcodingAuthenticityQualityChecker. Утилита предназначена для детерминированной проверки данных input.csv, формирования структурированного результата output.json и поддержки прослеживаемого QA/QC review.

Документ является проектной URS/FS-основой для CSV/CSA, IQ/OQ/PQ и дальнейшей валидации в контексте конкретной лабораторной процедуры.

2. Исходное описание утилиты

TCM DNA Barcoding Authenticity Quality Checker — Молекулярная верификация подлинности сырья ТКМ ℹ️ Утилита выполняет ДНК-идентификацию согласно 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 указывает на фальсификацию, контаминацию или ошибку сбора; партия должна быть карантинизирована до выяснения причин.

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 Поток обработки

  1. Проверить наличие и кодировку input.csv.
  2. Проверить заголовки, обязательные поля и типы данных.
  3. Нормализовать числовые и булевы значения без изменения исходного следа.
  4. Выбрать набор правил по категории продукта/типа, если он предусмотрен.
  5. Сравнить значения с лимитами и вычислить derived metrics.
  6. Сформировать запись результата по каждой строке.
  7. Сохранить output.json с общей сводкой, findings и traceability.

4.2 CSV-схема

Поле CSVТипОбяз.Назначение
1SampleIDstringДаВходной атрибут для детерминированной оценки правил и прослеживаемости результата.
2DeclaredHerbNamestringДаИдентичность продукта, препарата или образца.
3DeclaredLatinNamestringДаИдентичность продукта, препарата или образца.
4PartUsedstringДаВходной атрибут для детерминированной оценки правил и прослеживаемости результата.
5BarcodeMarkerstringДаВходной атрибут для детерминированной оценки правил и прослеживаемости результата.
6SequencingMethodstringДаМетаданные аналитического метода или условий анализа.
7SequenceLength_bpintegerДаВходной атрибут для детерминированной оценки правил и прослеживаемости результата.
8ExpectedMinLength_bpintegerДаВходной атрибут для детерминированной оценки правил и прослеживаемости результата.
9ExpectedMaxLength_bpintegerДаВходной атрибут для детерминированной оценки правил и прослеживаемости результата.
10MeanPhredScoredecimalДаПоказатель pH для контроля качества и совместимости матрицы.
11MinAcceptablePhredScoreintegerДаПоказатель pH для контроля качества и совместимости матрицы.
12DnaConcentration_ng_uLdecimalДаИзмеренный аналитический результат для сравнения с критерием приемлемости.
13MinDnaConcentration_ng_uLintegerДаИзмеренный аналитический результат для сравнения с критерием приемлемости.
14A260_A280_RatiodecimalДаИзмеренный аналитический результат для сравнения с критерием приемлемости.
15PcrAmplification_SuccessbooleanДаВходной атрибут для детерминированной оценки правил и прослеживаемости результата.
16TopHit_SpeciesstringДаПоказатель pH для контроля качества и совместимости матрицы.
17TopHit_AccessionstringДаПоказатель pH для контроля качества и совместимости матрицы.
18Identity_PercentdecimalДаИзмеренный аналитический результат для сравнения с критерием приемлемости.
19MinIdentityForConfirmation_PercentintegerДаИзмеренный аналитический результат для сравнения с критерием приемлемости.
20QueryCoverage_PercentintegerДаИзмеренный аналитический результат для сравнения с критерием приемлемости.
21MinQueryCoverage_PercentintegerДаИзмеренный аналитический результат для сравнения с критерием приемлемости.
22E_ValuedecimalДаИзмеренный аналитический результат для сравнения с критерием приемлемости.
23MaxE_ValuedecimalДаИзмеренный аналитический результат для сравнения с критерием приемлемости.
24TotalHits_AboveThresholdintegerДаВходной атрибут для детерминированной оценки правил и прослеживаемости результата.
25K2P_Distance_IntraspecificdecimalДаВходной атрибут для детерминированной оценки правил и прослеживаемости результата.
26K2P_Distance_NearestNeighbordecimalДаВходной атрибут для детерминированной оценки правил и прослеживаемости результата.
27MaxIntraspecific_K2PdecimalДаВходной атрибут для детерминированной оценки правил и прослеживаемости результата.
28MinInterspecific_K2PdecimalДаВходной атрибут для детерминированной оценки правил и прослеживаемости результата.
29BarcodeGap_PresentbooleanДаБинарный признак обнаружения для правил нулевой толерантности или предупреждений.
30MixedSpecies_DetectedbooleanДаБинарный признак обнаружения для правил нулевой толерантности или предупреждений.
31SpeciesCount_DetectedintegerДаБинарный признак обнаружения для правил нулевой толерантности или предупреждений.
32DominantSpecies_ReadPercentdecimalДаИзмеренный аналитический результат для сравнения с критерием приемлемости.
33SecondarySpecies_ReadPercentdecimalДаИзмеренный аналитический результат для сравнения с критерием приемлемости.
34SecondarySpecies_NamestringДаИдентичность продукта, препарата или образца.
35ContaminationThreshold_PercentdecimalДаИзмеренный аналитический результат для сравнения с критерием приемлемости.
36ReferenceDatabasestringДаВходной атрибут для детерминированной оценки правил и прослеживаемости результата.
37DatabaseVersionstringДаВходной атрибут для детерминированной оценки правил и прослеживаемости результата.
38ReferenceSequences_AvailableintegerДаВходной атрибут для детерминированной оценки правил и прослеживаемости результата.
39VoucherSpecimen_ConfirmedbooleanДаВходной атрибут для детерминированной оценки правил и прослеживаемости результата.

4.3 Пример входных данных

SampleIDDeclaredHerbNameDeclaredLatinNamePartUsedBarcodeMarkerSequencingMethodSequenceLength_bpExpectedMinLength_bpExpectedMaxLength_bpMeanPhredScoreMinAcceptablePhredScoreDnaConcentration_ng_uLMinDnaConcentration_ng_uLA260_A280_RatioPcrAmplification_SuccessTopHit_SpeciesTopHit_AccessionIdentity_PercentMinIdentityForConfirmation_PercentQueryCoverage_PercentMinQueryCoverage_PercentE_ValueMaxE_ValueTotalHits_AboveThresholdK2P_Distance_IntraspecificK2P_Distance_NearestNeighborMaxIntraspecific_K2PMinInterspecific_K2PBarcodeGap_PresentMixedSpecies_DetectedSpeciesCount_DetectedDominantSpecies_ReadPercentSecondarySpecies_ReadPercentSecondarySpecies_NameContaminationThreshold_PercentReferenceDatabaseDatabaseVersionReferenceSequences_AvailableVoucherSpecimen_Confirmed
TCM-DNA-2026-001Ren_ShenPanax_ginsengRootITS2Sanger46240050038.53045.0101.85truePanax_ginsengJX96789099.898100901e-1801e-50120.0020.0350.010.02truefalse110005.0TCM_IDv3.245true
TCM-DNA-2026-002Fang_JiStephania_tetrandraRootITS2Sanger44840050035.23022.0101.92trueAristolochia_fangchiKF23456799.59899901e-1751e-5080.0010.0420.010.02truefalse110005.0GenBank2026.0528true
TCM-DNA-2026-003Gou_Qi_ZiLycium_barbarumFruitpsbA_trnHNGS_Metabarcoding38030045032.03015.0101.78trueLycium_barbarumMH12345699.29898901e-1501e-50150.0030.0180.010.02truetrue382.512.3Lycium_chinense5.0BOLD2026.0432true

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 → тесты

URSFS-механизмПроверка
Загрузка корректного input.csvCSV parser + schema validatorOQ: валидный/невалидный CSV
Детерминированная оценка лимитовRule engine с фиксированной конфигурациейOQ: граничные значения и known expected results
Статусы Pass/Review/FailStatus aggregator по findingsOQ/PQ: образцы с проходными и провальными сериями
Прослеживаемость к исходной строкеinputTrace + recordIdPQ: сверка output.json с исходным CSV
Поддержка QA reviewструктурированные findings и warningsPQ: 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

TCM DNA Barcoding Authenticity Quality Checker — Molecular Verification of TCM Raw Material Authenticity Performs DNA-based species identification per ChP General Chapter 9107, USP <561>, WHO Guidelines on Quality Control of Herbal Materials and CBOL Plant Working Group standards: DNA/PCR quality assessment (concentration ≥10 ng/µL, A260/A280 purity 1.7–2.1, mean Phred score ≥30, sequence length within expected range for marker, PCR amplification success), BLAST identification (sequence identity ≥98%, query coverage ≥90%, E-value ≤1e-50, top-hit species match verification against declared Latin name), barcode gap analysis (Kimura 2-Parameter intraspecific distance ≤0.01, nearest neighbor interspecific distance ≥0.02, gap presence confirmation as prerequisite for reliable discrimination), mixed species detection via NGS metabarcoding (species count, dominant/secondary species read percentages, contamination threshold ≥5% for adulteration flagging, trace levels <5% documented as warnings), and reference database quality verification (≥3 reference sequences available, voucher specimen confirmation for taxonomic reliability). Five-tier classification: SPECIES_CONFIRMED / CLOSE_MATCH / MIXED_SPECIES / DEGRADED_DNA / UNIDENTIFIABLE. ⚠️ Critical: ITS2 is the primary barcode for TCM per ChP 9107; rbcL and matK are supplementary markers. For processed materials (extracts, powders, granules), use mini-barcodes (<200 bp). Fang_Ji (Stephania tetrandra) → Guang_Fang_Ji (Aristolochia fangchi) substitution is detected unambiguously via ITS2. NGS metabarcoding reveals multi-species mixtures and micro-contaminations missed by Sanger sequencing. Absence of barcode gap means the marker lacks resolving power for the taxon; alternative marker required. Reference databases must be curated; GenBank contains up to 10% misidentified entries. DNA degrades in processed materials; negative PCR result ≠ species absence (may indicate degradation). Always include no-template control (NTC) for laboratory contamination detection. Tool assesses MOLECULAR SPECIES AUTHENTICITY only; does not replace chemical assay (marker compounds, fingerprinting) or toxicological screening (aristolochic acids, PAs, heavy metals). SPECIES_CONFIRMED confirms identity but not quality, safety, or efficacy. CLOSE_MATCH requires additional analysis (second marker, morphology, chemistry). MIXED_SPECIES indicates adulteration, contamination, or collection error; batch must be quarantined pending investigation. Usage: TcmDnaBarcodingAuthenticityQualityChecker.exe → demo mode (console output) TcmDnaBarcodingAuthenticityQualityChecker.exe input.csv output.json → evaluate your data 📍 Scope of Application: • 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. 💡 Tips: 1. Multi-Marker Strategy: Use ITS2 + psbA-trnH combination for complex taxa (Panax, Lycium, Angelica). 2. Curated Internal Database: Build internal database with voucher specimens for critical and high-risk species. 3. Negative Controls: Always include NTC and extraction blank for reagent and lab contamination detection. 4. Degraded DNA Protocol: Prepare mini-barcode primers (<200 bp) in advance for extracts and aged samples. 5. Threshold Validation: Validate identity and K2P distance thresholds separately for each marker and taxon. 6. Regular DB Updates: Update reference database quarterly; plant taxonomy is actively revised. ⚠️ Note: This utility assesses MOLECULAR SPECIES AUTHENTICITY. It does not replace chemical analysis (marker compounds, fingerprinting) or toxicological screening (aristolochic acids, pyrrolizidine alkaloids, heavy metals). SPECIES_CONFIRMED status confirms species identity but does not guarantee quality, safety, or efficacy of the raw material. CLOSE_MATCH requires additional analysis (second marker, morphology, chemistry). MIXED_SPECIES indicates adulteration, contamination, or collection error; the batch must be quarantined until the cause is determined.

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

  1. Verify presence and encoding of input.csv.
  2. Validate headers, mandatory fields and data types.
  3. Normalize numeric and boolean values while preserving the source trace.
  4. Select an adaptive rule set by product/category type, where applicable.
  5. Compare values with limits and compute derived metrics.
  6. Create a result record for each input row.
  7. Write output.json with summary, findings and traceability.

4.2 CSV schema

#CSV fieldTypeReq.Purpose
1SampleIDstringYesInput attribute required for deterministic rule evaluation and output traceability.
2DeclaredHerbNamestringYesProduct, preparation or sample identity.
3DeclaredLatinNamestringYesProduct, preparation or sample identity.
4PartUsedstringYesInput attribute required for deterministic rule evaluation and output traceability.
5BarcodeMarkerstringYesInput attribute required for deterministic rule evaluation and output traceability.
6SequencingMethodstringYesAnalytical method / condition metadata required for technical review.
7SequenceLength_bpintegerYesInput attribute required for deterministic rule evaluation and output traceability.
8ExpectedMinLength_bpintegerYesInput attribute required for deterministic rule evaluation and output traceability.
9ExpectedMaxLength_bpintegerYesInput attribute required for deterministic rule evaluation and output traceability.
10MeanPhredScoredecimalYespH-related measurement used for quality and matrix compatibility control.
11MinAcceptablePhredScoreintegerYespH-related measurement used for quality and matrix compatibility control.
12DnaConcentration_ng_uLdecimalYesMeasured analytical result compared with the configured acceptance criterion.
13MinDnaConcentration_ng_uLintegerYesMeasured analytical result compared with the configured acceptance criterion.
14A260_A280_RatiodecimalYesMeasured analytical result compared with the configured acceptance criterion.
15PcrAmplification_SuccessbooleanYesInput attribute required for deterministic rule evaluation and output traceability.
16TopHit_SpeciesstringYespH-related measurement used for quality and matrix compatibility control.
17TopHit_AccessionstringYespH-related measurement used for quality and matrix compatibility control.
18Identity_PercentdecimalYesMeasured analytical result compared with the configured acceptance criterion.
19MinIdentityForConfirmation_PercentintegerYesMeasured analytical result compared with the configured acceptance criterion.
20QueryCoverage_PercentintegerYesMeasured analytical result compared with the configured acceptance criterion.
21MinQueryCoverage_PercentintegerYesMeasured analytical result compared with the configured acceptance criterion.
22E_ValuedecimalYesMeasured analytical result compared with the configured acceptance criterion.
23MaxE_ValuedecimalYesMeasured analytical result compared with the configured acceptance criterion.
24TotalHits_AboveThresholdintegerYesInput attribute required for deterministic rule evaluation and output traceability.
25K2P_Distance_IntraspecificdecimalYesInput attribute required for deterministic rule evaluation and output traceability.
26K2P_Distance_NearestNeighbordecimalYesInput attribute required for deterministic rule evaluation and output traceability.
27MaxIntraspecific_K2PdecimalYesInput attribute required for deterministic rule evaluation and output traceability.
28MinInterspecific_K2PdecimalYesInput attribute required for deterministic rule evaluation and output traceability.
29BarcodeGap_PresentbooleanYesBinary detection flag used for zero-tolerance or warning rules.
30MixedSpecies_DetectedbooleanYesBinary detection flag used for zero-tolerance or warning rules.
31SpeciesCount_DetectedintegerYesBinary detection flag used for zero-tolerance or warning rules.
32DominantSpecies_ReadPercentdecimalYesMeasured analytical result compared with the configured acceptance criterion.
33SecondarySpecies_ReadPercentdecimalYesMeasured analytical result compared with the configured acceptance criterion.
34SecondarySpecies_NamestringYesProduct, preparation or sample identity.
35ContaminationThreshold_PercentdecimalYesMeasured analytical result compared with the configured acceptance criterion.
36ReferenceDatabasestringYesInput attribute required for deterministic rule evaluation and output traceability.
37DatabaseVersionstringYesInput attribute required for deterministic rule evaluation and output traceability.
38ReferenceSequences_AvailableintegerYesInput attribute required for deterministic rule evaluation and output traceability.
39VoucherSpecimen_ConfirmedbooleanYesInput attribute required for deterministic rule evaluation and output traceability.

4.3 Input data example

SampleIDDeclaredHerbNameDeclaredLatinNamePartUsedBarcodeMarkerSequencingMethodSequenceLength_bpExpectedMinLength_bpExpectedMaxLength_bpMeanPhredScoreMinAcceptablePhredScoreDnaConcentration_ng_uLMinDnaConcentration_ng_uLA260_A280_RatioPcrAmplification_SuccessTopHit_SpeciesTopHit_AccessionIdentity_PercentMinIdentityForConfirmation_PercentQueryCoverage_PercentMinQueryCoverage_PercentE_ValueMaxE_ValueTotalHits_AboveThresholdK2P_Distance_IntraspecificK2P_Distance_NearestNeighborMaxIntraspecific_K2PMinInterspecific_K2PBarcodeGap_PresentMixedSpecies_DetectedSpeciesCount_DetectedDominantSpecies_ReadPercentSecondarySpecies_ReadPercentSecondarySpecies_NameContaminationThreshold_PercentReferenceDatabaseDatabaseVersionReferenceSequences_AvailableVoucherSpecimen_Confirmed
TCM-DNA-2026-001Ren_ShenPanax_ginsengRootITS2Sanger46240050038.53045.0101.85truePanax_ginsengJX96789099.898100901e-1801e-50120.0020.0350.010.02truefalse110005.0TCM_IDv3.245true
TCM-DNA-2026-002Fang_JiStephania_tetrandraRootITS2Sanger44840050035.23022.0101.92trueAristolochia_fangchiKF23456799.59899901e-1751e-5080.0010.0420.010.02truefalse110005.0GenBank2026.0528true
TCM-DNA-2026-003Gou_Qi_ZiLycium_barbarumFruitpsbA_trnHNGS_Metabarcoding38030045032.03015.0101.78trueLycium_barbarumMH12345699.29898901e-1501e-50150.0030.0180.010.02truetrue382.512.3Lycium_chinense5.0BOLD2026.0432true

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

URSFS mechanismTest evidence
Load valid input.csvCSV parser + schema validatorOQ: valid/invalid CSV cases
Deterministic limit evaluationRule engine with fixed configurationOQ: boundary values and known expected results
Pass/Review/Fail statusesStatus aggregator based on findingsOQ/PQ: passing and failing representative batches
Traceability to source rowinputTrace + recordIdPQ: output.json reconciliation to source CSV
QA review supportstructured findings and warningsPQ: 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.

Открыть