基于hi-c数据的大基因组重组。
instagraal的Python项目详细描述
安装
基于hi-c数据的大基因组重组(graal的继续和部分重写)和支架后抛光库。
这项工作正在不断发展/改进中-有关基本原则的信息,请参见graal。
安装
从pypi安装:
sudo pip3 install -U instagraal
或者,如果您想获得最新版本:
sudo pip3 install -e git+https://github.com/koszullab/instagraal.git@master#egg=instagraal
这将自动处理大多数依赖项。
要求
scaffolder和抛光库是用python 3和cuda编写的。因此,需要NVIDIA图形卡才能运行脚手架。python2的python2
分支提供了python2版本,但是要注意开发将主要关注python 3版本。该软件已经在Ubuntu17.04和更高版本上测试过了,大多数依赖项都可以通过它的包管理器(或者Python的pip
)下载。
外部库
您需要下载并安装nvidia cuda工具包。建议手动安装-从ubuntu的包管理器安装nvidia cuda toolkit会导致故障。由于安装向导的帮助,它在OSX上相当简单。下面是如何在ubuntu 18.04上快速完成的:
wget https://developer.nvidia.com/compute/cuda/10.0/Prod/local_installers/cuda_10.0.130_410.48_linux chmod +x cuda_10.0.130_410.48_linux sudo ./cuda_10.0.130_410.48_linux
注意ubuntu用户:请注意,如果安装脚本不是以根用户身份运行,或者图形实例(例如x)也在运行,则安装脚本将失败。您可能需要暂时关闭它,例如切换到tty1并运行以下命令(在安装脚本之前):
sudo service lightdm stop
(将lightdm
替换为mdm
,gdm
或机器上出现的任何登录管理器(如果失败);如果所有其他登录管理器也失败,则可能需要运行类似于sudo pkill xorg
的操作。)
OS X用户注意事项s:目前mojave(10.14)上没有cuda支持,也不清楚何时添加,是否要添加。这意味着instagraal(或者任何基于cuda的应用程序)将而不是在mojave上工作。如果您想在OSX上运行它,目前唯一的解决方案是降级到High Sierra(10.13)。
推荐的库
由于某些python依赖项(如pyopengl
或h5py
)需要针对特定文件构建,因此如果遇到错误,建议您安装以下软件包。
OpenGL库
libglu1台面
libxi dev
libxmu dev
libglu1 mesa dev
FreeGLUT3开发人员
hdf5序列化库
hdf5工具
(hdf5
用于brew中的os x)
增强库
libboost all dev
(boost
和boost python
用于brew中的os x)
python依赖项
libglu1台面
libxi dev
libxmu dev
libglu1 mesa dev
FreeGLUT3开发人员
hdf5工具
(hdf5
用于brew中的os x)
增强库
libboost all dev
(boost
和boost python
用于brew中的os x)
python依赖项
python包需求应该由pip
自动处理,但是您应该
要手动安装,请执行以下操作:
numpy
scipy
matplotlib
codepy
h5py
pyopengl
docopt
biopython
也可以使用repo中提供的需求文件轻松安装它们:
pip3 install -Ur requirements.txt
您还需要使用opengl支持构建pycuda
,并禁用其自定义boost库。直接从pypi安装它将在运行时导致错误。下面是如何在ubuntu或os x上使用git手动完成的:
git clone --recurse-submodules https://github.com/inducer/pycuda.git
cd pycuda
python3 configure.py --cuda-enable-gl --no-use-shipped-boost
sudo python3 setup.py install
你可以以根用户的身份运行instagraal安装程序,这是一个一体化的脚本,可以处理以上对ubuntu 17+的依赖性。
容器
Instagraal有实验性的Docker支持。您可以通过运行以下命令获取相应的图像:
docker pull koszullab/instagraal
如何使用
与graal不同,它是从命令行运行的。
用法
instagraal <hic_folder> <reference.fa> [<output_folder>]
[--level=4] [--cycles=100] [--coverage-std=1]
[--neighborhood=5] [--device=0] [--circular] [--bomb]
[--save-matrix] [--pyramid-only] [--save-pickle] [--simple]
[--quiet] [--debug]
选项
-h, --help Display this help message.
--version Display the program's current version.
-l 4, --level 4 Level (resolution) of the contact map.
Increasing level by one means a threefold smaller
resolution but also a threefold faster computation
time. [default: 4]
-n 100, --cycles 100 Number of iterations to perform for each bin.
(row/column of the contact map). A high number of
cycles has diminishing returns but there is a
necessary minimum for assembly convergence.
[default: 100]
-c 1, --coverage-std 1 Number of standard deviations below the mean.
coverage, below which fragments should be filtered
out prior to binning. [default: 1]
-N 5, --neighborhood 5 Number of neighbors to sample for potential
mutations for each bin. [default: 5]
--device 0 If multiple graphic cards are available, select
a specific device (numbered from 0). [default: 0]
-C, --circular Indicates genome is circular. [default: False]
-b, --bomb Explode the genome prior to scaffolding.
[default: False]
--pyramid-only Only build multi-resolution contact maps (pyramids)
and don't do any scaffolding. [default: False]
--save-pickle Dump all info from the instaGRAAL run into a
pickle. Primarily for development purposes, but
also for advanced post hoc introspection.
[default: False]
--save-matrix Saves a preview of the contact map after each
cycle, in csv format. [default: False]
--simple Only perform operations at the edge of the contigs.
[default: False]
--quiet Only display warnings and errors as outputs.
[default: False]
--debug Display debug information. For development purposes
only. Mutually exclusive with --quiet, and will
override it. [default: False]
输入数据集
格式规范
作为参数传递给instagraal的上述<;hic_folder>;
需要三个文件:
- 名为
abs_fragments_contacts_weighted.txt的文件,包含(稀疏)hi-c映射本身。第一行必须是
id_frag_a id_frag_b n_contact
。所有后续行必须以坐标格式表示地图的联系人(id_frag廑a
是行索引,id_frag廑b
是列索引,n廑u contact
是每个轨迹或索引对之间的联系人数量,例如,如果在下注中发现5个联系人在片段2和3之间,应该有一行代码在文件中读取235
)。n_contact
必须是整数。列表应首先根据id\u frag_a
进行排序,然后根据id\u frag_b
进行排序。片段ID从0开始。 - 一个名为
fragments\u list.txt的文件,包含与基因组每个片段相关的信息。第一行必须是
id chrom start_pos end_pos size gc_content
,随后的行(表示片段本身)应遵循该模板。这些字段应该是不言而喻的;值得注意的是,chrom
可以是表示给定行上片段所属的染色体名称的任何字符串,并且当染色体名称更改时片段ID应该从1开始。除了chrom
字段和gc
字段(此版本中当前未使用且可以用任何值填充)之外,所有字段都应为整数。注意开始位置代码>从0开始。
- 一个名为info-contigs.txt的文件,包含与基因组中每个contig/scaffold/染色体相关的信息。第一行必须是
contig length_kb n_frags cumul_length
。字段名也应该是不言而喻的;当然,contig字段必须包含与fragments\u list.txt
中找到的名称一致的名称。而且length_kb
应该是一个整数(如果需要,向上或向下取整),并且n_frags
和cumul_length
应该彼此一致,因为contig n的累积长度(片段中)应该等于ags用于前面的n-1行。请注意,cumul\u length
从0开始。
所有字段(包括文件头中的字段)必须用制表符分隔。
示例
文件夹中提供了最少的工作模板。
矩阵生成
如果您想从头开始生成Instagraal兼容矩阵(即从读取和参考基因组中生成,而不是从众多现有格式中的现有HI-C数据中生成),可以使用充当BO的hicstuffhicstuff。一个python库和一个管道。a还提供图形界面。指令、参数和可选参数在repo的自述文件中有详细说明。
输出
在scaffolder完成运行之后,无论您指定为输出的路径是什么,它都将包含一个test-mcmc-x
目录,其中x是执行scaffolding的级别(分辨率)。此目录依次包含以下内容:
genome.fasta
:构建的基因组。支架将通过增加碎片中的尺寸来订购,这大致(但并不总是)转化为增加bp中的尺寸。info-frags.txt
:一个文件,对于每个新形成的脚手架,该文件包含脚手架中每个箱子的原始坐标,格式为染色体、id、方向、开始、结束
。每个箱子都有一个唯一的id,可以方便地跟踪连续拉伸。方向是相对的,当提供"-1"时,应理解为应采用反向补码。
其他文件主要用于开发目的,并跟踪各种度量和模型参数的演变。
抛光
通过手工或使用脚本编辑info\u frags.txt
文件,可以更正输出基因组中存在的延迟工件。通过运行以下命令查看选项:
sudo pip3 install -U instagraal0
最常见的用例是一次运行所有抛光过程:
sudo pip3 install -U instagraal1
故障排除
加载CUDA库
如果遇到以下错误,尽管已安装nvidia cuda工具包:
sudo pip3 install -U instagraal2
这可能意味着由于某种原因,cuda相关库没有正确添加到您的$path
中。一个快速的解决方案是在.bashrc
或.bash_profile
的末尾添加此选项(用安装工具包的位置替换路径,并相应地更改版本号):
sudo pip3 install -U instagraal3
远程运行
如果遇到以下错误:
sudo pip3 install -U instagraal4
这很可能意味着您试图远程运行instagraal实例(例如通过ssh),但没有配置正确的$display
变量。为了避免这种情况,只需事先运行以下命令:
sudo pip3 install -U instagraal5
请注意,这将禁用电影(它将在远程计算机上播放)。
然而,instagraal是基于opengl的,这意味着无论怎样,你的目标机器上都必须有一个x服务器。虽然这允许漂亮的电影和可视化,但它可能证明在您无法完全控制的环境中有问题,例如,服务器群集。目前,最好的办法是让目标计算机的系统管理员设置一个x实例(如果他们还没有设置的话)。
代码复制工具链
如果遇到如下错误:
sudo pip3 install -U instagraal6
您需要直接从git存储库安装codepy,以获得比pypi上的版本更新的版本。运行以下命令:
sudo pip3 install -U instagraal7
您还需要更新到gcc/g++8:
sudo pip3 install -U instagraal8
之后应该可以直接工作。
一般提示
Instagraal将尝试检测HDF5格式的已构建金字塔,但如果由于某种原因中断构建,并且重新运行金字塔构建步骤,HDF5文件仍将存在,但已损坏。您需要手动删除
金字塔文件夹,然后重试。
如果您安装的CUDA版本与Instagraal似乎依赖的版本不匹配(e.g.您安装了CUDA 10,但Instagraal抱怨它找不到libcurand.so.9.1),请尝试使用E>--无缓存目录选项。
如果您使用conda处理依赖关系,例如未能生成
pycuda
可能会遇到问题,因为安装libboost all dev
时可能会出现一些头文件无法自动识别。如果您不想手动干扰$path
,那么最好完全停用conda,并使用操作系统的普通包管理器(以及pip
)安装所有内容。
文档
作为一个python包,instagraal提供了一个脚手架和抛光库,以及一个方便的hi-c矩阵处理框架,我们已经尝试在readthedocs上公开了其中的大部分api。如果您想了解更多有关脚手架工作原理的信息,请参阅参考资料,尤其是补充方法,深入了解模型的详细信息。
参考文献
原理
- 使用染色体接触数据的高质量基因组组装,HervéMarie Nelly,Material Marbouty,Axel Cournac,Jean Fran_ois Flot,Gianni Liti,Dante Poggi Parodi,Sylvie Syan,Nancy Guillén,Antoine Margeot,Christop何齐默和罗曼·科苏尔,《自然通讯》,2014年
- 利用高通量染色体构象捕获数据进行基因组组装的概率方法,HervéMarie Nelly,2013,博士论文
用例
- 两株里氏木霉基因组的邻近连接支架和比较Rique Bidard,生物燃料生物技术,2017年
- 通过近距离连接(染色体捕获)分析构建细菌基因组并探测肠道微生物组中的宿主病毒相互作用,Marbouty、Lyam Baudry、Axel Cournac和Romain Koszul,科学进展,2017年