Topaz

一个使用卷积神经网络从正样本和未标记样本中训练，用于冷冻电子显微镜图像中进行粒子检测的流程。Topaz还包括使用深度去噪模型对显微图和断层图进行去噪的方法。

请查看我们的讨论部分，获取使用Topaz的一般帮助、建议和技巧。您也可以在这里找到我们的文档网站。

v0.2.5 新功能

添加了Relion集成脚本
Topaz extract现在可以将粒子坐标写入每个输入显微图的一个文件中
在3D去噪后添加了高斯滤波选项
添加了Topaz工作坊的信息
更新了Topaz图形用户界面
修复了各种bug

v0.2.4 新功能

添加了使用__topaz denoise3d__进行3D去噪的功能和两个预训练的3D去噪模型
为多线程命令添加了设置线程数的参数
更新了Topaz图形用户界面
修复了各种bug

v0.2.3 新功能

改进了预训练的去噪模型
Topaz现在包含预训练的粒子拾取模型
更新了教程
更新了图形用户界面以包含去噪命令
去噪论文预印本可在这里查看

v0.2.2 新功能

Topaz论文已发表，可在这里查看
修复了bug并更新了图形用户界面

v0.2.0 新功能

Topaz现在支持最新版本的pytorch (>= 1.0.0)。如果您为旧版本的topaz安装了pytorch，需要进行升级。详情请参见安装说明。
添加了__topaz denoise__命令，用于使用神经网络对显微图进行去噪。
改进了图形用户界面的可用性。

先决条件

支持CUDA的Nvidia GPU，用于GPU加速。
基本的Unix/Linux知识。

安装

<details><summary>（推荐）点击这里使用Anaconda安装</summary>

如果您没有Anaconda Python发行版，请按照他们网站上的说明进行安装。

我们强烈建议将Topaz安装到单独的conda环境中。要为Topaz创建一个conda环境：

conda create -n topaz python=3.6 # 如果您喜欢Python 2，可以使用2.7
source activate topaz # 这会切换到topaz conda环境，如果anaconda版本 >= 4.4且配置正确，可以使用'conda activate topaz'
# source deactivate # 返回到基础conda环境

有关conda环境的更多信息可以在这里找到。

安装Topaz

要安装预编译的Topaz包及其依赖项（包括pytorch）：

conda install topaz -c tbepler -c pytorch

这会从官方渠道安装pytorch。要为特定CUDA版本安装pytorch，您需要添加'cudatoolkit=X.X'包。例如，要为CUDA 9.0安装pytorch：

conda install cudatoolkit=9.0 -c pytorch

或者将其合并为一个命令：

conda install topaz cudatoolkit=9.0 -c tbepler -c pytorch

有关pytorch安装的其他说明，请参见这里。

就是这样！Topaz现在已经安装在您的anaconda环境中了。

</details>

<details><summary>点击这里使用Pip安装</summary>

我们强烈建议将Topaz安装到_虚拟环境_中。请参见virtualenv的安装说明和用户指南。

安装Topaz

要为Python 3.X安装Topaz

pip3 install topaz-em

为Python 2.7安装

pip install topaz-em

有关pytorch安装的其他说明，包括如何为特定CUDA版本安装pytorch，请参见这里。

就是这样！Topaz现在已通过pip安装完成。

</details>

<details><summary>点击这里使用Docker安装</summary>

<details><summary>您是否已安装Docker？如果没有，请点击这里</summary>

Linux/MacOS （命令行）

下载并安装Docker 1.21或更高版本，适用于Linux或MacOS。

考虑使用Docker的"便捷脚本"进行安装（在您操作系统的Docker安装网页上搜索）。

根据您的Docker引擎说明启动docker，通常是 docker start。

注意： 您必须具有sudo或root权限才能安装Docker。如果您不希望以sudo/root身份运行Docker，则需要按照以下说明配置用户组：https://docs.docker.com/install/linux/linux-postinstall/

