primer-design

プライマー設計と特異性

候補オリゴを 5' 末端から 3' 末端の向きで作製し、各結論の背後にある正確なテンプレート、 化学的条件、意図する産物、および検索範囲を明示してください。配列に依存する量は、提供された ツールで計算してください。馴染みのある遺伝子名、良好な Primer3 ペナルティ、あるいは単一の BLAST アラインメントだけでは、プライマーの特異性を確立することはできません。

ワークフローを選択する

リクエスト	ここから始める
新規のゲノム PCR または RT-qPCR ペア	アッセイとリファレンスを定義し、設計し、熱力学を評価し、産物をスクリーニングします。
既存ペアの確認	ペアの TSV を準備し、完全なオリゴとアニーリングコアの両方を評価し、明示的な意図座標でスクリーニングします。
エクソンジャンクション、転写産物アイソフォーム、アレル識別	design-workflows.md を読み、制約を課す前に配列アノテーションを提供します。
クローニング／アダプター付きプライマー	アニーリングコアを設計し、宣言された 5' テールを付加し、完全なオリゴを再評価し、最終産物を再構築します。
マルチプレックスパネル	熱力学ツールと特異性ツールの両方で --multiplex を有効にして、オリゴ間相互作用とペア間産物を評価します。
縮重、バイサルファイト、プローブ、または修飾塩基アッセイ	design-workflows.md の専用ワークフローを使用します。同梱の通常 DNA モデルでは不十分です。

ローカルツールは、明確な ACGT コアを持つペアプライマーをサポートします。高度なアッセイ タイプには実質的な設計および検証のガイダンスがありますが、通常の PCR に黙って還元される ことはありません。このスキルはアッセイを設計します。発現の正規化、実験的な診断検証、および ガイド RNA 設計は別のタスクです。

アッセイの契約を確立する

結果を変える情報を入手してください。探索的な設計では、明示的な暫定仮定を使用し、それを レポートで明示してください。

• 目的とテンプレート: ゲノム DNA、cDNA、プラスミド、またはその他の定義された基質。 対象生物、バージョン付きのアクセッション、アセンブリ／転写産物リリース、鎖、 所望のアイソフォーム、および産物サイズ範囲。目的のテンプレートと不要なテンプレートを 明示してください。
• 配列の証拠: ローカル FASTA に加えて、ソース／取得日とその SHA-256 ハッシュ。 ローカス抜粋はローカル座標を使用します。完全なリファレンスへのマッピングを記録して ください。適切なスクリーニングには、関連するパラログ、偽遺伝子、代替コンティグ、 転写産物アイソフォーム、ベクターバックボーン、および宿主配列を含めてください。
• 反応条件: ポリメラーゼ／バッファー、一価塩、総二価塩、総 dNTP、およびオリゴ濃度。 Primer3 は塩／dNTP に mM を、DNA に nM を使用します。初期反応濃度と Primer3 の 有効アニーリングオリゴ濃度パラメータは別々に記録してください。エンジンのデフォルトは 仮定です。
• 制約: ターゲット区間、許容／除外結合領域、ジャンクション、バリアント除外とその ソース、固定プライマー、テール、またはマルチプレックスメンバーシップ。エクソン境界を 推測したり、別のアセンブリを黙って代用したりしないでください。
• 許容される結果の定義: 関連するオフターゲットリファレンス、アンプリコン長、 ミスマッチ検索限界、コントロール、およびアッセイに適した実験的検証。すべての PCR を 検証する普遍的な熱力学的カットオフは存在しません。

ファイルスキーマと座標の例については input-contract.md を 使用してください。証拠を収集するには、assay-report-template.md を分析ディレクトリにコピーしてください。リファレンスの取得は手動でも、確立された配列 API を通じてもかまいません。アクセッション／バージョンを保持し、返された配列を検証してください。 提供されたスクリプトはローカルファイルを使用し、配列をオンラインで送信しません。

インストールと検証

SKILL_DIR をこのスキルの実際のインストールディレクトリに設定します。環境、参照データベース、結果がスキル内に入らないよう、別の分析用ディレクトリで作業してください。

