MicrographCleaner

MicrographCleaner (micrograph_cleaner_em) 是一个Python包，用于将冷冻电子显微镜图像分割成

• 碳/高对比度或污染区域
• 良好区域

以便可以轻松排除错误选取的坐标

要获取使用说明的完整描述，请执行

cleanMics -h

示例

cleanMics -c path/to/inputCoords/ -o path/to/outputCoords/ -b 180 -s 1.0 -i /path/to/micrographs/ --predictedMaskDir path/to/store/masks --deepThr 0.5

安装

anaconda（如果系统有NVIDIA GPU，则推荐使用）

如果您的系统没有可用的GPU，请查看pip安装

1. 从https://anaconda.net.cn/distribution/ 安装anaconda Python 3x版本

2. 为MicrographCleaner创建环境
   conda create -n env_micrograph_cleaner_em python=3.6

3. 激活环境（每次您想使用micrograph_cleaner时，都需要激活它）
   conda activate env_micrograph_cleaner_em

4. 从存储库安装micrograph_cleaner_em
   conda install -c rsanchez1369 -c anaconda -c conda-forge micrograph-cleaner-em

5. 下载深度学习模型
   cleanMics --download

6. 完成！

pip/source选项

1. 以这种方式安装CUDA和cudnn，以便tensorflow（https://tensorflowcn.cn/）可以执行。micrograph_cleaner与CUDA-9和CUDA-10兼容。Tensorflow版本将根据CUDA版本自动选择并在之后安装。CUDA可在https://developer.nvidia.com/cuda-toolkit获取，cudnn可在https://developer.nvidia.com/cudnn获取。
   可以使用python模块cudnnenv自动在步骤2中执行简单的cudnn安装

1.1)（可选）创建虚拟环境

pip install virtualenv
virtualenv --system-site-packages -p python3 ./env_micrograph_cleaner_em
source ./env_micrograph_cleaner_em/bin/activate

2. 安装 micrograph_cleaner_em

git clone https://github.com/rsanchezgarc/micrograph_cleaner_em.git
cd micrograph_cleaner_em
python setup.py install

或
pip install micrograph_cleaner_em

2.1) 如果尚未安装 cudnn，请安装 install cudnnenv
pip install cudnnenv

并执行
cudnnenv install [VERSION]，推荐的版本为：CUDA-8 使用 "v6-cuda8"，CUDA-9 使用 "v7.0.1-cuda9"，CUDA-10 使用 "v7.4.1-cuda10"。

3. 下载深度学习模型
   cleanMics --download

4. 完成！

scipion 选项

1. 从 http://scipion.i2pc.es/ 安装 scipion 版本 2.0+

2. 从插件管理器或命令行安装 xmipp
   scipion installp -p scipion-em-xmipp

3. 从插件管理器或命令行安装 deepLearningToolkit
   scipion installb deepLearningToolkit

4. 完成！

用法

MicrographCleaner 使用基于 U-net 的深度学习模型将微图分割为好区域和坏区域。因此，它主要用于在选区后作为后处理步骤，其中在碳等高对比度伪影中选择的坐标将被排除。此外，它可以用于生成二值掩码，以防止选区器考虑有问题的区域。因此，micrograph_cleaner 必须使用一些微图文件名和像素中的粒子大小（与输入 mics 相比）作为强制参数。此外，它还可以接收以下输入

1. 存放选区坐标的目录和存放评分/清理坐标的另一个目录。坐标将保存为 pos 格式或纯文本（带有标题列名的 x 和 y 的列），位于以下位置。每个微图必须有一个不同的坐标文件，其名称与微图相同，输出的坐标将保留命名。
   例如：-c path/to/inputCoordsDirectory/ -o /path/to/outputCoordsDirectory/
   允许的格式是 xmipp pos，relion star 和至少有两列标题为 xcoor 和 ycoor 的原始文本制表符分隔。原始文本文件示例

micFname1.tab:
###########################################
xcoor ycoor otherInfo1 otherInfo2
12  143  -1  0.1
431  4341  0  0.2
323  321  1  0.213
###########################################

2. 保存预测掩码的目录（mrc 格式）。例如：--predictedMaskDir path/where/predictedMasksWillBeSaved/

3. 如果从不同比例的微图中拾取坐标，则可以下采样因子（如果实际上进行了上采样，则可以小于 1）。例如，-s 2 将通过因子 2 下采样坐标，然后应用与输入微图一样大的预测掩码。这种情况对应于我们使用原始微图进行选区，但使用 MicrographCleaner 与下采样 mics 的示例

