企业官网建设流程全解析

简介：这份压缩包是PyPI官方发布的HiCExplorer-1.8.1.tar.gz Python库，专注于Hi-C高通量测序数据的三维基因组分析，面向生物信息学科研人员、基因组学方向学生及想深入了解Hi-C分析流程的Python开发者。包内总计58个文件，核心为33个Python源码模块，涵盖数据预处理、质量控制、交互矩阵构建、TAD结构域识别、富集区域检测及可视化等主要功能；另有4个文本说明文件、2个包元数据文件和多个可执行命令行脚本，便于直接调用或嵌入自有流程。整个资源仅128KB，代码精简、组织清晰，非常适合对照源码学习算法实现和命令行工具设计。目前已有207人学习下载，是快速理解Hi-C数据分析管线、开展二次开发或教学演示的实用资料。通过拆解源码，读者可以理清Hi-C数据从原始读段到交互热图、结构域检测的完整链条，并借鉴PyPI库的标准打包方式。

1. 为什么今天还要从 PyPI 官网下载 HiCExplorer-1.8.1.tar.gz

如果你接过一条几年前跑通的 Hi-C 分析流程，大概率会跟我一样，先被要求在 PyPI 官网下载 HiCExplorer-1.8.1.tar.gz，再用它复现一组旧图旧表。这个版本的下载入口到今天还在，文件也确实是 tar.gz 源码包，但把它装到现在的 Linux 服务器上，比想象中折腾得多：它依赖 Python 2.7，依赖一批已经停止维护的旧版科学计算库，直接 pip install 会在依赖解析阶段就翻车，还有人为了图省事装错过 sklearn 占位包。这篇文章会把“这个包是什么、从 PyPI 官网下载后怎么装、参数怎么调、坑在哪”讲清楚。适合生物信息工程师、HPC 管理员，以及任何被旧流程卡住的人。

2. HiCExplorer 1.8.1 是什么：一套接触矩阵工作流

2.1 一个 tar.gz 里装着一整套 hic* 命令

HiCExplorer 不是单个命令，而是一组用于 Hi-C 数据处理的工具集合。解压 HiCExplorer-1.8.1.tar.gz 之后，包内是 Python 包和一批可执行脚本，几乎都以 hic 开头。常见的核心工具大致如下：

所以 1.8.1 这个 tar.gz 本质上是一条完整 Hi-C 分析链路的起点：先用 hicBuildMatrix 把 BAM 转成接触矩阵，再用 hicCorrectMatrix 归一化，之后根据研究目标走 hicFindTADs 或 hicPCA，最后用 hicPlotDistVsCounts 和 hicConvertFormat 做质量检验与格式对接。整个流程在当下依然说得通，唯一的门槛是它出生在 Python 2 时代。

2.2 1.8.1 的版本边界：Python 2 时代与依赖上限

1.8.1 属于 HiCExplorer 的旧版本线，默认解释器是 Python 2.7。这意味着今天任何“新装 Python 3 之后直接 pip install”的思路，在它身上都不成立。更麻烦的是它的间接依赖也有明确上限：numpy 在 Python 2 上的最终版本是 1.16.6，scipy 建议用 1.2.x，pandas 用 0.24.x，matplotlib 用 2.2.x，scikit-learn 用 0.20.x。一旦 pip 把某个依赖解析成新版，import 阶段就会报语法错误或直接报找不到模块。

这也是我在很多机器上反复看到的现象：有人把 HiCExplorer-1.8.1.tar.gz 下载下来，在自己笔记本上装了一晚上没成功，核心原因不是源码包坏了，而是新旧依赖混在一个环境里。1.8.1 不是不能装，而是必须按它的年代来对待：Python 2.7 解释器、旧版 numpy 全家桶、C 扩展依赖的开发头文件，三者缺一不可。如果只是临时跑一个矩阵，建议直接去装新版本；如果你要复现旧论文结果、对齐旧流程，或者团队内部约定必须用 1.8.1，那才值得把这条老链路完整搭起来。

2.3 装 1.8.1 前先做三个判断

动手之前，我一般先让读者回答三个问题，能帮你少走弯路：

1. 你要对比的旧结果是不是 1.8.1 跑出来的？如果是，版本必须锁定；如果不是，直接上 3.x 系列更省事。
2. 你的服务器能不能建 Python 2.7 环境？Linux x64 上 conda 还能解决，macOS ARM 基本没戏。
3. 你后续要不要把矩阵交给 cooler、Juicebox 这类的现代工具？如果要，hicConvertFormat 能否在这个老版本里正常工作也需要提前验证。

