Home

ScaleFEx℠: Feature Extraction for High-Content Imaging

ScaleFEx℠ (Scalable Feature Extraction ) is an open-source Python pipeline designed to extract biologically meaningful features from large high-content imaging (HCI) datasets.

Read more about it in the preprint: https://doi.org/10.1101/2023.07.06.547985

Key Features

• Robust Feature Extraction: Utilizes advanced algorithms to distill complex image data into critical features that drive insights into cellular phenotypes.
• High-Content Imaging Focus: Tailored for large-scale HCI screens, addressing challenges of scale, variability, and high-dimensionality in biomedical imaging.
• Low overhead: leveraging parallelizations over cores, it maximizes any computer resources
• AWS implementation: to scale up even more. Easy to deploy. Cheaper and faster than the state of the art

Installation Instructions

For a full description on how to run ScaleFEx on AWS, see the Wiki page here

Follow these steps to set up and run ScaleFEx:

1. Create and Activate a New Environment

Ensure you have Conda installed, then create a new environment:

conda create --name ScaleFEx python=3.12
conda activate ScaleFEx

2. Clone the Repository

Clone the repository and navigate into the main folder:

git clone https://github.com/NYSCF/ScaleFEx.git
cd ScaleFEx

3. Install the Package

Install the repository package:

pip install .

These steps will set up the environment with all necessary dependencies isolated to ensure everything works smoothly.

4. Parameters setup

Navigate to the folder where the repository was cloned and open the parameters.yaml file to edit it. Once the code is run, a copy of the used parameters will be saved for your records. NOTE: if you leave the parameters as they are, the code will compute ScaleFEx on the sample dataset provided

• vector_type: Write 'scalefex' for the feature vector, '' if you want only the preprocessing part (specified below)
• resource: 'local' for local computation, 'AWS' for cloud computing
• n_of_workers: 60 ;int, n of workers to use in parallel. If computing on AWS, this parameter will be ignored, as it is fixed in the AWS framework
• exp_folder: '/path/to/images/' ;
• experiment_name: 'exp001' ;this name will be appended to the saved files
• saving_folder: '/path/to/saving/folder/' ;path to the saving folder
• plates: ['1','2'] ;if you want to process a subset of plates, 'all' for all of the ones found in the folder
• max_file_size: 2000 ; max file size in MB before new file is created
• overwrite: True ; if True, overwrite existing files for the specified experiment; else, append results to existing files
• plate_identifiers: ['Plate','_'] ;identifier for finding the plate number; should directly precede and follow the plate identifier (eg for the default values the plate name extracted would be 1: exp_folder/Plate1/.tiffs) NOTE: The plate identifiers do not need to contain all the strings within the folder, but just the strings that are constant and can identify the plate. The identifiers are used to identify the plate even when the folder patterns are not the same. Eg sometimes folders include time stamps and it would be hard to query the plate without imputing all of the folders. (example: exp_folder/some_strings < identifier1 > Plate < identifier2 > some_other_string/.tiffs)
• pattern: 'Images/fp<Plane(2)>-<Channel(3)>.' # pattern of the image file: specify all the characters that make up the filepath indicating the location (more details in the Querying Data section) fi * le_extensions*: ['tiff',] ; specify the extensions of the image files
• image_size: [2160,2160] ;size of the image
• channel: ['ch4','ch1', 'ch5', 'ch3', 'ch2'] ;channels to be processed. NOTE: the nuclear channel should be first
• zstack: False ;Set to True if you have multi-plane images
• ROI: 150 ;Radius of the crop to be cut around the cell
• QC: True ;True if the user wants to compute a tile-level Quality Control step
• FFC: True ;True to compute the Flat Field Correction
• FFC_n_images: 500 ; n of images to be used to produce the background trend image for the Flat Field Correction
• downsampling: 1 ;Downsampling ratio
• csv_coordinates: '' ; '' if you don't want to use a pre-computed coordinates file, otherwise, path to the coordinate file. The columns and format of the csv file needs to be as follows, which is the output of the pipeline: If another code is used to extract the coordinates and the information about the distance is missing, make an empty column called distance
• segmenting_function: 'Nuclei_segmentation.nuclei_location_extraction' for threholding method
• save_coordinates: True ; save a csv file with the coordinates for each plate
• min_cell_size: 200 ;min area of the cell, all the object with smaller area will be removed
• max_cell_size: 100000 ;max area of the cell, all the object with bigger area will be removed
• visualization: False ; if true, the segmentation masks of the entire field will be visualizaed (using matplotlib). NOTE: we suggest to visualize the masks for testing, but to turn it off during the processing of large screens
• RNA_channel: 'ch5' ;RNA channel (if any) #set only if you want to compute ScaleFex
• Mito_channel: 'ch2' ;Mitochpndria channel (if any) #set only if you want to compute ScaleFex
• visualize_masks: False ; visualize the segmentation mask from each channel. NOTE: we suggest to visualize the masks for testing, but to turn it off during the processing of large screens
• visualize_crops: False ; visualizes the crop of the cell. This helps setting the best ROI size, but we suggest to visualize the crop for testing, but to turn it off during the processing of large screens

