Parameter Calculation

In the tab Parameter calculation you can compute additional measurements or features which can be extracted from image stacks for the whole biovolume, or for each pseudo-cell cube in the biovolume.

Note

The segmentation extracts the following parameters for each pseudo-cell cube (also called “object” below) by default:

  • CentroidCoordinate_{x, y, z}. Center of mass coordinate in \(x, y, z\) direction.
  • Shape_Volume. Volume in \(\mu m^3\).
  • Intensity_Mean. (Option: fluorescence channel on which teh segmentation is based) Mean of all fluorescent intensity values.
  • Cube_VolumeFraction. Ratio of occupied biovolume of the cube compared to the total cube volume.
  • Cube_Surface. Number of interface voxels between occupied and unoccupied volume in cube.
  • Cube_CenterCoord. This is an internal property only. Center coordinate of cube.
  • Grid_ID. Unique ID of grid position within the given volume (depends only on x, y, and z). Two cubes of different z-stacks at the same position will have the same Grid_ID.
  • ID. Unique object ID.

By selecting a row in the parameter calculation table, you toggle a description panel underneath the table. In this description, you will find brief information on the calculation process, the added features and if particular preprocessing steps are required.

If the calculation of a specific measurement depends on certain input parameters, a second panel will appear below the parameter calculation table, with the possibility to provide these parameters.

If you want to test a calculation (especially for debugging) without overwriting the already calculated results you can use the checkbox Don’t save results. Use the button Calculate object parameters to start the calculation of all ticked properties. With the button Restore to defaults you can reset all custom options.

Parameter calculation tab

We will now describe the different parameters that can be calculated. You can include them in the next calculation process by enabling the checkbox in the column Calculate.

Filter parameters

The execution of the first tasks in the list does not directly result in any object parameters. Here you will find useful tools to remove or exclude objects with certain properties from the overall biomass.

Filter objects

Exclude objects from further calculations which are outside the specified range of a given parameter (e.g. to exclude very small objects, or objects at a particular location).

Of course, the objects can only be filtered accordinig to parameters that have already been calculated at this stage of in the processing pipeline. So you may have to run the parameter calculation at least twice. Each filter range is defined on a per-file basis. Use the button Determine for a graphical range selection. Use the button Set for all if you want to use the same range on all files in the Files panel. After filtering, objects outside the parameter range are excluded from further analysis, but are not permanently deleted. To undo a filtering operation simply filter again with a data range including all objects. For filtering by several parameters you have to remove objects which did not pass filtering after each filtering step.

Note

More advanced filtering can be done in the data visualization mode of BiofilmQ. The filtering option in the parameter calculation is intended for actually removing objects from your dataset. To apply more complex filtering rules, use the tag cells task and filter based in the tagging afterwards.

Remove objects which did not pass filtering

Permanently deletes all objects which are excluded from parameter calculation by prior filtering.

Remove objects on the image border

Permanently delete all objects which overlap with the image border or crop rectangle.

Remove object parameters

Permanently delete all specified object parameters.

One (or multiple comma-separated) parameters can be defined in the Options panel for removal. You can find a list of all already calculated parameters in the Data export tab.

Object parameters

In this section we will discuss all available object parameter calculation tasks. Parameters starting with Biofilm_ are global parameters and are calculated for the whole biofilm once. All other parameters are calculated for each object separately.

Some parameters can be calculated with different options, such as different fluorescence channels, different range options or resolutions.

To keep track of these parameters, each one is appended to the parameter name for the visualization or data export. For example the note “Option: channel” for the parameter Intensity_Mean leads to a parameter name Intensity_Mean_chX where X is replaced by the picked channel number for the calculation.

Surface properties

All objects with the same \(x,y\) center coordinates are grouped to a ‘pillar’. For each ‘pillar’ the surface is calculated.