Windows （图形界面和命令行）

下载并安装适用于Windows的Docker Toolbox。

启动Kitematic。

如果在首次启动时Kitematic显示红色错误，建议您使用VirtualBox运行，请照做。

注意： 适用于MacOS的Docker Toolbox尚未经过测试。

Docker是什么？

这个教程解释了为什么Docker很有用。

</details>

提供了一个Dockerfile来构建具有CUDA支持的镜像。从github仓库构建：

docker build -t topaz https://github.com/tbepler/topaz.git

或下载源代码并从源目录构建

git clone https://github.com/tbepler/topaz
cd topaz
docker build -t topaz .

</details>

<details><summary>点击这里使用Singularity安装</summary> Topaz的预构建Singularity镜像可在此处获取，并可通过以下命令安装:

singularity pull shub://nysbc/topaz

然后，您可以在singularity镜像中运行topaz(需适当更改路径):

singularity exec --nv -B /mounted_path:/mounted_path /path/to/singularity/container/topaz_latest.sif /usr/local/conda/bin/topaz

<details><summary>点击此处从源代码安装</summary>

建议:将Topaz安装到Python虚拟环境中 关于如何设置虚拟环境，请参见https://conda.io/docs/user-guide/tasks/manage-environments.html 或 https://virtualenv.pypa.io/en/stable/。

安装依赖项

已在Python 3.6和2.7版本上测试

pytorch (>= 1.0.0)
torchvision
pillow (>= 6.2.0)
numpy (>= 1.11)
pandas (>= 0.20.3)
scipy (>= 0.19.1)
scikit-learn (>= 0.19.0)

使用conda可轻松安装依赖项

conda install numpy pandas scikit-learn
conda install -c pytorch pytorch torchvision

有关为您的CUDA版本安装pytorch的更多信息，请参见https://pytorch.org/get-started/locally/

下载源代码

git clone https://github.com/tbepler/topaz

安装Topaz

进入源代码目录

cd topaz

默认情况下，这将是最新版本的topaz源代码。要安装特定的旧版本，请检出该提交。例如，对于Topaz的v0.1.0版本:

git checkout v0.1.0

请注意，较旧的Topaz版本可能有不同的依赖项。请参阅特定Topaz版本的README。

将Topaz安装到您的Python路径中，包括topaz命令行界面

pip install .

要进行开发安装，请使用

pip install -e .

</details>

Topaz也可通过SBGrid获得。

教程

教程以Jupyter笔记本的形式呈现。请按照此处的说明安装Jupyter。

教程数据可以从这里下载。

要在您自己的系统上运行教程步骤，您需要安装Jupyter和用于可视化的matplotlib。

使用Anaconda可以通过以下方式完成:

conda install jupyter matplotlib

如果您使用anaconda安装了Topaz，请确保这些包安装在您的Topaz环境中。

用户指南

<details><summary>点击此处查看Topaz管道及其命令的描述</summary>

命令行界面的结构是一个单一的入口命令(topaz)，不同的步骤被定义为子命令。下面提供了一个一般使用指南，简要说明了颗粒拾取管道中最重要的子命令。

要查看所有子命令的列表及其简要描述，请运行topaz --help

图像预处理

降采样(topaz downsample)

建议在模型训练和预测之前对图像进行降采样和归一化。

降采样脚本使用离散傅里叶变换来降低图像的空间分辨率。可以这样使用:

topaz downsample --scale={降采样因子} --output={输出图像路径} {输入图像路径}

用法: topaz downsample [-h] [-s SCALE] [-o OUTPUT] [-v] file

位置参数:
  file

可选参数:
  -h, --help            显示此帮助消息并退出
  -s SCALE, --scale SCALE
                        降采样因子(默认: 4)
  -o OUTPUT, --output OUTPUT
                        输出文件
  -v, --verbose         打印信息

