cvapipe_analysis

[!重要]
为了重现我们论文[1]中的分析和图表，请使用此版本的代码

https://github.com/AllenCell/cvapipe_analysis/tree/nature-paper

[1] - Viana, M. P., Chen, J., Knijnenburg, T. A., Vasan, R., Yan, C., Arakaki, J. E., ... & Rafelski, S. M. (2023). Integrated intracellular organization and its variations in human iPS cells. Nature, 613(7943), 345-354.

细胞方差分析管道

---

安装

首先，为该项目创建一个conda环境

conda create --name cvapipe python=3.8
conda activate cvapipe

然后克隆此仓库

git clone https://github.com/AllenCell/cvapipe_analysis.git

并使用以下命令安装它

cd cvapipe_analysis
pip install -e .

或者，通过运行以下命令从pypi安装最新稳定版本

pip install cvapipe_analysis

使用类型

此软件包可用于重现[1]中显示的主要结果或使用您自己的数据生成类似结果。然而，在应用于您的数据集之前，我们强烈建议您首先在我们的测试数据集中运行它以了解该软件包的工作方式。

YAML配置文件

此软件包完全通过config.yaml文件进行配置。此文件分为几个部分，大致与现有的工作流程步骤一一对应。以下是您需要了解的配置文件的主要事项

项目

appName: cvapipe_analysis
project:
    # Sufix to append to local_staging
    local_staging: "path_to_your/local_staging"
    overwrite: on

在local_staging中设置您希望存储数据和结果的完整路径。

数据

data:
    nucleus:
        channel: "dna_segmentation"
        alias: "NUC"
        color: "#3AADA7"
    cell:
        channel: "membrane_segmentation"
        alias: "MEM"
        color: "#F200FF"
    structure:
        channel: "struct_segmentation_roof"
        alias: "STR"
        color: "#000000"
    structure-raw:
        channel: "structure"
        alias: "STRRAW"
        color: "#000000"

在此，我们提供了数据的描述。别名必须是唯一的，并在配置文件的其余部分中用于指定我们引用的数据。如果您在自己的数据上使用此包，请注意，在字段 channel 中使用的值必须在您的输入manifets文件中的 name_dict 列中找到（请参阅“在自己的数据上运行管道”部分）。

特征

features:
    aliases: ["NUC", "MEM", "STR"]
    # SHE - Spherical harmonics expansion
    SHE:
        alignment:
            align: on
            unique: off
            reference: "cell"
        aliases: ["NUC", "MEM"]
        # Size of Gaussian kernal used to smooth the
        # images before SHE coefficients calculation
        sigma: 2
        # Number of SHE coefficients used to describe cell
        # and nuclear shape
        lmax: 16

本节用于指定我们应该计算哪些别名的特征。此外，我们还应计算哪些别名的球谐系数，以及应使用哪种类型的对齐方式。

预处理

preprocessing:
    remove_mitotics: on
    remove_outliers: on

在此，我们设置是否从数据集中删除有丝分裂细胞或异常值。当在您的数据上运行 cvapipe_analysis 时，您可以关闭此功能。

形状空间

shapespace:
    # Specify the a set of aliases here
    aliases: ["NUC", "MEM"]
    # Sort shape modes by volume of
    sorter: "MEM"
    # Percentage of exteme points to be removed
    removal_pct: 1.0
    # Number of principal components to be calculated
    number_of_shape_modes: 8
    # Map points
    map_points: [-2.0, -1.5, -1.0, -0.5, 0.0, 0.5, 1.0, 1.5, 2.0]
    plot:
        swapxy_on_zproj: off
        # limits of x and y axies in the animated GIFs
        limits: [-150, 150, -80, 80]

在此，我们指定应使用哪些别名来创建形状空间。这必须是上述别名的子集，以便计算其球谐系数。对于只有数百个细胞的较小数据集，您可能希望减少形状空间的地图点数。地图点的数量必须是奇数。

强度参数化

parameterization:
    inner: "NUC"
    outer: "MEM"
    parameterize: ["RAWSTR", "STR"]
    number_of_interpolating_points: 32

首先，我们指定应使用哪些别名作为内部和外部参考以及我们获得参数化的别名。

结构

