When AlGrow is loaded, a menu is presented along with a logo page. Chose from the options described below to proceed.
The file menu contains options to:
Load an RGB image for configuration. The current loaded image filename is displayed in the bottom left of the relevant configuration toolbar.
Load an image mask for the current loaded image.
Load settings for configuration or analysis from a previously saved configuration file
Save the current settings to a configuration file for future use, either in the GUI or in the CLI.
The configuration menu conotains options to:
An internal reference with known dimensions should be included in at least one image at the relevant image depth. This tool allows you to use this internal reference to calculate an appropriate scale to convert from pixels to units of physical distance and area (mm²).
To dynamically detect a layout, AlGrow first detects circular edges in a grayscale image. This grayscale image is constructed from the distance (in Lab colourspace) from a chosen circle colour. The circle colour should be chosen to create a high contrast edge in a circular pattern surrounding each subject.
To dynamically detect a layout, Algrow needs additional parameters to: identify target circles, cluster circles into plates/trays and assign these incrementing integer identities.
Three of these can be measured from a loaded image in this interface, as is done with the scale utility:
There are counts that must be supplied:
Three tolerance factors are also provided to account for:
Additionally, there are six toggle buttons affecting the direction of ID incrementation, across plates:
and within plates:
There are then buttons to:
To detect circles in the circle colour distance image, the diameter is provided to determine the center of a range of radii to scan in a Hough transform. The breadth of the range to scan can be adjusted with the circle variability tolerance factor
To cluster circles into plates, a dendrogram is constructed reflecting the distance between circle centers. A key assumption to this plate identification strategy is that the distances between circles is less within plates than it is between plates. If this assumption is not held, consider treating the layout as a single plate.
The circle distance dendrogram is cut to identify clusters of a size corresponding to the specified number of circles per plate. The cut height is determined by the distance between circle centers, which is calculated from the supplied circle diameter and the value for separation between circle edges. An additional circle separation tolerance factor is provided, with higher values increasing the cut height.
Once plates have been identified, their alignment to the image axes is assessed by examining the angles between up to three points on each of the four possible corners. The position of each circle within the plate is then adjusted according to a corrective rotation to the image axes.
Once this rotation correction is applied, further clustering is performed into either rows or columns. This strategy provides a robust mechanism to identify grid-like patterns of experimental units. The relative positions along the relevant axis for each row or column (averaged across members of the row/column), and the relative position of circles within each row/column, defines the incrementation order, along with two additional circle id incrementation instructions; to start from the left or right and to start at the top or bottom.
Once clusters of circles conforming to the plate specification have been identified, the centers of these plates can then also be clustered into either rows or columns. A dendrogram of the distances between plates along the relevant axis is cut to define rows/columns, with the cut height is defined as half of the plate width. This strategy provides limited tolerance, scaling with plate size, to imperfect alignment of plates into rows/columns along the relevant image axis. The relative positions along the relevant axis for each row or column (averaged across members of the row/column), and the relative positions of plates within each row/column, defines the incrementation order, along with two additional plate id incrementation instructions; to start from the left or right and to start at the top or bottom.
Each set of images sharing a layout specification must have a constant number of circles to detect. This number is defined in the “circles” input field.
Each set of images sharing a layout specification must have a constant number of plates. This number is defined in the “plates” input field.
During layout detection, any detected circles are first filtered by clustering into groups of known sizes. The assumption used to detect these plate clusters is that circles within a plate are always closer to each other than they are to circles in other plates. If this assumption is not met then we recommend annotating each image as a single plate (i.e. “circles” == “circles per plate” and “plates” = 1). For layouts with singleton circles, 1 may be entered among this list of circles per plate, and the best matching circles up to the total number of circles will be used.
The known circle cluster sizes are defined as a comma separated list in the “circles per plate” input field.
In the CLI, multiple values should be entered as multiple arguments rather than as a comma separated list; e.g:
This factor affects the range of radii to search during circle detection.
This factor affects the evaluated target area following circle detection.
This factor affects the cut-height during plate detection.
Plates are assigned a unique integer per layout and sorted prior to circle ID incrementation.
When toggled, this button will read “plates in columns”. This option affects whether to cluster plates into rows (along the vertical axis) or columns (along the horizontal axis).
When toggled, this button will read “plates start right”. This option affects whether to start plate ID incrementation from the left or right, and then proceed to the right or left, respectively.
When toggled, this button will read “plates start bottom”. This option affects whether to start plate ID incrementation from the top or bottom, and then proceed to the bottom or top, respectively.
Although circle unit IDs are assigned to be unique per layout, these are assigned by incrementation AFTER sorting plates.
When toggled, this button will read “circles in columns”. This option affects whether to cluster circles within plates into rows (along the vertical axis) or columns (along the horizontal axis).
When toggled, this button will read “circles start right”. This option affects whether to start circle ID incrementation from the left or right (within plates) and then proceed to the right or left, respectively.
When toggled, this button will read “circles start bottom”. This option affects whether to start circle ID incrementation from the top or bottom (within plates) and then proceed to the bottom or top, respectively.
This button will start layout detection with the defined parameters. The duration of this search varies with many factors (from around second up to minute), so please be patient.
When the search is successful, and a layout is defined, an overlay will be depicted. This will highlight the detected circles with the applied circle expansion. It will also overlay the plate IDs and circle IDs. If the incrementation options are toggled, some of the search/clustering will be repeated. If the other parameters are changed you should click the “detect layout” button again to ensure the parameters result in a successful layout detection.
The layout detection can fail for a number of reasons and a dialog should appear warning of the issue. Click OK to close the dialogue. An overlay is also presented with the detected circles (including the applied circle expansion). If sufficient circles were detected, a dendrogram is also presented constructed from the distances between centers.
When a layout is detected, it is possible to save this as a fixed layout file (.csv). This file is a specification of the:
This file can be modified and custom versions loaded on the area analysis page. When saved or loaded, the fixed layout will be displayed on both the layout and target colour configuration pages.
However, be mindful that such fixed layouts will not support movement.
If a layout has been detected or loaded, it can be removed by clicking “clear layout”. This may be desired if you would prefer to examine the full image in target colour configuration, or to return to dynamic layout detection after loading a fixed layout.
The target colour configuration panel consists of a 3D plot (top-left), a toolbar (bottom left) and an image preview (right).
The 3D-plot is in the Lab colourspace, with points representing a down-sampling of image pixel values into voxels. The view can be rotated by left-click and drag, panned by a right-click and drag, or zoomed with a mouse wheel. Voxels can be selected by shift-clicking on the points, with the nearest point to the observer in a given radius of the click being selected. When selected, a voxel is displayed as a sphere, and the corresponding voxel colour is displayed as a button under “selected” in the toolbar. Selected voxels can be de-selected either by shift-clicking on the sphere, or by clicking on the corresponding button. When sufficient voxels are selected, a hull will be displayed.
The image preview highlights pixels corresponding to selected voxels, and target pixels, i.e. those corresponding to voxels inside or within delta of the hull surface. Voxels can also be selected/deselected by shift clicking on pixels in this image preview, and the view can be zoomed with a mouse wheel, or panned by clicking and dragging.
If a layout has been detected or loaded, the masked pixels are not considered for voxel sampling and are masked in black in the image preview.
Each of the inputs and buttons in the toolbar, and their impact on the 3D plot and image preview are described below.
Displayed voxels can be filtered by the minimum number of pixels represented by each voxel. Raising this value is useful to highlight clusters of pixel colour.
The “min pixels” value also affects hull construction from a loaded mask.
The alpha parameter guides hull construction from the selected points. When set to 0, the convex hull of all selected points is generated. All other values of alpha generate an alpha hull, where faces are only constructed if all edge lengths are less than alpha. This parameter thus provides support for generating target hulls with concave surfaces and/or disjoint polygons. Note that when alpha is low, more distal points may be excluded from the hull.
In simple cases, the convex hull may be preferred for speed and simplicity. However,the alpha-hull is useful and sometimes necessary in images where similar background colours are present.
The delta parameter determines the extent of the target-space outside the target hull, with higher values increasing the target colour volume. For images where the target colours are very distinct from background, a simple hull combined with a high delta value is sufficient to identify the target pixels. However, for more images with background colours closer to the target, lower delta is necessary and more points will likely be needed to accurately define the target hull.
It is recommended to use a delta value of at least 1, at least for the final analysis, to account for the variation introduced by voxel down-sampling. To improve responsiveness in the interactive panel, pixels mapped to voxels found inside or within delta of the hull are considered as target. However, in the area analysis, each pixel is considered independently.
Local heterogeneity is a complex issue in image segmentation. Frequently, a few isolated pixels may not fall within the target colour, despite being part of the target subject. To account for this, the option to fill areas surround by target pixels is provided. The maximum size of filled contiguous regions (in pixels) should be entered into “fill”.
As for fill, a few isolated pixels may fall within the target colour volume, despite not being part of the target subject. To account for this, the option to remove pixels surrounded by non-target pixels is provided. The maximum size of removed contiguous regions (in pixels) should be entered into “remove”.
This button will only be active if an image mask has been loaded. When clicked, voxels mapping to pixels selected in the image mask, representing at least min pixels are first identified. These points are then considered for hull construction using the alpha parameter. Vertices of this constructed hull are then added to the selection.
This is useful to rapidly generate a target full from existing image masks. Such a hull can then be adapted in AlGrow to improve robustness of the target hull across images.
The constructed target hull is displayed in the 3D plot. You can show/hide this hull by toggling this button. You can also change the colour of the hull with the tool below.
Pixels corresponding to selected voxels are displayed in the image preview. You can enable/disable this highlighting by toggling this button You can also change the colour of the highlighting with the tool below.
Pixels corresponding to voxels that are determined to be inside or within delta of the target hull. are displayed in the image preview. You can enable/disable this highlighting by toggling this button You can also change the colour of the highlighting with the tool below.
This vertical menu bar contains buttons for selected voxels. Each button details the voxel position in Lab colourspace in text, and is presented in the approximate corresponding colour.
Two buttons are found at the top of this selection:
This button removes all selected voxels
Clicking this button removes any voxels from the selection that are not vertices of the constructed hull. This is particularly useful when saving a configuration, when proceeding to analysis of multiple images, or to speed up interactions in this interface.
Reduce can occasionally result in unexpected outcomes with alpha hulls. This is due to the Delauney triangulation method used in hull construction, which, when performed on this new set of points, will result in a different set of triangles. The edges of these triangles are filtered by length and presence on the boundary to determine those to be used in construction of the alpha hull.
This vertical menu bar is similar to the adjacent selected. However, priors are stored across images, and any voxels found in selected are copied to here when loading a new image. Most importantly, this allows training and evaluation of a target hull across multiple images.
It should be noted that priors are no longer stored as voxels mapped to pixels.
Priors still contribute as points in hull construction and are presented in the 3D-plot as spheres.
Priors can also be removed by shift-clicking on the sphere in the 3D plot
or by clicking on the corresponding button in the priors panel.
The clear and reduce buttons have the same function as found in the selected menu, except that they operate on this set of priors.
The Dice similarity coefficient (aka Sørensen–Dice index, F1 score) is calculated when a true-mask is loaded for the current loaded image. It is defined as two times the area of the intersection of A and B, divided by the sum of the areas of A and B. Internally, it is calculated as 2tp / ( 2tp + fp + fn ), where tp=true positive, fp = false positive, fn = false negative.
The dice-coefficient is often preferred over accuracy in image segmentation due to the inclusion of true negative results in calculating accuracy. This can result in high accuracy values despite low true-positive rates, which is particularly important in comparing classification success when the ratio of target area to background area is small.
Area calculation will use the current configuration settings. At the top of this panel are buttons to add a directory of images, add a single file, remove a single file or remove all files. The selected image file names are loaded into the box below, and parsed by the filename regular expression to display block and time details.
A regular expression (a.k.a. regex) is a pattern that matches a set of strings. Sub-patterns in regex can be captured with parentheses “(“ and “)”.
AlGrow takes advantage of Python named groups in the pattern definition.
Named groups are prepended with “?P
.*(?P<year>[0-9]{4})-(?P<month>0[1-9]|1[0-2])-(?P<day>0[1-9]|[12][0-9]|3[01])_(?P<hour>[01][0-9]|2[0-4])h(?P<minute>[0-5][0-9])m_(?P<block>[a-z|A-Z|0-9]*).*
By way of explanation, we can break the start of this down sequentially:
.* allows for any preceding characters(?P<year> is the start of the capture group named year[0-9] matches any single digit number from 0-9{4} matches four of the preceding character, i.e. four numbers from 0-9) closes the year capture group.- then matches the “-“ character, outside the capture group.Much of the rest of the pattern is consistent with the above explanation, the pattern is just designed to specifically match time values (and provides a suitable example for users to modify).
The end of this pattern recognises the block name:
m_ matches preceding underscore (“m_”) characters(?P<block> starts the capture group named block[a-z|A-Z|0-9]* matches a series of any length of any lowercase (a-z) or uppercase (A-Z) or single digit numbers (0-9)).* closes the capture group but allows for any trailing charactersThis pattern will parse a filename that looks like this:
to provide these details:
With year, month and day provided, a time will returned in the resulting area output file, with hour minute and second defaulting to 0. Time and block details are required for subsequent growth analysis. If they cannot be parsed from the filename, they will not be found in the output area file. The time can be added manually to the area file in the format: “YYYY-MM-DD HH:mm:ss”. Similarly, a simple text string can be added to the block field in the output area.csv file for growth analysis.
When checked, the configured layout parameters will be used to detect the layout. If not checked, the layout will not be detected, and segmentation will proceed for the whole image.
A fixed layout can be loaded here from a layout.csv file, see save fixed layout. When loaded, the fixed layout overrides layout detection.
The number of processes to launch for parallel image processing. Each process will handle a single image until the list of images is processed. Set this value taking into consideration both CPU and memory usage.
There are three levels of debugging image production.
Set this to a suitable destination for the figures and area file etc. to be written to.
This launches optional layout detection and image segmentation using the defined target hull, appending results to area.csv in the output directory. If output file already exists, any image files already described within it will not be processed again.
The fields in the area file are:
Processing time varies with many factors, however the most significant factor is currently layout detection. Processing takes about 30 seconds per image if including layout detection in our images, though this varies depending on layout complexity.
Other factors that may noticeably affect processing time are image size (number of pixels) and hull complexity (number of points, convex vs. alpha hull). Despite this, segmentation should still take just a few seconds per image in typical conditions (e.g. 8MP image with <100 hull vertices)
Relative growth rate (RGR) can be calculated as the log difference in area over a given span of time. Assuming constant growth rates and unbiased error in our measurements, with more timepoints we can estimate RGR as the slope of a line of best fit to log transformed area over time. AlGrow can load an area file, and a samples map to perform this analysis.
Pressing “calculate” will perform the analysis and prepare a summary “RGR.csv” file. This describes the RGR estimated for each individual and the residual sum of squares (RSS) from the line fit. Any individual where the RSS is higher than the median RSS across all individuals plus 1.5 times the interquartile range (IQR), is flagged as a “ModelFitOutlier”.
Plots of area over time are also generated for each group according to the samples map, with the line fit in log(area) transformed back to units of area (“group_plots/group.png”). The legend to these plots describes the block, unit and RGR for each replicate. ModelFitOutliers are presented with dashed-lines.
Box-plots are also prepared, grouped according to the samples map, both with (“RGR.png”) and without ModelFitOutliers (“RGR_less_outliers.png”). A “RGR_mean.csv” file is also generated describing the mean RGR within each group, excluding individuals flagged as ModelFitOutliers.
Note that the assumption of constant RGR is not always reasonable, particularly given the presence of diurnal variation in growth for most plant and algal species. AlGrow does not attempt to correct for “seasonality” or any other variation or biases in its analysis, and we encourage careful consideration in your own analyses from the output area.csv. Also note that no attempt to estimate a “block” effect is made when reporting the mean RGR, despite our use of this term to identify distinct image sets. We expect that experimental designs will vary, and these analyses are provided as a convenience function for simple reporting contexts.
Nevertheless, provided the sampling of within day time points across days is balanced, the slope of the line of best fit through all timepoints is still likely to provide a good estimate of RGR. Taking advantage of specifying a start and end time-point, can be useful to avoid biases caused by incomplete measurements from the first or last day of an experiment.
The samples map file can be prepared in spreadsheet software, such as Microsoft Excel or LibreOffice Calc.
Three columns are required, with headers:
This value is relative to the first time point in the provided area file, in units of days. Data from prior timepoints will be excluded in preparing the line of best fit.
This value is relative to the first time point in the provided area file, in units of days. Data from subsequent timepoints will be excluded in preparing the line of best fit.
The default value for voxel size is 1. This can be modified during launch with the –voxel_size argument.
Voxel size is the resolution of the grid used to down-sample pixels to voxels.
The default value for downscaling is 1, i.e. no downscaling. This can be modified during launch with the –downscale argument.
An integer value provided to –downscale will reduce the image size before analysis, i.e. a value of 2 will halve the image resolution in both dimensions. This can be useful to speed up the interface for larger images and is provided for testing or target hull construction from very large images. Be warned, however, this isn’t handled terribly well. The scale and other pixel measurements including circle diameter etc. are not adjusted. As such scale and layout specifications should share the same downscale value as subsequent analyses.
This is currently just a flag, i.e. no value is provided. When used at launch, the loaded image will be passes with skimage.restoration.denoise_bilateral with the following options: sigma_color=1, sigma_spatial=1, mode=’edge’.