GuPPy-v1.2.0安装与使用-生信工具52

GuPPy：Python中用于光纤光度数据分析的免费开源工具

01 背景

Basecalling 是将原始测序信号转换为碱基序列的过程，通俗地说，就是“把碱基识别出来”。这一过程在不同代测序技术中各不相同：

一代测序是通过解析峰图实现；
二代测序则是对荧光图像进行处理；
而三代测序中的 Nanopore 技术 则是通过电信号，即电流强度的变化，来推断通过纳米孔的碱基。

由于每次测量的是多个碱基的叠加信号，识别过程更为复杂。因此，碱基识别算法仍在不断发展和优化中。

目前，Oxford Nanopore Technologies (ONT) 官方推荐的 basecalling 工具是 Guppy。在此之前曾使用过 Albacore，后续还有可能被更新的工具（如 Flappie）所替代。这也从侧面反映出该领域仍有广阔的优化空间，是当前测序研究的重要方向之一。

尽管存在如 poretools、nanopolish 等多种第三方工具，但在 basecalling 任务中，仍建议首选官方工具。毕竟，硬件由 ONT 提供，他们对信号特征的理解更加深入。此外，Nanopore 的 basecalling 与所用芯片类型密切相关，例如：

DNA 分子在纳米孔中以约 450 bp/s 的速度通过；
RNA 分子则较慢，约为 70 bp/s。

这一差异也决定了其识别算法存在本质上的不同。

Guppy 简介

Guppy 是 Oxford Nanopore 官方提供的碱基识别软件，是一个基于命令行的工具。

Guppy 主要包含以下几项核心功能：

碱基识别
Guppy 的核心功能是将电流信号转换为 DNA 或 RNA 碱基序列。其底层算法基于循环神经网络（RNN），可以准确识别五种标准碱基：腺嘌呤（A）、鸟嘌呤（G）、胞嘧啶（C）、胸腺嘧啶（T）以及尿嘧啶（U）。
条形码拆分（Demultiplexing）
如果文库构建中添加了条形码（barcode），Guppy 可自动识别两端的条码序列，并将样本数据进行拆分。这一过程类似于 Illumina 测序中基于 index 的样本区分。
参考序列比对
Guppy 支持将识别后的碱基序列与参考基因组进行比对，底层实际上调用的是 minimap2 工具。由于该功能中 minimap2 的参数设置是内嵌的，不可调整，建议用户在比对任务中使用独立的 minimap2 工具，以确保更高的灵活性与精度。
甲基化修饰检测
Guppy 还具备一定的碱基修饰检测能力。当碱基发生如甲基化等修饰时，其通过纳米孔时的电信号会表现出异常。Guppy 可通过识别这些“离群”信号推测潜在修饰位点。
目前该功能仍依赖于特定的训练数据集，支持的物种有限（如大肠杆菌、人类等模式生物）。若对特定物种感兴趣，可尝试构建定制训练集进行检测。

https://github.com/LernerLab/GuPPy   #官网
wget -c https://github.com/LernerLab/GuPPy/archive/refs/tags/v1.2.0.zip    #new version

02下载

下载 GuPPy 代码

a. 点击页面右上角绿色的 “Code” 按钮，会弹出下拉菜单。
b. 点击 “Download ZIP” 下载压缩包（注意：请保存在本地硬盘中，不要保存在iCloud、OneDrive、Box等云端，建议保存至 C盘 用户文件夹）。
c. 解压下载的ZIP文件，得到文件夹 “GuPPy-main”，并将其放在一个方便的位置（避免使用云同步文件夹）。
d. 记下 “GuPPy” 子文件夹的路径，在后续操作中会用到。

Mac：右键文件夹 → 点击“显示简介” → 查看“位置”字段
Windows/Linux：右键文件夹 → 属性 → 查看“位置”字段
示例：/Users/LernerLab/Desktop/GuPPy-main

`03 安装`

conda安装

cd 路径_to_GuPPy_folder
示例：cd /Users/LernerLab/Desktop/GuPPy-main创建并激活 GuPPy 环境
依次输入以下命令：注意：filename 替换为你的系统对应的配置文件：Windows: spec_file_windows10.txtMac: spec_file_mac.txtLinux: spec_file_linux.txtconda create --name guppy --file filename
conda activate guppy