structures:
    "FBL": ["nucleoli [DFC)", "#A9D1E5", "{'raw': (420, 2610), 'seg': (0,30), 'avgseg': (80,160)}"]
    "NPM1": ["nucleoli [GC)", "#88D1E5", "{'raw': (480, 8300), 'seg': (0,30), 'avgseg': (80,160)}"]
    "SON": ["nuclear speckles", "#3292C9", "{'raw': (420, 1500), 'seg': (0,10), 'avgseg': (10,60)}"]
    "SMC1A": ["cohesins", "#306598", "{'raw': (450, 630), 'seg': (0,2), 'avgseg': (0,15)}"]
    "HIST1H2BJ": ["histones", "#305098", "{'raw': (450, 2885), 'seg': (0,30), 'avgseg': (10,100)}"]
    "LMNB1": ["nuclear envelope", "#084AE7", "{'raw': (475,1700), 'seg': (0,30), 'avgseg': (0,60)}"]
    "NUP153": ["nuclear pores", "#0840E7", "{'raw': (420, 600), 'seg': (0,15), 'avgseg': (0,50)}"]
    "SEC61B": ["ER [Sec61 beta)", "#FFFFB5", "{'raw': (490,1070), 'seg': (0,30), 'avgseg': (0,100)}"]
    "ATP2A2": ["ER [SERCA2)", "#FFFFA0", "{'raw': (430,670), 'seg': (0,25), 'avgseg': (0,80)}"]
    "SLC25A17": ["peroxisomes", "#FFD184", "{'raw': (400,515), 'seg': (0,7), 'avgseg': (0,15)}"]
    "RAB5A": ["endosomes", "#FFC846", "{'raw': (420,600), 'seg': (0,7), 'avgseg': (0,10)}"]
    "TOMM20": ["mitochondria", "#FFBE37", "{'raw': (410,815), 'seg': (0,27), 'avgseg': (0,50)}"]
    "LAMP1": ["lysosomes", "#AD952A", "{'raw': (440,800), 'seg': (0,27), 'avgseg': (0,30)}"]
    "ST6GAL1": ["Golgi", "#B7952A", "{'raw': (400,490), 'seg': (0,17), 'avgseg': (0,30)}"]
    "TUBA1B": ["microtubules", "#9D7000", "{'raw': (1100,3200), 'seg': (0,22), 'avgseg': (0,60)}"]
    "CETN2": ["centrioles", "#C8E1AA", "{'raw': (440,800), 'seg': (0, 2), 'avgseg': (0,2)}"]
    "GJA1": ["gap junctions", "#BEE18C", "{'raw': (420,2200), 'seg': (0,4), 'avgseg': (0,8)}"]
    "TJP1": ["tight junctions", "#B4C878", "{'raw': (420,1500), 'seg': (0,8), 'avgseg': (0,20)}"]
    "DSP": ["desmosomes", "#B4C864", "{'raw': (410,620), 'seg': (0,5), 'avgseg': (0,3)}"]
    "CTNNB1": ["adherens junctions", "#96AA46", "{'raw': (410,750), 'seg': (0,22), 'avgseg': (5,40)}"]
    "AAVS1": ["plasma membrane", "#FFD2FF", "{'raw': (505,2255), 'seg': (0,30), 'avgseg': (10,120)}"]
    "ACTB": ["actin filaments", "#E6A0FF", "{'raw': (550,1300), 'seg': (0,18), 'avgseg': (0,35)}"]
    "ACTN1": ["actin bundles", "#E696FF", "{'raw': (440,730), 'seg': (0,13), 'avgseg': (0,25)}"]
    "MYH10": ["actomyosin bundles", "#FF82FF", "{'raw': (440,900), 'seg': (0,13), 'avgseg': (0,25)}"]
    "PXN": ["matrix adhesions", "#CB1CCC", "{'raw': (410,490), 'seg': (0,5), 'avgseg': (0,5)}"]

在此，我们指定一个字典，其中包含每个结构的基因名称、描述和颜色。同样，如果您正在将自己的数据应用于此，请确保在此指定您在manifest文件中的 structure_name 列中使用的值（请参阅“在自己的数据上运行管道”部分）。还指定了每个结构的对比值列表（最小值、最大值），这些值将用于绘图函数以显示原始数据、分割或平均形态细胞的单细胞图像（avgseg）。

运行管道以重现论文

此分析目前未配置为运行工作流。请单独运行步骤。

1. 下载包含原始GFP和分割裁剪图像的单细胞图像数据集manifest

cvapipe_analysis loaddata run

此命令下载了约7Tb的整个数据集。对于数据集中的每个细胞，我们提供了一个包含细胞膜和细胞核的参考标记以及一个细胞内结构的FP标记的3通道原始图像。我们还为每个细胞提供了5通道二值图像格式的分割。额外的两个通道对应于细胞和细胞内结构分割的屋顶增强版本。有关更多信息，请参阅我们的论文[1]。每个细胞的元数据可以在文件 manifest.csv 中找到。这是一个表格，其中每一行对应一个细胞。

重要的是，您可以从主数据集中随机下载由300个细胞组成的 小型测试数据集。为此，请运行

cvapipe_analysis loaddata run --test

此步骤将单细胞图像保存到文件夹 local_staging/loaddata/crop_raw 和 local_staging/loaddata/crop_seg 中。

2. 计算单细胞特征

cvapipe_analysis computefeatures run

此步骤提取单细胞特征，包括细胞、核和细胞内体积以及其他基本特征。我们在此还使用 aics-shparam (链接) 计算细胞和核形状的球谐系数。此步骤取决于步骤1。

此步骤将特征保存到文件 local_staging/computefeatures/manifest.csv 中。

3. 预处理数据集

cvapipe_analysis preprocessing run

此步骤从单细胞数据集中删除异常值和有丝分裂细胞。

