API Documentation

Module contents

The module bimato is the top-level namespace. It contains the following sub-modules:

See documentation for a general user guide.

Submodules

bimato.core module

The module bimato.core contains some fundamental functions for the bimato project. Mainly it contains the custom binarization technique tailored towards 3D biompolymer network images and others.

See documentation for a general user guide.

bimato.core.get_binary(data, bw_closing_frac=1024, min_obj_frac=256, win_frac=8, thresh_shift_percentage=0.01, morph_3d=True)[source]

Function to get a segmentation of input biopolymer network image data. Parameters are optional, but should be considered. Optimal values can vary for drastically differing image data.

Notes

All Parameters are determined automatically depending on input image properties. However, they can be influenced by specifying a factor.

Parameters

  • data (numpy.ndarray) – Input image data

  • bw_closing_frac (int) – Factor for calculation of the ball size during binary closing morphological operations

  • min_obj_frac (int) – Factor for determining the minimum object size

  • win_frac (int) – Factor for determining the local adaptive threshold window size

  • thresh_shift_percentage (float) – Percentage factor in [0,1] specifying the amount the threshold should be shifted

  • morph_3d (bool) – If morphological operations should be applied in 2D or 3D, default is 3D

Returns

Binary segmentation output

Return type

numpy.ndarray

bimato.core.get_edm(binary, sampling)[source]

It takes a binary image and a dictionary of sampling rates and returns the Euclidean distance map

Parameters

  • binary (numpy.ndarray) – a 3D binary array

  • sampling (dict) – a dictionary with keys ‘x’, ‘y’, and ‘z’ that contain the voxel size in each dimension

Returns

The Euclidean distance map (EDM) of the binary image.

Return type

numpy.ndarray

bimato.poresize module

The module bimato.poresize contains the complete pore-size algorithm published at https://www.nature.com/articles/s41598-019-44764-5. The most important is bimato.poresize.get_pore_sizes() and bimato.poresize.get_fiber_thickness().

See documentation for a general user guide.

bimato.poresize.calc_free_pore_space(df)[source]

Calculates the fraction of pore volume to sample volume.

Parameters

df (pandas.DataFrame) – Input DataFrame that came from initial pore detection function

Returns

Pandas Series with calculated free pore space

Return type

pandas.Series

bimato.poresize.calc_inhomogeneity(df)[source]

Calculates the inhomogeneity parameter based on sophisticated statistics and parameters, as described at https://www.frontiersin.org/articles/10.3389/fcell.2020.593879/. Takes a pandas.DataFrame that has been extended by bimato.poresize.get_fragmented_poresizes() and returns the inhomogeneity parameter of that DataFrame.

Note

This function is especially useful when combined with pandas.DataFrame.groupby() and pandas.core.groupby.GroupBy.apply() operations. See User Guide for more information.

Parameters

df – pandas.DataFrame with specific parameters calculated by bimato.poresize.get_fragmented_poresizes()

Return type

Inhomogeneity parameter

bimato.poresize.get_fiber_thickness(binary, sampling, sigma_frac=512)[source]

This function takes a binary image of a 3D biopolymer network image and returns the fiber thickness

Parameters

  • binary – The binary image containing the segmentation of fluid (=0) and polymer phase (=1)

  • sampling – The physical size of each voxel in the image

  • sigma_frac – The sigma parameter for the gaussian filter. The smaller the value, the more fibers are detected

  • optional – The sigma parameter for the gaussian filter. The smaller the value, the more fibers are detected

bimato.poresize.get_fragmented_poresizes(binary, sampling, part_size_micron, residual_pore_detection=False)[source]

Calculates fragmented pore-sizes of a sample, given the desired part size.

First, based on the given part size, the possible number of parts and their respective coordinate intervals are determined. Using the previous coordinate intervals, the binary segmentation of the original sample is split into multiple smaller samples and pore size calculations and statistics are calculated for each individual part. This is the basis for further inhomogeneity analyses, as described at https://www.frontiersin.org/articles/10.3389/fcell.2020.593879/.

The resulting pandas.DataFrame contains mainly the same columns as desccribed in bimato.poresize.get_pore_sizes(). However, it is extended by several columns containing the start and end coordinates of each part inside the original data, a unique slice-ID which can be used for example in pandas.DataFrame.groupby(), and several other data columns that are neccessary to calculate the inhomogeneity using bimato.poresize.calc_inhomogeneity().

Parameters

  • binary – The binary image containing the segmentation of fluid (=0) and polymer phase (=1)

  • sampling – The physical size of each voxel in the image

  • part_size_micron – Desired size of a single part in microns

  • residual_pore_detection – If True, the algorithm will try to detect even smaller and obscure pores

Return type

DataFrame with dedicated pore sizes and statistics for individual parts of the original sample

bimato.poresize.get_part_amount(df)[source]

Integral part of bimato.poresize.get_fragmented_poresizes(). Calculates specific parameters about the collagen content and pore sizes of each fragment.

Parameters

df – DataFrame with pore sizes

Return type

Extended DataFrame with specific parameters fundamental to the inhomogeneity calculation

bimato.poresize.get_pore_sizes(binary, sampling, sigma_frac=128, residual_pore_detection=False)[source]

This function takes a binary image of a 3D biopolymer network image and calculates the pore sizes given the pixel-micron conversion.

Parameters

  • binary – The binary image containing the segmentation of fluid (=0) and polymer phase (=1)

  • sampling – The physical size of each voxel in the image

  • sigma_frac – The sigma parameter for the gaussian filter. The smaller the value, the more pores are detected

  • optional – The sigma parameter for the gaussian filter. The smaller the value, the more pores are detected

  • residual_pore_detection – If True, the algorithm will try to detect even smaller and obscure pores

  • optional – If True, the algorithm will try to detect even smaller and obscure pores

