LLSpy: 晶格光片后处理实用工具

版权 © 2019 Talley Lambert, 哈佛医学院。

LLSpy是一个Python库，用于简化晶格光片数据处理。它扩展了Janelia研究园区Betzig实验室创建的cudaDeconv二进制文件，添加了以下功能：自动从数据文件夹结构和元数据中检测实验参数（最小化用户输入）、自动选择OTF、执行图像校正和操作，并简化文件处理。更完整的文档可在http://llspy.readthedocs.io/找到

使用LLSpy的三个方法

1. 图形用户界面

GUI提供了对LLSpy大部分功能的访问。它包括拖放队列、视觉进度指示器，并能够使用（令人惊叹的）4D查看器、Spimagine和实验支持napari预览使用当前设置处理的数据。

2. 命令行界面

命令行界面可用于在服务器环境中处理LLS数据（兼容Linux）。

$ lls --help

Usage: lls [OPTIONS] COMMAND [ARGS]...

  LLSpy

  This is the command line interface for the LLSpy library, to facilitate
  processing of lattice light sheet data using cudaDeconv and other tools.

Options:
  --version          Show the version and exit.
  -c, --config PATH  Config file to use instead of the system config.
  --debug
  -h, --help         Show this message and exit.

Commands:
  camera    Camera correction calibration
  clean     Delete LLSpy logs and preferences
  compress  Compression & decompression of LLSdir
  config    Manipulate the system configuration for LLSpy
  decon     Deskew and deconvolve data in LLSDIR.
  deskew    Deskewing only (no decon) of LLS data
  gui       Launch LLSpy Graphical User Interface
  info      Get info on an LLSDIR.
  install   Install cudaDeconv libraries and binaries
  reg       Channel registration

# process a dataset
$ lls decon --iters 8 --correctFlash /path/to/dataset

# change system or user-specific configuration
$ lls config --set otfDir path/to/PSF_and_OTFs

# or launch the gui
$ lls gui

3. 在Python控制台中进行交互式数据处理

>>> import llspy

