profiling recipe
1.0.0
profiling-recipe は、主に pycytominer 関数を使用して単一細胞の形態学的プロファイルを処理するスクリプトのコレクションです。 3つのスクリプトは、
profiling-pipeline.py - 画像ベースのプロファイル処理パイプラインを実行しますcsv2gz.py - .csvファイルを圧縮しますcreate_dirs.sh - 処理パイプラインの出力を保存するサブディレクトリを作成します。パッケージマネージャーとして Anaconda を使用します。ここの指示に従って Miniconda をインストールします。
大きなファイルの管理には、DVC によって追跡される AWS S3 ストレージを使用します。ここの手順に従って AWS CLI をインストールします。インストール後、AWS CLI インストールを次のように設定します。
aws configure次のことを求めるプロンプトが表示されます。
AWS Access Key ID: YOUR-KEY
AWS Secret Access Key: YOUR-SECRET-KEY
Default region name:例: us-east-1
Default output format: json
入力するプロファイルには、後で設定するバケットにアップロードする権限が必要であることに注意してください。
大きなファイルを AWS に保存/バージョン管理したくない場合は、AWS CLI のインストールをスキップできます。
単一セル プロファイルの集約にプロファイリング パイプラインを使用する場合は、 .sqliteファイルのサイズの少なくとも 2 倍のメモリを備えたシステムでパイプラインを実行することをお勧めします。パイプラインが集計の下流のステップを実行するためにのみ使用される場合は、ローカル マシン上で実行できます。
パイプラインには、次のように作成できる特定のフォルダー構造が必要です。
PROJECT_NAME= " INSERT-PROJECT-NAME "
mkdir -p ~ /work/projects/ ${PROJECT_NAME} /workspace/{backend,software}各バッチ内のすべてのプレートの単一セル プロファイルを含む.sqliteファイルとウェルレベルの集約プロファイルを含む.csvファイルをbackendフォルダーにダウンロードします。これら 2 つのファイルは、プロファイリング ハンドブックの第 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ディレクトリにダウンロードする必要があります。ファイルが 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} /environment.yml ファイルには、パイプラインの実行に必要な conda パッケージのリストが含まれています。
cp profiling-recipe/environment.yml .conda env create --force --file environment.ymlconda activate profilingこのプロジェクトの DVC を初期化し、大きなファイルを S3 に保存するように設定します。 DVC を使用しない場合は、この手順をスキップしてください。 S3 ではないリモート ストレージの場所に DVC を使用したい場合は、ここで手順を見つけてください。マシン上に複数の 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 - プレートとプレート マップ間のマッピングが含まれます。データのバッチごとにそのようなファイルが 1 つあります。ファイルには、 Assay_Plate_BarcodeおよびPlate_Map_Nameという名前の 2 つの列が含まれていますが、これらは変更しないでください。ファイル名も変更しないでください。このファイルは、カンマ区切りの.csvファイルである必要があります。platemap.txt - ウェル名と摂動名の間のマッピングが含まれています。このようなファイルは、バッチごとのプレート マップごとに 1 つあります。 2 つの列が必要です。1 つはwell_positionと呼ばれるウェル名 ( A01 、 A02 ...) を含み、もう 1 つは摂動識別子を含みます。摂動識別子列の名前はユーザー定義できます (変更する場合は、 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.txtCONFIG_FILE= " INSERT-CONFIG-FILE-NAME "
cd ~ /work/projects/ ${PROJECT_NAME} /workspace/software/ ${DATA} /
cp profiling-recipe/config_template.yml config_files/ ${CONFIG_FILE} .yml構成ファイルには、プロファイリング パイプラインによって呼び出されるさまざまな pycyminer 関数が必要とするすべてのパラメーターが含まれています。さまざまなパラメーターを使用してプロファイリング パイプラインを実行するために、複数の構成ファイルを作成できます。設定ファイルの各パラメータについては以下で説明します。パイプラインを実行する前に、構成ファイルに必要な変更をすべて加える必要があります。
プロファイリング パイプラインの最初のステップで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複数の構成ファイルがある場合は、上記のコマンドを使用して各構成ファイルを順番に実行できます。
注: プロファイリング パイプラインの各ステップは、前のステップからの出力を入力として使用します。したがって、プロファイリング パイプラインのステップを実行する前に、必要な入力ファイルがすべて生成されていることを確認してください。構成ファイルにそれらのステップのみを保持することで、パイプライン内のいくつかのステップのみを実行することができます。
データ リポジトリを使用している場合は、次のように、新しく作成したプロファイルを 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 pushDVC を使用せずにデータ リポジトリを使用する場合は、次のようにすべての新しいファイルを 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 | バッチレベルまたはall plates batchで選択されたフィーチャーであるバッチレベルのスタックされたプレート全体の正規化プロファイル | 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 : profilesaggregatedプロファイル内のウェル名列の名前。デフォルトではMetadata_well_positionです。
platemap_well_column : Metadata_well_positionデフォルトでは、CellProfiler の特徴は、 cells 、 cytoplasm 、 nuclei 3 つのコンパートメントから抽出されます。これらのコンパートメントは構成ファイルに次のようにリストされます。
compartments :
- cells
- cytoplasm
- nuclei他の「非正規」コンパートメントがデータセット内に存在する場合、それらは次のように上記のリストに追加されます。
compartments :
- cells
- cytoplasm
- nuclei
- newcompartment注: 非正規コンパートメントの名前がnewcompartmentの場合、そのコンパートメントの機能はNewcompartmentで始まる必要があります (最初の文字のみ大文字にする必要があります)。機能名にキャメルケースまたはその他の形式が使用されている場合、パイプラインは失敗します。
options :
compression : gzip
float_format : " %.5g "
samples : allcompression - プロファイル.csvの圧縮形式。デフォルトはgzipで、現在受け入れられる唯一の値です。float_format - 有効桁数。samples - すべてのサンプルまたはサンプルのサブセットに対して次の操作を実行するかどうか。デフォルトはall 、現在受け入れられる唯一の値です。 aggregateパラメータこれらは、 pycytominer.cyto_utils.cells.SingleCells()と対話し、単一セル プロファイルを集約してウェル レベルのプロファイルを作成するpipeline_aggregate()関数によって処理されるパラメーターです。
aggregate :
perform : true
plate_column : Metadata_Plate
well_column : Metadata_Well
method : median
fields : allperform - 集計を実行するかどうか。デフォルトは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これらはpycytominer.annotate()と対話し、坑井レベルのプロファイルにメタデータで注釈を付けるpipeline_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 - 集約されたプロファイル内のウェル名を含む列。externalperform - プロファイルに外部メタデータの注釈を付けるかどうか。デフォルトはtrueです。これを実行しない場合はfalseに設定します。file - フォルダーmetadata/external_metadata/にある外部メタデータ ファイル。merge_column - platemap.txtとexternal_metadata.tsvに共通の摂動識別子列の名前。 normalizeこれらは、 pycytominer.normalize()と対話し、すべてのウェルをプレート全体に対して正規化するpipeline_normalize()関数によって処理されるパラメーターです。
normalize :
perform : true
method : mad_robustize
features : infer
mad_robustize_fudge_factor : 0
image_features : trueperform - 正規化を実行するかどうか。デフォルトはtrueです。これを実行しない場合はfalseに設定します。method - 正規化に使用する方法。デフォルトはmad_robustizeです。 pycyminer では、 standardize 、 robustize 、 spherizeなどの他のオプションも利用できます。features - 特徴測定列の名前。デフォルトはinferで、注釈付きプロファイルから CellProfiler 機能を推測します。mad_robustize_fudge_factor - 正規化方法がmad_robustizeの場合のファッジ係数パラメーター。image_features : 画像の特徴全体が注釈付きプロファイルに存在するかどうか。デフォルトはtrueです。画像の特徴が存在しない場合はfalseに設定します。normalize_negconパラメータこれらは、 pycytominer.normalize()と対話し、すべてのウェルをネガティブ コントロールに対して正規化するpipeline_normalize()関数によって処理されるパラメーターです。
normalize_negcon :
perform : true
method : mad_robustize
features : infer
mad_robustize_fudge_factor : 0
image_features : trueperform - 正規化を実行するかどうか。デフォルトはtrueです。これを実行しない場合はfalseに設定します。method - 正規化に使用する方法。デフォルトはmad_robustizeです。 pycyminer では、 standardize 、 robustize 、 spherizeなどの他のオプションも利用できます。features - 特徴測定列の名前。デフォルトはinferで、注釈付きプロファイルから CellProfiler 機能を推測します。mad_robustize_fudge_factor - 正規化方法がmad_robustizeの場合のファッジ係数パラメーター。image_features : 画像の特徴全体が注釈付きプロファイルに存在するかどうか。デフォルトはtrueです。画像の特徴が存在しない場合はfalseに設定します。 feature_selectパラメータこれらは、 pycytominer.feature_select()と対話し、プレート全体の正規化プロファイル内の特徴を選択するpipeline_feature_select()関数によって処理されるパラメーターです。
perform : true
features : infer
level : batch
gct : false
image_features : true
operations :
- variance_threshold
- correlation_threshold
- drop_na_columns
- blocklistperform - 機能の選択を実行するかどうか。デフォルトはtrueです。これを実行しない場合はfalseに設定します。features - 特徴測定列の名前。デフォルトはinferで、正規化されたプロファイルから CellProfiler 機能を推測します。level - 機能の選択を実行するレベル。デフォルトはbatchです。特徴の選択は、 batchおよびallプレート レベルで実行することもできます。gct - バッチ レベルのスタック プロファイルと.gctファイルを作成するかどうか。デフォルトはfalseです。スタックされたプロファイルと.gctファイルは、 levelがbatchまたはall場合にのみ作成されます。image_features : 画像特徴全体がプレート正規化プロファイル全体に存在するかどうか。デフォルトはtrueです。画像の特徴が存在しない場合はfalseに設定します。operations - 機能選択操作のリスト。 variance_thresholdプレート上のすべてのウェルにわたって、しきい値未満の分散を持つフィーチャを削除します。 correlation_threshold冗長な機能を削除します。 drop_na_columns NaN値を持つ特徴を削除します。 blocklist機能ブロックリストの一部である機能を削除します。feature_select_negconパラメータこれらは、 pycytominer.feature_select()と対話し、ネガティブ コントロールに対して正規化されたプロファイル内の特徴を選択するpipeline_feature_select()関数によって処理されるパラメーターです。
feature_select_negcon :
perform : true
features : infer
level : batch
gct : false
image_features : true
operations :
- variance_threshold
- correlation_threshold
- drop_na_columns
- blocklistperform - 機能の選択を実行するかどうか。デフォルトはtrueです。これを実行しない場合はfalseに設定します。features - 特徴測定列の名前。デフォルトはinferで、正規化されたプロファイルから CellProfiler 機能を推測します。level - 機能の選択を実行するレベル。デフォルトはbatchです。特徴の選択は、 batchおよびallプレート レベルで実行することもできます。gct - バッチ レベルのスタック プロファイルと.gctファイルを作成するかどうか。デフォルトはfalseです。スタックされたプロファイルと.gctファイルは、 levelがbatchまたはall場合にのみ作成されます。image_features : 画像全体の特徴が negcon 正規化プロファイルに存在するかどうか。デフォルトはtrueです。画像の特徴が存在しない場合はfalseに設定します。operations - 機能選択操作のリスト。 variance_thresholdプレート上のすべてのウェルにわたって、しきい値未満の分散を持つフィーチャを削除します。 correlation_threshold冗長な機能を削除します。 drop_na_columns NaN値を持つ特徴を削除します。 blocklist機能ブロックリストの一部である機能を削除します。 quality_controlパラメータこれらのパラメータは、生成する品質管理指標と数値のタイプを指定します。 summary概要統計を含むテーブルを生成し、 heatmap 3 つのヒートマップを生成し、それぞれに異なる品質管理メトリックが表示されます。
quality_control :
perform : true
summary :
perform : true
row : Metadata_Row
column : Metadata_Col
heatmap :
perform : trueperform - 品質管理の指標または数値を生成するかどうか。デフォルトはtrueです。これらを生成しない場合はfalseに設定します。生成できる QC メトリクスには 2 つの異なるタイプがあります。 summary各バッチの各プレートの概要統計を含むsummary.tsvを作成します。 heatmap細胞数対プレートマップ、ウェル間の相関関係、および位置効果対プレートマップの 3 つのヒートマップを生成します。
summary :
perform : true
row : Metadata_Row
column : Metadata_Colperform - 概要ファイルを生成するかどうか。デフォルトはtrueです。このファイルを生成しない場合はfalseに設定します。row load_data.csvの行名フィールド。column - 列名フィールドload_data.csv 。 heatmap :
perform : trueperform - ヒートマップを生成するかどうか。デフォルトはtrueです。ヒートマップを生成しない場合はfalseに設定します。 batchとplatesパラメータこれらのパラメータは、処理するバッチとプレートの名前を指定します。
batch : <BATCH NAME>
plates :
- name : <PLATE NAME>
process : true
process : truebatch - 処理されるバッチの名前。plates -name - 処理されるプレートの名前。process - プレートを処理するかどうか。デフォルトはtrueです。このプレートを処理しない場合はfalseに設定します。process - バッチを処理するかどうか。デフォルトはtrueです。このバッチを処理しない場合はfalseに設定します。git submodule update --init --recursive
dvc pullDVC の使用に関する役立つ追加情報:
大きなファイルまたは大きなフォルダーを処理する場合は、 git addを使用してそれらを GH に追加しないでください。代わりに、 dvc add使用してそれらを DVC に追加します。これにより、大きなファイル/フォルダーが S3 にアップロードされ、S3 上のそのアップロードへのポインターが GH リポジトリ内に作成されます (ファイル/フォルダー自体の代わりに追跡します)。また、GH が大きなファイル/フォルダー自体を追跡しないように .gitignore も更新されます。次に、 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 " # 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 上で直接見つけることができます)、 getコマンドに --show-url フラグを追加します。
dvc get --show-url https://github.com/ORGANIZATION/DATA-REPO.git relative/path/to/LARGEFILE.csv
