objscale 0.1.0__py3-none-any.whl

objscale/__init__.py

@@ -0,0 +1,56 @@
+# objscale/__init__.py
+from ._size_distributions import (
+    finite_array_size_distribution,
+    finite_array_powerlaw_exponent,
+    array_size_distribution,
+)
+
+from ._fractal_dimensions import (
+    individual_fractal_dimension,
+    ensemble_correlation_dimension,
+    ensemble_box_dimension,
+    ensemble_coarsening_dimension,
+    total_perimeter,
+    total_number,
+    isolate_largest_structure,
+    coarsen_array,
+)
+
+from ._object_analysis import (
+    get_structure_props,
+    remove_structures_touching_border_nan,
+    label_periodic_boundaries,
+    remove_structure_holes,
+    clear_border_adjacent,
+)
+
+from ._utils import (
+    linear_regression,
+    encase_in_value,
+)
+
+__all__ = [
+    'finite_array_size_distribution',
+    'finite_array_powerlaw_exponent',
+    'array_size_distribution',
+    'individual_fractal_dimension',
+    'ensemble_correlation_dimension',
+    'ensemble_box_dimension',
+    'ensemble_coarsening_dimension',
+    'total_perimeter',
+    'total_number',
+    'isolate_largest_structure',
+    'coarsen_array',
+    'get_structure_props',
+    'remove_structures_touching_border_nan',
+    'label_periodic_boundaries',
+    'remove_structure_holes',
+    'clear_border_adjacent',
+    'linear_regression',
+    'encase_in_value',
+]
+
+__version__ = "0.1.0"
+__author__ = "Thomas DeWitt"
+__email__ = "thomas.dewitt@utah.edu"
+__description__ = "Object-based analysis functions for fractal dimensions and size distributions"

objscale/_fractal_dimensions.py

