-
Notifications
You must be signed in to change notification settings - Fork 0
Find MotiQ 3D Analyzer Settings
This guide was written on January 31, 2023 - it applies for MotiQ 3D Analyzer version v0.2.0 (contained in this MotiQ release).
This guide shows you how to systematically find good MotiQ 3D Analyzer settings for your data set. To conduct this guide, it is recommended to have successfully passed the guide on finding good MotiQ Thresholder settings and have run a few of your images through MotiQ Thresholder with the settings that you found optimal for your images. The output files from MotiQ Thresholder will then be used here to test different MotiQ 3D Analyzer settings.
We sectioned this guide by the different headings you find in the MotiQ 3D Analyzer settings dialog: Calibration, Particle Filtering, Calculation, and Output.
- Launch FIJI or ImageJ
- Open an output image from MotiQ Thresholder (file ending "_pBIN.tif" or "_BIN.tif") by drag and drop into the status bar of FIJI / ImageJ.
- Display the calibration settings of the image via the menu entry Image > Properties in FIJI/ImageJ.
-
Do the values indicated here match the calibration information that your microscope indicates you during acquisition? Verify in particular that
Pixel width
,Pixel height
,Voxel depth
(the distance between different slices in a 3D image), andUnit of length
(the calibration unit in which pixel width/height and voxel depth are given) in this dialog are correct. Side note: "µm" and "micron" can be used here interchangeably and indicate the same unit. If you are analyzing a time-lapse image make sure that theFrame Interval
field contains the correct frame interval time and unit. E.g., for a frame interval of 90 seconds, theFrame interval
field should specify either "90 sec" or "1.5 min". Also float values are allowed here, such as "0.02 sec" for a frame interval of 20 ms. The fieldsChannels
,Slices
,Frames
,Origin
do not matter for calibration information and can be ignored at this step. -
If you can answer step 4 with Yes (all values verified are correct), note down that in MotiQ 3D Analyzer settings you will later need to unclick the checkbox "Re-calibrate" and you can leave all other field under "Calibration" to default values since they are obsolete when you un-selected "Re-calibrate image".
- If you answered step 5 with No (some or all values stored as calibration data in the image properties are wrong), note down that in MotiQ 3D Analyzer settings you will later need to make sure that the "Re-calibrate image" checkbox is activated and fill out all fields under the "Calibration" heading with the correct values for your image. The parameter "length calibration" in MotiQ 3D Analyzer refers to the "pixel width" or "pixel height" displayed in the image-properties dialog.
- Launch FIJI or ImageJ (if not yet open)
- Open an output image from MotiQ Thresholder (file ending "_pBIN.tif" or "_BIN.tif") by drag and drop into the status bar of FIJI / ImageJ (if not yet open).
- Launch the Auto Threshold dialog via the menu entry Image > Adjust > Auto Threshold.
- Drag both sliders to the very left so that next to the sliders "0"s are displayed. Now you can very well see what the "semi-binarized" image shows as foreground (original intensity values) and background (red).
- If you plan to automatically detect cells in the image (without using MotiQ Cropper), go on at step 11. Otherwise go on reading here.
- No investigate the image by passing through the z planes. Look for particles that do not belong to a cell (low intensity level, not conencted to a cell / remote from the cell, examples indicated with blue arrows below).
- Count how many pixels / voxels these small particles feature (also consider that they stretch across multiple planes eventually) and note down the values.
This montage of images shows multiple different slices ("z" 14-19) for a small region of the image to visualize how to calculate particles that stretch across planes. I
- Estimate how many pixels/voxels the smallest particles belonging to a cell that you cropped out have. Try to find a branch that is small or not connected to the cell soma and count how many pixels / voxels it contains. Note down the value and estimate also the pixel / voxel numbers of other branches.
Here we found a very small piece of a branch, it may be connected in other planes, but in this case it is enough to just count one plane since a lower value here than real will be no issue (will be explained in the next step in more detail).
- Now compare the values for the particles measured in step 7 (these are the particles you do not aim to include into your analysis) to the values measured in step 8 (these are the particles you aim to include since they belong to the cell). Then find a value that clearly distinguishes the two types of particles and note it down to be used in the MotiQ setting here: . Also note down to disable the following checkbox in MotiQ (for when and how to use this box see Note 1 below):
As a calculation example for the screenshots provided above: The particles to be included were maximally 19 px large and the particles to be included were at least 46 px large. Thus, we select a threshold of 40 px since that seems to clearly remove too small particles while keeping small branch pieces.
-
Now that we have gauged the particle analyzer settings to start with, we will verify how well they perform in MotiQ 3D Analyzer.
-
Launch FIJI (if already open, close it and relaunch it again).
-
Open one, or ideally, multiple example output images from MotiQ thresholder in your data set, by drag and drop into the FIJI / ImageJ status bar.
-
Launch MotiQ 3D Analyzer via Plugins > MotiQ > MotiQ 3D Analyzer...
-
In the settings dialog, select at "Process" "all open images", enter the settings for particle filtering that you gauged. All other settings are not relevant for our test and can be left at default parameters.
-
Run MotiQ 3D Analyzer by clicking "OK" and wait for the processing to be finished.
-
Go into the output folder that was generated (ending _M3D). In case you are missing files ending with -3D (to read about the reason see this wiki post), skip step 17 and validate the results only as described in step 18.
- Open the file "M3D_RP...-3D.tif" (the number behind RP in the filename indicates the size threshold that you applied and may look different for you) and check whether you see any particles that may not belong to the cell (blue arrows in screenshot).
- Open the non-3D file "M3D_RP...tif" and create the display with red background as described in steps 4 and 5. Now also open the original cropped image with ending CUT___X<...>_Y<...>.tif next to it. For better seeing small particles you might need to adjust the display of intensity values - go to Image > Adjust > Brightness / Contrast at drag down the maximum in case you have a hard time seeing low intensity branches. Watch out for the particles you want to verify (see step 17) or if you skipped step 17 watch out for small particles that are detected by MotiQ 3D Analyzer but are not belonging to the cell. Verify whether they belong to the cell or not.
To better show that these particles are not connected to the cell and could be something else (maybe antibody aggregates?) we show here the different consecutive planes. When passing those this becomes clearer.
- If you did not discover any particle that was falsely detected as belonging to the cell move on at step 20. If you discovered particles that should also be excluded but are still detect, gauge there size in voxel, redetermine the size threshold (as described in step 9) also based on the sizes of these particles, and note down the new value to be used at . Go back to step 10 and retry with this new setting. Please also note the advice give after step 20 on the challenges in defining this value.
For the example image we measure two particles of 85 and 88 px that should also be excluded by MotiQ 3D Analyzer. Thus, we may raise the threshold to 90 px and retry.
- Now pass through the planes of the opened images (the RP...tif output file and the original cropped image) and check whether you miss out particles that should be included but were excluded by MotiQ 3D Analyzer. If you do not find such a particle move on to step 21. If you find such particles, gauge their size in px, redetermine the size threshold (as described in step 9) also based on the sizes of these particles (so adjust it too a lower value that will include these particles), and note down the new value to be used at . Go back to step 10 and retry with this new setting.
IMPORTANT NOTE for steps 19 and 20: It may be the case that you cannot find a size threshold that allows you to keep all branches of the cell while removing all non-cell particles. In that case you have three options: A) You need to repeat from cropping and crop out more precisely. B) You may just accept that once in a while you have a falsely-as-cell detected particle. For the large cells the small errors, which should be relatively random in your data sets, may not make an impact but just introduce a little bit more, acceptable noise in your measurement results (especially if you analyze large numbers of cells. C) Manually post-modify the images where you accidentally included one particle too much (BLOGPOST ON HOW TO DO THAT SOON TO BE WRITTEN).
- Congratulations you found good settings for Particle Filtering and you can move on at Step C - Calculation in this step by step guide.
- Since you aim to not use MotiQ Cropper but to automatically detect the individual cells, we need to find a size threshold to be used in this filtering step that excludes all small background particles or branches coming from cells mainly localized outside of the stack. First we estimate how big a cell soma is. Focus on a cell soma and estimate its width, height, and depth (number of z slices it spans) in pixels and compute the volume of a box containing the soma (width in px x height in px x depth in px).
To measure width and length of the bounding box you can use the rectangular ROI tool, when you are dragging the ROI around the soma you can see in the status bar of FIJI the width and height in px (here 62 and 56 px).
To measure the depth check roughly in how many slices the soma is present by switching between slices with the slider under the image. To display this process here we created a montage of consecutive slices and marked the selected bounding box. Based on what we see here we roughly gauge the z bounding box to be about 7 slices (marked by gray background). In the other slice images the soma is fading out / less / not present.
Now these values allow us to gauge the rough size that the cell at least features: 62 x 56 x 7 = 24304 px.
-
Repeat step 11 for a few more cells and try to focus in particular on the smaller cells. Then conclude what was the minimum volume in px that you calculated based on these tests.
-
Check what volume particles have that are from cells that are not entirely in the stack using the same approach.
To measure width and length of the bounding box you can use the rectangular ROI tool, when you are dragging the ROI around the soma you can see in the status bar of FIJI the width and height in px (here 35 and 16 px).
We measure a depth of about 10 slices (blue boxes)
Now these values allow us to gauge the rough size of a cell that is not fully in the stack: At least 35 x 16 x 10 = 5600 px.
- Now compare the values for the particles measured in step 12 (these are the particles you aim to include since they belong to complete cells) to the particles measured in step 13 (these are the particles you do not aim to include into your analysis) and decide on a "size threshold" for particles to be excluded and particles to be included. Note this threshold value down to be used in the MotiQ 3D Analyzer setting here: . Also note down to disable the following checkbox in the settings dialog of MotiQ 3D Analyzer (for when and how to use this box see Note 1 below):
In the example above we gauged a voxel number of about 24000 px for cells completely in the stack and of about 5600 px for cells incompletely in the stack. Based on these values we would select a size threshold somewhere in the model, e.g., 15000 px, to filter the particles in the image and exclude incomplete cells. Ideally we would have performed a few more measurements to better decide on the threshold.
-
Now that we have gauged the particle analyzer settings to start with, we will verify how well they perform in MotiQ 3D Analyzer.
-
Launch FIJI (if already open, close it and relaunch it again).
-
Open one, or ideally, multiple example output images from MotiQ thresholder in your data set, by drag and drop into the FIJI / ImageJ status bar.
-
Launch MotiQ 3D Analyzer via Plugins > MotiQ > MotiQ 3D Analyzer...
-
In the settings dialog, select at "Process" "all open images", enter the settings for particle filtering that you gauged, and select at "Calculate results for" the option "every particle separately...". All other settings are not relevant for our test and can be left at default parameters.
- Run MotiQ 3D Analyzer by clicking "OK" and wait for the processing to be finished.
- Inspect the generated output folder ending with "_M3D". In case you are missing files ending with -3D (to read about the reason see this wiki post), in the following just use the non-3D files (e.g., "M3D_RP...tif") for validation of what particles were detected. You may just open these in FIJI and apply steps 3 and 4 to visualize what is background and what is detected particle in these images.
- Verify whether the different detected particles (distinguishable by particle IDs ("P1", "P2", ...) in the file names) represent cells that you decide to be sufficiently contained within the stack. You may open along side also the original image and try to find the detected particles in the image to see if they represent a cell sufficiently in the stack or not. Here it may also help to also look at a maximum intensity projection of the original image along side the 3D representations (you can generated it from the original image via the menu entry Image > Stacks > Z Project... and selecting "Projection type" "Max Intensity").
In our example here we see that there are still 4 particles detected of cells that are likely also largely outside of the stack. P2 does not contain a cell soma and seems to be just a branch of a cell outside of the stack. This particle obviously needs to be excluded. P3 seems to be a cell that is at the uppermost or lower most slice of the stack - we will investigate it in more detail below. P4 shows a very straight line on the right and on the top where the processes end, it is likely also at the image border - we will investigate it in more detail below. P5 shows straight borders at the right and bottom and may also be at the image borders - we will investigate it in more detail below.
P3's soma is half out of the stack at the upper slice, meaning that we are missing at least half if not more of that cell, so this one should definitely be also excluded.
We find particle P4 to be at the top right corner of the image. Since it is soma is in the center of the stack it is a border line decision whether to keep it or not. Depending on how many cells you can extract that are fully in the stack and how many of such cases you have you may also decide to keep those cells where just a small part of the cell is missing since it may still be accurate enough if you include such cells equally in all your data set. The more accurate approach however will be to exclude it.
P5's soma is half out of the stack at the lower image border, meaning that we are missing at least half if not more of that cell, so this one should definitely be also excluded.
-
If you are not seeing any particles that are falsely detected move on to step 38. Otherwise continue here.
-
Look up what sizes the particles you aim to exclude have. Note down there particle IDs and inspect the generated M3D text file. Open it, copy all content (press
Ctrl
A
on Windows/Linux orCmd
A
on a Mac, and nextCtrl
A
on Windows/Linux orCmd
A
on a Mac, and paste it into a table document (Excel, Libre Office Calculator, Google Sheets, ...) (In such a document, click in the top left corner and pressCtrl
V
on Windows/Linux orCmd
V
on a Mac).
- Scrolling down we find results for the individual particles and the column that describes their volume in the calibration unit. Note down the values.
- Based on these values and knowing our image calibration, we can compute the volumes in voxel. To find out the image calibration you can look further up in the output file and note down the values.
- Now we calculated the voxel number for each particle and see how large particles are we want to include and how large particles are we want to definitely exclude. Based on this information we can recalculate the size threshold to be applied in MotiQ 3D Analyzer, go back to step 25, determine a new size threshold based on the new information and repeat the test from there. Please also note the explanations after step 40 on challenges in defining this value.
In the example we see that all particles to be excluded are at about 15000 to 60000 px. The succesfully reconstructed cell features about 180000 px. Thus a new, better exclusion threshold may be e.g. 100000 or even higher.
-
Scroll through the original image and verify that there is not a cell in it that you did not detect. If there is a cell that MotiQ 3D Analyzer did not detect but that needs to be included in your results, you will need to lower the size threshold that you applied. Try to gauge its size in px similar to what was applied above and move back to step 25 to recalculate the size threshold and retry the test analysis.
-
Scroll through the original image and the reconstructions by MotiQ 3D Analyzer (the 3D images) and verify that you do not observe any particles that represent two cells. If you do so, you may approach this problem in three different ways: A) Optimize the MotiQ Thresholder settings to be less "inclusive" for background pixels - it might be that the two cells are just connected through a small bridge of actually background pixels that emerges because the threshold is too inclusive for background pixels. Then repeat the tests with MotiQ 3D Analyzer. B) Switch to the semi automated workflow, crop out individual cells and analyze those. C) If this event just occurs very rarely you may just ignore these small errors in your data. If you reach high numbers of analyzed cells per conditions these small inaccuracies may be negligible and just increase a little bit the measurement noise but not impact your conclusions. D) You may manually exclude those fused particles by the particle ID later in the results.
-
A last sanity check to generally be done with this analysis workflow where you do not use the manual cropping of individual cells is that you completely detect the cells. Similar to inspecting the data in steps 33 and 38, scroll again through the stack and scrutinize whether the particles you obtained really represent whole cells. Check whether the reconstructions are not missing branches and whether there are no cells split into multiple particles. In case you observe split or incompletely detected cells the following three options may help you to fix the problem: A) Optimize the MotiQ Thresholder settings to be more "inclusive" for background pixels - you may get more noise in the images but may better connect processes. Then repeat the tests with MotiQ 3D Analyzer. B) Switch to the semi automated workflow, crop out individual cells and analyze those. C) If you just miss a tiny arm in only a small number of cells in your data set you may consider to accept these inaccuracies and instead of investing more time on optimizing it rather invest more time in analyzing even more cells. If you reach high numbers of analyzed cells per conditions these small inaccuracies may be negligible and just increase a little bit the measurement noise but not impact your conclusions.
IMPORTANT NOTE for steps 35 to 40: It may be the case that you cannot find a size threshold that allows you to get all cells you aim to detect while removing all partly cut off cells or branch-only particles. If you have small and large cells in your data set you may need to pick a lower size threshold value used at that results including a lot of particles of cells that are not completely in the stack. In this case you can however manually inspect the results and note down which particles to exclude for further analysis / or which to keep for further analysis and manually remove the particles by their particle id later from the results.
- Congratulations! You found good settings for Particle Filtering in MotiQ 3D Analyzer and may proceed with finding out the settings for Calculation.
-
If you do not analyze time-lapse images the setting is obsolete for you. Note down to just leave the default value in this field.
-
If you are analyzing time-lapse images you need to select setting based on your study design. This parameter defines how many time-points are jointly investigated to calculate "longer-term"-kinetics output parameters for the movements, such as the "directionality" or "scanning activity". If you are conducting experiments where you add substance or set stimuli and thus have a certain amount of baseline frames before the stimuli, and then follow-up recording you should select a parameter here that covers exactly the number of baseline frames. Thereby, you will get a value for the baseline and a value / multiple values for the during stimulus/post-stimulus time. If you are not conducting such experiments were something changes over time you may pick a value that either covers the entire time-series or for long time-series that covers only a part of the time series (in that case you would get measurements at multiple steps of the measurement). In the latter it may be advised to select a value that leaves no rest when you divide the number of frames of your recording through this value.
Example 1: In my data-set, I always recorded 6 frames at baseline conditions and then wash in substance X and continue recording for 20 more frames. In this case I would pick a value for "#time-steps grouped for long-term analysis" of 6.
Example 2: In my data-set, I just acquire 11 frames to estimate the motility. There is no changes to be expected during the time of analysis. In this case I would pick a value for "#time-steps grouped for long-term analysis" of 11, which covers the entire time series.
Example 3: In my data-set, I acquire 120 frames with a frame-interval of 1 min, so this is a long-term recording. In this case I would pick a value for "#time-steps grouped for long-term analysis" of 10 or 20, since when using higher values or a value covering the whole time-span I might not see any directional movement or scanning activity in the results since the cell might have returned to its original position even though it would be actually quite active.
-
If you have cropped out individual cells with MotiQ Cropper note down to select the setting:
-
If you have not cropped out individual cells but want MotiQ 3D Analyzer to detect individual cells, note down to select
-
Now we will try to find optimal settings for the skeletonization of the cells, which allows MotiQ 3D Analyzer to characterize the process tree:
-
Launch FIJI / ImageJ (if it is already open, close it and relaunch it).
-
Open one or ideally multiple example images by drag and drop into the status bar of FIJI / ImageJ.
-
Launch MotiQ 3D Analyzer via Plugins > MotiQ > MotiQ 3D Analyzer...
-
In the settings dialog, select at "Process" "all open images", enter all settings you determined in Steps A and B above, leave the rest at default parameters, and press OK. Wait for the analysis to finish.
-
Inspect the generated output folder ending with "_M3D".
-
For a coarse check, open the 3D files for the detected particle(s) ("...RP...-3D.tif") and skeelton(s) ("...Skl-3D.tif"). In case you are missing files ending with "-3D" (to read about the reason see this wiki post), in the following just use the non-3D files (e.g., "M3D...Skl.tif", "M3D..._RP....tif") for validation of the detected skeleton. You may project these into a maximum intensity projection for better seeing the process tree that was detected (you can generated it via the menu entry Image > Stacks > Z Project... and selecting "Projection type" "Max Intensity").
- Check whether the detected process tree matches your observation of processes.
We see that the processes follow the overall process tree. There is this one tiny kink that is not reflected in the process tree (see blue arrow), but this may also be just a falsely added background pixel.
- To check the detection of the process tree in more fine detail, open the "M3D...Skl.tif" "M3D..._RP....tif" files, click on the menu entry Image > Color > Merge Channels... and select the files as in the screenshot.
We see that the processes follow the overall process tree. There is this one tiny kink that is not reflected in the process tree (see blue arrow), but this may also be just a falsely added background pixel.
- Scroll through the stack in the merged image and check whether all processes are picked up with the skeleton, eventually also look at a maximum intensity projection of the merged image (you can generated it from via the menu entry Image > Stacks > Z Project... and selecting "Projection type" "Max Intensity")
We see that the processes follow the overall process tree.
However we also see that few very fine short processes are missed out.
- In case you see that fine processes are missed out you may try to obtain a finer process tree by reducing the parameter and repeating steps 6-14. If you repeat the analysis you may check to avoid overwriting of the previously generated test output and to be able to compare the lowered blur to the higher blur.
We repeated the workflow and tested a Gaussian Blur of 0.5 and found that it better detects these small processes. Left: Gaussian Blur of 1.0. Right: Gaussian Blur of 0.5.
- In case you see that many noise pixels at the cell edge are detected as processes which in fact are not processes you may try to obtain a coarser process tree by increasing the parameter and repeating steps 6-14. If you repeat the analysis you may check to avoid overwriting of the previously generated test output and to be able to compare the lowered blur to the higher blur.
Here you can see that a noisy addition of background and a small Gaussian Blur of 0.0 led to a detection of a branch even though there was no actual branch (It could be that there was a branch that is super small and below the resolution limit but that's rather unlikely).
-
Concluding notes on adjusting the Gaussian Blur: Here again it can be hard to find a perfect Gaussian Blur value that includes all processes and does not include noise. Another problem that is not described in points 15 and 16 is that it can also happen that at a too strong Gaussian Blur you may fuse neighbored processes into on process. All in all, you may decide on one value that seems to be overall "okayish" and just use the same value for all cells in the same data set. However, it may be advised to pick rather a higher than a lower value since the addition of many noisy additional branches falsifies your results stronger than if you miss once in a while a small process. In this consideration it may also be important to think about what your study question is: Does the overall process tree and larger branches are more relevant to you than smaller branches? Or do you really need to detect even the tiniest branches? Lastly, you may of course also add a blur in Z direction () and try how it changes the skeleton detection - note, however, that in light microscopy the resolution in z direction is anyways worse than in x,y, direction and thus all your images anyways have a natural z blur compared to x,y. Thus, it usually does not make sense to also introduce a z blur.
-
Based on the trying-and-testing in the previous steps, select the best Gaussian Blur setting and note it done to be used in your analysis.
-
Select the number format based on the number format that your table calculation software prefers / your post-hoc analysis prefers. E.g., if your OS is using "," as a decimal separator, you may think about selecting - otherwise, better keep the setting as is ().
-
Unless you check MotiQ 3D Analyzer will automatically overwrite any analysis of the same image in the same folder. In case you are repeating an analysis you may check this option and in turn, MotiQ 3D Analyzer will not overwrite an existing analysis and instead create a folder and files containing the date and time of analysis. Otherwise just leave this checkbox unchecked to avoid that all filenames get extremely long.
Left: Example output folder name when not including analysis date and time in the file name. Right: Example output folder name when including analysis date and time in the file name.
The option is helpful to be used when you are analyzing images of which you know that you always have maximum one intact cell in the image. This can be e.g. the case when you conducted targeted imaging: you always selected one cell to be of interest and tried to acquire only a bounding box around this cell. Another use case for this option is if you want to accelerate cell selection and do more "sloppy" cropping with MotiQ Cropper. You might have selected specific cells of interest using MotiQ Cropper just by a coarse ROI. In that case this option may allow you to just consider the largest cell in the cropped image.
There is however one Caveat to consider: This approach only works if the imaging and segmentation approach are excellent, meaning that neither the particles of two neighbored cells are fused nor due to low signal-to-noise-ratio a cell may be "bursted" into multiple particles belonging to the same cell (for more details and screenshots see in particular section B.2 above).
Here are two example images. The left image stems from an in vitro 3D culture experiment with sparsely seeded cells where anyways only one cell per image was acquired. In the right image the cell with the lower cell body is actually at the image border on the top slice. The imaging was conducted with the aim to acquire the cell in the center only.
Left: in vitro 3D culture experiment with sparsely seeded cells where anyways only one cell per image was acquired. Right: In vivo 3D stack image that was required to record the center cell but that also contains a second cell which is only partially in the field of view (lower cell body).
Copyright (C) 2017-2024: Jan N. Hansen.
MotiQ is part of the following publication: Hansen et al., MotiQ: an open-source toolbox to quantify the cell motility and morphology of microglia, Molecular biology of the cell, 33:11 (2022). https://doi.org/10.1091/mbc.E21-11-0585