profiling recipe下载 - profiling recipe源代码下载

基于图像的分析方法

描述

profiling-recipe 是主要使用 pycytominer 函数来处理单细胞形态学特征的脚本集合。这三个脚本是

profiling-pipeline.py - 运行基于图像的配置文件处理管道
csv2gz.py - 压缩.csv文件
create_dirs.sh - 创建子目录来存储处理管道的输出

入门

要求

蟒蛇

我们使用 Anaconda 作为我们的包管理器。按照此处的说明安装 Miniconda。

AWS CLI

我们使用 DVC 跟踪的 AWS S3 存储来进行大文件管理。按照此处的说明安装 AWS CLI。安装后，使用以下命令配置您的 AWS CLI 安装

aws configure

它会提示您：
AWS Access Key ID:您的密钥
AWS Secret Access Key:您的秘密密钥
Default region name:例如 us-east-1
Default output format: json

请注意，您输入的配置文件必须具有上传到您稍后设置的存储桶的权限。

如果您不想在 AWS 上存储/版本化大文件，则可以跳过 AWS CLI 安装。

系统要求

如果分析管道用于聚合单单元分析文件，我们建议在内存至少为.sqlite文件大小两倍的系统上运行管道。如果管道仅用于运行聚合下游的步骤，则它可以在本地计算机上运行。

创建文件夹结构

管道需要特定的文件夹结构，可以按如下方式创建

PROJECT_NAME= " INSERT-PROJECT-NAME "
mkdir -p ~ /work/projects/ ${PROJECT_NAME} /workspace/{backend,software}

下载数据

将每批中所有板的.sqlite文件（其中包含单细胞配置文件）和.csv文件（其中包含井级聚合配置文件）下载到backend文件夹。这两个文件是通过运行分析手册第 5.3 章中的命令创建的。下载文件后，文件夹结构应如下所示

backend
├── batch1
│   ├── plate1
│   │   ├── plate1.csv
│   │   └── plate1.sqlite
│   └── plate2
│       ├── plate2.csv
│       └── plate2.sqlite
└── batch2
    ├── plate1
    │   ├── plate1.csv
    │   └── plate1.sqlite
    └── plate2
        ├── plate2.csv
        └── plate2.sqlite

注意：聚合可能尚未执行。在这种情况下，只有.sqlite文件可供下载。

焊接到数据存储库（推荐）

焊接是一个将分析配方存储库作为子模块添加到数据存储库中的过程，以便数据存储库中的文件和生成这些文件的分析配方中的脚本一起进行版本控制。此处提供焊接说明。我们强烈建议将分析配方焊接到数据存储库。焊接后，使用命令将数据存储库克隆到software夹

 cd ~ /work/projects/ ${PROJECT_NAME} /workspace/software
git clone < location of the data repository > .git
cd < name of the data repository >
git submodule update --init --recursive

克隆后，文件夹结构应如下所示

software
└── data_repo
    ├── LICENSE
    ├── README.md
    └── profiling-recipe
        ├── LICENSE
        ├── README.md
        ├── config_template.yml
        ├── environment.yml
        ├── profiles
        │   ├── profile.py
        │   ├── profiling_pipeline.py
        │   └── utils.py
        └── scripts
            ├── create_dirs.sh
            └── csv2gz.py

无需焊接即可运行配方

无需将分析配方存储库焊接到数据存储库即可运行管道。如果以这种方式运行，分析配方存储库应作为子目录克隆到数据目录。然后文件夹结构将如下所示。

 software
└── data_directory
    ├── LICENSE
    ├── README.md
    └── profiling-recipe
        ├── LICENSE
        ├── README.md
        ├── config_template.yml
        ├── environment.yml
        ├── profiles
        │   ├── profile.py
        │   ├── profiling_pipeline.py
        │   └── utils.py
        └── scripts
            ├── create_dirs.sh
            └── csv2gz.py

下载load_data_csv

生成汇总统计表需要load_data_csv文件。这些文件应下载到load_data_csv目录。确保文件被 gzip 压缩，并且文件夹结构如下所示。

load_data_csv/
├── batch1
│   ├── plate1
│   │   ├── load_data.csv.gz
│   │   └── load_data_with_illum.csv.gz
│   └── plate2
│       ├── load_data.csv.gz
│       └── load_data_with_illum.csv.gz
└── batch2
    ├── plate1
    │   ├── load_data.csv.gz
    │   └── load_data_with_illum.csv.gz
    └── plate2
        ├── load_data.csv.gz
        └── load_data_with_illum.csv.gz

运行管道

管道应从数据存储库或数据目录运行。