@@ -0,0 +1,632 @@
+import numpy as np
+from numba import njit, prange
+from numba.typed import List
+from scipy.ndimage import label
+from skimage.segmentation import clear_border
+from warnings import warn
+from ._object_analysis import remove_structures_touching_border_nan, remove_structure_holes
+from ._utils import linear_regression, encase_in_value
+
+
+def ensemble_correlation_dimension(arrays, x_sizes=None, y_sizes=None, middle_ninth=True, return_C_l=False, bins=None, point_reduction_factor=1):
+    """
+        Given a binary array, calculate the correlation dimension D where C_l\propto l^D
+
+        Input:
+            array: 
+                binary array to calculate correlation dimension of
+            x_sizes, y_sizes: 
+                pixel sizes in the x and y directions.
+                    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], etc, for all i
+            middle_ninth: 
+                For each pixel, only use distances between that pixel and pixels within the central 9th section of the array. This reduces boundary effects.
+            return_C_l: 
+                if True, 
+                    return dimension, error, bins, C_l
+                    else, return dimension, error
+            bins:
+                Values of l to use for the regression
+                    if None, automatically calculate as 
+                    logarithmically spaced intervals between
+                    3*minimum length and the array width or height
+            point_reduction_factor: float, >= 1
+                Draw N/point_reduction_factor circles, where N is the total number of available circles.
+                Choose the circle centers randomly. 
+
+        Output:
+            if return_C_l:
+                return dimension, error, bins, C_l
+            else:
+                return dimension, error
+    """
+    nbins = 50
+
+    if type(arrays) == np.ndarray: arrays = [arrays]
+
+    if x_sizes is None: x_sizes = np.ones(arrays[0].shape, dtype=np.float32)
+    if y_sizes is None: y_sizes = np.ones(arrays[0].shape, dtype=np.float32)
+    locations_x, locations_y = get_locations_from_pixel_sizes(x_sizes, y_sizes)
+
+    h = x_sizes.shape[0]
+    w = x_sizes.shape[1]
+
+    if middle_ninth:    # min(width, height) of middle 9th, where width, height are calculated in the center
+        maxlength = np.sqrt((locations_x[int(h/2), int(w/3)]-locations_x[int(h/2), int(2*w/3)])**2 + (locations_y[int(h/3), int(w/2)]-locations_y[int(2*h/3), int(w/2)])**2)
+    else:   # min(width, height) of entire array, where width, height are calculated in the center
+        maxlength = np.sqrt((locations_x[int(h/2), 0]-locations_x[int(h/2), w-1])**2 + (locations_y[0, int(w/2)]-locations_y[h-1, int(w/2)])**2)
+
+    minlength = 3*min(np.nanmin(x_sizes), np.nanmin(y_sizes))
+    if bins is None: bins = np.geomspace(minlength, maxlength, nbins)
+
+    C_l = np.zeros(bins.shape)
+
+    for array in arrays:
+        if np.any(array.shape != x_sizes.shape): raise ValueError(f'All arrays must be same shape as pixel sizes (currently {array.shape} and {x_sizes.shape}, respectively)')
+
+        array = array.astype(np.float16)
+
+        all_boundary_coordinates = get_coords_of_boundaries(array)
+
+        if middle_ninth:
+            middle_coordinates = all_boundary_coordinates[np.argwhere((all_boundary_coordinates[:,0]<int(2*h/3)) & (all_boundary_coordinates[:,0]>int(h/3))).flatten()]
+            middle_coordinates = middle_coordinates[np.argwhere((middle_coordinates[:,1]<int(2*w/3)) & (middle_coordinates[:,1]>int(w/3))).flatten()]
+
+            circle_centers = middle_coordinates
+        else:
+            circle_centers = all_boundary_coordinates
+
+        if point_reduction_factor>1:
+            circle_centers = circle_centers[np.random.choice(np.arange(len(circle_centers)), int(len(circle_centers)/point_reduction_factor), replace=True)]
+        elif point_reduction_factor<1: raise ValueError('point_reduction_factor must be >= 1')
+
+        C_l += correlation_integral(circle_centers, all_boundary_coordinates, locations_x, locations_y, bins)
+
+    # Perform linear regression to estimate dimension
+    x,y = np.log10(bins), np.log10(C_l)
+    index = np.isfinite(x) & np.isfinite(y)
+    if len(x[index]) <3:   
+        warn('Not enough data to estimate correlation dimension, returning nan')
+        if return_C_l:
+            return np.nan,np.nan,np.array([np.nan]),np.array([np.nan])
+        else:
+            return np.nan,np.nan
+    coefficients, cov = np.polyfit(x[index], y[index], 1, cov=True)
+    fit_error = np.sqrt(np.diag(cov))
+    dimension, error = coefficients[0], 2*fit_error[0]  # fit error is for 95% conf. int.
+
+    if return_C_l:
+        return dimension, error, bins, C_l
+    else:
+        return dimension, error
+
+
+def ensemble_box_dimension(binary_arrays, set = 'edge', min_pixels=1, min_box_size=2, box_sizes = 'default', return_values=False):
+    """
+    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.
+
+    Parameters:
+    -----------
+    binary_arrays : list of numpy.ndarray or numpy.ndarray
+        A list of 2D binary arrays or a single 2D binary array.
+    set : str, optional (default='edge')
+        Specifies which set to consider for box counting:
+        - 'edge': Box dimension of the set of boundaries between 0 and 1: Count boxes that contain at least one pixel with value 1 AND one pixel with value 0.
+        - 'ones': Box dimension of the set of values equal to 1: Count boxes that contain at least one pixel with value 1.
+    min_pixels : int, optional (default=1)
+        Largest box size, in units of the number of boxes required to cover the array in the smaller direction
+    min_box_size : int, optional (default=2)
+        Smallest box size
+    box_sizes : array-like or 'default', optional (default='default')
+        Box sizes used. If 'default', uses those powers of 2 up to 2^14 that satisfy the above criteria.
+    return_values : bool, optional (default=False)
+        If True, return additional data used in the calculation.
+
+    Returns:
+    --------
+    float
+        The estimated box-counting dimension.
+    float
+        The error of the estimate.
+    tuple, optional
+        If return_values is True, also returns:
+        box_sizes
+        mean_number_boxes
+
+    Raises:
+    -------
+    ValueError
+        If an unsupported value is provided for 'set' or 'upscale_factors'.
+        If an array contains nan values
+
+    Notes:
+    ------
+    The function uses linear regression on log-log plot of box counts vs. scale
+    to estimate the box-counting dimension. The slope of this regression gives
+    the negative of the box-counting dimension.
+
+    """
+
+    if type(binary_arrays) == np.ndarray: binary_arrays = [binary_arrays]
+
+    if type(box_sizes) == str:    # to not try elementwise comparison
+        if box_sizes != 'default': raise ValueError(f'upscale_factors={box_sizes} not supported')
+        
+        box_sizes = 2**np.arange(1,15)    # assumed any array is smaller than 32768 pixels
+    else: box_sizes = np.array(box_sizes)
+    
+    max_upscale_factor = min(binary_arrays[0].shape)/min_pixels
+    box_sizes = box_sizes[box_sizes<=max_upscale_factor]
+    box_sizes = box_sizes[box_sizes>=min_box_size]
+
+    mean_number_boxes = np.empty((0,box_sizes.size), dtype=np.float32)
+    
+    for array in binary_arrays:
+        number_boxes = []
+        if np.count_nonzero(np.isnan(array))>0: raise ValueError('array has nan values')
+        for factor in box_sizes:
+
+            # Upscale
+            upscaled_array = encase_in_value(coarsen_array(array, factor), np.nan)
+            
+            # Count boxes
+            if set == 'edge':
+                nboxes = np.count_nonzero((upscaled_array>0) & (upscaled_array<1))
+            elif set == 'ones':
+                nboxes = np.count_nonzero(upscaled_array>0)
+            else: raise ValueError(f'set={set} not supported (supported values are "edge" or "ones")')
+
+            number_boxes.append(nboxes)
+
+        mean_number_boxes = np.append(mean_number_boxes, [number_boxes], axis=0)
+
+    mean_number_boxes = np.mean(mean_number_boxes, axis=0)
+    mean_number_boxes[mean_number_boxes==0] = np.nan # eliminate warning when logging 0
+
+    (slope, _), (error,_) = linear_regression(np.log10(box_sizes), np.log10(mean_number_boxes))
+
+    if return_values: return -slope, error, box_sizes, mean_number_boxes
+    return -slope, error
+
+
+def ensemble_coarsening_dimension(arrays, x_sizes=None, y_sizes=None, cloudy_threshold=0.5, min_pixels=30, return_values=False, upscale_factors = 'default', count_exterior=False):
+    """
+        Given a list of 2-D arrays, calculate the ensemble fractal dimension by 
+        coarsening the resolution and calculating the total perimeter as a function of resolution.
+
+        Input:
+            arrays: array, or list of arrays, to upscale, apply cloudy_thresh to make binary, then calculate total perimeter
+            min_pixels: limit the upscale factors such that upscaled matrices always have shape >= (min_pixels, min_pixels)
+            return_values: if True, return (D_e, error), (upscale_factors, mean_total_perimeters)
+            x_sizes, y_sizes: Pixel sizes in the x and y directions. 
+                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], etc, for all i
+        return: 
+            D_e, error (95% conf)
+            if return_values: D_e, error, upscale_factors, mean_total_perimeters
+    """
+    if type(arrays) == np.ndarray: arrays = [arrays]
+    if x_sizes is None: x_sizes = np.ones(arrays[0].shape, dtype=bool)
+    if y_sizes is None: y_sizes = np.ones(arrays[0].shape, dtype=bool)
+
+    if type(upscale_factors) == str:    # to not try elementwise comparison
+        if upscale_factors != 'default': raise ValueError(f'upscale_factors={upscale_factors} not supported')
+        if np.count_nonzero((arrays[0]<1) & (arrays[0]>0))==0:
+            # If a binary array, even upscale factors can be ambiguous because sometimes the superpixel is half cloudy. In this case, use the following
+            upscale_factors = 3**np.arange(0,10)
+        else:
+            # Otherwise, use more upscale factors:
+            upscale_factors = 2**np.arange(0,15)
+    else: upscale_factors = np.array(upscale_factors)
+    
+    max_upscale_factor = min(arrays[0].shape)/min_pixels
+    upscale_factors = upscale_factors[upscale_factors<=max_upscale_factor]
+
+    mean_total_perimeters = np.empty((0,upscale_factors.size), dtype=np.float32)
+    
+    for i in range(len(arrays)):
+        array = arrays[i]
+        if type(x_sizes) == list:
+            xs = x_sizes[i]
+        else:
+            xs = x_sizes
+        if type(y_sizes) == list:
+            ys = y_sizes[i]
+        else:
+            ys = y_sizes
+
+        total_perimeters = []
+        for factor in upscale_factors:
+
+            # Upscale
+            upscaled_array = encase_in_value(coarsen_array(array, factor), np.nan)
+            upscaled_x_sizes = factor*encase_in_value(coarsen_array(xs, factor), 0)    # the value appended here is irrelevant since the array is 0 here, just to make the shape the same
+            upscaled_y_sizes = factor*encase_in_value(coarsen_array(ys, factor), 0)    # the value appended here is irrelevant since the array is 0 here, just to make the shape the same
+
+            nanmask = (np.isnan(upscaled_array) | np.isnan(upscaled_x_sizes) | np.isnan(upscaled_y_sizes))
+            # Make binary
+            upscaled_array_binary = (upscaled_array>cloudy_threshold).astype(np.float32)
+
+            # To not count exterior perimeter, set to nan, to count it, set to 0
+            if count_exterior: padding = 0
+            else: padding = np.nan
+            upscaled_array_binary[nanmask] = padding
+
+            total_p = total_perimeter(upscaled_array_binary, upscaled_x_sizes, upscaled_y_sizes)
+            total_perimeters.append(total_p)
+        mean_total_perimeters = np.append(mean_total_perimeters, [total_perimeters], axis=0)
+
+    mean_total_perimeters = np.mean(mean_total_perimeters, axis=0)
+    mean_total_perimeters[mean_total_perimeters==0] = np.nan # eliminate warning when logging 0
+
+    (slope, _), (error,_) = linear_regression(np.log10(upscale_factors), np.log10(mean_total_perimeters))
+    if return_values: return 1-slope, error, upscale_factors, mean_total_perimeters
+
+    return 1-slope, error
+
+
+def individual_fractal_dimension(arrays, x_sizes=None, y_sizes=None, min_a=10, max_a=np.inf, return_values=False):
+    """
+        Calculate the individual fractal dimension Df of objects within arrays. 
+
+        The method is by a linear regression to log a vs. log p, where a and p 
+        are calculated not including structure holes, and omitting structures touching the array edge.
+
+
+        Input:
+            arrays: list of boolean 2D np.ndarrays
+            min_a, max_a: use structure areas within these bounds to calculate Df
+            return_values: if True, return (Df, err), (log10(sqrt(a)), log10(p))
+            x_sizes, y_sizes: Pixel sizes in the x and y directions. 
+                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], etc, for all i
+        Output:
+            Df, uncertainty (95% conf)
+            if return_values: Df, err, log10_sqrt(a), log10(p)
+
+    """
+    from ._object_analysis import get_structure_props
+
+    areas, perimeters = [], []
+    if (type(arrays) != list): arrays = [arrays]
+
+    if x_sizes is None: x_sizes = np.ones_like(arrays[0])
+    if y_sizes is None: y_sizes = np.ones_like(arrays[0])
+
+    for i in range(len(arrays)):
+        array = arrays[i]
+        if type(x_sizes) == list:
+            xs = x_sizes[i]
+        else:
+            xs = x_sizes
+        if type(y_sizes) == list:
+            ys = y_sizes[i]
+        else:
+            ys = y_sizes
+
+        if np.any(array.shape != xs.shape): raise ValueError('Each array shape must match corresponding pixel sizes shape')
+            
+        array = remove_structures_touching_border_nan(array)
+        array = remove_structure_holes(array)
+        new_p, new_a, _, _ = get_structure_props(array, xs, ys)
+        areas.extend(new_a)
+        perimeters.extend(new_p)
+
+    areas, perimeters = np.array(areas), np.array(perimeters)
+    areas, perimeters = areas[(areas>min_a) & (areas<max_a)], perimeters[(areas>min_a) & (areas<max_a)]
+
+    (slope, _), (err, _) = linear_regression(np.log10(np.sqrt(areas)), np.log10(perimeters))
+
+    if return_values: return slope, err, np.log10(np.sqrt(areas)), np.log10(perimeters)
+    else: return slope, err
+
+
+# Helper functions for fractal dimension calculations
+
+def get_coords_of_boundaries(array):
+    """
+        Find coordinates of pixels of value 1 that are adjacent to pixels of value 0
+        Input: 
+            -array: 2-D binary np.ndarray
+        Output: 
+            np.ndarray of shape(n_boundaries, 2)
+                where each element is a pair of indicies corresponding to the locations
+                of pixels with value 1 that are adjacent to a pixel of value 0
+                
+        Note:  
+            Topology is toroidal, so pixels on one edge are considered adjacent to pixels
+            on the opposite edge.
+        Example:
+
+            array1 = np.zeros((10,10))
+            array1[6:8,6:8] = 1
+            array1[3:4,2:5] = 1
+            array2 = np.zeros((10,10))
+            for i,j in get_coords_of_boundaries(array1):
+                array2[i,j] = 1
+            print(np.all(array2==array1))
+
+            >>> True
+    """
+    array = array.astype(np.int16)
+    shifted_right = np.roll(array, shift=1, axis=1)
+    shifted_down = np.roll(array, 1, axis=0)
+    diff_right = shifted_right-array
+    diff_down = shifted_down-array
+
+    right_side_of_pixel = np.argwhere(diff_right==1)
+    right_side_of_pixel[:,1] -= 1
+    left_side_of_pixel = np.argwhere(diff_right==-1)
+    bottom_of_pixel = np.argwhere(diff_down==1)
+    bottom_of_pixel[:,0] -= 1
+    top_of_pixel = np.argwhere(diff_down==-1)
+
+    all_coords = np.append(right_side_of_pixel, left_side_of_pixel, axis=0)
+    all_coords = np.append(all_coords, top_of_pixel, axis=0)
+    all_coords = np.append(all_coords, bottom_of_pixel, axis=0)
+
+    # remove duplicates
+    all_coords = np.unique(all_coords, axis=0)
+
+    return all_coords
+
+
+def get_locations_from_pixel_sizes(pixel_sizes_x, pixel_sizes_y):
+    return np.nancumsum(pixel_sizes_x, 1), np.nancumsum(pixel_sizes_y, 0)
+
+
+@njit(parallel=True)
+def correlation_integral(coordinates_to_check, coordinates_to_count, locations_x, locations_y, bins):
+    """
+        Input:
+            coordinatess: np array of coordinates of boundaries of shape
+                            [[x1,y2],
+                             [x2,y2],
+                             [x3,y3],
+                             ...
+                             ]
+            locations_x, locations_y: locations of each pixel. 
+                For example, np.sqrt((locations_x[i,j]-locations_x[p,q])**2 + (locations_y[i,j]-locations_y[p,q])**2)
+                should represent the physical distance between pixel locations at i,j and p,q
+            bins: np 1-D array of distances to bin
+        Output:
+            of same shape as bins
+        For each coordinates_to_check:
+            Calculate how many coordinates_to_count are less than a distance bin_i of the chosen coord, for each bin_i in bin.
+    """
+    C_l = np.zeros(bins.shape)  # will be count
+    
+    for i in prange(coordinates_to_check.shape[0]):
+        for j in range(coordinates_to_count.shape[0]):
+            p,q = coordinates_to_check[i]
+            r,s = coordinates_to_count[j]
+        
+            dx = (locations_x[p,q]-locations_x[r,s])
+            dy = (locations_y[p,q]-locations_y[r,s])
+            
+            distance = np.sqrt((dx**2)+(dy**2))
+            for bin_index, bin in enumerate(bins):
+                if distance<bin: C_l[bin_index] += 1
+    return C_l
+
+
+def coarsen_array(array, factor):
+    """
+    Coarsen a given array by a specified factor by averaging along both dimensions.
+
+    This function takes an input array and reduces it by a given factor along both the x and y dimensions. The
+    upscaling is achieved by summing 'superpixel' regions of the original array and dividing by the square of the
+    scaling factor. Optionally, the resulting upscaled array can be thresholded to create a binary array, where
+    values above 0.5 are set to 1 and values below or equal to 0.5 are set to 0.
+
+    Args:
+        array (numpy.ndarray): The input array to be upscaled.
+        factor (int): The scaling factor for enlarging the array. Must be a positive integer.
+
+    Returns:
+        numpy.ndarray: The upscaled array.
+
+    Raises:
+        ValueError: If an even scaling factor is provided while attempting to create a binary array, as this may lead
+            to rounding issues.
+
+    Example:
+        original_array = np.array([[1, 2],
+                                    [3, 4]])
+        coarsened = coarsen_array(original_array, factor=2)
+        # Resulting coarsened array:
+        # array([2.5])
+
+    """
+
+    upscaled_array = np.add.reduceat(array, np.arange(array.shape[0], step=factor), axis=0)     # add points in x direction
+    upscaled_array = np.add.reduceat(upscaled_array, np.arange(array.shape[1], step=factor), axis=1)     # add points in y direction
+
+    # The number of pixels that are upscaled is usually factor**2, but not for edge superpixels if the factor does not evenly divide into array size. Solution:
+    pixel_counts = np.add.reduceat(np.ones(array.shape), np.arange(array.shape[0], step=factor), axis=0)     # add points in x direction
+    pixel_counts = np.add.reduceat(pixel_counts, np.arange(array.shape[1], step=factor), axis=1)     # add points in y direction
+
+    upscaled_array = upscaled_array/pixel_counts
+
+    return upscaled_array
+
+
+@njit()
+def total_perimeter(array, x_sizes, y_sizes):
+    """
+        Given a binary array, calculate the total perimeter. Boundary conditions are assumed periodic. 
+        Only counts perimeter along edges between 1 and 0. (so that for different b.c. the array could be encased in any other value)
+        Assumes periodic B.C.; for something else, padd inputs with 0s or nans.
+
+        Raises ValueError if x_sizes or y_sizes is nan where array is 1
+    """
+    perimeter = 0
+    for (i, j), value in np.ndenumerate(array):
+        if value == 1:
+            if np.isnan(x_sizes[i,j]) or np.isnan(y_sizes[i,j]): 
+                raise ValueError('x_sizes or y_sizes is nan where array is 1')
+            if i != array.shape[0]-1 and array[i+1, j] == 0: perimeter += x_sizes[i,j]
+            elif i == array.shape[0]-1 and array[0, j] == 0: perimeter += x_sizes[i,j]
+
+            if i != 0 and array[i-1, j] == 0: perimeter += x_sizes[i,j]
+            elif i == 0 and array[array.shape[0]-1, j] == 0: perimeter += x_sizes[i,j]
+
+            if j != array.shape[1]-1 and array[i, j+1] == 0: perimeter += y_sizes[i,j]
+            elif j == array.shape[1]-1 and array[i, 0] == 0: perimeter += y_sizes[i,j]
+
+            if j != 0 and array[i, j-1] == 0: perimeter += y_sizes[i,j]
+            elif j == 0 and array[i, 0] == 0: perimeter += y_sizes[i,j]
+
+    return perimeter
+
+
+def total_number(array, structure = np.array([[0, 1, 0], [1, 1, 1], [0, 1, 0]])):
+    """
+        Given a 2-D array with 0's, nans, and 1's, calculate number of objects of connected 1's where connectivity is defined by structure
+    """
+    array_copy = array.copy()
+    array_copy[np.isnan(array_copy)] = 0
+    _, n_structures = label(array_copy.astype(bool), structure, output=np.float32)
+    return n_structures
+
+
+def isolate_largest_structure(binary_array, structure=np.array([[0, 1, 0], [1, 1, 1], [0, 1, 0]])):
+
+    labelled_array = label(binary_array, structure)[0]
+    cloud_values = labelled_array[labelled_array!= 0] # remove background
+    values, counts = np.unique(cloud_values, return_counts=True)
+    most_common = values[np.argmax(counts)]
+    return labelled_array == most_common
+
+
+def label_size(array, variable='area',wrap='both', x_sizes=None, y_sizes=None):
+    """
+        Input:
+            array - Binary array of strc: 2-d np.ndarray, padded with 0's or np.nan's
+            variable - 'area', 'perimeter', 'width', 'height'
+                        What variable to use for 'size'
+            x_sizes, y_sizes - 2-D np.ndarray of pixel sizes in the x and y directions
+            wrap = None, 'sides', 'both': 
+                if 'sides', connect structures that span the left/right edge
+                if 'both', connect structures that span the left/right edge and top/bottom edge
+        Output:
+            labelled_array, total_P
+            : label where structures are labelled with their perimeter, and the background is 0
+
+        Note: if x_sizes or y_sizes are not uniform, the width will be the sum of the average pixel widths of the pixels in the column and in the object.
+        Similarly, the height will be the sum of the average pixel heights of the pixels in the row and in the object.
+        Given a array and the sizes of each pixel in each direction, calculate properties of structures. 
+        Any perimeter between structure and nan is not counted. 
+    """
+    from ._object_analysis import label_periodic_boundaries
+
+    labelled_array, n_structures = label(array.astype(bool), output=np.float32)      # creates array where every unique structure is composed of a unique number, 1 to n_structures
+
+    if variable not in ['area', 'perimeter', 'width', 'height']:
+        raise ValueError(f'variable={variable} not supported (supported values are "area", "perimeter", "width", "height")')
+
+    if x_sizes is None:
+        x_sizes = np.ones_like(labelled_array)
+    if y_sizes is None:
+        y_sizes = np.ones_like(labelled_array)
+
+    if wrap is None: pass
+    elif wrap == 'sides':
+        # set those on right to the same i.d. as those on left
+        for j,value in enumerate(labelled_array[:,0]):
+            if value != 0:
+                if labelled_array[j, labelled_array.shape[1]-1] != 0 and labelled_array[j, labelled_array.shape[1]-1] != value:
+                    # want not a structure and not already changed
+                    labelled_array[labelled_array == labelled_array[j, labelled_array.shape[1]-1]] = value  # set to same identification number
+    
+    if wrap is None: pass
+    elif wrap == 'both' or wrap == 'sides': 
+        labelled_array = label_periodic_boundaries(labelled_array, wrap)
+    else: raise ValueError(f'wrap={wrap} not supported')
+
+    # Flatten arrays to find their indices.
+    values = np.sort(labelled_array.flatten())
+    original_locations = np.argsort(labelled_array.flatten())  # Get indices where the original values were
+    indices_2d = np.array(np.unravel_index(original_locations, labelled_array.shape)).T    # convert flattened indices to 2-d
+    
+    labelled_array[np.isnan(array)] = np.nan      # Turn this back to nan so perimeter along it is not included
+    split_here = np.roll(values, shift=-1)-values   # Split where the values changed.
+    split_here[-1] = 0                  # Last value rolled over from first
+
+    separated_structure_indices = np.split(indices_2d, np.where(split_here!=0)[0]+1)
+    separated_structure_indices = separated_structure_indices[1:]   # Remove the locations that were 0 (not structure)
+    if len(separated_structure_indices) == 0: return np.zeros(array.shape),0
+
+    labelled_with_sizes = np.zeros(array.shape, dtype=int)
+
+    # must use numba.typed.List here for some reason https://numba.readthedocs.io/en/stable/reference/pysupported.html#feature-typed-list   
+    labelled_with_sizes = _label_size_helper(labelled_array, List(separated_structure_indices), labelled_with_sizes, variable, x_sizes, y_sizes) 
+    return labelled_with_sizes
+
+
+@njit()
+def _label_size_helper(labelled_array, separated_structure_indices, labelled_with_sizes, variable, x_sizes, y_sizes):
+    
+    for indices in separated_structure_indices:
+        perimeter = 0
+        area = 0
+
+        y_coords_structure = np.array([c[0] for c in indices])
+        x_coords_structure = np.array([c[1] for c in indices])
+        unique_y_coords = []
+        unique_x_coords = []
+        height = 0
+        width = 0
+
+        for (i,j) in indices:
+            # Height, Width
+            if i not in unique_y_coords:
+                unique_y_coords.append(i)
+                mask = (y_coords_structure==i)
+                y_sizes_here = []
+                for loc,take in enumerate(mask):
+                    if take: y_sizes_here.append(y_sizes[y_coords_structure[loc],x_coords_structure[loc]])
+                y_sizes_here = np.array(y_sizes_here)
+                height += np.mean(y_sizes_here)
+            if j not in unique_x_coords:
+                unique_x_coords.append(j)
+                mask = (x_coords_structure==j)
+                x_sizes_here = []
+                for loc,take in enumerate(mask):
+                    if take: x_sizes_here.append(x_sizes[y_coords_structure[loc],x_coords_structure[loc]])
+                x_sizes_here = np.array(x_sizes_here)
+                width += np.mean(x_sizes_here)
+
+            # Perimeter:
+            if i != labelled_array.shape[0]-1 and labelled_array[i+1, j] == 0: perimeter += x_sizes[i,j]
+            elif i == labelled_array.shape[0]-1 and labelled_array[0, j] == 0: perimeter += x_sizes[i,j]
+
+            if i != 0 and labelled_array[i-1, j] == 0: perimeter += x_sizes[i,j]
+            elif i == 0 and labelled_array[labelled_array.shape[0]-1, j] == 0: perimeter += x_sizes[i,j]
+
+            if j != labelled_array.shape[1]-1 and labelled_array[i, j+1] == 0: perimeter += y_sizes[i,j]
+            elif j == labelled_array.shape[1]-1 and labelled_array[i, 0] == 0: perimeter += y_sizes[i,j]
+
+            if j != 0 and labelled_array[i, j-1] == 0: perimeter += y_sizes[i,j]
+            elif j == 0 and labelled_array[i, 0] == 0: perimeter += y_sizes[i,j]
+
+            # Area:
+            area += y_sizes[i,j] * x_sizes[i,j]
+        for (i,j) in indices:
+            if variable == 'perimeter':
+                labelled_with_sizes[i,j] = perimeter
+            elif variable == 'area':
+                labelled_with_sizes[i,j] = area
+            elif variable == 'width':
+                labelled_with_sizes[i,j] = width
+            elif variable == 'height':
+                labelled_with_sizes[i,j] = height
+        
+
+    return labelled_with_sizes