AWS parameters (Can be left untouched if the code is run locally)

For a full description on how to run ScaleFEx on AWS, see the Wiki page [here] (https://github.com/NYSCF/ScaleFEx/wiki/Running-ScaleFEx-on-AWS)

• s3_bucket: 'your-bucket'; name of the S3 Bucket storing your images
• nb_subsets: 6; how many machines per plate you want to deploy. A good number would be n_of_wells_per_plate/n_of_workers. We defaulted the n_of_workers=40, so in this case 6 comes from our standard n of wells 240/40=6
• subset_index: 'all'; can use an int to compute a specific subset to compute (i.e:'2')
• region: 'us-east-1'; what region you want to deploy machines into
• instance_type: 'c5.12xlarge' ; Machine type/size
• amazon_image_id: 'ami-xxxxxxxxxxxx' ; AMI linked to region
• ScaleFExSubnetA: 'subnet-xxxxxxxxxxxxxx'; ARN of the subnet you want to use for machines deployment, empty string if you want to use the default one
• ScaleFExSubnetB: 'subnet-xxxxxxxxxxxxxxx'; second subnet you want to use, if only one use the same
• ScaleFExSubnetC: 'subnet-xxxxxxxxxxxxxxxxxx' ; third subnet you want to use, if only one use the same
• security_group_id: 'sg-xxxxxxxxxxxxxxxxxxxxx' ; security group you want to use, empty string if you want to use the default one

For the number of subsets here are some guidances. If you have a large dataset, you can use several virtual machines to scale with the dataset size, each will compute a subset of your plate. Each machine is set to compute 40 wells in parallel, if you have 240 wells in your plate for instance : 240/40 = 6 subsets would be the most optimal.

If you wish to change machines types and number of workers, please refer to the 'Running-ScaleFEx-on-AWS' section.

5. Execute Analysis:

If running the code locally:
From the terminal: After setting the parameters of the yaml file, navigate to the folder of your code and execute

python vector_extraction_class.py -p your_parameters_file.yaml

if no parameters file is passed using the -p flag, parameters.yaml will be used by default

6. File Output:

There are three main results output by the pipeline:

1. ScaleFEx feature vectors: these are saved to a series of CSV files each of max_file_size MB (or less if its last file)

2. Quality control metrics: these are saved to a single file, with metrics for each channel of each site image (see details here)

3. Site analysis tracking: this file has a list of site images that have been analyzed thus far, along with:

   1. total cells found
   2. cells analyzed (and their ids)
   3. cells on the image edges (and their ids; these are not analyzed because valid crops can be created)
   4. cells where computation failed (this can happen if the channel is blank; a consistently high count for this column can indicate issues with your parameters/dataset)

   This file is used to resume computation if the pipeline is interrupted (i.e., if a site is found in this file, it is assumed that it's already been analyzed; see the overwrite parameter)

7 Example

A example notebook for running our pipeline on a single field is included here. To run it, make sure to have installed the correct library (on terminal input pip install notebook)

An example of a possible analysis that can be performed on the ScaleFEx features is outlined in demos/demo_scalefex_analysis.ipynb`

License

ScaleFEx℠ is released under the Clear BSD License. See LICENSE.md for more details.