uv venv --python 3.13 .venv-primer
uv pip install --python .venv-primer/bin/python -r "$SKILL_DIR/assets/requirements.txt"
.venv-primer/bin/python "$SKILL_DIR/scripts/design_primers.py" --help

Windows では環境の Scripts/python.exe を使用してください。設計/熱力学の例は primer3-py 2.3.1 を対象とし、Python 3.13 でテストされています。オプションの BLAST エンジンについては、NCBI BLAST+ を公式ディストリビューションからインストールし、次を確認してください:

blastn -version
makeblastdb -version

ローカル統合チェックでは BLAST+ 2.17.0 も検証しています。その他のリリースでは、同等のカバレッジを主張する前に、その出力と検索動作を確認する必要があります。

依存関係や API の前提を更新する際は、sources.md を参照してください。各スクリプトはエンジンのバージョンと有効な設定を JSON レポートに記録します。

1. 候補の設計

初期の機能デモンストレーションには、同梱の合成配列を使用してください。これは非生物学的な例示入力であり、実験的に検証されたアッセイではありません:

.venv-primer/bin/python "$SKILL_DIR/scripts/design_primers.py" \
  --template "$SKILL_DIR/assets/demo-template.fasta" \
  --preset qpcr --config "$SKILL_DIR/assets/qpcr-config.json" \
  --output design.json --pairs-out pairs.tsv --expected-out expected.tsv

実際の作業では、レビュー済みのターゲット FASTA と制約に置き換えてください。複数レコードの FASTA では、正確な ID を指定した --record が必要です。pcr プリセットは 100–1000 bp を要求し、qpcr は 70–200 bp を要求します。これらの開始範囲は設定で上書きしてください。この例では範囲を 90–180 bp に上書きし、特定のターゲット区間を含めています。複数の SEQUENCE_TARGET 区間は選択肢であり、Primer3 は少なくとも 1 つを挟みます。すべての区間のカバレッジを必須にするには、それらを包含する 1 つのターゲットを指定し、返されたプロダクトを検証してください。別々のアッセイには別々の設計実行が必要です。

このツールは:

• 検証済みの sequence_args と global_args を Primer3 に渡します。サポートされていないタグやスペルミスのあるタグは、タスクを黙って変更するのではなく失敗します。
• 曖昧なテンプレート位置を N に変換し、曖昧なプライマー塩基を禁止します。小文字の配列をリピートマスクとして解釈しません。明示的な除外を使用してください。
• オプションで --mask-bed による除外を 指定されたテンプレートの座標 で取り込みます。BED 区間をバリアント/リピートのマスキングに使用するのは、参照マッピングを検証した後のみにしてください。アレル頻度を推測したり、任意の VCF を変換したりすることはありません。
• 返されたフォワード配列とリバース配列をテンプレートと照合し、プロダクト長を確認します。Primer3 の右プライマー位置はハーフオープンの結合区間に変換されます。リバースプライマーはすでにオーダリングの向きになっています。
• オプションで --forward-tail と --reverse-tail をコアに付加します。設計スコアとコア Tm にはこれらのテールは含まれません。ステップ 2 で完全なオリゴを確認します。

候補が見つからない場合は engine_explanations を確認してください。生物学的に正当化される制約を変更して再実行してください。すべての制約を黙って緩めたり、でっち上げた配列を返したりしないでください。パラメータの選択を比較する際は、以前のレポートを保存してください。

expected.tsv は 設計テンプレート上での 意図されたプロダクトを記述します。別の参照でスクリーニングする場合は、これらの座標をその正確なレコード ID と向きにマッピングしてください。cDNA プロダクトを、イントロンをまたいでゲノム区間として再ラベル付けすることはできません。

2. 熱力学を評価する

設計と同じ化学的条件を使用してください。以下の明示的な値は同梱の設計デフォルトと一致しています。実際の条件が異なる場合は、これらをまとめて置き換えてください:

.venv-primer/bin/python "$SKILL_DIR/scripts/check_thermodynamics.py" \
  --pairs pairs.tsv --mv-conc 50 --dv-conc 1.5 --dntp-conc 0.6 \
  --dna-conc 50 --temp-c 37 --output thermodynamics.json