这三个判断对应的是选型问题，不是安装问题。团队里如果只是“某条旧流程需要跑完”，那 1.8.1 值得装；如果“想用 Hi-C 分析但还没定方案”，别从历史版本开始。这个区分很重要，因为老版本不是更好的版本，它只是“能复现当时结果”的版本。

3. 从 PyPI 官网下载 HiCExplorer-1.8.1.tar.gz 并准备安装环境

3.1 用 pip download 从 PyPI 官网拿 tar.gz 源码包

最常见的做法是打开 PyPI 官网，在 HiCExplorer 项目页面选择 1.8.1 版本，然后下载 HiCExplorer-1.8.1.tar.gz。这个操作没有问题，但在命令行环境里我更推荐用 pip download，因为可以同时拿到一个干净的源码包，还不会触发依赖安装：

mkdir -p ~/hic_src && cd ~/hic_src pip download --no-binary :all: --no-deps HiCExplorer==1.8.1 -d ./ tar -tzf HiCExplorer-1.8.1.tar.gz | head -30

这里的--no-binary :all:意思是只接受源码包，不接受 wheel，确保最终落到磁盘的是 tar.gz 而不是编译好的二进制包；--no-deps表示不下载依赖，因为 1.8.1 的依赖版本必须手动控制。tar -tzf只是列出压缩包内的文件名，不会解压，主要用来确认包里有 setup.py、包目录和文档，而不是拿错一个空壳文件。

如果你是在 Python 3 环境里执行上面这条命令，没有问题。这里只下载不安装，下载完成后在系统里没有留下任何包记录。对比下来，比用浏览器手工找文件更可控：文件版本、文件名、下载目录都清楚，以后想推到内网也有源文件。

3.2 用 Conda 建 Python 2.7 环境并固定 pip 版本

拿到 tar.gz 之后，第一步不是解压安装，而是准备一个干净的 Python 2.7 环境。直接在系统 Python 3 里跑的结局几乎都是失败，因为 1.8.1 的源码是 Python 2 语法。我一般用 Conda 建一个独立环境，Linux x64 上很顺：

conda create -n hic_18 python=2.7 -y conda activate hic_18 conda install -n hic_18 pip=20.3.4 -y python -V pip -V

这里python=2.7是关键约束。Conda 在 Linux x64 上还能解析到这个老版本；如果你在 macOS ARM 上执行，基本会失败，建议直接换 x64 服务器。pip=20.3.4是最后一个支持 Python 2 的 pip 版本，不锁版本的话，conda 可能给你装一个新版 pip，进入环境后任何 pip 操作都会直接语法报错。

python -V和pip -V是安装前的双确认。很多翻车现场都是因为 conda activate 没生效，命令行的python仍然指向系统默认解释器。如果which python出来的路径不是你新建的 conda 环境，后面每一步都白做。

3.3 先锁旧版科学计算依赖，再装本体的安装顺序

依赖安装顺序是我认为整个流程里最值得抄的部分。不要直接运行pip install HiCExplorer==1.8.1，因为 pip 会自作主张去解析最新依赖，然后在 Python 2.7 环境里把版本解析到崩溃。正确做法是先把所有间接依赖按旧版本装好，再装本体：

pip install "numpy==1.16.6" "scipy==1.2.3" "matplotlib==2.2.5" \ "pandas==0.24.2" "scikit-learn==0.20.4" pyBigWig pysam

这些版本不是随手写的，它们是 Python 2 生命周期最后期的可用版本：numpy 1.16.6 是支持 py2.7 的最后一个 numpy 版本，pandas 0.24.2 和 matplotlib 2.2.5 也是同理；scipy 用 1.2.3 在生物信息场景下兼容性最稳。pyBigWig 和 pysam 没有锁版本，因为它们的安装主要取决于系统有没有 zlib、openssl 开发库，版本本身相对宽容。

这个顺序的核心逻辑是“先满足依赖，再安装本体”。装完上面这行，再跑pip install HiCExplorer==1.8.1时，pip 发现所有依赖都满足，就不会做多余解析。如果你在安装 pyBigWig 或 pysam 时看到编译报错，先不要怀疑命令，回到系统层面检查zlib1g-dev和libssl-dev是否安装，这是这两个包最常见的前置条件。

4. 编译安装 HiCExplorer-1.8.1.tar.gz：setup.py 安装与入口验证

4.1 解压并执行 pip install ./：为什么不用 setup.py install