The option range (in \(\mu m\)) defines the radius of a sphere around the CentroidCoordinate of each object for the calculation of Surface_LocalRoughness.

  • Surface_LocalRoughness. (Option: range) Number of interface voxels between occupied and unoccupied volume in a sphere with radius range around CentroidCoordinate of each object (in other words, this paramter quantifies “surface density, or amount of surface area in a given volume”).
  • Surface_PerSubstrateArea. Each object in the pillar gets assigned the number of the pillar interface voxels divided by the pillar base area. The base area is identical to the squared grid size. This parameter has the same value for every pseudo-cell cube in the same “pillar” of the biofilm.
  • Surface_LocalThickness. For each pillar the highest \(z\) value for each base pixel is calculated, the Surface_LocalThickness is the mean value of all \(z\) values in \(\mu m\). This parameter has the same value for every pseudo-cell cube in the same “pillar” of the biofilm.
  • Biofilm_MeanThickness. (global) Mean value of Surface_LocalThickness. This paramter has one value for the entire biofilm biovolume.
  • Biofilm_Roughness. (global) Defined as \(\frac{mean(d)}{N} \cdot \sum_i^N |mean(d) - d_i|\), with \(N\) denoting the total number of pillars, \(d_i\) the thickness of pillar \(i\).
  • Biofilm_OuterSurface. (global) is the sum of all pillar surfaces (including holes).

Note

These “Surface properties” parameters only work for biofilms that have been dissected into cubes.

Substrate area

To calculate the substrate area, the intersection between the segmentation results and the defined substrate plane is calculated. You can insert the index of the substrate plane of the z-stack in the options panel. This limits the choice of the substrate plane to the available \(xy\) planes. If no input is given, the brightest plane in the z-stack is assumed to be the substrate plane.

Note

You can use the button ortho view in the Image preview panel to scroll through your image stack.

  • Architecture_LocalSubstrateArea. Number of voxels of each cube which are intersecting the given substrate plane.
  • Biofilm_SubstrateArea. (global) Sum of all plane intersections in \(\mu m^2\) for the whole biofilm.

Global biofilm properties

The global biofilm properties module calculates shape-related biofilm properties. Some require an approximation of the 2D footprint of the biofilm at the substrate (base shape). This is done by calculating the convex hull of the \(x\) and \(y\) coordinate of each detected object. To minimize the effect of single objects which are not part of the bulk biofilm, only objects within the 1% - 99% percentile range in \(x\) direction, 1% - 99% percentile range in the \(y\) direction, and 1% - 99.5% percentile range in \(z\) direction are used. The \(z\) direction is additionally corrected by subtracting the 1% percentile value from the remaining object coordinates.

If there are more than 5 cubes objects at the biofilm base, the base shape is approximated by fitting an ellipse into the convex hull.

  • Biofilm_Width. (global) Sub axis of the \(x\) axis of the non-tilted ellipse in \(\mu m\) (0 if less than 5 cube objects at the biofilm base).
  • Biofilm_Length. (global) Sub axis of the \(y\) axis of the non-tilted ellipse in \(\mu m\) (0 if less than 5 cube objects at the biofilm base).
  • Biofilm_Height. (global) Measure of the height within the [1%, 99%] range of \(z\) coordinates in \(\mu m\).
  • Biofilm_BaseEccentricity. (global) Eccentricity of the fitted ellipse (1 if less than 5 cube objects at the biofilm base).
  • Biofilm_BaseArea. (global) Area of the fitted ellipse in \(\mu m^2\) (Area of the convex hull if less than 5 cube objects at the biofilm base).
  • Biofilm_Volume. (global) Sum of the detected biovolume of all cubes during segmentation in \(\mu m^3\).
  • Biofilm_AspectRatio_HeightToWidth. (global) Defined as Biofilm_Height/Biofilm_Width.
  • Biofilm_AspectRatio_HeightToLength. (global) Defined as Biofilm_Height/Biofilm_Length.
  • Biofilm_AspectRatio_LengthToWidth. (global) Defined as Biofilm_Length/Biofilm_Width.
  • Biofilm_OuterSurfacePerSubstrate. (global) Defined as Biofilm_OuterSurface/Biofilm_SubstrateArea (or Biofilm_OuterSurface/Biofilm_BaseArea if Biofilm_SubstrateArea has not be calculated; NaN if Biofilm_OuterSurface does not exist).
  • Biofilm_OuterSurfacePerVolume. (global) Defined as Biofilm_OuterSurface/Biofilm_Volume (NaN if Biofilm_OuterSurface does not exist).
  • Biofilm_VolumePerSubstrate. (global) Defined as Biofilm_Volume/Biofilm_SubstrateArea (Biofilm_Volume/ Biofilm_BaseArea of Biofilm_SubstrateArea has not be calculated).