此步骤将结果保存到文件 local_staging/preprocessing/manifest.csv 和文件夹 local_staging/preprocessing/outliers/ 中。

• xx.png：异常值检测的诊断图。

4. 计算形态模式

cvapipe_analysis shapemode run

在这里我们实现了一些预处理步骤。首先，我们从数据集中删除所有有丝分裂细胞。接下来，我们使用基于特征的异常值检测来检测和删除数据集中的异常值。剩下的数据集作为主成分分析（PCA）的输入。最后，我们计算细胞和核形状模式。这一步依赖于步骤3。

这一步产生了两个输出文件夹

文件夹：local_staging/shapemode/pca/

• explained_variance.png：每个主成分的解释方差。
• feature_importance.txt：每个主成分前几个特征的重要性。
• pairwise_correlations.png：所有主成分之间的成对相关性。

文件夹：local_staging/shapemode/avgshape/

• xx.vtk：与3D细胞和核网格对应的vtkPolyData文件。我们推荐使用Paraview打开这些文件。
• xx.gif：从3个不同投影角度说明细胞和核形状模式的动画GIF。
• combined.tif：将所有动画GIF组合在同一图像中的多通道TIF。

5. 创建参数化的细胞内位置表示（PILR）

cvapipe_analysis parameterization run

在这里我们使用aics-cytoparam (链接)为所有单细胞数据创建参数化。这一步依赖于步骤4和步骤3。

这一步产生一个输出文件夹

文件夹：local_staging/parameterization/representations/

• xx.tif：带有细胞PILR的多通道TIFF图像。

6. 创建平均PILR

cvapipe_analysis aggregation run

这一步平均多个细胞PILR，并将它们从形状空间中变形为理想形状。这一步依赖于步骤5。

这一步产生了两个输出文件夹

文件夹：local_staging/aggregation/repsagg/

• avg-SEG-TUBA1B-DNA_MEM_PC4-B5-CODE.tif：示例文件。这代表所有落入形状模式4的第5个箱子的TUBA1B细胞的分割图像的平均PILR。

文件夹：local_staging/aggregation/aggmorph/

• avg-SEG-TUBA1B-DNA_MEM_PC4-B5.tif：与上面相同，但PILR已经被变形为形状模式4的第5个箱子的细胞形状。

7. 相关性分析单细胞PIRL

cvapipe_analysis correlation run

这一步计算细胞PIRL之间的成对相关性。这一步依赖于步骤5。

这一步产生一个输出文件夹

文件夹：local_staging/correlation/values/

• avg-STR-NUC_MEM_PC8-1.tif：示例文件。所有落入形状模式8的第1个箱子的细胞PIRL之间的相关矩阵。
• avg-STR-NUC_MEM_PC8-1.csv：示例文件。提供上述相关矩阵的细胞索引。

8. 同型性分析

cvapipe_analysis stereotypy run

这一步计算结构的单个位置变化程度。这一步依赖于步骤5。

这一步产生了两个输出文件夹

文件夹：local_staging/stereotypy/values

• *.csv*：同型性值。

文件夹：local_staging/stereotypy/plots

• 结果图。

9. 一致性分析

cvapipe_analysis concordance run

这一步计算结构相对于所有其他细胞结构的定位程度。这一步依赖于步骤6。

这一步产生了两个输出文件夹

文件夹：local_staging/concordance/values/

• *.csv*：一致性值

文件夹：local_staging/concordance/plots/

• 结果图。

在自己的数据上运行管道

您需要使用一个manifest.csv文件来指定您数据的格式。该文件的每一行对应于您数据集中的细胞。此文件必须包含以下列

CellId：细胞的唯一ID。例如：AB98765。

structure_name：在细胞中标记的FP结构。如果您为细胞没有标记任何内容，请添加“NA”。例如：TOMM20。

crop_seg：多通道单细胞分割的完整路径。

crop_raw：多通道单细胞原始图像的完整路径。

name_dict：指定上述两张图像中每个通道名称的字典。例如："{'crop_raw': ['dna_dye', 'membrane', 'gfp'], 'crop_seg': ['dna_seg', 'cell_seg', 'gfp_seg', 'gfp_seg2']}"。在这种情况下，您的crop_raw图像必须具有3个通道，因为这是您在name_dict中提供的名称数量。同样，在这个例子中，crop_seg必须具有4个通道。

一旦创建了此清单文件，您就可以开始使用cvapipe_analysis。为此，您应运行带有附加标志--csv path_to_manifest的loaddata步骤，其中path_to_manifest是您刚刚创建的清单文件的完整路径

cvapipe_analysis loaddata run --csv path_to_manifest

其他所有步骤都可以不进行修改运行。

在具有sbatch功能的集群上运行管道

如果您在Slurm集群或其他具有sbatch功能的集群上运行cvapipe_analysis，则可以使用带有标志--distribute调用每个步骤。这将在大集群中并行运行多个作业。可以在YAML配置文件的resources部分中设置特定参数。

自由软件：艾伦研究所软件许可