Fractal Dimensions

Functions for calculating fractal dimensions of objects and object ensembles.

objscale.individual_fractal_dimension(arrays, x_sizes=None, y_sizes=None, min_a=10, max_a=inf, return_values=False)[source]

Calculate the individual fractal dimension Df of objects within arrays.

The method uses linear regression on log a vs. log p, where a and p are calculated not including structure holes, and omitting structures touching the array edge.

Parameters:

  • arrays (list of np.ndarray) – List of boolean 2D arrays.

  • x_sizes (np.ndarray or list, optional) – Pixel sizes in the x direction. If None, assume all pixel dimensions are 1. If np.ndarray, use these for each array in ‘arrays’. If list, assume x_sizes[i] corresponds to arrays[i].

  • y_sizes (np.ndarray or list, optional) – Pixel sizes in the y direction. If None, assume all pixel dimensions are 1. If np.ndarray, use these for each array in ‘arrays’. If list, assume y_sizes[i] corresponds to arrays[i].

  • min_a (float, default=10) – Minimum structure area to include in calculation.

  • max_a (float, default=np.inf) – Maximum structure area to include in calculation.

  • return_values (bool, default=False) – If True, return (Df, err), (log10(sqrt(a)), log10(p)).

Returns:

  • Df (float) – The individual fractal dimension.

  • uncertainty (float) – Uncertainty estimate (95% confidence).

  • log10_sqrt_a (np.ndarray, optional) – Log10 of sqrt(area) values. Only returned if return_values=True.

  • log10_p (np.ndarray, optional) – Log10 of perimeter values. Only returned if return_values=True.

objscale.ensemble_correlation_dimension(arrays, x_sizes=None, y_sizes=None, minlength='auto', maxlength='auto', interior_circles_only=True, return_C_l=False, bins=None, point_reduction_factor=1, nbins=50)[source]

Calculate the correlation dimension D where C_l ∝ l^D for binary arrays.

Requires that each array has the same pixel sizes, although across the array they may be nonuniform (e.g. increasing from left to right)

Note that the resulting dimension is for the set of object edge points.

Parameters:

  • arrays (list or np.ndarray) – List of binary arrays to calculate correlation dimension of.

  • x_sizes (np.ndarray or list, optional) – Pixel sizes in the x direction. If None, assume all pixel dimensions are 1. If np.ndarray, use these for each array in ‘arrays’. If list, assume x_sizes[i] corresponds to arrays[i].

  • y_sizes (np.ndarray or list, optional) – Pixel sizes in the y direction. If None, assume all pixel dimensions are 1. If np.ndarray, use these for each array in ‘arrays’. If list, assume y_sizes[i] corresponds to arrays[i].

  • minlength (str or float, default='auto') – Minimum length scale for correlation calculation. If ‘auto’, uses 3 times the minimum pixel size.

  • maxlength (str or float, default='auto') – Maximum length scale for correlation calculation. If ‘auto’, uses 0.1 times the minimum array dimension.

  • interior_circles_only (bool, default=True) – If True, only use circle centers that are at least maxlength distance from all array edges to avoid boundary effects. In other words, only use circles that are fully contained within the array. Recommended!

  • return_C_l (bool, default=False) – If True, return dimension, error, bins, C_l. Otherwise, return dimension, error.

  • bins (None, int, or array-like, optional) –

    Values of l to use for the regression. Can be: - None: automatically calculate as logarithmically spaced intervals between

    3*minimum length and the array width or height using nbins points

    • int: number of logarithmically spaced bins to generate automatically

    • array-like: explicit bin edges to use

  • point_reduction_factor (float, default=1) – Draw N/point_reduction_factor circles, where N is the total number of available circles. Choose the circle centers randomly. Must be >= 1.

  • nbins (int, default=50) – Number of bins to use when bins=None or when bins is an int. Only used for automatic bin generation.

Returns:

  • dimension (float) – The correlation dimension.

  • error (float) – Error estimate for the dimension.

  • bins (np.ndarray, optional) – The bins used for calculation. Only returned if return_C_l=True.

  • C_l (np.ndarray, optional) – The correlation integral values. Only returned if return_C_l=True.

objscale.ensemble_box_dimension(binary_arrays, set='edge', min_pixels=1, min_box_size=2, box_sizes='default', return_values=False)[source]

Calculate the ensemble box-counting dimension of binary arrays.

This function estimates the box-counting dimension (also known as Minkowski-Bouligand dimension) for a list of binary arrays. It averages the results across multiple arrays.

objscale.ensemble_coarsening_dimension(arrays, x_sizes=None, y_sizes=None, cloudy_threshold=0.5, min_pixels=30, return_values=False, coarsening_factors='default', count_exterior=False)[source]

Calculate the ensemble fractal dimension by coarsening resolution and calculating total perimeter.

Parameters:

  • arrays (np.ndarray or list of np.ndarray) – Array, or list of arrays, to coarsen, apply cloudy_threshold to make binary, then calculate total perimeter.

  • x_sizes (np.ndarray or list, optional) – Pixel sizes in the x direction. If None, assume all pixel dimensions are 1. If np.ndarray, use these for each array in ‘arrays’. If list, assume x_sizes[i] corresponds to arrays[i].

  • y_sizes (np.ndarray or list, optional) – Pixel sizes in the y direction. If None, assume all pixel dimensions are 1. If np.ndarray, use these for each array in ‘arrays’. If list, assume y_sizes[i] corresponds to arrays[i].

  • cloudy_threshold (float, default=0.5) – Threshold for making arrays binary.

  • min_pixels (int, default=30) – Limit the coarsening factors such that coarsened matrices always have shape >= (min_pixels, min_pixels).

  • return_values (bool, default=False) – If True, return (D_e, error), (coarsening_factors, mean_total_perimeters).

  • coarsening_factors (str or array-like, default='default') – Coarsening factors to use. If ‘default’, automatically determined.

  • count_exterior (bool, default=False) – Whether to count exterior perimeter.

Returns:

  • D_e (float) – The ensemble fractal dimension.

  • error (float) – Error estimate (95% confidence).

  • coarsening_factors (np.ndarray, optional) – The coarsening factors used. Only returned if return_values=True.

  • mean_total_perimeters (np.ndarray, optional) – Mean total perimeters. Only returned if return_values=True.