Welcome to NPC Image Analysis’s documentation!¶
NPC Image Analysis is a Python app for analyzing 3D images of Neural Progenitor Cells (NPCs). In particular, it was made to answer the specific question of analyzing the radial process of the cells. This application aims to allow you to use a default implementation to get you started, but also allows the user to customize the analysis process.
Note
This project is still under active development.
Why NPC Image Analysis?¶
Originally, this project was aimed to answer a specific question by looking at NPCs in developing zebrafish brains. The purpose of this, what to hopefully eliminate some of the biase that can come with trying to perform image analysis. As the sole developer of this project, I grew attached to continuously iterating on this project. While working on it and trying to explain this image analysis project to my PI, I found that the growing Python scripts might be overwhelming for a non-programmer. Thus, this project has been born to hopefully bridge the gap between trying to analyze the images in a specific context.
This may have other purposes beyond this specific context, so I decided to share it here.
Check out the Usage section for further information.
You can find the source code here
Navigation¶
Usage¶
Requirements¶
Python 3.6 or above
Installation¶
pip install npc-analyze-image
However, the sourcecode of this program can be found at this github page.
Once installed you can run the following in the command line to initate the program.
python -m NPCAnalysis
General Usage¶
This software is intended to be modifiable in order to answer particular needs to identify organelles and structures. Using this software, you will be able to look within the radial process of a specific cell of interest. This is used in conjuction with ImageJ’s Simple Neurite Tracer.
- To use this software, you will need…
A greyscale tiff image that contains the channel for the organelles or structures of interest you would like analyzed
The skeleton file created from the simple neurite tracer as a .tiff file. You cannot use the .trace file for this as it cannot be read in.
After you load in your images using the “Load Images” button, you can selected “Perform Analysis”. You will be provided with two options, “Default Analysis” and “Custom Analysis”. If you would like to just see what a default analysis would look like, selected Default Analysis.
This will ask for the “z” spacing of your images. This only effects the presentation of your images not the analysis. From there, depending on the size of the image, it can take a while for the analysis to complete. If it looks temporarily frozen, that’s possibly why. You can find more information about the Default Analysis option and what operations are performed, selected the Default Analysis under the help window.
You can see examples of this file being used in Example Usage
While this program is tailored to a specific use case. The default analysis presumes that you are loading using a skeleton mask (or a skeleton/mask file in general) along with an image to be analyzed. As a result, the program will require you to load two images and certain operations will presume that both files are loaded. However, you can use most of the operations the skeleton file.
Why use a skeleton mask?¶
Originally this was used to isolate the file to a specific location for the analysis, however, this also reduced the overall file size and image size lowering the memory usage and time required to process images.
Default Analysis¶
The default analysis was created based off an analysis process that worked generally will on all of the images that this project was originally created for.
As such, this process is automatic when you click the button to start the analysis preventing any intervention.
This can be used as a general guide for what analysis processes might work. Image analysis is a process that doesn’t work for all images so it can require tweaking to better suit images loaded into the application.
Note
The default analysis presumes that you are using the skeleton file and the image to be analyzed.
Image Processing Steps¶
Skeleton Dilation (Default dilation is 10)
Cropping of the image to the length/size/volume of the skeleton
Median filter with a cube width of 3
Background subtraction using a gaussion blur of strength 7.
Adaptive Histogram Equalization: This consists of using scikit image’s adaptive histogram equalization option. It is then multipled to the background subtracted image to give the final contrast.
Multiotsu mask at 2 classes (there are presumed only 2 classes, background and regions of interest)
Default morphology: Dilation morphology and then closing morphology
Labels are added to the image.
This information can also be found in the “Help” section of the application.
Custom Analysis Options¶
Custom analysis allows you to customize the image processing steps. This is created to allow the user the opportunity to tailor the processing to the best of their ability without having to worry about the code behind it.
For information on what an operation might do, the scikit image page (which these processing steps draw on) will be linked to allow the user to read more on its purpose.
Below is a general list of the steps.
Main Processing Options¶
- Skeleton Dilation
Utilizes the Morphology Binary Dilation Operation
- Median Filter
Uses the Median Filter from skimage
- Background Subtraction
Utilizes SciKit Image Gaussian Filter
- Sobel Filter
Uses the Sobel Filter
- Adaptive Histogram Equalization
This consists of using scikit image’s adaptive histogram equalization option. It is then multipled to the background subtracted image to give the final contrast.
Uses the Adaptive Histogram Equalization from skimage
- Rescale Intensity operation
Uses the Rescale Intensity from skimage
Mask Options¶
Morphology Options¶
- Default Morphology
Includes binary dilation and the closing. Used in the default analysis process
- Get Labels
Obtain the labels after the morphology to get your ROIs
Undo/Redo¶
Note
Previous image can only go back once.
Use Previous Image (will use the previously created image prior to the most recent action)
Use Most Recent Image (this will return you to the current image if you clicked previous image)
Use Original Image (reset to the originally loaded in image)
Use Previous Mask (will use the previously created mask prior to the most recent action)
Use Most Recent Image (this will return you to the current mask if you clicked previous mask)
This information can also be found in the “Help” section of the application.
Region Properties¶
area¶
The property calculates the area of the region of interest. For 3D options this really means volume as it is taking into account the x, y, and z planes.
bbox¶
Calculates the boundary box points locations for each plane. This returns six columns as it accounts for the highest and lowest x, y, and z planes coordinates.
bbox_area¶
Calculates the bounding box area based on the bounding box coordinate points. As this is 3D this is closer to volume than area.
max_intensity¶
Calculates the maximum intensity for each of the ROIs identified. This takes into account the passed in intensity_image. For this program, it uses the original image so that the intensity values are not impacted by the processing steps.
mean_intensity¶
Calculates the mean intensity for each of the the ROIs identified. This takes into account the passed in intensity_image. For this program, it uses the original image so that the intensity values are not impacted by the processing steps.
min_intensity¶
Calculates the min intensity for each of the the ROIs identified. This takes into account the passed in intensity_image. For this program, it uses the original image so that the intensity values are not impacted by the processing steps.
equivalent_diameter¶
Calculates the diameter of a circle with the same area as the region.
minor_axis_length¶
The length of the minor axis of the ellipse that has the same normalized second central moments as the region; that is, the same normalized variance as the region which is a measure used to quantify whether the set obsevered occurences are clustered or dispersed.
major_axis_length¶
The length of the major axis of the ellipse that has the same normalized second central moments as the region; that is, the same normalized variance as the region which is a measure used to quantify whether the set obsevered occurences are clustered or dispersed.
centroid¶
This returns the coordinates of the central point within the specific region of interest. Creates three columns with x, y, and z coordinates.
coords¶
Returns the coordinate list (plane, row, col) of the region
Example Usage¶
Using NPC Image Analysis¶
Above is what the application will look like upon initialization. The application’s simple interface was designed to not overwhelm the user with too much information and options at one time.
We’ll start with loading in the images. When the loading button is clicked, the status screen will inform you of the order of the images.
Warning
You must import the images in a specific order:
Skeleton file first (this must be a .tiff or .tif file)
Your image for analysis
They must be the same size, or else the application will not be able to process the images.
After the images are loaded, the “Status” screen of the application will list the images loaded and will ask the user to confirm that these are correct.
Choosing an analysis option¶
Clicking “Perform Analysis” will open another small window. There are two options to choose for analysis: The “Default Analysis” option and the “Custom Analysis” option.
Default Analysis¶
When you select “Default Analysis” this will ask you to input the image spacing. This is asking for the “z” spacing of your images.
Note
The spacing indicates the distance between each “z” plane image to create the depth of the image.
For this example, we are using .5:
Pressing “Okay” will initiate the analysis. A napari viewer will open. While this process is occuring, the screen may remain white and the app may be unresponsive as it operates. Don’t panic, this is a sign that it is working.
If it remains white and the app is unresponsive for an extended period of time, you should consider the size of your images as this will contribute to the amount of time processing will take.
When the process is complete, you will be able to interact with the napari viewer and see what the final results are.
Note
If you are unhappy with this final result, you can begin a new process with the Custom Analysis option. This will start a new napari viewer and cannot continue with the default analysis as you will be restarting from the beginning.
You can follow through the default analysis process and tweak it by visiting the Default Analysis page.
Custom Analysis¶
Selecting “Custom Analysis” will expand the current window with the image processing options. Additionally, it will ask the same question as in the default analysis “What is the image spacing?” Again, you will provide the “z” spacing of your images.
Note
The spacing indicates the distance between each “z” plane image to create the depth of the image.
Here we will be using .5:
Upon entering your spacing, a napari viewer window will open. It will be empty and allow you the option to begin your image processing.
We will start with a skeleton dilation. Clicking “Skeleton Dilation” will prompt you to input how much you would like to dilate the skeleton image.
The default is 10. For this example, we will also use 10.
Warning
This operation can take some time, so if it appears that application is frozen, keep in mind the size of the images as this is a contributing factor to the processing power and time consumption of each operation.
This process will return the dilated skeleton as well as the cropped image called ‘ROI’. The “status” window will also update with the process that was just performed and what value was performed to allow the user to keep track of what operations they have performed so far.
Next, we will apply a median filter. Upon clicking “Median Filter” the application will prompt you to input the cube width to use. The default is 3 which we will use for this example.
This will return the image after the median filter has been applied.
We will apply a background subtraction after this to even out the surrounding background and make it easier for the final step of identify our regions of interest easier. Clicking this will prompt the user to input a gaussian sigma or how strong the blur will be.
The default is 7. In this case, we’ll use 10:
While we could apply the sobel filter which will define the edges of the objects within this image, it’s not really necessary here. We want to make the images within the radial process is clear so defining the edges of this particular image may not work in our favor.
We’ll enhance the contrast of the image now. One of the byproducts of a background subtraction is that it can also lower the contrast of the overall image as we try to smooth out the background. We’ll try the “Rescale Intensity” option first.
Clicking this button will prompt you to enter two values, the minimum intensity value of the image and the maximum intensity values in the image. They are percentages in this case, but the defaults for rescaled intensity is .5 and 99.5 for minimum and maximum respectively.
Note
Choosing the minimum and maximum intensity values means that you will be deciding what the minimum intensity values allowed within the total image allowed and the maximum intensity values allowed in the overall image. If you choose .5 and 99.5, you will be clipping the darkest and brightest 0.5% of pixels within the image thus increasing the overall contrast of the image.
We will use 99.65 and 99.98 for the minimum and maximum values respectively.
This returns the above. While it is not terrible, it’s not exactly what we’re looking for right now and adjusting the contrast this way will require a little more playing around.
We’ll click the previous image button to go back one step. This will add the previous image we were working with to the viewer once more and the status will update with our selection.
Note
You can only go back one step at the moment.
We should return to the background subtracted image now. We’ll go ahead and use the “Adaptive Histogram Equalizaiton” option which will operate automatically. The purpose of this option is to provide an automatic contrast that doesn’t require any input from the user. The Rescale Intensity option allows more freedom for the user and can be applied after the adaptive histogram equalization operation is performed to continue to tweak the contrast.
We now have our final contrasted image. From here, it’s time to select a mask option. In the default analysis, the multiotsu mask is used. If you don’t like the mask that is used you can use the “Use Most Recent Image” option to return to the image prior to using the mask and play around with the options you would like to use.
We’ll use the multiotsu mask with 2 classes.
Great! This is looking pretty good, but we can probably define this mask a little bit. The default morphology option allows the user to use the morphological steps that are used in the Default Analysis. The default analysis uses the Dilation and Closing morphological adjustments in that order.
We can see what each of those look like here by using them in that order instead of pressing Default Morphology.
This final mask looks pretty good. Once you’re pleased with the final mask, you can generate labels by pressing the “Get Labels” options. Labels will be generated and added to the viewer.
From here, we can start getting data from our analysis.
Getting ROI Properties¶
From here you can begin the process of obtaining properties of the identified regions of interest (ROI) by clicking the “Get ROI Properties” button.
Clicking this button will open up a new window allowing you to select the data you would like to obtain. For this example, we’ll select “area”, “mean_intensity”, and “centroids”.
After that, click the “Start ROI Properties Analysis” button.
After this process is completed, you will be presented with a table containing data for each region of interest and the properties you selected.
Clicking the “Export ROI Properties” button will open the save dialog and allow you to save your data. If you would like to get additional properties, you can return to the window with your property options and generate a new table.
Example Data Returned¶
Note
This does not include all of the data that can be returned. Additionally, all data returned regarding points or coordinates (this includes bbox, centroids, coords) are returned in z, x, y order (plane, row, column)
label |
area |
mean_intensity |
centroid-0 |
centroid-1 |
centroid-2 |
|---|---|---|---|---|---|
1 |
1467 |
8187.162236 |
12.07089298 |
27.30811179 |
278.9284254 |
2 |
41 |
6525.073171 |
7.512195122 |
7.43902439 |
332.5853659 |
3 |
147 |
6552.14966 |
9.789115646 |
12.14965986 |
308.6326531 |
4 |
2 |
8102.5 |
8 |
12.5 |
291.5 |
5 |
83 |
7006.204819 |
34.97590361 |
114.0120482 |
183.4939759 |
6 |
232 |
7184.99569 |
42.68103448 |
158.2931034 |
141.8965517 |
7 |
168 |
6671.392857 |
53.32738095 |
232.6785714 |
86.57142857 |
8 |
1873 |
8293.038441 |
58.56326749 |
265.2530699 |
48.32407902 |
9 |
113 |
6718.911504 |
63.91150442 |
294.8495575 |
23.45132743 |
10 |
26 |
6214.153846 |
65.5 |
301.6923077 |
15.69230769 |
11 |
12 |
6545.666667 |
66.5 |
305 |
12 |
The data above is generated using sci-kit image’s regionprops table module. If you would like to read more about it and the function you can find it here.