归一化(topaz normalize)

然后可以使用normalize脚本对图像进行归一化。此脚本拟合一个两分量高斯混合模型，并为每个图像添加一个额外的缩放乘数，以捕获碳膜像素并考虑曝光差异。然后通过将每个图像除以其缩放因子，再减去主要高斯混合分量的均值并除以其标准差来调整像素值。可以这样使用:

topaz normalize --destdir={存放归一化图像的目录} [图像文件列表]

用法: topaz normalize [-h] [-s SAMPLE] [--niters NITERS] [--seed SEED]
                       [-o DESTDIR] [-v]
                       files [files ...]

位置参数:
  files

可选参数:
  -h, --help            显示此帮助消息并退出
  -s SAMPLE, --sample SAMPLE
                        模型拟合的像素采样因子(默认: 100)
  --niters NITERS       模型拟合运行的迭代次数(默认: 200)
  --seed SEED           模型初始化的随机种子(默认: 1)
  -o DESTDIR, --destdir DESTDIR
                        输出目录
  -v, --verbose         详细输出

单步预处理(topaz preprocess)

可以使用preprocess脚本在一个步骤中完成降采样和归一化。

topaz preprocess --scale={降采样因子} --destdir={存放处理后图像的目录} [图像文件列表]

用法: topaz preprocess [-h] [-s SCALE] [-t NUM_WORKERS]
                        [--pixel-sampling PIXEL_SAMPLING] [--niters NITERS]
                        [--seed SEED] -o DESTDIR [-v]
                        files [files ...]

位置参数:
  files

可选参数:
  -h, --help            显示此帮助消息并退出
  -s SCALE, --scale SCALE
                        图像降采样的重缩放因子(默认: 4)
  -t NUM_WORKERS, --num-workers NUM_WORKERS
                        用于并行图像降采样的进程数(默认: 0)
  --pixel-sampling PIXEL_SAMPLING
                        模型拟合的像素采样因子(默认: 100)
  --niters NITERS       模型拟合运行的迭代次数(默认: 200)
  --seed SEED           模型初始化的随机种子(默认: 1)
  -o DESTDIR, --destdir DESTDIR
                        输出目录
  -v, --verbose         详细输出

模型训练

文件格式

训练脚本需要一个列出图像文件路径的文件和另一个列出颗粒坐标的文件。坐标从图像左上角开始索引。这些文件应该是制表符分隔的，带有以下标题:

图像文件列表

image_name	path
...

颗粒坐标

image_name	x_coord	y_coord
...

使用标记的颗粒训练区域分类器(topaz train)

使用topaz train命令训练模型。有关完整的训练参数列表，请参见

topaz train --help

分割和颗粒提取

图像分割（topaz segment，可选）

可以使用训练好的模型通过 topaz segment 命令对图像进行分割。

用法: topaz segment [-h] [-m MODEL] [-o DESTDIR] [-d DEVICE] [-v]
                     paths [paths ...]

位置参数:
  paths                 待处理图像文件的路径

可选参数:
  -h, --help            显示此帮助信息并退出
  -m MODEL, --model MODEL
                        训练好的分类器路径
  -o DESTDIR, --destdir DESTDIR
                        输出目录
  -d DEVICE, --device DEVICE
                        使用哪个设备，<0 对应 CPU（默认：如果可用则使用 GPU）
  -v, --verbose         详细模式

粒子提取（topaz extract）

可以直接从保存的分割图像中提取预测的粒子坐标（见上文），或者使用 topaz extract 命令通过训练好的模型在一个步骤中完成图像分割和粒子提取。

用法: topaz extract [-h] [-m MODEL] [-r RADIUS] [-t THRESHOLD]
                     [--assignment-radius ASSIGNMENT_RADIUS]
                     [--min-radius MIN_RADIUS] [--max-radius MAX_RADIUS]
                     [--step-radius STEP_RADIUS] [--num-workers NUM_WORKERS]
                     [--targets TARGETS] [--only-validate] [-d DEVICE]
                     [-o OUTPUT]
                     paths [paths ...]