04 使用

启动 GuPPy 用户界面
输入以下命令以启动GUI界面：panel serve --show GuPPy/savingInputParameters.ipynb
此时，GuPPy 已成功安装并可开始使用！卸载 GuPPy
若需卸载：conda remove --name guppy --all

05 官方教学视频

Installation steps
Explaining Input Parameters GUI
Individual Analysis steps
Artifacts Removal
Group Analysis steps
Use of csv file as an input
Use of Neurophotometrics data as an input

06 官方示例数据

Sample data for the user to go through the tool in the start. This folder of sample data has two types of sample data recorded with a TDT system : 1) Clean Data 2) Data with artifacts (to practice removing them) 3) Neurophotometrics data 4) Doric system data. Finally, it has a control channel, signal channel and event timestamps file in a 'csv' format to get an idea of how to structure other data in the 'csv' file format accepted by GuPPy.

07 常用 Basecall

7.1 基本命令格式

通过 guppy_basecaller -h 可查看工具的基本使用方式：

guppy_basecaller -i <输入路径> -s <输出路径> -c <配置文件> [options]

常用参数说明：

-i：输入文件夹（包含 .fast5 文件）
-s：输出文件夹（保存 fastq 或 bam 文件）
--config：指定 basecall 配置文件
-r / --recursive：递归处理子目录
--flowcell：芯片类型（如 FLO-MIN106、FLO-MIN107）
--num_callers：并行处理数（通常影响输出文件数量）
--cpu_threads_per_caller：每个 caller 使用的 CPU 线程数
--compress_fastq：输出压缩格式的 fastq 文件
-q：每个输出文件中包含的最大读段数（设为 0 表示每个读段单独输出）
--disable_qscore_filtering：禁用质量分数过滤，保留低质量读段
--align_ref：参考基因组 FASTA 或索引文件
--model_file：指定模型文件
--device / -x：设置使用的 GPU（如 cuda:0、cuda:1,2 或 auto）
--bed_file：指定包含感兴趣区域的 .bed 文件
--align_type：设置比对模式（auto、full 或 coarse）
--minimap_opt_string：传递 minimap2 的自定义参数
--bam_out：输出 BAM 格式文件
--index：生成 BAM 索引
--moves_out：在 BAM 文件中输出碱基移动信息

7.2 使用配置文件 (`-c`) 进行 Basecall

最基础的 basecall 命令如下，可按需调整参数：

guppy_basecaller \-i fast5_files/ \-s output/ \--config dna_r9.4.1_450bps_sup.cfg \--model_file $HOME/bio/tools/ont-guppy-cpu/data/template_r9.4.1_450bps_hac.jsn \--disable_qscore_filtering \-r \--align_ref refs/dna.fa

7.3 通过 Flow Cell 和 Reagent Kit 指定模型

若未使用 --config 指定模型，可通过 flow_cell 和 kit 参数自动选择合适配置。

查看支持的芯片和试剂盒：

guppy_basecaller --print_workflows

过滤特定组合（例如：FLO-MIN106 与 SQK-LSK109）：

guppy_basecaller --print_workflows | grep FLO-MIN106 | grep SQK-LSK109

示例输出：

FLO-MIN106  SQK-LSK109  dna_r9.4.1_450bps_hac  2021-05-17_dna_r9.4.1_minion_384_d37a2ab9

使用该组合进行 basecall：

guppy_basecaller \-i fast5_files/ \-s output/ \--flowcell FLO-MIN106 \--kit SQK-LSK109 \--model_file $HOME/tools/ont-guppy-cpu/models/template_r9.4.1_450bps_hac.jsn

7.4 使用自定义模型进行 Basecall

如使用自定义训练模型（如 Taiyaki 训练的模型）：

导出模型为 JSON 格式：

dump_json.py training/model_final.checkpoint > model.json

使用该模型进行 basecall：

可结合 Guppy + Megalodon 等工具进行碱基修饰检测（如甲基化）等！

08 引用

Venus N. Sherathiya, Michael D. Schaid, Jillian L. Seiler, Gabriela C. Lopez, and Talia N. Lerner GuPPy, a Python toolbox for the analysis of fiber photometry data. Sci Rep 11, 24212 (2021). GuPPy, a Python toolbox for the analysis of fiber photometry data | Scientific Reports