# the LLSdir object contains most of the useful attributes and
# methods for interacting with a data folder containing LLS tiffs
>>> E = llspy.LLSdir('path/to/experiment_directory')
# it parses the settings file into a dict:
>>> E.settings
{'acq_mode': 'Z stack',
 'basename': 'cell1_Settings.txt',
 'camera': {'cam2name': '"Disabled"',
            'cycle': '0.01130',
            'cycleHz': '88.47 Hz',
            'exp': '0.01002',
    ...
}

# many important attributes are in the parameters dict
>>> E.parameters
{'angle': 31.5,
 'dx': 0.1019,
 'dz': 0.5,
 'nc': 2,
 'nt': 10,
 'nz': 65,
 'samplescan': True,
  ...
}

# and provides methods for processing the data
>>> E.autoprocess()

# the autoprocess method accepts many options as keyword aruguments
# a full list with descriptions can be seen here:
>>> llspy.printOptions()

              Name  Default                    Description
              ----  -------                    -----------
      correctFlash  False                      do Flash residual correction
flashCorrectTarget  cpu                        {"cpu", "cuda", "parallel"} for FlashCor
            nIters  10                         deconvolution iters
         mergeMIPs  True                       do MIP merge into single file (decon)
            otfDir  None                       directory to look in for PSFs/OTFs
            tRange  None                       time range to process (None means all)
            cRange  None                       channel range to process (None means all)
               ...  ...                        ...

# as well as file handling routines
>>> E.compress(compression='lbzip2')  # compress the raw data into .tar.(bz2|gz)
>>> E.decompress()  # decompress files for re-processing
>>> E.freeze()  # delete all processed data and compress raw data for long-term storage.

注意： LLSpy API 目前不稳定（可能会更改）。以 llspy.llsdir.LLSdir 类作为大多数有用方法的起点。文档中提供的文档最少。请在 github 上fork此项目并提出更改或补充意见。

要求

• 兼容 Windows（已在 7/10 上测试）、Mac 或 Linux（已在 Ubuntu 16.04 上测试）
• Python 3.6（自版本 0.4.0 以来，2.7 和 3.5 的支持已结束）
• 大多数功能假设数据文件夹结构由 Betzig 实验室 Dan Milkie 编写的 Lattice Scope LabeView 软件生成。如果您使用的是不同的采集软件（如 3i 软件），则可能需要更改数据结构和元数据解析例程，以便使用此软件。
• 目前，核心 deskew/deconvolution 处理基于 Lin Shao 编写的 cudaDeconv，由 Dan Milkie 维护。cudaDeconv 由 HHMI 许可并分发。它于 2019 年 2 月开源，可在此处找到：https://github.com/dmilkie/cudaDecon
• cudadeconv 需要具备 CUDA 功能的 GPU
• Spimagine 查看器需要一个正常工作的 OpenCL 环境

安装

1. 安装 conda/mamba

2. 启动一个 终端 窗口（Linux），或 Miniforge Prompt（Windows）

3. 将 LLSpy 安装到一个新的 conda 环境中

   conda create -n llsenv python=3.11 cudadecon
   conda activate llsenv
   pip install llspy
   

   create -n llsenv 行创建一个虚拟环境。这是可选的，但推荐使用，因为它更容易干净地卸载，并防止与其他任何 python 环境冲突。如果要在虚拟环境中安装，必须在继续之前激活环境，并且每次使用 llspy 之前都要激活。

每次使用程序时，都需要激活虚拟环境。主要命令行界面是 lls，GUI 可以通过 lls gui 启动。如果您希望的话，可以创建一个 bash 脚本或批处理文件来自动加载环境并启动程序。

# Launch Anaconda Prompt and type...
conda activate llsenv

# show the command line interface help menu
lls -h
# process a dataset
lls decon /path/to/dataset
# or launch the gui
lls gui

有关完整的使用说明，请参阅 文档。

LLSpy 的功能

• 具有持久/可保存处理设置的图形用户界面
• 用于远程/服务器使用的命令行界面（即将推出）
• 在处理完整实验之前预览处理后的图像以验证设置
• 预处理校正:
  • 在重叠同步模式下使用 Flash4.0 时纠正“残余电子”问题。包括 CUDA 和并行 CPU 处理以及用于生成校准文件的 GUI。
  • 对特别嘈杂的像素应用选择性中值滤波器
  • 在 deskew 之前裁剪图像边缘（有助于 CMOS 边缘行伪影）
  • 自动检测背景
• 处理
  • 选择要处理的采集图像子集（C 或 T）
  • 基于自动解析 Settings.txt 的自动参数检测
  • 根据采集日期、使用的掩码（如果已输入 SPIMProject.ini）和波长从原始 PSF 文件夹自动生成/选择 OTF
  • 图形进度条和时间估计
• 后处理
  • 正确嵌入体素尺寸元数据（Cimg 的新版本）
  • 将 MIP 文件合并为单个可由 ImageJ/Fiji 查看的超堆栈
  • 根据图像内容自动选择宽度/偏移量（“自动裁剪到特征”）
  • 基于标志自动图像配准（提供 tetraspeck 珠子堆栈）
  • 处理后压缩原始数据
• 监视文件夹自动处理（实验性）
  • 服务器模式：指定一个文件夹来监视传入的 已完成 LLS 文件夹（带有 Settings.txt 文件）。当检测到新文件夹时，它们将被添加到处理队列中，如果队列尚未开始，则启动队列。
  • 采集模式：设计用于在采集计算机上使用。指定一个文件夹来监视新的 LLS 文件夹，并处理到达的新文件。类似于 Lattice Scope 软件内建的 GPU 处理选项卡，但增加了 GUI 中的所有校正和参数选择。
• 轻松将 LLS 文件夹恢复到原始（预处理）状态
• 使用lbzip2压缩和解压缩文件夹及子文件夹（在Windows上不工作）
• 合并两个实验 - 更新文件名中的相对时间戳和栈号
• 将脚本编辑模式下获取的文件名中含有Iter_的文件重命名为符合标准命名的位置（正在开发中）
• 跨平台：包含预编译的二进制文件和共享库，应在所有系统上工作。

错误报告、功能请求等

欢迎提交拉取请求！

要报告错误或请求功能，请在GitHub上提交问题

请确保在任何错误报告中包含以下信息

• 操作系统版本
• GPU型号
• CUDA版本（在命令行提示符中输入nvcc --version）
• Python版本（在命令行提示符中输入python --version，如果适用，请先激活llsenv conda环境）

最依赖系统的组件（也最可能失败）是Spimagine的OpenCL依赖项。LLSpy将优雅地回退到内置的基于Qt的查看器，但Spimagine选项将在GUI的配置标签上不可用并变灰。如有需要，请在GitHub上提交问题以获取帮助。