位置参数:
  paths                 待处理图像文件的路径

可选参数:
  -h, --help            显示此帮助信息并退出
  -m MODEL, --model MODEL
                        训练好的子图像分类器路径，如果没有提供模型，输入图像必须已经分割
  -r RADIUS, --radius RADIUS
                        提取区域的半径
  -t THRESHOLD, --threshold THRESHOLD
                        终止区域提取的分数分位数阈值（默认：0.5）
  --assignment-radius ASSIGNMENT_RADIUS
                        预测和标记目标之间允许匹配的最大距离（默认：与提取半径相同）
  --min-radius MIN_RADIUS
                        调整半径参数时的最小区域提取半径（默认：5）
  --max-radius MAX_RADIUS
                        调整半径参数时的最大区域提取半径（默认：100）
  --step-radius STEP_RADIUS
                        搜索最佳半径参数时的网格大小（默认：5）
  --num-workers NUM_WORKERS
                        用于并行提取的进程数，0 表示使用主进程（默认：0）
  --targets TARGETS     指定粒子坐标的文件路径。用于找到使 AUPRC 最大化的提取半径
  --only-validate       仅计算验证指标的标志。不报告完整的预测列表
  -d DEVICE, --device DEVICE
                        使用哪个设备，<0 对应 CPU
  -o OUTPUT, --output OUTPUT
                        输出文件路径

该脚本使用非极大值抑制算法贪婪地选择粒子坐标，并从候选列表中移除附近的坐标。这个过程涉及两个额外的参数：

radius：被选中坐标周围该参数范围内的坐标会从候选列表中移除
threshold：指定停止提取的分数分位数阈值

给定一组已知的粒子坐标，可以通过寻找使平均精度分数最大化的半径来自动调整半径参数。在这种情况下，预测的坐标必须分配给目标坐标，这需要一个额外的距离阈值（--assignment-radius）。

选择最终粒子列表阈值（topaz precision_recall_curve）

使用 Topaz 提取的粒子仍然具有相关的分数，应通过选择高于某个分数阈值的粒子来确定最终的粒子列表。topaz precision_recall_curve 命令可以通过报告预测粒子坐标列表和已知目标坐标列表的精确率-召回率曲线来辅助这一过程。然后可以在一组保留的显微图上选择阈值来优化 F1 分数或特定的召回率/精确率水平。

用法: topaz precision_recall_curve [-h] [--predicted PREDICTED]
                                    [--targets TARGETS] -r ASSIGNMENT_RADIUS

可选参数:
  -h, --help            显示此帮助信息并退出
  --predicted PREDICTED
                        包含预测粒子坐标及其分数的文件路径
  --targets TARGETS     指定目标粒子坐标的文件路径
  -r ASSIGNMENT_RADIUS, --assignment-radius ASSIGNMENT_RADIUS
                        预测和标记目标之间允许匹配的最大距离

模型架构

目前，有几种可用于区域分类器的模型架构：

resnet8 [感受野 = 71]
conv127 [感受野 = 127]
conv63 [感受野 = 63]
conv31 [感受野 = 31]

ResNet8 在性能和感受野大小之间提供了良好的平衡。当需要较少复杂的模型时，Conv63 和 Conv31 可能是更好的选择。

基础层的单元数可以通过 --units 标志设置。ResNet8 在图像处理过程中进行步进时总是将单元数翻倍。Conv31、Conv63 和 Conv127 默认不这样做，但可以使用 --unit-scaling 标志来设置步进时单元数的乘法因子。

可以更改 conv* 模型的池化方案。默认不进行任何池化，但可以通过指定 "--pooling=max" 或 "--pooling=avg" 来使用最大池化或平均池化。

