Virome Analysis in Metagenomics: Hands-on Practice with ViWrap

在微生物学研究中，宏基因组学技术为探索复杂微生物群落的组成与功能提供了强大的工具。而病毒组作为微生物群落的重要组成部分，其在生态系统、宿主健康与疾病中的作用日益受到关注。从宏基因组数据中分析病毒组，不仅可以揭示病毒的多样性、进化关系，还能帮助我们理解病毒与宿主之间的相互作用机制，对于疾病防控、生态平衡维护等领域具有重要意义。

ViWrap对近年来病毒组分析的主流方法进行汇总整理，整合了多种高效的分析流程与算法，较为完整地覆盖了该组学分析的上下游关键步骤，方便研究人员快速、深入地解读数据。借助对ViWrap的安装、部署、使用、理解，十分便于我们快速上手掌握病毒组分析的关键技术和方法，从而更高效地投入到相关领域的深入分析工作当中。

名词解释

在代码中出现的尖括号通常表示一些需要替换的通配符，如<username>意味着需要连通尖括号一起替换为使用者用户名。<password> 需要替换成密码。请读者注意领会变通，切忌直接复制粘贴代码进行操作。

注意：本protocol纵使当前能顺利运行，但随着一些包和软件的更新，可能有新的冲突和错误发生，以至于产生新报错。当出现这种情况时，可以关注Github等社区寻求解决方案。

参考文献： https://doi.org/10.1002/imt2.118

ViWrap实操指南

1. 安装conda

1.1 本课程提供了conda的安装包，路径如下

stu50@ubuntuserver:~$ ls /data/Miniconda*
/data/Miniconda3-latest-Linux-x86_64.sh

1.2 把 `/data/Miniconda3-latest-Linux-x86_64.sh` 安装到 `/data/<username>/` 目录下。

1.3 进入安装包所在目录，然后先创建你的conda安装目录

cd /data
mkdir /data/<username>/miniconda3

1.4 运行安装脚本，指定安装目录

bash Miniconda3-latest-Linux-x86_64.sh -b -p /data/<username>/miniconda3

-b：表示 batch 模式，自动接受协议，不提示用户输入。
-p：指定安装路径。

1.5 安装完成后，你可以验证

/data/<username>/miniconda3/bin/conda --version
conda 25.3.11.6

1.6 查看你的~/.bashrc

(base) stu50@ubuntuserver:~$ cat ~/.bashrc

1.7 初始化conda命令

/data/<username>/miniconda3/bin/conda init bash

1.8 重新加载你的shell配置文件

source ~/.bashrc

1.9 再次查看你的~/.bashrc吧！

(base) stu50@ubuntuserver:~$ cat ~/.bashrc

# >>> conda initialize >>>
# !! Contents within this block are managed by 'conda init' !!
__conda_setup="$('/data/temp_software/miniconda3/bin/conda' 'shell.bash' 'hook' 2> /dev/null)"
if [ $? -eq 0 ]; then
    eval "$__conda_setup"
else
    if [ -f "/data/temp_software/miniconda3/etc/profile.d/conda.sh" ]; then
        . "/data/temp_software/miniconda3/etc/profile.d/conda.sh"
    else
        export PATH="/data/temp_software/miniconda3/bin:$PATH"
    fi
fi
unset __conda_setup
# <<< conda initialize <<<

1.10 现在享受直入conda便利吧！

conda --version
# conda create -n myenv python=3.10
# conda activate myenv

2. ViWrap的准备工作

2.1 先建立/返回好自己的文件夹

(base) stu50@ubuntuserver:/data$ cd /data/<username>

2.2 克隆项目仓库，克隆在“/data/”

推荐使用Gitee的仓库

#git clone https://github.com/BGIGPD/ViWrap.git
#(base) stu50@ubuntuserver:/data/Virome_zlk$ git clone https://github.com/BGIGPD/ViWrap.git
#Cloning into 'ViWrap'...
#remote: Enumerating objects: 790, done.
#remote: Counting objects: 100% (135/135), done.
#remote: Compressing objects: 100% (19/19), done.
#remote: Total 790 (delta 123), reused 118 (delta 116), pack-reused 655 (from 1)
#Receiving objects: 100% (790/790), 468.29 MiB | 1.31 MiB/s, done.
#Resolving deltas: 100% (484/484), done.