DATA= " INSERT-NAME-OF-DATA-REPO-OR-DIR "
cd ~ /work/projects/ ${PROJECT_NAME} /workspace/software/ ${DATA} /

设置conda环境

复制environment.yml文件

environment.yml 文件包含运行管道所需的 conda 包列表。

cp profiling-recipe/environment.yml .

创造环境

conda env create --force --file environment.yml

激活conda环境

conda activate profiling

设置 DVC

为此项目初始化 DVC 并将其设置为在 S3 中存储大文件。如果不使用 DVC，请跳过此步骤。如果您想将 DVC 用于非 S3 的远程存储位置，请在此处查找说明。如果您的计算机上有多个 AWS 配置文件，并且不想使用 DVC 的默认配置文件，则可以通过在添加远程和执行最终 DVC 推送之间的任何时刻运行dvc remote modify S3storage profile PROFILE_NAME来指定要使用的配置文件。

 # Navigate
cd ~ /work/projects/ ${PROJECT_NAME} /workspace/software/ < data_repo >
# Initialize DVC
dvc init
# Set up remote storage
dvc remote add -d S3storage s3:// < bucket > /projects/ ${PROJECT_NAME} /workspace/software/ < data_repo > _DVC
# Commit new files to git
git add .dvc/.gitignore .dvc/config
git commit -m " Setup DVC "

创建目录

将包含管道输出的目录创建如下

profiling-recipe/scripts/create_dirs.sh

元数据、印版图和条形码_印版图文件

该管道需要barcode_platemap.csv和platemap.txt才能运行。还可以提供可选的external_metadata.tsv用于附加注释。以下是每个文件的说明

barcode_platemap.csv - 包含板和板图之间的映射。每一批数据有一个这样的文件。该文件包含两列，其名称分别为Assay_Plate_Barcode和Plate_Map_Name ，不应更改。文件的名称也不应该更改。该文件应该是一个以逗号分隔的.csv文件。
platemap.txt - 包含孔名称和扰动名称之间的映射。每个批次的每个板图都有一个这样的文件。两列是必需的，一列包含井名称（ A01 、 A02 ...），称为well_position ，另一列包含扰动标识符。扰动标识符列的名称可以是用户定义的（如果更改，请更改config.yml文件中的名称）。该文件的名称可以更改。如果更改，还请更改barcode_platemap.csv中的名称。该文件应该是制表符分隔的.txt文件
external_metadata.tsv - 包含扰动标识符到其他元数据之间的映射。该文件是可选的。扰动标识符列应与platemap.txt中的列具有相同的名称。该文件应该是制表符分隔的.tsv文件。

以下是barcode_platemap.csv文件的示例

 Assay_Plate_Barcode,Plate_Map_Name
plate1,platemap
plate2,platemap

这是一个示例板映射文件，这是一个示例外部元数据文件。

这些文件应添加到适当的文件夹中，以便文件夹结构如下所示

metadata
├── external_metadata
│   └── external_metadata.tsv
└── platemaps
    ├── batch1
    │   ├── barcode_platemap.csv
    │   └── platemap
    │       └── platemap.txt
    └── batch2
        ├── barcode_platemap.csv
        └── platemap
            └── platemap.txt

复制配置文件

CONFIG_FILE= " INSERT-CONFIG-FILE-NAME "
cd ~ /work/projects/ ${PROJECT_NAME} /workspace/software/ ${DATA} /
cp profiling-recipe/config_template.yml config_files/ ${CONFIG_FILE} .yml

配置文件包含由分析管道调用的各种 pycytominer 函数所需的所有参数。要使用不同的参数运行分析管道，可以创建多个配置文件。配置文件中的每个参数如下所述。在运行管道之前，必须对配置文件进行所有必要的更改。

复制聚合配置文件

如果分析管道的第一步aggregate已经执行（在backend文件夹中，除了.sqlite文件之外，还有一个.csv文件），则必须将.csv文件复制到数据存储库或数据目录。如果没有，请跳至运行分析管道。

分别为每个批次运行以下命令。这些命令为每个批次创建一个文件夹，压缩.csv文件，然后将它们复制到数据存储库或数据目录。

BATCH= " INSERT-BATCH-NAME "
mkdir -p profiles/ ${BATCH}
find ../../backend/ ${BATCH} / -type f -name " *.csv " -exec profiling-recipe/scripts/csv2gz.py {} ;
rsync -arzv --include= " */ " --include= " *.gz " --exclude " * " ../../backend/ ${BATCH} / profiles/ ${BATCH} /

运行分析管道

对config.yml文件进行必要的更改后，按如下方式运行分析管道

