profiling recipe
1.0.0
Рецепт профилирования представляет собой набор скриптов, которые в основном используют функции пицитоминера для обработки морфологических профилей одиночных клеток. Эти три сценария
profiling-pipeline.py — запускает конвейер обработки профиля на основе изображений.csv2gz.py — сжимает файлы .csvcreate_dirs.sh — создает подкаталоги для хранения результатов конвейера обработки.Мы используем Anaconda в качестве менеджера пакетов. Установите Miniconda, следуя инструкциям здесь.
Мы используем хранилище AWS S3, отслеживаемое DVC, для управления большими файлами. Установите AWS CLI, следуя инструкциям здесь. После установки настройте установку AWS CLI с помощью
aws configure Вам будет предложено:
AWS Access Key ID: YOUR-KEY
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 . Убедитесь, что файлы заархивированы 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. Если вы хотите использовать DVC для удаленного хранилища, отличного от S3, найдите инструкции здесь. Если на вашем компьютере установлено несколько профилей AWS и вы не хотите использовать профиль по умолчанию для DVC, вы можете указать, какой профиль использовать, запустив dvc remote modify S3storage profile PROFILE_NAME в любой момент между добавлением удаленного устройства и выполнением окончательной отправки DVC.
# 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.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Файл конфигурации содержит все параметры, которые требуются различным функциям 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Если существует несколько файлов конфигурации, каждый из них можно запустить один за другим с помощью приведенной выше команды.
Примечание. Каждый шаг конвейера профилирования использует выходные данные предыдущего шага в качестве входных данных. Поэтому перед выполнением шагов конвейера профилирования убедитесь, что все необходимые входные файлы созданы. Можно выполнить только несколько шагов конвейера, сохранив только эти шаги в файле конфигурации.
Если вы используете репозиторий данных, отправьте вновь созданные профили в 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 | Файл .gct , созданный на основе файла <BATCH>_normalized_feature_select_<LEVEL>.csv.gz | gct/ПАРТИЯ |
<BATCH>_normalized_feature_select_negcon_<LEVEL>.csv.gz | Нормализованные профили негативного контроля на уровне партии, которые выбраны на уровне batch или all plates | gct/ПАРТИЯ |
<BATCH>_normalized_feature_select_negcon_<LEVEL>.gct | Файл .gct , созданный на основе файла <BATCH>_normalized_feature_select_negcon_<LEVEL>.csv.gz | 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 : allcompression — формат сжатия для профиля .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 : 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 параметры Это параметры, которые обрабатываются функцией 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 – Столбец с названиями скважин в агрегированных профилях.externalperform — следует ли аннотировать профили внешними метаданными. По умолчанию 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 : trueperform — выполнять ли нормализацию. По умолчанию 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 : trueperform — выполнять ли нормализацию. По умолчанию 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
- 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 Это параметры, которые обрабатываются функцией 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
- 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 создает три тепловые карты, каждая из которых показывает разные показатели контроля качества.
quality_control :
perform : true
summary :
perform : true
row : Metadata_Row
column : Metadata_Col
heatmap :
perform : trueperform — генерировать ли показатели или цифры контроля качества. По умолчанию true . Установите значение false если они не должны создаваться. Существует два разных типа метрик контроля качества, которые можно сгенерировать. summary создает summary.tsv со сводной статистикой каждой пластины из каждой партии. heatmap генерирует три тепловые карты: количество клеток по сравнению с картой планшета, корреляция между лунками и эффект положения по сравнению с картой планшета.
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 pull Дополнительная информация об использовании DVC, которая может оказаться вам полезной:
При работе с большими файлами или большой папкой НЕ добавляйте их в GH с помощью git add . Вместо этого добавьте их в DVC с помощью dvc add . При этом большой файл/папка загружается на S3 и создается указатель на эту загрузку на S3 в репозитории GH (который мы отслеживаем вместо самого файла/папки). Он также обновляет .gitignore, чтобы GH не отслеживал сам большой файл/папку. Затем dvc push , чтобы загрузить файлы на S3.
# Add a file or folder to DVC
dvc add LARGEFILE.csv
dvc pushЗатем добавьте версию .dvc файла/папки, созданную в github, вместе с .gitignore. Совершить.
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. Чтобы увидеть хеш файла (чтобы вы могли найти его непосредственно на S3) для любого файла DVC, добавьте флаг --show-url к команде get :
dvc get --show-url https://github.com/ORGANIZATION/DATA-REPO.git relative/path/to/LARGEFILE.csv