如果Github网络连接不稳定，则使用在国内的Gitee托管的项目文件

git clone https://gitee.com/BGIGPD/ViWrap.git
#(base) stu50@ubuntuserver:/data/gittee_Virome$ git clone https://gitee.com/BGIGPD/ViWrap.git
#Cloning into 'ViWrap'...
#remote: Enumerating objects: 790, done.
#remote: Counting objects: 100% (790/790), done.
#remote: Compressing objects: 100% (295/295), done.
#remote: Total 790 (delta 484), reused 790 (delta 484), pack-reused 0 (from 0)
#Receiving objects: 100% (790/790), 468.29 MiB | 9.78 MiB/s, done.
#Resolving deltas: 100% (484/484), done.

2.3 然后进入你的克隆下来的项目仓库里面：

cd ViWrap

赋予可执行脚本权限

chmod +x ViWrap scripts/*.py

将流程路径写入PATH环境变量并作为默认的启动配置项，以便快速调用。

echo "export PATH=`pwd`:\$PATH" >> ~/.bashrc

启动配置项目，立即生效

source ~/.bashrc

3. 部署ViWrap以及各个分析模块的虚拟环境

3.1 主程序ViWrap的环境

官方版本在这个环节存在bug，在更新前请按以下命令部署先安装mamba

conda install mamba -n base -c conda-forge

查看mamba版本

(base) stu50@ubuntuserver:/data$

然后使用mamba创建以下环境，mamba是全局环境，已经安装在基础环境（base environment）里面后就不用在安装在虚拟环境下了

mamba create -c bioconda -c conda-forge -n ViWrap python=3.8 biopython=1.80 numpy=1.24.2 pandas=1.5.3 pyfastx=0.8.4 matplotlib=3.6.3 seaborn=0.12.2 diamond=2.0.15 hmmer=3.3.2 pyparsing=2.4.7

首次初始化时就绑定到 Conda 根目录，一步到位

mamba shell init --shell bash --root-prefix=/data/<username>/miniconda3
# mamba shell init --shell bash --root-prefix=/data/temp_software/miniconda3

让当前终端立即生效 ~/.bashrc 文件中的配置修改，无需重启终端或重新登录用户

source ~/.bashrc

激活ViWrap 分析环境

mamba activate ViWrap

这里不要运行，只是一个常识提示。退出ViWrap环境 # mamba deactivate

然后利用ViWrap脚本自动安装所需模块的虚拟环境

ViWrap set_up_env --conda_env_dir /data/<username>/miniforge3/envs
# ViWrap set_up_env --conda_env_dir /data/temp_software/miniforge3/envs

分析所需数据库的下载与安装（跳过）

该过程需要从互联网下载各个模块分析所需的比对数据库，十分耗时。对于需要在自己单位或个人电脑上部署的读者，可以参考上述命令。

# ViWrap download --db_dir /data/<username>/ViWrap_db  --conda_env_dir /data/<username>/miniforge3/envs

由于我们已经实现下载好了所需文件，可以直接设置数据库位置--db_dir /data/example/ViWrap_db.

conda run -n ViWrap-vs2 virsorter config --init-source --db-dir=/data/example/ViWrap_db/VirSorter2_db

问题报错：

# (ViWrap) stu50@ubuntuserver:/data/temp_software/ViWrap$ conda run -n ViWrap-vs2 virsorter config --init-source --db-dir=/data/example/ViWrap_db/VirSorter2_db
# EnvironmentLocationNotFound: Not a conda environment: /data/temp_software/miniconda3/envs/ViWrap-vs2

解决：

conda run -p /data/<username>/miniforge3/envs/ViWrap-vs2 virsorter config --init-source --db-dir=/data/example/ViWrap_db/VirSorter2_db

运行上面修改为合适目录的代码后输出的结果如下：

#(base) stu50@ubuntuserver:/data/temp_software/ViWrap$ # 用实际路径运行命令，无需依赖环境名称
#(base) stu50@ubuntuserver:/data/temp_software/ViWrap$ conda run -p /data/temp_software/miniforge3/envs/ViWrap-vs2 virsorter config --init-source --db-dir=/data/example/ViWrap_db/VirSorter2_db
#[2025-07-11 19:17 INFO] VirSorter 2.2.4
#[2025-07-11 19:17 INFO] /data/temp_software/miniforge3/envs/ViWrap-vs2/bin/virsorter config --init-source --db-dir=/data/example/ViWrap_db/VirSorter2_db
#[2025-07-11 19:17 INFO] saving /data/example/ViWrap_db/VirSorter2_db as DBDIR to config file /data/temp_software/miniforge3/envs/ViWrap-vs2/lib/python3.10/site-packages/virsorter/template-config.yaml
#(base) stu50@ubuntuserver:/data/temp_software/ViWrap$

4. 运行测试任务

进入“reads_1.fastq.gz”和“reads_2.fastq.gz”的目录下，运行：

ViWrap run  --input_metagenome test_metaG.fasta \
            --input_reads reads_1.fastq.gz,reads_2.fastq.gz \
            --out_dir  test_metaG_ViWrap_out2 \
            --db_dir /data/example/ViWrap_db \
            --identify_method vb-vs \
            --conda_env_dir /data/<username>/miniforge3/envs/ \
            --threads 20 \
            --input_length_limit 5000

如果先前安装虚拟环境出现问题，这里也可以直接使用我们预先部署好的虚拟环境，指定--conda_env_dir /data/example/miniforge3/envs.

Virome Analysis in Metagenomics: Hands‐on Practice with ViWrap - BGIGPD/BestPractices4Pathogenomics GitHub Wiki

Virome Analysis in Metagenomics: Hands-on Practice with ViWrap

名词解释

注意：本protocol纵使当前能顺利运行，但随着一些包和软件的更新，可能有新的冲突和错误发生，以至于产生新报错。当出现这种情况时，可以关注Github等社区寻求解决方案。

ViWrap实操指南

1. 安装conda

1.1 本课程提供了conda的安装包，路径如下

1.2 把 `/data/Miniconda3-latest-Linux-x86_64.sh` 安装到 `/data/<username>/` 目录下。

1.3 进入安装包所在目录，然后先创建你的conda安装目录

1.4 运行安装脚本，指定安装目录

1.5 安装完成后，你可以验证

1.6 查看你的~/.bashrc

1.7 初始化conda命令

1.8 重新加载你的shell配置文件

1.9 再次查看你的~/.bashrc吧！

1.10 现在享受直入conda便利吧！

2. ViWrap的准备工作

2.1 先建立/返回好自己的文件夹

2.2 克隆项目仓库，克隆在“/data/”

2.3 然后进入你的克隆下来的项目仓库里面：

3. 部署ViWrap以及各个分析模块的虚拟环境

3.1 主程序ViWrap的环境

分析所需数据库的下载与安装（跳过）

问题报错：

解决：

4. 运行测试任务

⚠️ GitHub.com Fallback ⚠️

Virome Analysis in Metagenomics: Hands‐on Practice with ViWrap - BGIGPD/BestPractices4Pathogenomics GitHub Wiki

Virome Analysis in Metagenomics: Hands-on Practice with ViWrap

名词解释

注意：本protocol纵使当前能顺利运行，但随着一些包和软件的更新，可能有新的冲突和错误发生，以至于产生新报错。当出现这种情况时，可以关注Github等社区寻求解决方案。

ViWrap实操指南

1. 安装conda

1.1 本课程提供了conda的安装包，路径如下

1.2 把 /data/Miniconda3-latest-Linux-x86_64.sh 安装到 /data/<username>/ 目录下。

1.3 进入安装包所在目录，然后先创建你的conda安装目录

1.4 运行安装脚本，指定安装目录

1.5 安装完成后，你可以验证

1.6 查看你的~/.bashrc

1.7 初始化conda命令

1.8 重新加载你的shell配置文件

1.9 再次查看你的~/.bashrc吧！

1.10 现在享受直入conda便利吧！

2. ViWrap的准备工作

2.1 先建立/返回好自己的文件夹

2.2 克隆项目仓库，克隆在“/data/”

2.3 然后进入你的克隆下来的项目仓库里面：

3. 部署ViWrap以及各个分析模块的虚拟环境

3.1 主程序ViWrap的环境

分析所需数据库的下载与安装（跳过）

问题报错：

解决：

4. 运行测试任务

⚠️ **GitHub.com Fallback** ⚠️

1.2 把 `/data/Miniconda3-latest-Linux-x86_64.sh` 安装到 `/data/<username>/` 目录下。

⚠️ GitHub.com Fallback ⚠️