レポートには、コア Tm、コアおよび全オリゴのヘアピン/ホモダイマー、全オリゴのヘテロダイマー、自己 3' 末端安定性、および両方向のオリゴ間 3' 末端安定性計算が含まれます。Delta-G と delta-H は kcal/mol で、delta-S は cal/(mol K) で報告されます。--temp-c は delta-G の温度を制御するものであり、推奨される PCR アニーリング温度ではありません。

設計で異なる Tm/塩モデルを使用した場合は、一致させるために --tm-method と --salt-corrections-method も設定してください。入力契約のマッピングを参照してください。

パネルの場合は、--multiplex を追加して、異なるペア間の forward/forward および reverse/reverse を含む、すべての順序なしオリゴの組み合わせを調べます。組み合わせるパネルと、別々にテストする代替候補を区別してください。

これらの値を解釈する前に thermodynamics.md をお読みください。60 塩基より長い全オリゴは未解決として報告されます。決して黙って切り詰められることはありません。修飾塩基および縮重混合物には適切なモデルが必要です。熱力学的予測はランキングと実験計画を支援するものであり、プライマー品質を包括的に保証する主張ではありません。 非有限の Tm、または絶対零度以下の Tm は計算/入力の失敗として拒否されます。そのような結果は、通常の低 Tm プライマーとしてランク付けしてはなりません。

3. 増幅産物をスクリーニングする

特異性の主張を行う前に specificity.md をお読みください。各プライマーを両方の鎖で検索し、内向きの結合部位をペアにします。結合ヒットだけではアンプリコンではありません。報告されたヒットがないことは、存在しないことの証明にはなりません。

網羅的な有界ローカル検索

.venv-primer/bin/python "$SKILL_DIR/scripts/screen_specificity.py" \
  --pairs pairs.tsv --reference "$SKILL_DIR/assets/demo-template.fasta" \
  --expected expected.tsv --engine exhaustive \
  --min-product 40 --max-product 1000 --max-mismatches 2 \
  --three-prime-bases 5 --max-three-prime-mismatches 0 \
  --output specificity.json

これは、有界ローカル参照内の全長、ギャップなしの結合部位を列挙し、各ペアについて F/R、R/F、F/F、R/R 産物をチェックします。参照の曖昧性は未解決配列として保守的に扱われます。クリーンな結果を確立することはできません。 ミスマッチ制限は検索モデルであり、検証されたポリメラーゼ識別規則ではありません。厳しい 3' 末端閾値は増幅可能なミスマッチ部位を除外する可能性があります。その不確実性を評価する際は検索を広げてください。

環状分子には --circular RECORD_ID を使用してください。ラップされた産物は正規の開始座標と参照長より大きい非ラップ末端を使用します。最大で 1 分子にまたがる産物のみが考慮されます。比較、ヒット、産物の上限は無制限の作業を防ぎます。上限に達すると結果は不完全になります。

BLAST 支援ローカル検索

.venv-primer/bin/python "$SKILL_DIR/scripts/screen_specificity.py" \
  --pairs pairs.tsv --reference "$SKILL_DIR/assets/demo-template.fasta" \
  --expected expected.tsv --engine blast \
  --min-product 40 --max-product 1000 --max-mismatches 2 \
  --three-prime-bases 5 --max-three-prime-mismatches 0 \
  --output specificity-blast.json

このスクリプトは一時的なローカル BLAST データベースを構築し、短いクエリのアラインメントを実行し、完全なプライマー長の候補部位を再チェックし、コマンドとバージョンを記録します。設定されたヒット制限とツールの失敗をチェックします。BLAST による発見はヒューリスティックです。実行が成功し、制限が飽和していないからといって、網羅的なカバレッジが確立されるわけではありません。 参照はメモリにロードされます。大規模ゲノムではメモリと検索範囲を計画してください。小さな例は実行を検証するものであり、ヒトゲノムの感度やスケーラビリティを検証するものではありません。

より広範な公開参照のスクリーニングについては、specificity.md の公式 NCBI Primer-BLAST ワークフローに従い、生物種、データベース、対象テンプレート、最大産物長、およびミスマッチポリシーを意図的に選択してください。配列を送信すると NCBI に送信されます。ローカルのみの作業はローカルに保ってください。Primer-BLAST は、これらのスクリプトによって実装された文書化された REST API ではありません。

