profiling recipe
1.0.0
La receta de creación de perfiles es una colección de scripts que utilizan principalmente funciones de pycytominer para procesar perfiles morfológicos unicelulares. Los tres guiones son
profiling-pipeline.py : ejecuta el proceso de procesamiento de perfiles basado en imágenescsv2gz.py : comprime archivos .csvcreate_dirs.sh : crea los subdirectorios para almacenar la salida del proceso de procesamiento.Usamos Anaconda como nuestro administrador de paquetes. Instale Miniconda siguiendo las instrucciones aquí.
Usamos almacenamiento AWS S3 rastreado por DVC para la administración de archivos grandes. Instale AWS CLI siguiendo las instrucciones aquí. Después de la instalación, configure su instalación de AWS CLI con
aws configure Le pedirá:
AWS Access Key ID: SU-LLAVE
AWS Secret Access Key: SU CLAVE SECRETA
Default region name: por ejemplo, us-east-1
Default output format: json
Tenga en cuenta que el perfil que ingrese debe tener permiso para cargar en el depósito que configure más adelante.
Si no desea almacenar o versionar archivos grandes en AWS, puede omitir la instalación de la CLI de AWS.
Si la canalización de creación de perfiles se utiliza para agregar perfiles de celdas individuales, recomendamos ejecutar la canalización en un sistema con una memoria de al menos el doble del tamaño de los archivos .sqlite . Si la canalización se utilizará solo para ejecutar pasos posteriores a la agregación, entonces se puede ejecutar en una máquina local.
La canalización requiere una estructura de carpetas particular que se puede crear de la siguiente manera
PROJECT_NAME= " INSERT-PROJECT-NAME "
mkdir -p ~ /work/projects/ ${PROJECT_NAME} /workspace/{backend,software} Descargue el archivo .sqlite , que contiene los perfiles de celda única y el archivo .csv , que contiene los perfiles agregados de nivel de pozo, para todas las placas de cada lote a la carpeta backend . Estos dos archivos se crean ejecutando los comandos del capítulo 5.3 del manual de creación de perfiles. Después de descargar los archivos, la estructura de carpetas debería tener el siguiente aspecto
backend
├── batch1
│ ├── plate1
│ │ ├── plate1.csv
│ │ └── plate1.sqlite
│ └── plate2
│ ├── plate2.csv
│ └── plate2.sqlite
└── batch2
├── plate1
│ ├── plate1.csv
│ └── plate1.sqlite
└── plate2
├── plate2.csv
└── plate2.sqlite Nota: Es posible que la agregación aún no se haya realizado. En ese caso, sólo el archivo .sqlite estará disponible para descargar.
La soldadura es un proceso mediante el cual el repositorio de recetas de perfiles se agrega al repositorio de datos como un submódulo de manera que los archivos en el repositorio de datos y los scripts en la receta de perfiles que generaron esos archivos se versionan juntos. Aquí se proporcionan instrucciones para soldar. Recomendamos encarecidamente soldar la receta de perfilado al repositorio de datos. Después de soldar, clone el repositorio de datos en la carpeta software , usando el 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 --recursiveDespués de la clonación, la estructura de carpetas debería tener el siguiente aspecto
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.pyEs posible ejecutar la canalización sin soldar el repositorio de recetas de perfiles al repositorio de datos. Si se ejecuta de esta manera, el repositorio de recetas de perfiles debe clonarse en un directorio de datos como un subdirectorio. Entonces la estructura de carpetas tendrá el siguiente aspecto.
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
La generación de una tabla de estadísticas resumidas requiere archivos load_data_csv . Estos archivos deben descargarse en el directorio load_data_csv . Asegúrese de que los archivos estén comprimidos con gzip y que la estructura de carpetas tenga el siguiente aspecto.
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.gzLa canalización debe ejecutarse desde el repositorio de datos o el directorio de datos.
DATA= " INSERT-NAME-OF-DATA-REPO-OR-DIR "
cd ~ /work/projects/ ${PROJECT_NAME} /workspace/software/ ${DATA} /El archivo Environment.yml contiene la lista de paquetes Conda necesarios para ejecutar la canalización.
cp profiling-recipe/environment.yml .conda env create --force --file environment.ymlconda activate profiling Inicialice DVC para este proyecto y configúrelo para almacenar archivos grandes en S3. Omita este paso si no utiliza DVC. Si desea utilizar DVC para una ubicación de almacenamiento remota que no sea S3, encuentre las instrucciones aquí. Si tiene varios perfiles de AWS en su máquina y no desea usar el predeterminado para DVC, puede especificar qué perfil usar ejecutando dvc remote modify S3storage profile PROFILE_NAME en cualquier punto entre agregar el control remoto y realizar la inserción final de 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 " Los directorios que contendrán la salida de la canalización se crean de la siguiente manera
profiling-recipe/scripts/create_dirs.sh La canalización requiere barcode_platemap.csv y platemap.txt para ejecutarse. También se puede proporcionar un external_metadata.tsv opcional para realizar anotaciones adicionales. Las siguientes son las descripciones de cada uno de estos archivos.
barcode_platemap.csv : contiene el mapeo entre placas y mapas de placas. Hay un archivo de este tipo por lote de datos. El archivo contiene dos columnas cuyos nombres son Assay_Plate_Barcode y Plate_Map_Name , que no deben cambiarse. El nombre del archivo tampoco se debe cambiar. Este archivo debe ser un archivo .csv separado por comas.platemap.txt : contiene el mapeo entre los nombres de los pozos y los nombres de las perturbaciones. Hay un archivo de este tipo por mapa de placas y por lote. Son necesarias dos columnas, una con los nombres de los pozos ( A01 , A02 ...) llamada well_position y la otra con el identificador de perturbación. El nombre de la columna del identificador de perturbación puede ser definido por el usuario (si se cambia, cambie el nombre en el archivo config.yml ). El nombre de este archivo se puede cambiar. Si se cambia, cambie también el nombre dentro de barcode_platemap.csv . Este archivo debe ser un archivo .txt separado por tabulaciones.external_metadata.tsv : contiene la asignación entre el identificador de perturbación y otros metadatos. Este archivo es opcional. La columna del identificador de perturbación debe tener el mismo nombre que la columna en platemap.txt . Este archivo debe ser un archivo .tsv separado por tabulaciones. El siguiente es un ejemplo del archivo barcode_platemap.csv
Assay_Plate_Barcode,Plate_Map_Name
plate1,platemap
plate2,platemap
Aquí hay un archivo de mapa de placas de ejemplo y aquí hay un archivo de metadatos externos de ejemplo.
Estos archivos deben agregarse a la carpeta adecuada para que la estructura de carpetas se vea como se muestra a continuación
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} .ymlEl archivo de configuración contiene todos los parámetros que requieren varias funciones de pycytominer, llamadas por la canalización de creación de perfiles. Para ejecutar la canalización de creación de perfiles con diferentes parámetros, se pueden crear varios archivos de configuración. Cada parámetro en el archivo de configuración se describe a continuación. Se deben realizar todos los cambios necesarios en el archivo de configuración antes de poder ejecutar la canalización.
Si el primer paso de la canalización de creación de perfiles, aggregate , ya se ha realizado (en la carpeta backend , hay un archivo .csv además del archivo .sqlite ), entonces el archivo .csv debe copiarse al repositorio de datos o al directorio de datos. . De lo contrario, vaya a Ejecutar la canalización de creación de perfiles.
Ejecute los siguientes comandos para cada lote por separado. Estos comandos crean una carpeta para cada lote, comprimen los archivos .csv y luego los copian al repositorio de datos o al directorio de datos.
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} / Después de realizar los cambios necesarios en el archivo config.yml , ejecute la canalización de creación de perfiles de la siguiente manera
python profiling-recipe/profiles/profiling_pipeline.py --config config_files/ ${CONFIG_FILE} .ymlSi hay varios archivos de configuración, cada uno de ellos se puede ejecutar uno tras otro usando el comando anterior.
Nota: Cada paso del proceso de creación de perfiles utiliza el resultado del paso anterior como entrada. Por lo tanto, asegúrese de que se hayan generado todos los archivos de entrada necesarios antes de ejecutar los pasos en la canalización de creación de perfiles. Es posible ejecutar solo unos pocos pasos en el proceso manteniendo solo esos pasos en el archivo de configuración.
Si utiliza un repositorio de datos, envíe los perfiles recién creados a DVC y los archivos .dvc y otros archivos a GitHub de la siguiente manera
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 pushSi no usa DVC pero usa un repositorio de datos, envíe todos los archivos nuevos a GitHub de la siguiente manera
git add *
git commit -m ' add profiles '
git pushLa ejecución del flujo de trabajo de creación de perfiles con todos los pasos incluidos genera los siguientes archivos
| Nombre del archivo | Descripción | Ubicación |
|---|---|---|
<PLATE>.csv.gz | Perfiles agregados a nivel de pozo | perfiles/LOTE/PLACA |
<PLATE>_augmented.csv.gz | Perfiles anotados de metadatos | perfiles/LOTE/PLACA |
<PLATE>_normalized.csv.gz | Perfiles normalizados a toda la placa. | perfiles/LOTE/PLACA |
<PLATE>_normalized_negcon.csv.gz | Perfiles normalizados al control negativo. | perfiles/LOTE/PLACA |
<PLATE>_normalized_feature_select_<LEVEL>.csv.gz | Perfiles normalizados de placa completa que se seleccionan a nivel de plate , batch o all plates | perfiles/LOTE/PLACA |
<PLATE>_normalized_feature_select_negcon_<LEVEL>.csv.gz | Perfiles normalizados de control negativo que se seleccionan a nivel de plate , batch o all plates | perfiles/LOTE/PLACA |
<BATCH>_normalized_feature_select_<LEVEL>.csv.gz | Perfiles normalizados de placa completa apilados a nivel de lote que se seleccionan por características en el nivel batch o all plates | gct/LOTE |
<BATCH>_normalized_feature_select_<LEVEL>.gct | Archivo .gct creado a partir del archivo <BATCH>_normalized_feature_select_<LEVEL>.csv.gz | gct/LOTE |
<BATCH>_normalized_feature_select_negcon_<LEVEL>.csv.gz | Perfiles normalizados de control negativo apilados a nivel de lote que se seleccionan en el nivel batch o en all plates | gct/LOTE |
<BATCH>_normalized_feature_select_negcon_<LEVEL>.gct | Archivo .gct creado a partir del archivo <BATCH>_normalized_feature_select_negcon_<LEVEL>.csv.gz | gct/LOTE |
summary.tsv | Estadísticas resumidas | control_de_calidad/resumen |
<PLATE>_cell_count.png | Recuento de células en placa | control_de_calidad/mapa de calor/LOTE/PLACA |
<PLATE>_correlation.png | Correlación por pares entre todos los pocillos de una placa. | control_de_calidad/mapa de calor/LOTE/PLACA |
<PLATE>_position_effect.png | Porcentaje de coincidencia entre cada pocillo y otros pocillos en la misma fila y columna | control_de_calidad/mapa de calor/LOTE/PLACA |
Estos son los parámetros que requerirán todos los ductos
El nombre de la canalización ayuda a distinguir los diferentes archivos de configuración. No es utilizado por la propia tubería.
pipeline : <PIPELINE NAME> Nombre del directorio donde se almacenarán los perfiles. Son profiles por defecto.
output_dir : profiles Nombre de la columna de nombre del pozo en los perfiles aggregated . Es Metadata_well_position por defecto.
platemap_well_column : Metadata_well_position De forma predeterminada, las características de CellProfiler se extraen de tres compartimentos: cells , cytoplasm y nuclei . Estos compartimentos se enumeran en el archivo de configuración de la siguiente manera
compartments :
- cells
- cytoplasm
- nucleiSi hay otros compartimentos 'no canónicos' presentes en el conjunto de datos, se agregan a la lista anterior de la siguiente manera
compartments :
- cells
- cytoplasm
- nuclei
- newcompartment Nota: si el nombre del compartimento no canónico es newcompartment , entonces las funciones de ese compartimento deben comenzar con Newcompartment (solo el primer carácter debe estar en mayúscula). La canalización fallará si se utiliza el formato camel o cualquier otro formato para los nombres de las funciones.
options :
compression : gzip
float_format : " %.5g "
samples : allcompression : el formato de compresión para el perfil .csv s. El valor predeterminado es gzip , que actualmente es el único valor aceptado.float_format : el número de dígitos significativos.samples : si se deben realizar las siguientes operaciones en todas o en un subconjunto de muestras. El valor predeterminado es all lo que actualmente es el único valor aceptado. aggregate Estos son parámetros que son procesados por la función pipeline_aggregate() que interactúa con pycytominer.cyto_utils.cells.SingleCells() y agrega perfiles de celdas individuales para crear perfiles a nivel de pozo.
aggregate :
perform : true
plate_column : Metadata_Plate
well_column : Metadata_Well
method : median
fields : allperform : si se debe realizar la agregación. El valor predeterminado es true . Establezca en false si esto no se debe realizar.plate_column : nombre de la columna con el nombre de la placa. El valor predeterminado es Metadata_Plate .well_column : nombre de la columna con los nombres de los pozos. El valor predeterminado es Metadata_Well .method : cómo realizar la agregación. El valor predeterminado es median . También acepta mean .fields : ¿Celdas desde qué campo de visión se deben agregar? El valor predeterminado es all . Si se van a agregar campos de visión específicos (por ejemplo, 1, 4, 9), se puede hacer de la siguiente manera fields :
- 1
- 4
- 9 Además, para agregar funciones de imagen completas a los perfiles, enumere las categorías de funciones en el parámetro image_feature_categories . Por ejemplo
image_feature_catageories :
- Count
- Intensity annotate parámetros Estos son parámetros que son procesados por la función pipeline_annotate() que interactúa con pycytominer.annotate() y anota los perfiles de nivel de pozo con metadatos.
annotate :
perform : true
well_column : Metadata_Well
external :
perform : true
file : <metadata file name>
merge_column : <Column to merge on>perform : si se debe realizar la anotación. El valor predeterminado es true . Establezca en false si esto no se debe realizar.well_column : columna con los nombres de los pozos en los perfiles agregados.externalperform : si se deben anotar los perfiles con metadatos externos. El valor predeterminado es true . Establezca en false si esto no se debe realizar.file : archivo de metadatos externo que debe estar en la carpeta metadata/external_metadata/ .merge_column : nombre de la columna del identificador de perturbación que es común a platemap.txt y external_metadata.tsv . normalize parámetros Estos son parámetros que son procesados por la función pipeline_normalize() que interactúa con pycytominer.normalize() y normaliza todos los pocillos en toda la placa.
normalize :
perform : true
method : mad_robustize
features : infer
mad_robustize_fudge_factor : 0
image_features : trueperform : si se debe realizar la normalización. El valor predeterminado es true . Establezca en false si esto no se debe realizar.method : qué método utilizar para la normalización. El valor predeterminado es mad_robustize . Hay otras opciones disponibles en pycytominer, como standardize , robustize y spherize .features : nombres de las columnas de medición de características. El valor predeterminado es infer , que infiere las características de CellProfiler a partir de los perfiles anotados.mad_robustize_fudge_factor : el parámetro del factor de manipulación si el método de normalización es mad_robustize .image_features : si las características completas de la imagen están presentes en los perfiles anotados. El valor predeterminado es true . Se establece en false si las características de la imagen no están presentes.normalize_negcon Estos son parámetros que son procesados por la función pipeline_normalize() que interactúa con pycytominer.normalize() y normaliza todos los pocillos al control negativo.
normalize_negcon :
perform : true
method : mad_robustize
features : infer
mad_robustize_fudge_factor : 0
image_features : trueperform : si se debe realizar la normalización. El valor predeterminado es true . Establezca en false si esto no se debe realizar.method : qué método utilizar para la normalización. El valor predeterminado es mad_robustize . Hay otras opciones disponibles en pycytominer, como standardize , robustize y spherize .features : nombres de las columnas de medición de características. El valor predeterminado es infer , que infiere las características de CellProfiler a partir de los perfiles anotados.mad_robustize_fudge_factor : el parámetro del factor de manipulación si el método de normalización es mad_robustize .image_features : si las características completas de la imagen están presentes en los perfiles anotados. El valor predeterminado es true . Se establece en false si las características de la imagen no están presentes. feature_select Estos son parámetros que son procesados por la función pipeline_feature_select() que interactúa con pycytominer.feature_select() y selecciona características en los perfiles normalizados de toda la placa.
perform : true
features : infer
level : batch
gct : false
image_features : true
operations :
- variance_threshold
- correlation_threshold
- drop_na_columns
- blocklistperform : si se debe realizar la selección de funciones. El valor predeterminado es true . Establezca en false si esto no se debe realizar.features : nombres de las columnas de medición de características. El valor predeterminado es infer , que infiere las características de CellProfiler a partir de los perfiles normalizados.level : nivel en el que se debe realizar la selección de funciones. El valor predeterminado es batch . La selección de funciones también se puede realizar a nivel batch y all las placas.gct : si se debe crear un perfil apilado a nivel de lote y un archivo .gct . El valor predeterminado es false . Los perfiles apilados y los archivos .gct se crean solo cuando level es batch o all .image_features : si las características completas de la imagen están presentes en los perfiles normalizados de toda la placa. El valor predeterminado es true . Se establece en false si las características de la imagen no están presentes.operations : lista de operaciones de selección de funciones. variance_threshold elimina las características que tienen una variación por debajo del umbral, en todos los pocillos de una placa. correlation_threshold elimina funciones redundantes. drop_na_columns elimina entidades con valores NaN . blocklist elimina las funciones que forman parte de la lista de bloqueo de funciones.feature_select_negcon Estos son parámetros que son procesados por la función pipeline_feature_select() que interactúa con pycytominer.feature_select() y selecciona características en los perfiles normalizados al control negativo.
feature_select_negcon :
perform : true
features : infer
level : batch
gct : false
image_features : true
operations :
- variance_threshold
- correlation_threshold
- drop_na_columns
- blocklistperform : si se debe realizar la selección de funciones. El valor predeterminado es true . Establezca en false si esto no se debe realizar.features : nombres de las columnas de medición de características. El valor predeterminado es infer , que infiere las características de CellProfiler a partir de los perfiles normalizados.level : nivel en el que se debe realizar la selección de funciones. El valor predeterminado es batch . La selección de funciones también se puede realizar a nivel batch y all las placas.gct : si se debe crear un perfil apilado a nivel de lote y un archivo .gct . El valor predeterminado es false . Los perfiles apilados y los archivos .gct se crean solo cuando level es batch o all .image_features : si las características completas de la imagen están presentes en los perfiles normalizados de negcon. El valor predeterminado es true . Se establece en false si las características de la imagen no están presentes.operations : lista de operaciones de selección de funciones. variance_threshold elimina las características que tienen una variación por debajo del umbral, en todos los pocillos de una placa. correlation_threshold elimina funciones redundantes. drop_na_columns elimina entidades con valores NaN . blocklist elimina las funciones que forman parte de la lista de bloqueo de funciones. quality_control Estos parámetros especifican el tipo de métricas y cifras de control de calidad a generar. summary genera una tabla con estadísticas resumidas, mientras que heatmap genera tres mapas de calor, cada uno de los cuales muestra una métrica de control de calidad diferente.
quality_control :
perform : true
summary :
perform : true
row : Metadata_Row
column : Metadata_Col
heatmap :
perform : trueperform : si se deben generar cifras o métricas de control de calidad. El valor predeterminado es true . Establezca en false si no deben generarse. Hay dos tipos diferentes de métricas de control de calidad que se pueden generar. summary crea summary.tsv con estadísticas resumidas de cada placa de cada lote. heatmap genera tres mapas de calor: recuento de células frente a mapa de placas, correlación entre los pocillos y efecto de posición frente a mapa de placas.
summary :
perform : true
row : Metadata_Row
column : Metadata_Colperform : si se genera o no el archivo de resumen. El valor predeterminado es true . Establezca en false si este archivo no debe generarse.row : campo de nombre de fila en load_data.csv .column : campo de nombre de columna load_data.csv . heatmap :
perform : trueperform : si se generarán o no mapas de calor. El valor predeterminado es true . Establezca en false si no se deben generar mapas de calor. batch y platesEstos parámetros especifican el nombre del lote y la placa a procesar.
batch : <BATCH NAME>
plates :
- name : <PLATE NAME>
process : true
process : truebatch : nombre del lote a procesar.plates -name - Nombre de la placa a procesar.process : si se debe procesar la placa. El valor predeterminado es true . Configúrelo en false si esta placa no debe procesarse.process : si se debe procesar el lote. El valor predeterminado es true . Establezca en false si este lote no debe procesarse.git submodule update --init --recursive
dvc pull Información adicional sobre el uso de DVC que puede resultarle útil:
Cuando maneje archivos grandes o una carpeta grande, NO los agregue a GH con git add . En su lugar, agréguelos a DVC con dvc add . Esto carga el archivo/carpeta grande en S3 y crea un puntero a esa carga en S3 en el repositorio de GH (que rastreamos en lugar del archivo/carpeta en sí). También actualiza .gitignore para que GH no rastree el archivo/carpeta grande. Luego dvc push para cargar los archivos a S3.
# Add a file or folder to DVC
dvc add LARGEFILE.csv
dvc pushLuego agregue la versión .dvc del archivo/carpeta que se crea en github junto con .gitignore. Comprometerse.
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 convierte los nombres de los archivos en hashes en S3. Para ver el hash del archivo (para que pueda encontrarlo directamente en S3) para cualquier archivo DVC determinado, agregue el indicador --show-url al comando get :
dvc get --show-url https://github.com/ORGANIZATION/DATA-REPO.git relative/path/to/LARGEFILE.csv
