Latest release: March 2016

引文

请注意，在集群上处理 SPIM 数据的自动化工作流程基于出版物。如果您成功地将其用于您的研究，请引用以下工作：

C. Schmied、P. Steinbach、T. Pietzsch、S. Preibisch、P. Tomancak (2015)“用于并行处理大型多视图 SPIM 记录的自动化工作流程。” 生物信息学，12 月 1 日； doi：10.1093/生物信息学/btv706 Webpage

自动化工作流程基于 Fiji 插件 Multiview Reconstruction 和 BigDataViewer。请参考并引用以下出版物：

S. Preibisch、S. Saalfeld、J. Schindelin 和 P. Tomancak (2010)“基于珠子的选择性平面照明显微镜数据配准软件”，NatureMethods，7(6):418-419.Webpage
S. Preibisch、F. Amat、E. Stamataki、M. Sarov、R.H. Singer、E. Myers 和 P. Tomancak (2014)“基于贝叶斯的高效多视图解卷积”，自然方法，11(6)：645-648。 Webpage
T. Pietzsch、S. Saalfeld、S. Preibisch、P. Tomancak (2015)“BigDataViewer：大型图像数据集的可视化和处理。” 自然方法，12(6)481–483。 Webpage

多视图重建

在 Multiview Reconstruction (MVR) 管道中，所有结果都写入 XML。这给集群处理带来了新的问题，因为多个并发运行的作业需要更新同一个文件。

Stephan Preibisch 解决了这个问题，方法是允许为每个作业（通常是一个时间点）编写一个 XML 文件，然后将作业特定的 XML 合并到整个数据集的一个 XML 中。

实际上，这意味着需要执行以下步骤：

定义 XML 数据集 - 为整个延时拍摄创建一个 XML
将数据重新保存为 HDF5 - 将数据转换为经过优化的 HDF5 容器，以便在 BigDataViewer 中快速访问
按时间点注册运行 - 创建与时间点一样多的 XML
合并 XML - 将每个时间点的 XML 合并回单个 XML

引入了一些新参数，一些旧参数更改了名称。因此，请使用本章中描述的config.yaml通过MVR管道进行处理。

此工作流程所基于的集群处理脚本的过时版本您可以找到 here

工作流程逻辑

我们使用自动化工作流引擎 Snakemake 在单台计算机或 HPC 集群上映射和分派工作流逻辑。在 Snakefile 中定义了包含处理步骤以及输入和输出规则的工作流程。每个步骤都调用 Fiji beanshell 脚本。这些脚本反过来又通过斐济驱动处理。

当前的工作流程包括以下步骤。它涵盖了延时多视图 SPIM 处理的主要处理：

定义czi或tif数据集。

2.重新保存为hdf5。

3.检测并注册兴趣点。

4.合并xml，为注册数据集创建XML。

5.延时注册。

6.双通道数据集可选：重复转换

7.反卷积可选：外部变换

平均权重融合/反卷积
定义输出
将输出重新保存到 hdf5 中，为融合数据集创建 XML。

支持的数据集

该脚本支持多角度、多通道和多照明方向，无需调整 Snakefile 或 .bsh 脚本。

使用 spimdata 版本：0.9-revision

使用SPIM注册版本2.3.9

支持的数据集采用以下格式：

使用 Zeiss Lightsheet Z.1 数据集 (LOCI) Multiple timepoints: YES (one file per timepoint) or (all time-points in one file) Multiple channels: YES (one file per channel) or (all channels in one file) Multiple illumination directions: YES (one file per illumination direction) Multiple angles: YES (one file per angle) 使用 LOCI Bioformats 开启器 (.tif) Multiple timepoints: YES (one file per timepoint) or (all time-points in one file) Multiple channels: YES (one file per channel) or (all channels in one file) Multiple illumination directions: YES (one file per illumination direction) => not tested yet Multiple angles: YES (one file per angle) 使用 ImageJ Opener (.tif)： Multiple timepoints: YES (one file per timepoint) Multiple channels: YES (one file per channel) Multiple illumination directions: YES (one file per illumination direction) => not tested yet Multiple angles: YES (one file per angle)

