profiling recipe
1.0.0
A receita de criação de perfil é uma coleção de scripts que usam principalmente funções do pycytominer para processar perfis morfológicos unicelulares. Os três roteiros são
profiling-pipeline.py - executa o pipeline de processamento de perfil baseado em imagemcsv2gz.py - compacta arquivos .csvcreate_dirs.sh – cria os subdiretórios para armazenar a saída do pipeline de processamentoUsamos Anaconda como nosso gerenciador de pacotes. Instale o Miniconda seguindo as instruções aqui.
Usamos armazenamento AWS S3 rastreado por DVC para gerenciamento de arquivos grandes. Instale o AWS CLI seguindo as instruções aqui. Após a instalação, configure a instalação da AWS CLI com
aws configure Ele irá solicitar:
AWS Access Key ID: SUA-CHAVE
AWS Secret Access Key: SUA CHAVE SECRETA
Default region name: por exemplo, us-east-1
Default output format: json
Observe que o perfil inserido deve ter permissão para fazer upload para o bucket definido posteriormente.
Se não quiser armazenar/versionar arquivos grandes na AWS, você pode pular a instalação da AWS CLI.
Se o pipeline de criação de perfil for usado para agregar perfis de célula única, recomendamos executar o pipeline em um sistema com memória pelo menos duas vezes maior que o tamanho dos arquivos .sqlite . Se o pipeline for usado apenas para executar etapas posteriores à agregação, ele poderá ser executado em uma máquina local.
O pipeline requer uma estrutura de pastas específica que pode ser criada da seguinte maneira
PROJECT_NAME= " INSERT-PROJECT-NAME "
mkdir -p ~ /work/projects/ ${PROJECT_NAME} /workspace/{backend,software} Baixe o arquivo .sqlite , que contém os perfis de célula única e o arquivo .csv , que contém os perfis agregados de nível de poço, para todas as placas em cada lote para a pasta backend . Esses dois arquivos são criados executando os comandos no capítulo 5.3 do manual de criação de perfil. Depois de baixar os arquivos, a estrutura de pastas deve ficar assim
backend
├── batch1
│ ├── plate1
│ │ ├── plate1.csv
│ │ └── plate1.sqlite
│ └── plate2
│ ├── plate2.csv
│ └── plate2.sqlite
└── batch2
├── plate1
│ ├── plate1.csv
│ └── plate1.sqlite
└── plate2
├── plate2.csv
└── plate2.sqlite Nota: A agregação pode ainda não ter sido realizada. Nesse caso, apenas o arquivo .sqlite estará disponível para download.
Soldagem é um processo pelo qual o repositório de receita de perfil é adicionado ao repositório de dados como um submódulo, de modo que os arquivos no repositório de dados e os scripts na receita de perfil que gerou esses arquivos sejam versionados juntos. Instruções para soldagem são fornecidas aqui. É altamente recomendável unir a receita de criação de perfil ao repositório de dados. Após a soldagem, clone o repositório de dados para a pasta software , usando o comando
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 --recursiveApós a clonagem, a estrutura de pastas deve ficar assim
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É possível executar o pipeline sem unir o repositório de receitas de criação de perfil ao repositório de dados. Se executado dessa maneira, o repositório de receita de criação de perfil deverá ser clonado em um diretório de dados como um subdiretório. Então a estrutura de pastas ficará assim.
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
A geração da tabela de estatísticas resumidas requer arquivos load_data_csv . Esses arquivos devem ser transferidos por download para o diretório load_data_csv . Certifique-se de que os arquivos estejam compactados e que a estrutura de pastas seja a seguinte.
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.gzO pipeline deve ser executado a partir do repositório ou diretório de dados.
DATA= " INSERT-NAME-OF-DATA-REPO-OR-DIR "
cd ~ /work/projects/ ${PROJECT_NAME} /workspace/software/ ${DATA} /O arquivo Environment.yml contém a lista de pacotes conda necessários para executar o pipeline.
cp profiling-recipe/environment.yml .conda env create --force --file environment.ymlconda activate profiling Inicialize o DVC para este projeto e configure-o para armazenar arquivos grandes no S3. Pule esta etapa se não estiver usando DVC. Se você quiser usar o DVC para um local de armazenamento remoto que não seja o S3, encontre instruções aqui. Se você tiver vários perfis da AWS em sua máquina e não quiser usar o perfil padrão para DVC, poderá especificar qual perfil usar executando dvc remote modify S3storage profile PROFILE_NAME em qualquer ponto entre a adição do controle remoto e a execução do push DVC final.
# 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 " Os diretórios que conterão a saída do pipeline são criados da seguinte forma
profiling-recipe/scripts/create_dirs.sh O pipeline requer que barcode_platemap.csv e platemap.txt sejam executados. Um external_metadata.tsv opcional também pode ser fornecido para anotações adicionais. A seguir estão as descrições de cada um desses arquivos
barcode_platemap.csv - contém o mapeamento entre placas e mapas de placas. Existe um desses arquivos por lote de dados. O arquivo contém duas colunas cujos nomes são Assay_Plate_Barcode e Plate_Map_Name , que não devem ser alterados. O nome do arquivo também não deve ser alterado. Este arquivo deve ser um arquivo .csv separado por vírgula.platemap.txt - contém o mapeamento entre nomes de poços e nomes de perturbações. Existe um desses arquivos por mapa de placa por lote. São necessárias duas colunas, uma com os nomes dos poços ( A01 , A02 ...) chamada well_position e outra com o identificador de perturbação. O nome da coluna do identificador de perturbação pode ser definido pelo usuário (se alterado, altere o nome no arquivo config.yml ). O nome deste arquivo pode ser alterado. Se alterado, altere também o nome em barcode_platemap.csv . Este arquivo deve ser um arquivo .txt separado por tabulaçõesexternal_metadata.tsv - contém o mapeamento entre o identificador de perturbação e outros metadados. Este arquivo é opcional. A coluna do identificador de perturbação deve ter o mesmo nome da coluna em platemap.txt . Este arquivo deve ser um arquivo .tsv separado por tabulações. A seguir está um exemplo do arquivo barcode_platemap.csv
Assay_Plate_Barcode,Plate_Map_Name
plate1,platemap
plate2,platemap
Aqui está um exemplo de arquivo de mapa de placa e aqui está um exemplo de arquivo de metadados externos.
Esses arquivos devem ser adicionados à pasta apropriada para que a estrutura da pasta fique conforme abaixo
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} .ymlO arquivo de configuração contém todos os parâmetros exigidos por várias funções do pycytominer, chamadas pelo pipeline de criação de perfil. Para executar o pipeline de criação de perfil com parâmetros diferentes, vários arquivos de configuração podem ser criados. Cada parâmetro no arquivo de configuração é descrito abaixo. Todas as alterações necessárias no arquivo de configuração devem ser feitas antes que o pipeline possa ser executado.
Se a primeira etapa do pipeline de criação de perfil, aggregate , já tiver sido executada (na pasta backend , há um arquivo .csv além do arquivo .sqlite ), então o arquivo .csv deverá ser copiado para o repositório de dados ou diretório de dados . Caso contrário, vá para Executando o pipeline de criação de perfil.
Execute os comandos a seguir para cada lote separadamente. Esses comandos criam uma pasta para cada lote, compactam os arquivos .csv e depois os copiam para o repositório ou diretório de dados.
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} / Depois de fazer as alterações necessárias no arquivo config.yml , execute o pipeline de criação de perfil da seguinte maneira
python profiling-recipe/profiles/profiling_pipeline.py --config config_files/ ${CONFIG_FILE} .ymlSe houver vários arquivos de configuração, cada um deles poderá ser executado um após o outro usando o comando acima.
Observação: cada etapa do pipeline de criação de perfil usa a saída da etapa anterior como entrada. Portanto, certifique-se de que todos os arquivos de entrada necessários foram gerados antes de executar as etapas no pipeline de criação de perfil. É possível executar apenas algumas etapas no pipeline mantendo apenas essas etapas no arquivo de configuração.
Se estiver usando um repositório de dados, envie os perfis recém-criados para o DVC e os arquivos .dvc e outros arquivos para o GitHub da seguinte maneira
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 pushSe não estiver usando DVC, mas usando um repositório de dados, envie todos os novos arquivos para o GitHub da seguinte maneira
git add *
git commit -m ' add profiles '
git pushA execução do fluxo de trabalho de criação de perfil com todas as etapas incluídas gera os seguintes arquivos
| Nome do arquivo | Descrição | Localização |
|---|---|---|
<PLATE>.csv.gz | Perfis de nível de poço agregados | perfis/LOTE/PLATA |
<PLATE>_augmented.csv.gz | Perfis anotados de metadados | perfis/LOTE/PLATA |
<PLATE>_normalized.csv.gz | Perfis normalizados para toda a placa | perfis/LOTE/PLATA |
<PLATE>_normalized_negcon.csv.gz | Perfis normalizados para o controle negativo | perfis/LOTE/PLATA |
<PLATE>_normalized_feature_select_<LEVEL>.csv.gz | Perfis normalizados de placa inteira com recurso selecionado no nível de plate , batch ou all plates | perfis/LOTE/PLATA |
<PLATE>_normalized_feature_select_negcon_<LEVEL>.csv.gz | Perfis normalizados de controle negativo que são selecionados em nível de plate , batch ou all plates | perfis/LOTE/PLATA |
<BATCH>_normalized_feature_select_<LEVEL>.csv.gz | Perfis normalizados de placa inteira empilhados em nível de lote que são selecionados no nível batch ou all plates | gct/LOTE |
<BATCH>_normalized_feature_select_<LEVEL>.gct | Arquivo .gct criado a partir do arquivo <BATCH>_normalized_feature_select_<LEVEL>.csv.gz | gct/LOTE |
<BATCH>_normalized_feature_select_negcon_<LEVEL>.csv.gz | Perfis normalizados de controle negativo empilhados em nível de lote que são selecionados no nível batch ou all plates | gct/LOTE |
<BATCH>_normalized_feature_select_negcon_<LEVEL>.gct | Arquivo .gct criado a partir do arquivo <BATCH>_normalized_feature_select_negcon_<LEVEL>.csv.gz | gct/LOTE |
summary.tsv | Estatísticas resumidas | controle de qualidade/resumo |
<PLATE>_cell_count.png | Contagem de células da placa | controle de qualidade/mapa de calor/LOTE/PLATA |
<PLATE>_correlation.png | Correlação de pares entre todos os poços em uma placa | controle de qualidade/mapa de calor/LOTE/PLATA |
<PLATE>_position_effect.png | Porcentagem de correspondência entre cada poço e outros poços na mesma linha e coluna | controle de qualidade/mapa de calor/LOTE/PLATA |
Estes são os parâmetros que todos os pipelines exigirão
O nome do pipeline ajuda a distinguir os diferentes arquivos de configuração. Não é usado pelo próprio pipeline.
pipeline : <PIPELINE NAME> Nome do diretório onde os perfis serão armazenados. São profiles por padrão.
output_dir : profiles Nome da coluna de nome de poço nos perfis aggregated . É Metadata_well_position por padrão.
platemap_well_column : Metadata_well_position Por padrão, os recursos do CellProfiler são extraídos de três compartimentos, cells , cytoplasm e nuclei . Esses compartimentos estão listados no arquivo de configuração da seguinte forma
compartments :
- cells
- cytoplasm
- nucleiSe outros compartimentos 'não canônicos' estiverem presentes no conjunto de dados, eles serão adicionados à lista acima da seguinte forma
compartments :
- cells
- cytoplasm
- nuclei
- newcompartment Nota: se o nome do compartimento não canônico for newcompartment então os recursos desse compartimento deverão começar com Newcompartment (apenas o primeiro caractere deverá ser maiúsculo). O pipeline falhará se camel case ou qualquer outro formato for usado para nomes de recursos.
options :
compression : gzip
float_format : " %.5g "
samples : allcompression - O formato de compactação para o perfil .csv s. O padrão é gzip , que atualmente é o único valor aceito.float_format - O número de dígitos significativos.samples - Se as seguintes operações devem ser executadas em todas ou em um subconjunto de amostras. O padrão é all , que é atualmente o único valor aceito. aggregate Esses são parâmetros processados pela função pipeline_aggregate() que interage com pycytominer.cyto_utils.cells.SingleCells() e agrega perfis de célula única para criar perfis de nível de poço.
aggregate :
perform : true
plate_column : Metadata_Plate
well_column : Metadata_Well
method : median
fields : allperform - Se deve realizar a agregação. O padrão é true . Defina como false se isso não deve ser executado.plate_column - Nome da coluna com o nome da placa. O padrão é Metadata_Plate .well_column - Nome da coluna com os nomes dos poços. O padrão é Metadata_Well .method - Como realizar a agregação. O padrão é median . Também aceita mean .fields - Células de qual campo de visão deve ser agregado? O padrão é all . Se campos de visão específicos devem ser agregados (por exemplo, 1, 4, 9), isso pode ser feito da seguinte forma fields :
- 1
- 4
- 9 Além disso, para adicionar recursos de imagem inteiros aos perfis, liste as categorias de recursos no parâmetro image_feature_categories . Por exemplo
image_feature_catageories :
- Count
- Intensity annotate parâmetros Esses são parâmetros processados pela função pipeline_annotate() que interage com pycytominer.annotate() e anota os perfis de nível de poço com metadados.
annotate :
perform : true
well_column : Metadata_Well
external :
perform : true
file : <metadata file name>
merge_column : <Column to merge on>perform - Se deseja realizar anotação. O padrão é true . Defina como false se isso não deve ser executado.well_column - Coluna com os nomes dos poços nos perfis agregados.externalperform - Se deseja anotar os perfis com metadados externos. O padrão é true . Defina como false se isso não deve ser executado.file - arquivo de metadados externos que deve estar na pasta metadata/external_metadata/ .merge_column - Nome da coluna do identificador de perturbação que é comum a platemap.txt e external_metadata.tsv . normalize parâmetros Esses são parâmetros processados pela função pipeline_normalize() que interage com pycytominer.normalize() e normaliza todos os poços para toda a placa.
normalize :
perform : true
method : mad_robustize
features : infer
mad_robustize_fudge_factor : 0
image_features : trueperform - Se deve realizar a normalização. O padrão é true . Defina como false se isso não deve ser executado.method - Qual método usar para normalização. O padrão é mad_robustize . Outras opções estão disponíveis no pycytominer, como standardize , robustize e spherize .features – Nomes das colunas de medição de recursos. O padrão é infer , que infere recursos do CellProfiler a partir dos perfis anotados.mad_robustize_fudge_factor - O parâmetro do fator de correção se o método de normalização for mad_robustize .image_features : se todos os recursos da imagem estão presentes nos perfis anotados. O padrão é true . Defina como false se os recursos da imagem não estiverem presentes.normalize_negcon Esses são parâmetros processados pela função pipeline_normalize() que interage com pycytominer.normalize() e normaliza todos os poços para o controle negativo.
normalize_negcon :
perform : true
method : mad_robustize
features : infer
mad_robustize_fudge_factor : 0
image_features : trueperform - Se deve realizar a normalização. O padrão é true . Defina como false se isso não deve ser executado.method - Qual método usar para normalização. O padrão é mad_robustize . Outras opções estão disponíveis no pycytominer, como standardize , robustize e spherize .features – Nomes das colunas de medição de recursos. O padrão é infer , que infere recursos do CellProfiler a partir dos perfis anotados.mad_robustize_fudge_factor - O parâmetro do fator de correção se o método de normalização for mad_robustize .image_features : se todos os recursos da imagem estão presentes nos perfis anotados. O padrão é true . Defina como false se os recursos da imagem não estiverem presentes. feature_select Esses são parâmetros processados pela função pipeline_feature_select() que interage com pycytominer.feature_select() e seleciona recursos nos perfis normalizados de placa inteira.
perform : true
features : infer
level : batch
gct : false
image_features : true
operations :
- variance_threshold
- correlation_threshold
- drop_na_columns
- blocklistperform - Se deve realizar a seleção de recursos. O padrão é true . Defina como false se isso não deve ser executado.features – Nomes das colunas de medição de recursos. O padrão é infer , que infere recursos do CellProfiler a partir dos perfis normalizados.level - Nível no qual a seleção de recursos deve ser executada. O padrão é batch . A seleção de recursos também pode ser realizada em batch e em nível all as placas.gct - Se deseja criar um perfil empilhado em nível de lote e um arquivo .gct . O padrão é false . Perfis empilhados e arquivos .gct são criados somente quando level é batch ou all .image_features : se os recursos da imagem inteira estão presentes em todos os perfis normalizados da placa. O padrão é true . Defina como false se os recursos da imagem não estiverem presentes.operations - Lista de operações de seleção de recursos. variance_threshold remove recursos que apresentam variação abaixo do limite, em todos os poços de uma placa. correlation_threshold remove recursos redundantes. drop_na_columns remove recursos com valores NaN . blocklist remove recursos que fazem parte da lista de bloqueio de recursos.feature_select_negcon Esses são parâmetros processados pela função pipeline_feature_select() que interage com pycytominer.feature_select() e seleciona recursos nos perfis normalizados para o controle negativo.
feature_select_negcon :
perform : true
features : infer
level : batch
gct : false
image_features : true
operations :
- variance_threshold
- correlation_threshold
- drop_na_columns
- blocklistperform - Se deve realizar a seleção de recursos. O padrão é true . Defina como false se isso não deve ser executado.features – Nomes das colunas de medição de recursos. O padrão é infer , que infere recursos do CellProfiler a partir dos perfis normalizados.level - Nível no qual a seleção de recursos deve ser executada. O padrão é batch . A seleção de recursos também pode ser realizada em batch e em nível all as placas.gct - Se deseja criar um perfil empilhado em nível de lote e um arquivo .gct . O padrão é false . Perfis empilhados e arquivos .gct são criados somente quando level é batch ou all .image_features : se todos os recursos da imagem estão presentes nos perfis normalizados negcon. O padrão é true . Defina como false se os recursos da imagem não estiverem presentes.operations - Lista de operações de seleção de recursos. variance_threshold remove recursos que apresentam variação abaixo do limite, em todos os poços de uma placa. correlation_threshold remove recursos redundantes. drop_na_columns remove recursos com valores NaN . blocklist remove recursos que fazem parte da lista de bloqueio de recursos. quality_control Esses parâmetros especificam o tipo de métricas e números de controle de qualidade a serem gerados. summary gera uma tabela com estatísticas resumidas, enquanto heatmap gera três mapas de calor, cada um mostrando uma métrica de controle de qualidade diferente.
quality_control :
perform : true
summary :
perform : true
row : Metadata_Row
column : Metadata_Col
heatmap :
perform : trueperform - Seja para gerar métricas ou números de controle de qualidade. O padrão é true . Defina como false se estes não devem ser gerados. Existem dois tipos diferentes de métricas de controle de qualidade que podem ser geradas. summary cria summary.tsv com estatísticas resumidas de cada placa de cada lote. heatmap gera três heatmaps - contagem de células vs. platemap, correlação entre os poços e efeito de posição vs. platemap.
summary :
perform : true
row : Metadata_Row
column : Metadata_Colperform - Se deve ou não gerar o arquivo de resumo. O padrão é true . Defina como false se este arquivo não deve ser gerado.row - Campo de nome de linha em load_data.csv .column - campo de nome da coluna load_data.csv . heatmap :
perform : trueperform - Se deve ou não gerar mapas de calor. O padrão é true . Defina como false se os mapas de calor não devem ser gerados. batch e platesEsses parâmetros especificam o nome do lote e da placa a ser processada.
batch : <BATCH NAME>
plates :
- name : <PLATE NAME>
process : true
process : truebatch - Nome do lote a ser processado.plates -name - Nome da placa a ser processada.process - Se a placa deve ser processada. O padrão é true . Defina como false se esta placa não deve ser processada.process - Se o lote deve ser processado. O padrão é true . Defina como false se este lote não precisar ser processado.git submodule update --init --recursive
dvc pull Informações adicionais sobre o uso do DVC que podem ser úteis:
Ao manusear arquivos grandes ou pastas grandes, NÃO os adicione ao GH com git add . Em vez disso, adicione-os ao DVC com dvc add . Isso carrega o arquivo/pasta grande para o S3 e cria um ponteiro para esse upload no S3 no repositório GH (que rastreamos em vez do próprio arquivo/pasta). Ele também atualiza .gitignore para que o GH não rastreie o arquivo/pasta grande em si. Em seguida, dvc push para fazer upload dos arquivos para o S3.
# Add a file or folder to DVC
dvc add LARGEFILE.csv
dvc pushEm seguida, adicione a versão .dvc do arquivo/pasta criado no github junto com .gitignore. Comprometer-se.
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 transforma nomes de arquivos em hashes no S3. Para ver o hash do arquivo (para que você possa encontrá-lo diretamente no S3) para qualquer arquivo DVC, adicione o sinalizador --show-url ao comando get :
dvc get --show-url https://github.com/ORGANIZATION/DATA-REPO.git relative/path/to/LARGEFILE.csv