python profiling-recipe/profiles/profiling_pipeline.py  --config config_files/ ${CONFIG_FILE} .yml

如果有多个配置文件，则可以使用上述命令依次运行每个配置文件。

注意：分析管道中的每个步骤都使用上一步的输出作为其输入。因此，请确保在运行分析管道中的步骤之前已生成所有必需的输入文件。通过仅在配置文件中保留这些步骤，可以仅运行管道中的几个步骤。

将配置文件推送到 GitHub

如果使用数据存储库，请将新创建的配置文件推送到 DVC，并将 .dvc 文件和其他文件推送到 GitHub，如下所示

dvc add profiles/ ${BATCH} --recursive
dvc push
git add profiles/ ${BATCH} / * / * .dvc profiles/ ${BATCH} / * / * .gitignore
git commit -m ' add profiles '
git add *
git commit -m ' add files made in profiling '
git push

如果不使用 DVC 但使用数据存储库，请将所有新文件推送到 GitHub，如下所示

git add *
git commit -m ' add profiles '
git push

生成的文件

运行包含所有步骤的分析工作流程会生成以下文件

文件名	描述	地点
`<PLATE>.csv.gz`	聚合的井级配置文件	型材/批次/板材
`<PLATE>_augmented.csv.gz`	元数据注释配置文件	型材/批次/板材
`<PLATE>_normalized.csv.gz`	轮廓标准化为整个板	型材/批次/板材
`<PLATE>_normalized_negcon.csv.gz`	轮廓归一化至阴性对照	型材/批次/板材
`<PLATE>_normalized_feature_select_<LEVEL>.csv.gz`	在`plate` 、 `batch`或`all plates`级别选择特征的全板归一化轮廓。	型材/批次/板材
`<PLATE>_normalized_feature_select_negcon_<LEVEL>.csv.gz`	阴性对照归一化特征是在`plate` 、 `batch`或`all plates`水平上选择的特征	型材/批次/板材
`<BATCH>_normalized_feature_select_<LEVEL>.csv.gz`	批次级堆叠全板标准化轮廓，是在`batch`或`all plates`级选择的特征	gct/批次
`<BATCH>_normalized_feature_select_<LEVEL>.gct`	从`<BATCH>_normalized_feature_select_<LEVEL>.csv.gz`文件创建的`.gct`文件	gct/批次
`<BATCH>_normalized_feature_select_negcon_<LEVEL>.csv.gz`	批次级堆叠阴性对照归一化配置文件，是在`batch`或`all plates`级选择的功能	gct/批次
`<BATCH>_normalized_feature_select_negcon_<LEVEL>.gct`	从`<BATCH>_normalized_feature_select_negcon_<LEVEL>.csv.gz`文件创建的`.gct`文件	gct/批次
`summary.tsv`	统计汇总	质量控制/摘要
`<PLATE>_cell_count.png`	平板细胞计数	质量控制/热图/批次/板
`<PLATE>_correlation.png`	板上所有孔之间的成对相关性	质量控制/热图/批次/板
`<PLATE>_position_effect.png`	每个孔与同一行和同一列中的其他孔之间的匹配百分比	质量控制/热图/批次/板

配置文件

管道参数

这些是所有管道都需要的参数

管道名称

管道的名称有助于区分不同的配置文件。它不被管道本身使用。

 pipeline : <PIPELINE NAME>

输出目录

将存储配置文件的目录的名称。默认情况下是profiles 。

 output_dir : profiles

井名栏

aggregated剖面中井名列的名称。默认为Metadata_well_position 。

 platemap_well_column : Metadata_well_position

隔间名称

默认情况下，CellProfiler 特征是从三个区室中提取的： cells 、 cytoplasm和nuclei 。这些隔间在配置文件中列出，如下所示

 compartments :
  - cells
  - cytoplasm
  - nuclei

如果数据集中存在其他“非规范”隔间，则将它们添加到上面的列表中，如下所示

 compartments :
  - cells
  - cytoplasm
  - nuclei
  - newcompartment

注意：如果非规范隔间的名称是newcompartment ，则该隔间的功能应以Newcompartment开头（仅第一个字符应大写）。如果使用驼峰式大小写或任何其他格式作为要素名称，管道将会失败。

其他管道选项

 options :
  compression : gzip
  float_format : " %.5g "
  samples : all

compression - 配置文件.csv的压缩格式。默认值为gzip ，这是当前唯一接受的值。
float_format - 有效位数。
samples - 是否对所有样本或样本子集执行以下操作。默认all是当前唯一接受的值。

`aggregate`参数