斐济工作流程

您可以在此处下载我们已经测试了与自动集群处理的兼容性的斐济版本 (2015-06-30_Fiji.app.tar.gz ）：

Link to repository

需要注意的是，我们只能保证使用提供的斐济版本正确执行工作流程。我们会不时升级以涵盖插件的最新更改。

Snakemake 工作流程

Snakemake（命令行工作流引擎）用于自动执行工作流中的各个步骤。本页记录的工作流程已使用 Snakemake 3.3（与 PyYAML（版本 3.11）和 python drmaa（版本 0.7.6）支持接口进行测试。

自动多视图重建工作流程

从 github 克隆工作流程的存储库。

git 克隆 https://github.com/mpicbg-scicomp/snakemake-workflows.git

该存储库包含单通道和双通道数据集的示例配置脚本、定义工作流程的 Snakefile、通过 Fiji 驱动处理的 beanshell 脚本以及包含集群排队系统信息的 cluster.json 文件。

延时拍摄目录

/路径/到/存储库/spim_registration/timelapse/
├── 自述文件.md
├── 蛇锉
├── cluster.json
├── 配置.yaml
├── 反卷积.bsh
├── 定义_czi.bsh
├── 定义_输出.bsh
├── 定义_tif_zip.bsh
├── 重复转换.bsh
├── 导出.bsh
├── 导出输出.bsh
├── fusion.bsh
├── 注册.bsh 
├── timelapse_registration.bsh
├── timelapse_utils.py
├── 变换.bsh       
└── xml_merge.bsh

Snakefile 包含处理步骤的名称以及处理的输入和输出规则。
config.yaml 包含配置在数据目录中找到的 beanshell 脚本的参数。
cluster.json 包含排队系统的资源信息（处理时间、核心数量和内存）。
*.bsh 脚本包含 Fiji 运行处理的说明。

工具目录

工具目录包含常见文件格式预处理的脚本。某些数据集当前仅在将其重新保存到 .tif 时才可用：

不连续的 .czi 数据集
.czi 具有多个组的数据集
.ome.tiff 文件

master_preprocessing.sh 文件是配置脚本，其中包含需要重新保存的数据集的信息。在 czi_resave 以及 ometiff_resave 目录中，您将找到 create-re saving-jobs.sh 脚本，该脚本为每个时间点创建一个作业。 submit-jobs 脚本将这些作业发送到集群，并在其中调用 re saving.bsh 或 ometiff_resave.bsh 脚本。然后，beanshell 使用 Fiji 宏并重新保存文件。 .czi 文件的重新保存使用 LOCI 生物格式并保留元数据。

/路径/到/存储库/spim_registration/工具/
├── czi_resave/
	├── create-resaving-jobs.sh
	├── resaving.bsh
	└── submit-jobs
├── ometiff_resave/
	├── create-ometiff_resave.sh
	├── ometiff_resave.bsh
	└── submit-jobs
└── master_preprocessing.sh

cluster_tools 目录

集群工具目录包含用于 GPU 反卷积的库和用于运行 Fiji headless 的虚拟帧缓冲区 (xvfb)。

libFourierConvolutionCUDALib.so
xvfb-run

系统配置CPU

我们使用 Libsysconfcpus 来限制 Fiji 在集群上使用的核心数量。

编译：

CFLAGS=-ansi ./configure --prefix=$PREFIX
使
进行安装

其中 PREFIX 是安装目录。使用我们的默认 GCC 版本 4.9.2 进行编译时，需要使用 ANSI 模式。对于旧版本可能有必要，也可能没有必要。

命令行

集群计算机很可能不运行任何图形用户界面，而仅依赖于命令行。从命令行控制集群相当简单 - 我使用大约 10 个不同的命令来完成我需要做的一切。由于大多数生物学家可能不熟悉 Linux 命令行，因此我们开始单独的 Linux command line tutorial 和 Software Carpentry’s workshop The Unix Shell 页面来解释基本要点。

工作流程的初始设置

克隆 Snakemake-workflows 存储库后，您需要为您的设置配置 config.yaml。这意味着您需要指定 Fiji 的目录、xvfb-run 的位置以及 GPU 反卷积库的位置。进入 Snakemake-workflows 的 timelapse 目录并使用您喜欢的编辑器（例如 nano）打开 config.yaml 并更改第 7 部分中的设置。软件目录：

cd Snakemake-workflows/spim_registration/timelapse/
纳米配置.yaml

#================================================================================
# 7. 软件目录
# 
# 描述：处理软件依赖的路径
# 选项：斐济位置
#beanshell和snakefile目录
# cuda 库的目录
#xvfb设置
# sysconfcpus 设置
#================================================================================
# 目前在斐济工作
斐济应用程序：“/sw/users/schmied/packages/2015-06-30_Fiji.app.cuda/ImageJ-linux64”，
# bean shell 脚本和 Snakefile
bsh_directory: "/projects/pilot_spim/Christopher/snakemake-workflows/spim_registration/timelapse/",
# 包含cuda库的目录
Directory_cuda：“/ sw / users / schmied / cuda /”，
#xvfb 
fiji-prefix: "/sw/users/schmied/packages/xvfb-run -a", # 调用 xvfb 进行斐济无头模式
sysconfcpus: "sysconfcpus -n",
内存前缀：“-Xmx”

初始设置完成后，您可以继续修改特定数据集的 config.yaml。

数据集设置

您可以在此处下载 5 视图、单通道 .czi 示例数据集 (example.zip)：

Link to repository

示例数据集如下所示：

/路径/到/数据/
├── exampleSingleChannel.czi
├── exampleSingleChannel(1).czi
├── exampleSingleChannel(2).czi
├── exampleSingleChannel(3).czi
└── exampleSingleChannel(4).czi

为了进行处理，数据集目录还将包含特定数据集的 config.yaml 文件。转到数据集目录并为 config.yaml 创建符号链接：

cd /路径/到/数据/
ln -s /path/snakemake-workflows/spim_registration/timelapse/config.yaml

现在数据集目录有一个 config.yaml 的符号链接：

/路径/到/数据/
├── exampleSingleChannel.czi
├── exampleSingleChannel(1).czi
├── exampleSingleChannel(2).czi
├── exampleSingleChannel(3).czi
├── exampleSingleChannel(4).czi
└── config.yaml # 从此存储库复制/符号链接

config.yaml

整个处理过程是通过yaml文件控制的。

处理的关键参数可以在 yaml 文件的第一（公共）部分中找到。这些参数通常取决于数据集和用户。第二部分包含每个处理步骤的高级和手动覆盖。这些步骤对应于snakefile 中的规则。

设置 config.yaml 文件进行处理

处理开关

在第一部分中，您需要决定要执行哪些处理。打开 config.yaml 文件：

cd Snakemake-workflows/spim_registration/timelapse/
纳米配置.yaml

转换开关在正常的单通道/多通道处理（所有通道都包含用于配准的珠子）和多通道处理（其中只有一个通道包含珠子）之间切换。如果存在没有珠子的通道，则需要复制其他通道的转换才能注册它们。

将 transformation_switch 设置为 timelapse 以进行单通道处理或多通道处理，其中所有通道都包含珠子：

转换开关：“游戏中时光倒流”，

将 transformation_switch 设置为 timelapse_duplicate 以将变换从一个通道复制到其他通道：

conversion_switch: "timelapse_duplicate",

fusion_switch 在加权平均融合和反卷积之间做出决定。将 fusion_switch 设置为 fusion 以进行加权平均融合：

fusion_switch：“融合”，

将 fusion_switch 设置为 devolve 以执行反卷积：

fusion_switch: “反卷积”,

常规设置

在下一部分中指定数据集的名称。这将是 HDF5 文件和 XML 文件的名称：

hdf5_xml_filename: '"dataset_one"',

然后指定数据集的时间点数量。示例数据集有 2 个时间点。每个时间点的处理在集群上并行运行。

n时间点：2，

然后指定角度、通道和照明侧。如果您将数据从 .czi 重新保存到 .tif 中，则给出适当的数字（即 0,1）。这些值用逗号分隔：

角度：“0,72,144,216,288”，
渠道：“绿色”， 
照明：“0”，

如果要处理双通道数据集，请为通道使用两个不同的名称：

角度：“0,72,144,216,288”，
频道：“绿色，红色”， 
照明：“0”，

.czi 文件的设置

如果您处理 .czi 文件，则给出第一个 .czi 文件的名称（没有索引的文件）：

first_czi: "exampleSingleChannel.czi",

.tif 数据集的设置

对于 .tif 文件的处理，请给出文件的模式，以及如果您处理单通道数据集还是双通道数据集：

image_file_pattern: 'img_TL_角度.tif',
multiple_channels: '"NO（一个通道）"',

对于具有多个通道的数据集，文件可以按通道分隔，或者每个文件可以包含两个通道。对于每个通道具有单独文件的多通道数据集，另外提供 image_file_pattern 的通道信息

image_file_pattern: 'img_TL_角度_通道.tif',
multiple_channels: '"是（每个通道一个文件）"',

如果文件包含两个通道，则忽略 image_file_pattern 中的通道信息。并为 multiple_channels 指定您要处理多通道数据集：

image_file_pattern: 'img_TL_角度.tif',
multiple_channels: '"是（一个文件中的所有通道）"',

检测与注册

要进行注册，请指定包含珠子的数据的通道。对于单通道数据和多通道数据（其中所有通道都包含用于注册的珠子），您需要选择以下内容：作为兴趣点，指定“珠子”。对于多通道数据集，指示“珠子，珠子”：

reg_process_channel: '"所有通道"',
reg_interest_points_channel: '"珠子"',

如果您有双通道数据集，其中只有一个通道包含微珠，请指定您只想选择一个通道。还指定源通道和目标通道。并指定不应注册的正确通道：

reg_process_channel: '"所有通道"',
来源频道：“红色”，
target_channel：“绿色”，
reg_interest_points_channel: '"[不要注册此频道],beads"',

接下来给出检测方法的参数。选择用于配准的方法（即均值差或高斯差）。我们建议使用高斯差分。给出半径 1 和 2 的信息以及通过使用图形用户界面处理参考时间点检索到的阈值：

type_of_detection: '"高斯差分"',
西格玛：'1.3'，
reg_threshold: '0.005',

对于均值差配准，指定半径_1、半径_2 和阈值：

type_of_detection: '"高斯差分"',
reg_radius_1: '2',
reg_radius_2: '3',
reg_threshold: '0.005',

延时拍摄注册

指定应使用哪个时间点作为参考时间点。我们通常使用数据集中间的时间点：

参考时间点：'1'，

加权平均融合

对于加权平均融合，指定在参考时间点的 GUI 处理中确定的下采样因子和边界框。边界框用于独立于下采样的加权平均融合：

下采样：'1'， 
最小_x：'274'，
最小_y：'17'，
最小_z：'-423'，
maximal_x: '1055',
maximal_y: '1928',
最大_z：'480'，

多视图反卷积

外部改造

如果要对多视图反卷积使用下采样，请将 external_trafo_switch 设置为 external_trafo。不使用下采样_transform。外部变换的矩阵指定下采样。这里设置为 2x 下采样：

external_trafo_switch: "external_trafo",
矩阵变换: '"0.5, 0.0, 0.0, 0.0, 0.0, 0.5, 0.0, 0.0, 0.0, 0.0, 0.5, 0.0"',

反卷积设置

要执行反卷积，请指定迭代次数以及边界框。对于多视图反卷积，边界框需要考虑下采样：

迭代次数：'15'，
最小_x_装饰：'137'，
最小_y_装饰：'-8'，
最小_z_装饰：'-211'，
maximal_x_deco: '527',
maximal_y_deco: '964',
maximal_z_deco: '240',

然后指定点扩散函数 (PSF) 的源。对于单通道数据集，它只是“珠子”。

detectors_to_extract_psf_for_channel: '"珠子"',

对于双通道数据集，其“珠子，珠子”

detectors_to_extract_psf_for_channel: '"珠子，珠子"',

如果您处理只有一个通道包含珠子的多通道数据集，则指定哪个通道不包含珠子：

detectors_to_extract_psf_for_channel: '"[与红色通道相同的 PSF]，珠子"',

软件目录

这里存储 Fiji、beanshell 脚本、CUDA 库和 xvfb 的目录。还存储了 sysconfcpus 的前缀和 Fiji 的内存前缀：

# 目前在斐济工作
斐济应用程序：“/sw/users/schmied/packages/2015-06-30_Fiji.app.cuda/ImageJ-linux64”，
# bean shell 脚本和 Snakefile
bsh_directory: "/projects/pilot_spim/Christopher/snakemake-workflows/spim_registration/timelapse/",
# 包含cuda库的目录
Directory_cuda：“/ sw / users / schmied / cuda /”，
#xvfb 
fiji-prefix: "/sw/users/schmied/packages/xvfb-run -a", # 调用 xvfb 进行斐济无头模式
sysconfcpus: "sysconfcpus -n",
内存前缀：“-Xmx”

斐济资源设置

这里为每个处理步骤指定了斐济的资源限制，包括核心数量和内存数量。这些设置需要与 cluster.json 文件匹配：

斐济资源：{
  # hdf5 重新保存的设置：
  num_cores_hdf5: 3,
  mem_hdf5：“20克”，
  # 注册设置：
  num_cores_reg: 4,
  mem_reg：“40克”，
  # 延时拍摄注册设置：
  核心数时间：3，
  mem_time: "50g",
  # 平均融合设置：
  核数融合：6，
  mem_fusion: "50g",
  # 反卷积设置：
  核心装饰数：12，
  mem_deco：“110克”，
  # 重新保存输出的设置：
  核心数输出：3，
  内存输出：“20g”

高级设置

在高级设置中，有更多用于进一步细化处理的选项。仅应在必要时更改这些设置。

集群.json

cluster.json 包含排队系统的资源信息。它应该与斐济资源设置相匹配。

    {
        "__default__" :
        {
        "lsf_extra" : "-R \"span[hosts=1]\"",
        "lsf_q" : "short"   
        },
        
        "hdf5_xml" :
        {
        "lsf_extra" : "-n 3 -R \"span[hosts=1] rusage[mem=20000]\""
        },

        "resave_hdf5" : 
        {
        "lsf_extra" : "-n 3 -R \"span[hosts=1] rusage[mem=20000]\""
        },

        "registration" :
        {
            "lsf_extra" : "-n 4 -R \"span[hosts=1] rusage[mem=40000]\""
        },
        
        "timelapse" : 
        {
            "lsf_extra" : "-n 6 -R \"span[hosts=1] rusage[mem=50000]\""
        },

        "external_transfrom" :
        {
            "lsf_extra" : "-R \"span[hosts=1] rusage[mem=10000]\""
        },

        "fusion" : 
        {
            "lsf_extra" : "-n 6 -R \"span[hosts=1] rusage[mem=50000]\"",
            "lsf_q" : "short"
        },

        "deconvolution" :
        {
            "lsf_extra" : "-n 12 -R \"span[hosts=1] rusage[mem=110000]\"",
        "lsf_q" : "gpu"
        },
        
        "resave_hdf5_output" :
        {
        "lsf_extra" : "-n 3 -R \"span[hosts=1] rusage[mem=20000]\""
        }
    }

提交作业

我们建议在 screen 内执行 Snakemake。要执行 Snakemake，您需要调用 Snakemake，指定作业数量、数据位置，并将作业分派到具有排队系统信息的集群。以下是用于 Snakemake 工作流程的命令和标志的列表：

本地后端：/path/to/snakemake/snakemake -j 1 -d /path/to/data/

并行运行的作业数量标志：-j

用于指定数据位置的标志：-d /path/to/data/

Snakemake 试运行标志：-n

强制执行规则：-R

对于 DRMAA 后端添加： –drmaa “ -q {cluster.lsf_q} {cluster.lsf_extra}”

对于 Lsf 后端添加： –cluster “bsub -q {cluster.lsf_q} {cluster.lsf_extra}”

指定排队系统的配置脚本： –cluster-config ./cluster.json

要保存集群的错误和输出文件，请添加： –drmaa “ -q {cluster.lsf_q} {cluster.lsf_extra} -o test.out -e test.err” –cluster “bsub -q {cluster.lsf_q} {cluster.lsf_extra} -o test.out -e test.err”

执行snakemake的命令将如下所示：

如果您的集群支持 DRMAA：

/path/to/snakemake/snakemake -j 2 -d /path/to/data/ --cluster-config ./cluster.json --drmaa " -q {cluster.lsf_q} {cluster.lsf_extra}"

如果没有：

/path/to/snakemake/snakemake -j 2 -d /path/to/data/ --cluster-config ./cluster.json --cluster "bsub -q {cluster.lsf_q} {cluster.lsf_extra}"

对于集群的错误和输出，添加 -o test.out -e test.err 例如：

DRMAA

/path/to/snakemake/snakemake -j 2 -d /path/to/data/ --cluster-config ./cluster.json --drmaa " -q {cluster.lsf_q} {cluster.lsf_extra} -o test.out -e test.err"

LSF

/path/to/snakemake/snakemake -j 2 -d /path/to/data/ --cluster-config ./cluster.json --cluster "bsub -q {cluster.lsf_q} {cluster.lsf_extra} -o test.out -e test.err"

注意：所有作业的集群的错误和输出都写入这些文件中。

日志文件和管道的监控

日志文件被写入数据目录中名为“logs”的新目录中。日志文件根据其在工作流程中的位置进行排序。管道中的多个或替代步骤由数字表示。

强制某些规则：使用 -R 标志重新运行特定规则和下游的所有内容 -R

集群

每个集群在使用的硬件和运行的软件方面都不同，特别是调度系统。在这里，我们在 MPI-CBG 上使用一台集群计算机，该计算机由 44 节点组成，每个节点具有 12 Intel Xeon E5-2640 内核，运行频率为 2.50 GHz，并拥有 128GB 内存。集群节点可以访问由专用 Lustre 分布式文件系统提供的 200TB 数据存储，可以说它针对高性能输入/输出（读/写）操作进行了优化，这对于 SPIM 数据量至关重要。

该集群的每个节点都运行 CentOS 6.3 Linux 发行版。 MPI-CBG集群上运行的排队系统是LSF。各个排队系统的作业提交的基本原理是相同的，但确切的语法当然会有所不同。

ImageJ 文档

重要统计数据

页面内容

并行多视图重建的自动化工作流程

引文

多视图重建

工作流程逻辑

支持的数据集

斐济工作流程

Snakemake 工作流程

自动多视图重建工作流程

延时拍摄目录

工具目录

cluster_tools 目录

系统配置CPU

命令行

工作流程的初始设置

数据集设置

config.yaml

设置 config.yaml 文件进行处理

处理开关

常规设置

.czi 文件的设置

.tif 数据集的设置

检测与注册

延时拍摄注册

加权平均融合

多视图反卷积

外部改造

反卷积设置

软件目录

斐济资源设置

高级设置

集群.json

提交作业

日志文件和管道的监控

集群