結果を解釈する

• potential_off_target: 予期しないすべての生成物を検査し、その向き、長さ、ミスマッチ位置、参照同一性を確認してください。関連性を再設計するか、正当化してください。
• intended_target_not_found: 特異性の結論を導く前に、マッピング、参照、配列、検索の問題を解決してください。
• no_expected_target: 結果は生成物の一覧であり、ターゲット固有の結論はありません。アッセイの意図するすべての生成物区間を指定してください。
• incomplete: 参照の不確実性、リソース制限、または計算の失敗により、結論は未解決のままです。報告された理由を確認し、適切に再実行してください。
• no_off_target_found_within_search_scope: 正確な参照と検索モデルを明記してください。レポートの網羅的/ヒューリスティックフラグを確認してください。これは経験的な検証ではありません。

マルチプレックス反応では、熱力学コマンドと同様に特異性コマンドにも --multiplex を追加します。すると特異性ツールはすべてのクロスペアのオリゴの組み合わせを検索し、元のオリゴの同一性とテールを保持します。クロスペアの生成物は意図しないものとして扱われます。意図的にプライマーを共有する設計では、レビュー済みの予期される生成物を伴う明示的なスタンドアロンの組み合わせが必要です。--max-panel-combinations の上限はデフォルトで 10,000 で、展開前にチェックされます。熱力学の --multiplex は構造をチェックし、特異性の --multiplex は参照生成物をチェックします。このパネル評価には両方が必要です。

4. アッセイを検証し、エビデンスを提供する

最低の Primer3 ペナルティだけでなく、アッセイの目的、カバレッジ、特異性のエビデンス、化学に基づいて候補を選択してください。不確実性が残る場合は複数の候補を保持してください。関連する実験的チェックについては design-workflows.md に従ってください。すなわち、予期される生成物の同一性/サイズ、陰性対照と鋳型なし対照、RT-qPCR のゲノム混入対照、定量を意図する場合の効率/ダイナミックレンジの評価です。単一のメルトピークだけでは同一性を証明できません。

完成した report template、ペア TSV、設計/熱力学/特異性の JSON、ソースマニフェストを提出してください。以下を含めます。

1. 正確な注文配列、分離されたアニーリングコアとテール、プライマー長、意図する生成物の座標/サイズ、および関連する転写産物/ジャンクションマッピング。
2. 化学およびモデル設定、エンジンのバージョン、参照のアクセッション/リリース、ソース、取得日、ファイルハッシュ、明示的な除外とその根拠。
3. 意図する生成物および潜在的に意図しない生成物。未知の塩基、不完全な参照、ヒューリスティック検索、上限、サポートされていないアッセイ化学による不確実性。
4. 実際に取得された実験的エビデンス、未完了の検証、および推奨する各候補の理由。未検証の候補は正確にラベル付けしてください。

この実装の検証と限界

tests/primer-design/ のリポジトリのスイートは、実際の Primer3 計算、向きと座標の再構成、マスキング、テール、濃度の扱い、オフターゲット生成物の形状、ミスマッチ/曖昧性の挙動、失敗状態、および実行ファイルがインストールされている場合のローカル BLAST 統合を検証します。合成フィクスチャはソフトウェアの挙動を確立するものであり、生物学的アッセイを検証したり、ゲノム全体の再現率を証明したりするものではありません。

ツールは、計算が完了した場合は 0 を、候補のない完了した設計または不完全な長鎖オリゴの熱力学の場合は 1 を、無効な入力またはツールの失敗の場合は 2 を返します。終了コードが 0 の場合でも JSON の科学的ステータスを確認してください。オフターゲットの発見は、正常に完了した計算です。画面固有の終了コードについては入力コントラクトを参照してください。

Scientific Agent Skills の引用

公開された成果物で使用する場合は、sources.md および Scientific Agent Skills の上流の手法を引用してください。実際の解析を再現するために必要なソフトウェアのバージョンとアッセイ固有の設定を報告してください。