4. 前面选项的任何组合。

训练好的 MicrographCleaner 模型可在 http://campins.cnb.csic.es/micrograph_cleaner/ 获取，并可通过执行以下操作自动下载
cleanMics --download

注意，如果您使用 pip/source 安装了 micrograph_cleaner，那么在执行之前应提供 CUDA 和 cudnn 库，因此如果在执行前未找到 CUDA，则在执行前导出其路径

export LD_LIBRARY_PATH=/path/to/cuda/cuda-9.0/lib64:$LD_LIBRARY_PATH

然后执行 cleanMics 程序

示例

#Donwload deep learning model
cleanMics --download
    
#Compute masks from imput micrographs and store them
cleanMics -b $BOX_SIXE  -i  /path/to/micrographs/ --predictedMaskDir path/to/store/masks

#Rule out input bad coordinates (threshold<0.5) and store them into path/to/outputCoords
cleanMics  -c path/to/inputCoords/ -o path/to/outputCoords/ -b $BOX_SIXE -s $DOWN_FACTOR  -i  /path/to/micrographs/ --deepThr 0.5

#Compute goodness scores from input coordinates and store them into path/to/outputCoords
cleanMics  -c path/to/inputCoords/ -o path/to/outputCoords/ -b $BOX_SIXE -s $DOWN_FACTOR  -i  /path/to/micrographs/ --deepThr 0.5     

API

MicrographCleaner 中使用的根本类是 MaskPredictor，这是一个设计用来根据微图预测污染/碳掩码的类。

class micrograph_cleaner_em.MaskPredictor

用法：给定一个形状为 HxW 的 numpy 数组（表示微图），预测形状为 HxW 的掩码。掩码值范围从 0. 到 1.，其中 0. 与清洁区域相关联，1. 与污染相关。

构建器

micrograph_cleaner_em.MaskPredictor(boxSize, deepLearningModelFname=DEFAULT_PATH , gpus=[0], strideFactor=2)
    
    :param boxSize (int): estimated particle boxSize in pixels
    :param deepLearningModelFname (str): a path where the deep learning model will be loaded. DEFAULT_PATH="~/.local/share/micrograph_cleaner_em/models/defaultModel.keras"
    :param gpus (list of gpu ids (ints) or None): If None, CPU only mode will be employed.
    :param strideFactor (int): Overlapping between windows. Micrographs are divided into patches and each processed individually.
                         The overlapping factor indicates how many times a given row/column is processed by the network. The 
                         bigger the better the predictions, but higher computational cost.

方法

predictMask(self, inputMic, preproDownsampleMic=1, outputPrecision=np.float32):
    Obtains a contamination mask for a given inputMic

    :param inputMic (np.array shape HxW): the micrograph to clean
    :param preproDownsampleMic: the downsampling factor applied to the micrograph before processing. Make it bigger if
                   large carbon areas are not identified
    :param outputPrecision: the type of the floating point number desired as input. Default float32
    :return: mask (np.array shape HxW): a mask that ranges from 0. to 1. ->
                   0. meaning clean area and 1. contaminated area.

getDownFactor(self):
    MaskPredictor preprocess micrographs before Nnet computation. First step is donwsampling using a donwsampling factor
    that depends on particle boxSize. This function computes the downsampling factor
    
    :return (float): the donwsampling factor that MaskPredictor uses internally when preprocessing the micrographs
    
close(self):
    Used to release memory

示例

以下行显示了如何为给定的微图计算掩码

import numpy as np
import mrcfile
import micrograph_cleaner_em as mce

boxSize = 128 #pixels

# Load the micrograph data, for mrc files you can use mrcifle
# but you can use any other method that return a numpy  array

with mrcfile.open('/path/to/micrograph.mrc') as mrc:
    mic = mrc.data

# By default, the mask predictor will try load the model at  
# "~/.local/share/micrograph_cleaner_em/models/"
# provide , deepLearningModelFname= modelPath argument to the builder 
# if the model is placed in other location 

with mce.MaskPredictor(boxSize, gpus=[0]) as mp:
    mask = mp.predictMask(mic) #by default, mask is float32 numpy array
    
# Then write the mask as a file

with mrcfile.new('mask.mrc', overwrite=True) as maskFile:
    maskFile.set_data(mask.astype(np.half)) # as float