Table of Contents
This project uses machine learning to distinguish between "marked" and "unmarked" brain cells. It uses an ensemble of boosted trees, generated using XGBoost. The ensemble is used to distinguish between cells for which there is a confident prediction of being "marked", those that are confidently "unmarked" (or negative) and those on which the classification is "unsure".
- Extracting cells from brain images
- Evaluating cells to be negative, sure positive and unsure positive
- Manually verifying detection accuracy using a rudimentary annotation tool.
- Estimating cell density in brain regions YF: ???
Developed with Python 3.10.
To get a local copy up and running, follow these simple example steps.
- Please ensure you have any tool to create virtual environments. Our environment setting uses
virtualenv.
- Installing virtualenv
- On Linux
sudo apt install virtualen
- On Mac-OS:
pip(3) install pipx pipx install virtualenv
- ImageMagick` is required to convert images. The installment guide is here.
-
Clone the repo to your own computer.
git clone https://github.com/ActiveBrainAtlas2/cell_extractor.git
-
Activate the essential environment variables.
source variables_env.sh -
Set up the virtual environment.
a. Edit the path for virtual environment in configure_env.sh
# Directory to create virtual environment export venv=~/Github/venv/ # CHANGE TO YOUR DIRECTORY
Note: The working directory should be out of the project directory to avoid uploading them to Github.
b. When the configuration file is set, run the following command to activate the virtual environment. Essential packages listed in
requirements.txtwould be installed meanwhile.source configure_env.shYou can also set up the virtual environment by your familiar way. Install the essential packages by running the following command:
pip install -r $PROJECT_DIR/requirements.txt
Running a marked cell detector involves the following stages:
- full aligned brain images> 2. tiff image tiles> 3. cell examples> 4. cell features> 5.detection result
Activate the essential environment variables and virtual environment.
source variables_env.sh
source configure_env.shNote: Run the following command to check if libraries are installed correctly.
pip install -r $PROJECT_DIR/requirements.txt The full resolution, within stack aligned images are used for the cell detection. Fluorescence images and nissel stain images are processed together in our project.
There are some example images in data_for_test.
The full resolution images are too big to work with, therefore we break them down to smaller chunks for processing with the script generate_tif_tiles.py.
python $SCRIPT_DIR/generate_tif_tiles.py --animal XXX --fluorescence_image $PROJECT_DIR/data_for_test/fluorescence_image --nissel_stain_image $PROJECT_DIR/data_for_test/nissel_stain_image --disk output_directoryoptional arguments:
-h, --help show this help message and exit
--animal ANIMAL Animal ID
--fluorescence_image FLUORESCENCE_IMAGE
Where fluorescence images are stored
--nissel_stain_image NISSEL_STAIN_IMAGE
Where nissel stained images are stored
--disk DISK Storage Disk
--njobs NJOBS Number of parallel jobs
The cell examples are patches of images from both fluorescent channel and nissel stain channel. Each cell example represent a candidate for cell detection. The candidates are found by the following steps:
-
Blurring the image
-
Generate an image mask based an intensity threshold, all pixels with intensity > threshold will be labeled as 1 and the rest 0.
-
Finding the connected segments of the images mask with CV2
-
All connected segments with area <100000 are considered as cell candidates
-
Candidates on the edges of the tiles are excluded
Generate examples by running the following:
python $SCRIPT_DIR/parallel_create_examples.py --animal XXX --disk output_directory --njobs 7optional arguments:
-h, --help show this help message and exit
--animal ANIMAL Animal ID
--disk DISK storage disk
--njobs NJOBS Number of parallel jobs
A set of image features are calculated from each cell candidate. The features are used as the input to the machine learning algorithm.
python $SCRIPT_DIR/parallel_create_features.py --animal XXX --disk output_directory --njobs 7optional arguments:
-h, --help show this help message and exit
--animal ANIMAL Animal ID
--disk DISK storage disk
--njobs NJOBS Number of parallel jobs
In this step, 30 previously trained models are used to calculate a prediction score for features calculated in step 4. The mean and standard deviation of the 30 detectors are then used to make a decision if a candidate is a sure or unsure detection.
python $SCRIPT_DIR/detect_cell_for_one_brain.py --animal XXX --disk output_directory --round 1 --model $PROJECT_DIR/data_for_test/model/models_example.pkloptional arguments:
-h, --help show this help message and exit
--animal ANIMAL Animal ID
--disk DISK storage disk
--round ROUND model version
--model model file path
We are trying to improve the models with new marked cells round by round. The argument 'ROUND' refers to the model version of each round.
You can get the detection result by using the function load_detections in the class CellDetectorBase.
This will return a dataframe with the coordinate of the cells and the predictions. There are different places in the code refer to the coordinates in different ways. Remember that columns always comes before row, and x before y.
The detection result is stored in the predictions column in the dataFrame. the result is -2 if it is not a cell, 0 if it is unsure and 2 if it is sure.
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License.