依赖装好之后，进入源码包执行安装。这里有一个选择：是运行python setup.py install还是pip install ./。我的建议是后者。虽然两者最终都会把包放进 site-packages，但 pip 安装会保留安装记录，也会把 hic* 命令脚本正确放进 conda 环境的 bin 目录；直接 setup.py install 在老 setuptools 下有时不会生成命令行入口，装完找不到命令又要返工。

cd ~/hic_src tar -xzf HiCExplorer-1.8.1.tar.gz cd HiCExplorer-1.8.1 pip install ./

安装过程中，终端会滚过大量日志。如果出现 warning，比如 C 扩展编译时关于旧 API 的提示，不用管；出现error:才需要停下排查，常见的是 gcc 找不到头文件，或者某个依赖版本没装对，回到第 3 章重新确认。另外要注意，整个安装过程是在hic_18这个 conda 环境激活状态下执行的，pip 对应的是环境内的 pip 20.3.4，这一点直接决定安装是否落位。

装完不要急着跑真实数据。先做入口验证，再跑最小参数，这是我每次装这种老工具都坚持的步骤，能省掉后面大量“命令不存在”或“import 失败”的排查时间。

4.2 用 which 与 --help 验证命令入口和 import 路径

安装完成后，先验证命令行入口：

which hicBuildMatrix hicBuildMatrix --help 2>&1 | head -40 python -c "import hicexplorer; print(hicexplorer.__file__)"

which hicBuildMatrix应该输出$CONDA_PREFIX/bin/hicBuildMatrix这类路径。如果输出的是系统目录，说明安装时不在 conda 环境内，或者 PATH 里存在另一个更早的版本，需要先处理干净。hicBuildMatrix --help是最直接的安装成功标志：能打印出--samFiles、--binSize、--restrictionSequence、--outFileName、--threads这些参数，说明脚本入口和 import 链路都正常。

最后一条import hicexplorer是检查包有没有装错解释器。打印出的路径必须指向hic_18环境的 site-packages；如果打印的是/usr/lib/python3/dist-packages/...，说明这个包在系统 Python 3 里也装了一份，而 Python 2.7 环境根本没有加载到它。这种情况比找不到模块更难排查，因为你以为装过了，实际是装到别的解释器里去了。

4.3 用最小参数跑通 hicBuildMatrix：参数表与调参顺序

入口验证通过后，用一个小 BAM 文件跑一次 hicBuildMatrix，确认工具链能真正进入数据处理流程。命令如下：

hicBuildMatrix --samFiles sample_hic.bam --binSize 10000 \ --restrictionSequence AAGCTT --restrictionCutSite AAGCT \ --outFileName sample_1_8.h5 --threads 8

参数含义如下：

第一次跑的时候，建议准备一个很小的 BAM，比如只包含一条染色体前几十万个 read 的测试文件，跑通即可，别直接上全基因组数据。真实 Hi-C 样本的 BAM 动辄几十 GB，hicBuildMatrix 对 BAM 解析和目标矩阵构建都很吃内存，最小验证和真实运行是两回事。

如果这里的--restrictionSequence或--restrictionCutSite和你实际建库用的酶不一致，矩阵会出现大量背景 noise，最典型的表现是距离衰减曲线不平滑。这个问题经常被误认为软件 bug，其实只是酶切参数写错了。调整顺序也很简单：先确认建库 protocol，再填参数，最后再跑图。

5. 安装与运行 HiCExplorer 1.8.1 的 5 个常见坑与排查

5.1 Python 3 环境直接 pip install，import 时崩溃

现象：在系统默认 Python 3 环境里执行pip install HiCExplorer==1.8.1，过程看起来成功，但运行python -c "import hicexplorer"就报错，有的报语法错误，有的报缺少模块。

原因：1.8.1 的源码还是 Python 2 语法，Python 3 解释器在 import 阶段就过不去。pip 安装成功只是把文件放进了 site-packages，并不代表这个包能在当前解释器运行。

解决：把安装和运行全部放到 conda 的 Python 2.7 环境里；Python 3 环境只用来执行 pip download 下载 tar.gz，不要用它安装 1.8.1。这也是我前面强调环境隔离的原因，旧包必须用旧解释器。

5.2 sklearn 与 scikit-learn 的包名陷阱

现象：依赖装完之后，跑 hicPCA 或 hicFindTADs 报ImportError: No module named sklearn，可是pip list里明明有 sklearn。

原因：PyPI 上 sklearn 是一个弃用占位包，真正的实现要装 scikit-learn。老项目的依赖说明里如果写成了 sklearn，很容易让人照单全装。PyPI 的提示语说得很直白，sklearn 这个包已经废弃，该装的是 scikit-learn。