这些是由pipeline_aggregate()函数处理的参数，该函数与pycytominer.cyto_utils.cells.SingleCells()交互并聚合单细胞配置文件以创建良好级别的配置文件。

 aggregate :
  perform : true
  plate_column : Metadata_Plate
  well_column : Metadata_Well
  method : median
  fields : all

perform - 是否执行聚合。默认为true 。如果不应执行此操作，则设置为false 。
plate_column - 具有板名称的列的名称。默认为Metadata_Plate 。
well_column - 具有孔名称的列的名称。默认为Metadata_Well 。
method - 如何执行聚合。默认值为median 。也接受mean 。
fields - 应聚合哪个视野的单元格？默认为all 。如果要聚合特定视野（例如1、4、9），可以按如下方式完成

 fields :
  - 1
  - 4
  - 9

此外，要将整个图像特征添加到配置文件中，请将特征类别列出到参数image_feature_categories中。例如

 image_feature_catageories :
  - Count
  - Intensity

`annotate`参数

这些是由pipeline_annotate()函数处理的参数，该函数与pycytominer.annotate()交互，并用元数据注释孔级别剖面。

 annotate :
  perform : true
  well_column : Metadata_Well
  external :
    perform : true
    file : <metadata file name>
    merge_column : <Column to merge on>

perform - 是否执行注释。默认为true 。如果不应执行此操作，则设置为false 。
well_column - 聚合配置文件中包含井名称的列。
external
- perform - 是否使用外部元数据注释配置文件。默认为true 。如果不应执行此操作，则设置为false 。
- file - 外部元数据文件，应位于文件夹metadata/external_metadata/中。
- merge_column - platemap.txt和external_metadata.tsv共用的扰动标识符列的名称。

`normalize`参数

这些是由pipeline_normalize()函数处理的参数，该函数与pycytominer.normalize()交互并将所有孔标准化为整个板。

 normalize :
  perform : true
  method : mad_robustize
  features : infer
  mad_robustize_fudge_factor : 0
  image_features : true

perform - 是否执行标准化。默认为true 。如果不应执行此操作，则设置为false 。
method - 使用哪种方法进行标准化。默认为mad_robustize 。 pycytominer 中还提供其他选项，例如standardize 、 robustize和spherize 。
features - 特征测量列的名称。默认值为infer ，它从带注释的配置文件推断 CellProfiler 功能。
mad_robustize_fudge_factor - 标准化方法为mad_robustize时的模糊因子参数。
image_features ：整个图像特征是否存在于带注释的配置文件中。默认为true 。如果不存在图像特征，则设置为false 。

`normalize_negcon`参数

这些是由pipeline_normalize()函数处理的参数，该函数与pycytominer.normalize()交互并将所有孔标准化为阴性对照。

 normalize_negcon :
  perform : true
  method : mad_robustize
  features : infer
  mad_robustize_fudge_factor : 0
  image_features : true

perform - 是否执行标准化。默认为true 。如果不应执行此操作，则设置为false 。
method - 使用哪种方法进行标准化。默认为mad_robustize 。 pycytominer 中还提供其他选项，例如standardize 、 robustize和spherize 。
features - 特征测量列的名称。默认值为infer ，它从带注释的配置文件推断 CellProfiler 功能。
mad_robustize_fudge_factor - 标准化方法为mad_robustize时的模糊因子参数。
image_features ：整个图像特征是否存在于带注释的配置文件中。默认为true 。如果不存在图像特征，则设置为false 。

`feature_select`参数

这些是由pipeline_feature_select()函数处理的参数，该函数与pycytominer.feature_select()交互并选择全板标准化配置文件中的特征。

  perform : true
  features : infer
  level : batch
  gct : false
  image_features : true
  operations :
    - variance_threshold
    - correlation_threshold
    - drop_na_columns
    - blocklist

perform - 是否执行特征选择。默认为true 。如果不应执行此操作，则设置为false 。
features - 特征测量列的名称。默认值为infer ，它从标准化配置文件中推断 CellProfiler 特征。
level - 应执行功能选择的级别。默认为batch 。特征选择也可以在batch和all板级别上执行。
gct - 是否创建批次级堆叠配置文件和.gct文件。默认为false 。仅当level为batch或all时，才会创建堆叠配置文件和.gct文件。
image_features ：整个图像特征是否存在于整个板标准化配置文件中。默认为true 。如果不存在图像特征，则设置为false 。
operations - 特征选择操作列表。 variance_threshold删除板上所有孔中方差低于阈值的特征。 correlation_threshold删除冗余特征。 drop_na_columns删除具有NaN值的特征。 blocklist删除属于功能阻止列表一部分的功能。