Convexity

  • Shape_Convexity. Volume of convex hull of each object divided by the biovolume of each object. This aprameter is calculated for each pseudo-cell cube of the biofilm.

Distance to center of biofilm

Calculates the center of mass of the whole biofilm biovolume by taking the mean value over the CentroidCoordinates of all objects (excluding the ones filtered out by Filter objects).

  • Distance_ToBiofilmCenterOfMass. Distance of each object CentroidCoordinate to the center of mass in \(\mu m\).
  • Distance_ToBiofilmCenterAtSubstrate. Same as Distance_ToBiofilmCenterOfMass but uses the minimal value in \(z\) of the whole biofilm instead of the mean. This is the distance of each object to the center of mass projected down to the substrate plane.

Distance to surface

The surface of the biofilm is approximated as a custom convex hull, which is calculated as follows. To calculate the convex hull, a mesh with a custom resolution is generate in the \(xy\) plane. For each mesh point a circular pillar with the radius resolution is generated. The highest \(z\) centroid value of all objects within this pillar is used as a \(z\) coordinate for the convex hull.

  • Distance_ToSurface. (Option: resolution) Distance between cube object centroid to the outer convex hull.

Distance to specific object

The option ID indicates the object of interest, to which the distance of all other objects is calculated.

  • Distance_ToObject. (Option: ID) The distance of the object centroid to the centroid of the object with the provided ID in \(\mu m\).

Note

To figure out the ID of a certain object visualize the biofilm in ParaView and color the objects by their ID.

Local density

To compute measures of the local density, BiofilmQ calculates a sphere with radius range in \(\mu m\) around the each object CentroidCoordinates.

  • Architecture_LocalNumberDensity. (Option: range) Number of other object CentroidCoordinates within the sphere.
  • Architecture_LocalDensity. (Option: range) Occupied volume fraction in the sphere (results in NaN if calculation is not possible).

Fluorescence properties

This module applies again all filters used for the Segmentation on the raw image stacks (noise removal is optional). Based on the filtered/ cropped/ isotropical-pixel-spacing-transformed images the user can calculate the fluorescence properties listed below. The properties can be categorized into three major categories:

Use the Options panel to create a custom processing pipeline by adding desired calculation tasks. You can find each calculation task in the drop-down menu on the right. As soon as you have selected a task, you can modify the task-related options via the interface elements below.

Use the Add button to append the task to the pipeline. With the buttons Delete entry or Clear you can remove a selected entry from the list or reset the whole selection.

Intensity Properties

The background value is defined as the lowest 30% of fluorescence pixel values in the entire image stack. Every fluorescence intensity-related task needs the channel number as argument, to indicate to BiofilmQ which fluorescence channel be used. The ratio measurements compare the intensity ratios, which can be useful to compare specific reporter expression levels with constitutive signals.