解决：先pip uninstall -y sklearn，再pip install "scikit-learn==0.20.4"。装完后用python -c "import sklearn; print(sklearn.__file__)"确认模块路径存在。这个教训可以推广到所有旧项目：看到一个包名和 import 名不完全一致时，先查 PyPI 页面提示，别直接装。

5.3 新 GCC 编译 pyBigWig 或 pysam 时缺头文件

现象：安装 pyBigWig 或 pysam 时，编译日志最后一行是error: command 'gcc' failed with exit status 1，往上翻能看到zlib.h: No such file or directory，或者 openssl 相关头文件缺失。

原因：这两个包都是 C 扩展，需要系统有 zlib 和 openssl 的开发头文件。新装的 Ubuntu/Debian 服务器默认只有 runtime 库，没有-dev包；新版 GCC 编译老代码时报错也更明显。

解决：Ubuntu/Debian 执行apt-get install zlib1g-dev libssl-dev，RHEL 系执行yum install zlib-devel openssl-devel。也可以在 conda 环境里直接conda install -c conda-forge zlib openssl，再重装 pyBigWig 和 pysam。装完头文件后记得退出当前 Python 重新进入，再 import 测试。

5.4 Conda 建 python=2.7 环境卡死或失败

现象：执行conda create -n hic_18 python=2.7 -y后，终端一直在 Solving environment 转圈，几十分钟没有结果，有时直接报PackagesNotFoundError。

原因：新版 Conda 默认的经典 solver 在解析 Python 2.7 这种老包时，要回溯大量历史依赖，效率很低；python 2.7 也不在默认 channel 的活跃列表里，需要 conda-forge 提供。

解决：先把 solver 切到 libmamba：conda config --set solver libmamba，再重新执行 create 命令；或者直接用 mamba：mamba create -n hic_18 python=2.7 -y。如果还是失败，显式加 channel：conda create -n hic_18 python=2.7 pip=20.3.4 -c conda-forge -y。这个坑在新机器上特别常见，不是你的命令写错，是 solver 太慢。

5.5 hicBuildMatrix 不认 BAM 或矩阵缺染色体

现象：同一个 BAM 文件用其它比对流程处理都没问题，喂给 hicBuildMatrix 后提示 Invalid sam header，或者生成的矩阵里染色体数量明显少于预期。

原因：HiCExplorer 对 BAM 的 header 要求比较严格，@SQ 里的染色体命名风格必须统一，chr1和1混用会导致无法匹配；如果 BAM 经过下游工具重排或过滤，配对 read 的位置关系也可能破坏 hicBuildMatrix 的解析假设。

解决：回到比对后的原始 BAM，先用samtools view -H检查 header 里的 @SQ 列表；必要时用samtools sort重排并重新建立索引。染色体命名问题要在比对阶段就固定参考基因组，不能在矩阵构建阶段靠改名补救。

6. 装好不一定能用：先跑一张距离衰减图再迁移

6.1 用 hicPlotDistVsCounts 做第一张结果图

安装完成后，我一般不会直接跑全流程，而是先输出一张距离衰减图，用来验证矩阵质量。命令很简单：

hicPlotDistVsCounts --matrix sample_1_8.h5 --plotFile dist_1_8.png

这张图的横轴是 read 对之间的线性距离，纵轴是信号强度。正常 Hi-C 数据会呈现平滑下降的曲线；如果曲线在某个距离突然断掉，或者远距离信号抬升，基本可以推断矩阵构建时的酶切参数、bin 大小或 BAM 输入有问题。这一步能一次性暴露第 4.3 节里那些参数错误，比直接跑 TAD 检测省事很多。

6.2 与新版交叉验证并保留旧版本

1.8.1 跑通之后，我的建议是不要把它当成唯一工具链长期使用，而是把新版本同时装起来做交叉验证。新旧版本对同一份 BAM 构建出的矩阵在整体结构上应该相近，但 TAD 边界、compartment 得分会有细微差异，这是算法迭代的正常结果。要判断你的旧结果可信，就把 1.8.1 的结果和新版结果叠在一张图上对比。

输出环节用 hicConvertFormat 把 .h5 转成 .cool，可以继续接 cooler 生态做可视化。这样既保住了旧流程的复现能力，又没有被老版本绑定死。我的习惯是给每个流程目录写清楚 HiCExplorer 版本、Python 版本、核心依赖版本和距离衰减图路径，防止三个月之后自己都说不清这个矩阵是哪个版本产出的。这个习惯已经帮我避免过好几次复现翻车，希望也帮到你。

本文还有配套的精品资源，点击获取