`feature_select_negcon`参数

这些是由pipeline_feature_select()函数处理的参数，该函数与pycytominer.feature_select()交互，并选择标准化为阴性对照的配置文件中的特征。

 feature_select_negcon :
  perform : true
  features : infer
  level : batch
  gct : false
  image_features : true
  operations :
    - variance_threshold
    - correlation_threshold
    - drop_na_columns
    - blocklist

perform - 是否执行特征选择。默认为true 。如果不应执行此操作，则设置为false 。
features - 特征测量列的名称。默认值为infer ，它从标准化配置文件中推断 CellProfiler 特征。
level - 应执行功能选择的级别。默认为batch 。特征选择也可以在batch和all板级别上执行。
gct - 是否创建批次级堆叠配置文件和.gct文件。默认为false 。仅当level为batch或all时，才会创建堆叠配置文件和.gct文件。
image_features ：整个图像特征是否存在于 negcon 标准化配置文件中。默认为true 。如果不存在图像特征，则设置为false 。
operations - 特征选择操作列表。 variance_threshold删除板上所有孔中方差低于阈值的特征。 correlation_threshold删除冗余特征。 drop_na_columns删除具有NaN值的特征。 blocklist删除属于功能阻止列表一部分的功能。

`quality_control`参数

这些参数指定要生成的质量控制指标和数据的类型。 summary生成一个包含摘要统计信息的表，而heatmap生成三个热图，每个热图显示不同的质量控制指标。

 quality_control :
  perform : true
  summary :
    perform : true
    row : Metadata_Row
    column : Metadata_Col
  heatmap :
    perform : true

perform - 是否生成质量控制指标或数字。默认为true 。如果不应生成这些，则设置为false 。

可以生成两种不同类型的质量控制指标。 summary创建summary.tsv其中包含每个批次中每个板的汇总统计数据。 heatmap生成三个热图 - 细胞计数与平板图、孔之间的相关性以及位置效应与平板图。

 summary :
  perform : true
  row : Metadata_Row
  column : Metadata_Col

perform - 是否生成摘要文件。默认为true 。如果不应生成此文件，则设置为false 。
row - load_data.csv中的行名称字段。
column - 列名称字段load_data.csv 。

 heatmap :
  perform : true

perform - 是否生成热图。默认为true 。如果不应生成热图，则设置为false 。

`batch`和`plates`参数

这些参数指定要处理的批次和板的名称。

 batch : <BATCH NAME>
plates :
  - name : <PLATE NAME>
    process : true
process : true

batch - 要处理的批次的名称。
plates -
- name - 要处理的板的名称。
- process - 是否对板材进行处理。默认为true 。如果不应处理此板，则设置为false 。
process - 是否处理批次。默认为true 。如果不应处理该批次，则设置为false 。

重新运行管道

本自述文件中的说明假定分析管道是在数据存储库中首次运行。您可能正在使用已包含配置文件的存储库中的新配置文件重新运行管道。在这种情况下，克隆数据存储库后，在运行管道之前下载 profiling-recipe 子模块并从 DVC 下载配置文件非常重要。这可以使用以下命令来完成

git submodule update --init --recursive
dvc pull

使用 DVC

有关使用 DVC 的其他信息可能对您有用：
当处理大文件或大文件夹时，不要使用git add将它们添加到 GH 中。相反，请使用dvc add将它们添加到 DVC。这会将大文件/文件夹上传到 S3，并在 GH 存储库中创建指向 S3 上上传的指针（我们跟踪该文件/文件夹而不是文件/文件夹本身）。它还更新 .gitignore，以便 GH 不会跟踪大文件/文件夹本身。然后dvc push将文件上传到S3。

 # Add a file or folder to DVC
dvc add LARGEFILE.csv
dvc push

然后将创建的文件/文件夹的 .dvc 版本与 .gitignore 一起添加到 github。犯罪。

git add LARGEFILE.csv.dvc
git add .gitignore
git commit -m " add largefile "

下载S3中DVC存储的数据：

 # Download ALL data stored by DVC in S3
# Only do this if you really, truly want ALL the data
dvc pull

 # Download a specific file stored by DVC in S3
dvc get https://github.com/ORGANIZATION/DATA-REPO.git relative/path/to/LARGEFILE.csv

DVC 将文件名转换为 S3 中的哈希值。要查看任何给定 DVC 文件的文件哈希（以便您可以直接在 S3 上找到它），请将 --show-url 标志添加到get命令中：

dvc get --show-url https://github.com/ORGANIZATION/DATA-REPO.git relative/path/to/LARGEFILE.csv

展开

profiling recipe