With the shell-related parameters, the fluorescence signal inside a shell around each object can be quantified. The shell is constructed by expanding each object by a layer of thickness range. Then the average or integrated intensity of all voxels inside this shell is calculated. For cubed biofilms inter-cube faces are not considered for the shell calculation. These shell-related parameters are particularly useful for quantifying the signal of extra-cellular components labeled with fluorescent dyes.

  • Intensity_Mean. (Option: channel) Average of all pixel intensity values for all cube object voxels.
  • Intensity_Mean_noBackground. (Option: channel) Same as Intensity_Mean but prior to calculation the background intensity is subtracted.
  • Intensity_Integrated. (Option: channel) Sum of all intensity values per cube object.
  • Intensity_Integrated_noBackground. (Option: channel) Same as Intensity_Integrated but prior to calculation the background intensity is subtracted.
  • Intensity_Ratio_Mean. (Options: channelA, channelB) Mean ratio of the intensity values per cube object in channelB and channelA.
  • Intensity_Ratio_Mean_noBackground. (Options: channelA, channelB) Like Intensity_Ratio but prior to calculation the background intensity values are subtracted for each channel.
  • Intensity_Ratio_Integrated. (Options: channelA, channelB) Same as Intensity_Ratio_Mean but with the integrated intensities.
  • Intensity_Ratio_Integrated_noBackground. (Options: channelA, channelB) Same as Intensity_Ratio_Mean_noBackground but with the integrated intensities.
  • Intensity_Shells_Mean. (Options: channel, range) Like Intensity_Mean but for all voxels inside the shell defined by the radius given by the parameter range.
  • Intensity_Shells_noBackground. (Options: channel, range) Like Intensity_Mean_noBackground but for all voxels inside the shell defined by range.
  • Intensity_Shells_Integrated. (Options: channel, range) Like Intensity_Integrated but for all voxels inside the shell defined by range.
  • Intensity_Shells_Integrated_noBackground. (Options: channel, range) Like Intensity_Integrated_noBackground but for all voxels inside the shell defined by range.

The task Visualize extracellular fluorophores creates vtk files in the data subfolder which can be used to visuallize the intensity values of the shell-based calculations in ParaView.

Correlation Properties

Some fluorescence correlation properties can be calculated for every single object as well as for the full 3D image z-stack.

  • Correlation_Pearson. (Options: channelA, channelB, range) (global/ local) The Pearson’s correlation coefficient of two channels. Can be calculated either per object or for the full 3D image z-stack.

  • Correlation_Manders. (Options: channelA, channelB, range) (global/ local) The Manders’ overlap coefficient of two channel. Can be calculated either per object or for the full stack.

    • Correlation_MandersSplit_<channelA>_<channelB>. (Options: channelA, channelB, range) (global/ local) The Manders’ split coefficient of one channel in the other. Can be calculated either per object or for the full stack.
    • Correlation_MandersSplit_<channelB>_<channelA>. (Options: channelA, channelB, range) (global/ local) Like Correlation_MandersSplit_<channelA>_<channelB> but with swapped channel definitions.
  • Correlation_AutoCorrelation_CorrelationFcn. (Options: channel) (global) Calculates the autocorrelation function in 3D for the full image.

    • Correlation_AutoCorrelation_CorrelationLength2D_ch%d. (Option: channel) (global) 2D correlation length (distance where the autocorrelation has dropped by 50%) as determined from the average 2D autocorrelation functions for each plane of the image stack.
    • Correlation_AutoCorrelation_CorrelationLength2D_Subtrate. (Option: channel) (global) 2D correlation length determined from the autocorrelation function at the brightest plane of the biofilms.
    • Correlation_AutoCorrelation_CorrelationLength3D. (Option: channel) (global) 3D correlation length (distance where the autocorrelation has dropped by 50%) as determined in 3D for the whole image stack.
    • Correlation_AutoCorrelation_Zero3D. (Option: channel) (global) (global) Position of the first zero-crossing of the 3D autocorrelation function.
    • Correlation_AutoCorrelation_Zero2D. (Option: channel) (global) (global) Position of the first zero-crossing of the averaged 2D autocorrelation functions for each plane of the image stack.
    • Correlation_AutoCorrelation_Zero2D_Substrate. (Option channel) Like Correlation_AutoCorrelation_Zero2D only in the substrate plane.
  • Correlation_DensityCorrelation. (Options: channelA, channelB, range) The density correlation for each object \(C = \frac{\sum^N_i a_i \cdot \sum^M_j b_j}{N^2}\), where \(a_i, b_j\) denotes all pixel values of channelA, channelB in a box with edge length 2x range around the objects centroid, respectively.

  • Correlation_DensityCorrelation_Binary. (Options: channelA, channelA, range) The Correlation_DensityCorrelation on the binary image which resulted from the segmentation.

    Note

    The density correlation task requires a data file containing data merged from two channels. Segmented biofilms in two different channels can be merged with the post-processing option merge channels in the Segmentation tab.

  • Correlation_Local3dOverlap. (Options: channelA, channelB) The volume overlap in \(\mu m^3\) of each object in channelA with all segmented objects in channelB.

  • Correlation_LocalOverlapFraction. (Options: channelA, channelB) Like Correlation_Local3dOverlap divided by the objects volume.

  • Biofilm_Overlap. (Options: channelA, channelB) (global) The sum of Correlation_Local3dOverlap for all objects in channelA.

  • Biofilm_OverlapFraction. (Options: channelA, channelB) (global) The sum of Correlation_LocalOverlapFraction for all objects in channelA.

