ngs-bcl-to-fastq
Validate Illumina BCL run folders and sample sheets, plan demultiplexing, review index/UMI/lane choices, run BCL-to-FASTQ conversion, and interpret demux metrics while surfacing license/download boundaries.
- License 许可
- AGPL-3.0
- 所属仓库
- wxdwu/new-api
- 最近更新
- 2026-10-05
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- ngs-bcl-to-fastq
- description
- Validate Illumina BCL run folders and sample sheets, plan demultiplexing, review index/UMI/lane choices, run BCL-to-FASTQ conversion, and interpret demux metrics while surfacing license/download boundaries.
02 资源文件 1
- 参考文档agents/openai.yaml291 B
03 SKILL.md 正文
BCL To FASTQ
Use this skill when the input is an Illumina BCL run folder or the user asks to demultiplex a sequencing run. This is a deep demultiplexing and run-validation skill, not only a command wrapper.
Essential Inputs
Confirm:
- run folder path with
RunInfo.xml - sample sheet path and format
- output directory
- instrument/run metadata from
RunInfo.xmlandRunParameters.xml - lane handling: split by lane or combine lanes
- index mismatch tolerance
- index read structure and dual-index orientation
- UMI layout, if any
- whether adapter trimming/masking should happen during conversion
- whether undetermined reads and demultiplexing metrics should be reviewed before downstream analysis
Public Tool Boundary
Prefer bcl-convert if it is already installed. It is free for local use but proprietary and RPM-distributed by Illumina, so do not auto-download without explicit user approval.
Legacy bcl2fastq may exist in older environments. Use it only when BCL Convert is unavailable or the run requires legacy compatibility.
Preflight
python plugins/ngs-analysis/scripts/ngs_preflight.py --pipeline bcl_to_fastq --emit-install-plan
Also check run-folder structure:
test -f /path/to/run/RunInfo.xml
test -f /path/to/SampleSheet.csv
find /path/to/run -maxdepth 4 -type d -name BaseCalls
Local Execution Package
Use the plugin-owned runner when the user provides a local run folder and sample sheet:
python plugins/ngs-analysis/scripts/run_bcl_to_fastq.py \
--run-folder /path/to/run \
--sample-sheet /path/to/SampleSheet.csv \
--output-directory /path/to/fastq_out
Add --execute only when conversion is requested. The runner validates RunInfo.xml, optional RunParameters.xml, the BaseCalls directory, sample-sheet rows, duplicate lane/index combinations, and index length compatibility. With --execute, it uses installed bcl-convert, then legacy bcl2fastq if available; if neither exists, it records the blocker instead of downloading proprietary software.
Validation Checklist
Before conversion, validate:
RunInfo.xmlexists and its read structure matches the expected sequencing design.SampleSheet.csvexists, is the intended version, and has no duplicate sample/index combinations within each lane.- Index sequence lengths match the index reads and any trimming/masking requested by the sample sheet.
- Dual-index orientation is explicit for the instrument and library prep; do not infer i5 orientation from filenames.
- UMI bases are assigned to the intended read or index read and carried through to FASTQ headers or output metadata as needed.
- Lane-splitting, sample-name normalization, and output directory behavior are agreed before running.
- Disk space is sufficient for output FASTQs, reports, and temporary files.
Kickoff Pattern
First produce a preflight plan with paths and sample sheet validation. Then run conversion only after the user confirms:
bcl-convert \
--bcl-input-directory /path/to/run \
--output-directory /path/to/fastq_out \
--sample-sheet /path/to/SampleSheet.csv
Metrics Review
After conversion, inspect and report:
- total clusters, clusters passing filter, and yield by lane
- percent assigned by sample and percent undetermined by lane
- top undetermined index sequences when available
- per-sample FASTQ counts and read-pair consistency
- unexpected index hopping, barcode collision, or sample-sheet mismatch signals
Record software version, command, sample sheet checksum, run-folder path, output path, and conversion metrics. Do not start downstream analysis until severe demultiplexing anomalies are surfaced.
04 同仓库更多 Skills
Zotero
Use Zotero Desktop from Codex to enable/probe the local API, search a local Zotero library, list items/collections/tags, export BibTeX, insert citation keys into LaTeX or Markdown drafts, read indexed full text when requested, and import BibTeX/RIS records into Zotero through the connector server. Use when the user mentions Zotero, citations, references.bib, BibTeX export, local Zotero API, localhost:23119, or adding citations from a Zotero library.
zoom-apps-sdk
Use when using Apps SDK.
setup-zoom-websockets
Use when building Zoom WebSockets.
setup-zoom-webhooks
Use when building Zoom webhooks.
zoom-virtual-agent-web
Zoom Virtual Agent SDK for web embeds. Use for campaign or entry ID chat launch, event-driven controls, user context updates, and CSP-safe deployment.
zoom-virtual-agent-ios
Zoom Virtual Agent iOS integration via WKWebView. Use for Swift/Objective-C script injection, message handlers, support_handoff relay, and URL routing policies.