要查看架构的详细布局，请使用 --describe 标志。

训练方法

PN 方法选项将每个未标记为正（y=1）的坐标都视为负（y=0），然后优化标准分类目标： $$ \piE_{y=1}[L(g(x),1)] + (1-\pi)E_{y=0}[L(g(x),0)] $$ 其中 $\pi$ 是权衡正例和负例的参数，$L$ 是错误分类成本函数，$g(x)$ 是模型输出。

GE-binomial 方法选项将未标记为正（y=1）的坐标视为未标记（y=?），然后优化包含通用期望准则的目标，该准则旨在与小批量 SGD 配合良好。

GE-KL 方法选项将未标记为正（y=1）的坐标视为未标记（y=?），然后优化目标： $$ E_{y=1}[L(g(x),1)] + \lambdaKL(\pi, E_{y=?}[g(x)]) $$ 其中 $\lambda$ 是松弛参数（--slack 标志），指定对未标记数据上分类器期望与 $\pi$ 之间的 KL 散度的权重。

PU 方法使用 Kiryo 等人（2017）提出的目标函数。

半径

这设置了每个粒子坐标周围多少像素被视为正例，作为一种数据增强形式。这些坐标遵循一种分布，这种分布是在标记数据时选择哪个像素作为粒子中心的结果。应选择半径足够大，以覆盖可能被选择的像素的合理区域，但不要大到标记粒子外部的像素为正例。

Topaz GUI 中也内置了用户指南。

集成

Topaz 还与 RELION、CryoSPARC、Scipion 和 Appion 集成。您可以在以下位置找到信息和教程：

RELION：https://github.com/tbepler/topaz/tree/master/relion_run_topaz CryoSPARC：https://guide.cryosparc.com/processing-data/all-job-types-in-cryosparc/deep-picking/deep-picking

Scipion：https://github.com/scipion-em/scipion-em-topaz

参考文献

Topaz

Bepler, T., Morin, A., Rapp, M., Brasch, J., Shapiro, L., Noble, A.J., Berger, B. 冷冻电子显微镜图像中用于颗粒拾取的正-未标记卷积神经网络。自然方法 16, 1153–1160 (2019)。https://doi.org/10.1038/s41592-019-0575-8

<details><summary>Bibtex</summary>

@Article{Bepler2019,
author={Bepler, Tristan
and Morin, Andrew
and Rapp, Micah
and Brasch, Julia
and Shapiro, Lawrence
and Noble, Alex J.
and Berger, Bonnie},
title={Positive-unlabeled convolutional neural networks for particle picking in cryo-electron micrographs},
journal={Nature Methods},
year={2019},
issn={1548-7105},
doi={10.1038/s41592-019-0575-8},
url={https://doi.org/10.1038/s41592-019-0575-8}
}

</details>

Topaz-Denoise

Bepler, T., Kelley, K., Noble, A.J., Berger, B. Topaz-Denoise：用于冷冻电镜和冷冻电子断层扫描的通用深度去噪模型。自然通讯 11, 5208 (2020)。https://doi.org/10.1038/s41467-020-18952-1

<details><summary>Bibtex</summary>

@Article{Bepler2020_topazdenoise,
author={Bepler, Tristan
and Kelley, Kotaro
and Noble, Alex J.
and Berger, Bonnie},
title={Topaz-Denoise: general deep denoising models for cryoEM and cryoET},
journal={Nature Communications},
year={2020},
issn={2041-1723},
doi={10.1038/s41467-020-18952-1},
url={https://doi.org/10.1038/s41467-020-18952-1}
}

</details>

作者

<details><summary>Tristan Bepler</summary> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/f6494efa-7be9-4bb2-b69c-bd25ef709c33.png" width="120"> </details> <details><summary>Alex J. Noble</summary> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/29c4afd4-6cfe-4ec5-8dd9-8d28eccc4450.png" width="120"> </details>