Haralick texture features

Currently only the mean of the Haralick features in the directions up, down, right, left, back, forth in the given channel and range are calculated. The Haralick features are based on the entities of the co-occurrence matrix \(p_{i,j}\). Additionally the properties:

  • \(\mu_x = \sum_{i,j} i\cdot p_{i,j}\),
  • \(\mu_y = \sum_{i,j} j \cdot p_{i,j}\),
  • \(\sigma_x = \sum_{i,j} (i-\mu_x)^2 \cdot p_{i,j}\),
  • \(\sigma_y = \sum_{i,j} (j-\mu_y)^2 \cdot p_{i,j}\)

are used for the calculation.

  • Texture_Haralick_Energy. (Options: channel, range) Defined as \(\sum_{i,j} p_{i,j}^2\).
  • Texture_Haralick_Entropy. (Options: channel, range) Defined as \(\sum_{i,j} p_{i,j}\cdot \log_{10}(p_{i,j})\).
  • Texture_Haralick_Correlation. (Options: channel, range) Defined as \(\sum_{i,j} ((i-\mu_x)*(j-\mu_y)*(p_{i,j}/(\sigma_y*\sigma_x)))\).
  • Texture_Haralick_Contrast. (Options: channel, range) Defined as \(\sum_{i,j} p_{i,j} \cdot |i-j|^2\).
  • Texture_Haralick_Homogeneity. (Options: channel, range) Defined as \(\sum_{i,j} \frac{p_{i,j}}{1+|1-j|}\).
  • Texture_Haralick_Variance. (Options: channel, range) Defined as \(\sum_{i,j} (i-\mu_x)^2 \cdot p_{i,j} + (j-\mu_y)^2 \cdot p_{i,j}\).
  • Texture_Haralick_SumMean. (Options: channel, range) Defined as \(\sum_{i,j} (i+j) \cdot p_{i,j}\).
  • Texture_Haralick_Inertia. (Options: channel, range) Defined as \(\sum_{i,j} (i-j)^2 \cdot p_{i,j}\).
  • Texture_Haralick_ClusterShade. (Options: channel, range) Defined as \(\sum_{i,j} (i+j-\mu_x - \mu_y)^3 \cdot p_{i,j}\).
  • Texture_Haralick_ClusterTendendy. (Options: channel, range) Defined as \(\sum_{i,j} (i+j-\mu_x - \mu_y)^4 \cdot p_{i,j}\).
  • Texture_Haralick_MaxProbability. (Options: channel, range) Defined as \(\max_{i,j} p_{i,j}\).
  • Texture_Haralick_InverseVariance. (Options: channel, range) Defined as \(\frac{p_{i,j}}{(i-j)^2}\).

Tag cells

Sometimes (especially for the analysis or visualization of the experiment) it becomes useful to tag a subset of the observed cube objects based on the already calculated parameters. In contrast to filter objects, this function will add a new parameter for each new tag. All objects are still processed by the other parameter calculations in the same way.

  • <user_defined_name>. (requires: parameter for tagging, rules) stores for each object the value 1 (true) if all filter rules are fulfilled otherwise it stores 0 (false)

Custom parameters

BiofilmQ allows users to create custom parameter calculations. In the default file (located at the file path: includes/object processing/actions/template.m in the BiofilmQ source files) you can find a short overview of the accessible variables during runtime and a description for how to save custom parameters in the objects variable.

  • User-defined parameter.