Returns

  • A dataframe with the following columns, each row represents data for a single pore

  • x [px] (x coordinate in pixel)

  • y [px] (y coordinate in pixel)

  • z [px] (z coordinate in pixel)

  • Diameter [µm] (pore diameter)

  • Residual Degree (number of iterative pore detections, 0 for first step, 1 for second)

  • Size x [px] (total x size of 3D image)

  • Size y [px] (total y size of 3D image)

  • Size z [px] (total z size of 3D image)

  • PhysicalSize x (pixel-micron conversion factor used)

  • PhysicalSize y (pixel-micron conversion factor used)

  • PhysicalSize z (pixel-micron conversion factor used)

  • Number Of Pores (total number of detected pores in sample)

  • Cube Volume [µm³] (physical volume of 3D image)

  • Single Pore Volume [µm³] (volume of detected pore)

  • Real Pore Volume [µm³] (physical volume occupied by detected pores, without overlapping of individual pores)

  • Collagen Volume [µm³] (volume of the polymer phase)

  • Fluid Volume [µm³] (volume of the fluid phase)

  • Single Pore Volume Fraction (space occupied in relation to the sample volume)

  • Real Pore Volume Fraction (space occupied in relation to the sample volume)

  • Collagen Volume Fraction (space occupied in relation to the sample volume)

  • Fluid Volume Fraction (space occupied in relation to the sample volume)

  • Zeta Single Pores (pore diameter scaled with its corresponding column fraction)

  • Zeta Real Pores (pore diameter scaled with its corresponding column fraction)

  • Zeta Collagen (pore diameter scaled with its corresponding column fraction)

  • Zeta Fluid (pore diameter scaled with its corresponding column fraction)

  • Pseudo Pore Diameter [µm] (theoretical pore diameter calculated by assuming that all detected pores would occupy the fluid-phase fully)

bimato.network module

docstring of module

bimato.network.classify_network(skeleton)[source]

Classifies each binary fibril pixel of input skeleton depending on number of neighbouring pixels.

Class 0 is fluid phase. Class 2 is a fibril with class 1 being a fibril ending. Classes higher than 2 mean that this is a node, while denoting the number of connections outgoing.

Warning: the center pixel is always 1, so the sum of each cut out fibril environment needs to be reduced by 1

Parameters

skeleton (numpy.ndarray) – Input skeleton

Returns

Classification matrix

Return type

numpy.ndarray

bimato.network.get_edge_fibril_ids(fibril_labels)[source]
bimato.network.get_network_skeleton(binary, min_size=10)[source]

Calculates the network skeletonization of an input network binary.

Parameters

  • binary (numpy.ndarray) – Input binary segmentation of typed bool

  • min_size (int) – Minimum size of objects in px

Returns

Skeleton output

Return type

numpy.ndarray

bimato.network.get_nodes(fibril_class, se_radius=1)[source]
bimato.network.get_single_fibrils_labeled(skeleton, node_stack)[source]

Returns a label matrix with single fibrils. Each integer number in the label matrix represents pixels of a single, individual fibril.

Parameters

fibril_class (numpy.ndarray) – Matrix with classified skeleton

Returns

Labelled matrix with single fibrils

Return type

numpy.ndarray

bimato.utils module

# TODO: write helpers module docstring docstring of module

bimato.utils.calc_weighted_median(df, data_col, weight_col)[source]

Calculates the weighted median of specified DataFrame column with respect to another specified column-

Parameters

  • df (pandas.DataFrame) – Input DataFrame that came from initial pore detection function

  • data_col (str) – Name of column from which the median is calculated

  • weight_col (str) – Name of column that is used as weight

Returns

Pandas Series with calculated weighted median

Return type

pandas.Series

bimato.utils.denoise_image(image, denoise_weight=None)[source]

Apply TV-denoising on input image data. Denoising weight factor is determined automatically, except explicitly specified

Parameters

  • image (numpy.ndarray) – Input raw image data

  • denoise_weight (int or float, optional) – Weight factor for scikit image TV-denoising

Returns

Denoised image data

Return type

numpy.ndarray

bimato.utils.get_cube_size_in_micron(data_shape, sampling)[source]
bimato.utils.get_interval_list(part_size, number_parts)[source]
bimato.utils.get_intervals(data_shape, sampling, part_size_micron)[source]
bimato.utils.get_part_size_px(data_shape, nx, ny, nz)[source]
bimato.utils.get_possible_part_numbers(data_shape, sampling, part_size)[source]
bimato.utils.get_voxel_volume(sampling)[source]
bimato.utils.get_weight_factor(size)[source]

Calculates the weight factor for TV-denoising using scikit-image. Values have been determined empirically.

Notes

Formulas of fitting empirical data:

  • mean values: 3E-08x^2 + 8E-06x + 0,0037

  • more denoising: 3E-08x^2 + 6E-06x + 0,0127

  • linear fit was: 6E-05x - 0,0215

Parameters

size (int) – Relevant size of image data

Returns

TV-denoising weight factor

Return type

float

bimato.utils.normalize_image(image, scale)[source]

Standard function to normalize image data values to [0,1].

Parameters

  • image (numpy.ndarray) – Input image data

  • scale (int or float) – Scaling factor, e.g. 255 would scale to 8bit integer matrices

Returns

Normalized image data

Return type

numpy.ndarray

bimato.utils.read_lif_image(lif_image)[source]

It reads the image data from the readlif LifFile and returns it as a 3D numpy array

Parameters

lif_image (readlif.reader.LifFile) – instance of readlif LifFile

Returns

A 3D numpy array of the image data.

Return type

numpy.ndarray