Size Distributions

Functions for calculating size distributions with finite domain corrections.

objscale.finite_array_powerlaw_exponent(arrays: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | list[ndarray[tuple[int, ...], dtype[_ScalarType_co]]], variable: str, x_sizes: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | list[ndarray[tuple[int, ...], dtype[_ScalarType_co]]] | None = None, y_sizes: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | list[ndarray[tuple[int, ...], dtype[_ScalarType_co]]] | None = None, bins: int | ndarray[tuple[int, ...], dtype[_ScalarType_co]] = 100, min_threshold: float = 10, truncation_threshold: float = 0.5, min_count_threshold: int = 30, return_counts: bool = False) → tuple[float, float] | tuple[tuple[float, float], tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]]]

Calculate the power-law exponent for size distributions of structures.

Calculates the power-law exponent for a list of binary arrays, where ‘size’ phi can be summed perimeter, area, length, or width:

n(phi) ∝ phi^{-(1+exponent)}

Works for binary arrays and also for binary arrays where the data boundary is demarcated by nans. This enables the domain boundary to be an arbitrary shape, rather than be rectangular.

Parameters:

• arrays (np.ndarray or list of np.ndarray) – 2-D arrays where objects of interest have value 1, the background has value 0, and no data has np.nan. Interior nans are treated like 0’s, except the perimeter along them is not counted.

• variable (str) – Object attribute to bin by. Options: 'area', 'summed perimeter', 'nested perimeter', 'height', 'width'. See Notes for definitions. 'perimeter' is accepted but deprecated.

• 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].

• bins (int or array-like, default=100) – If int, auto calculate bin locations and make that number of bins. If 1-D array: use these as log10(bin edges). They must be uniformly logarithmically spaced. If using per-array x_sizes/y_sizes lists with very different overall scales, prefer explicit bins.

• min_threshold (float, default=10) – Smallest bin edge. If bin edges are passed, this arg is ignored.

• truncation_threshold (float, default=0.5) – Float between 0 and 1. Bins with a larger fraction of truncated objects than this are omitted from the regression.

• min_count_threshold (int, default=30) – Omit any bin with counts fewer than this value from the linear regression.

• return_counts (bool, default=False) – If True, also return the bin middles and counts used in the regression.

Returns:

• exponent (float) – The power-law exponent.

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

• log_bin_middles (np.ndarray, optional) – Log10 of bin middle values. Only returned if return_counts=True.

• log_counts (np.ndarray, optional) – Log10 of counts used in regression. Only returned if return_counts=True.

Notes

Variable definitions:

• ‘summed perimeter’: Sum of pixel edge lengths between all pixels within a structure and neighboring values of 0. Does not include perimeter adjacent to a nan. A donut shaped structure returns a single value.

• ‘nested perimeter’: Sum of pixel edge lengths between all pixels that are between a structure and a neighboring region of 0s. Does not include perimeter adjacent to a nan. A donut shaped structure returns two values.

• ‘area’: Sum of individual pixel areas constituting the structure.

• ‘length’ or ‘width’: Overall distance between the farthest two points in a structure in the x- or y- direction.

objscale.finite_array_size_distribution(arrays: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | list[ndarray[tuple[int, ...], dtype[_ScalarType_co]]], variable: str, x_sizes: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | list[ndarray[tuple[int, ...], dtype[_ScalarType_co]]] | None = None, y_sizes: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | list[ndarray[tuple[int, ...], dtype[_ScalarType_co]]] | None = None, bins: int | ndarray[tuple[int, ...], dtype[_ScalarType_co]] = 100, bin_logs: bool = True, min_threshold: float = 10, truncation_threshold: float = 0.5) → tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]], int]

Calculate size distributions for structures within binary arrays.

Returns the size distributions for truncated objects and nontruncated objects and the index where truncated objects begin to dominate. Works for binary arrays and also for binary arrays where the data boundary is demarcated by nans, enabling the domain boundary to be an arbitrary shape.

Parameters:

• arrays (np.ndarray or list of np.ndarray) – 2-D arrays where objects of interest have value 1, background has value 0, and no data has np.nan. Interior nans are treated like 0’s, except the perimeter along them is not counted.

• variable (str) – Object attribute to bin by. Options: 'area', 'summed perimeter', 'nested perimeter', 'height', 'width'. See Notes for definitions. 'perimeter' is accepted but deprecated.

• 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].

• bins (int or array-like, default=100) – If int, auto calculate bin locations and make that number of bins. If 1-D array: use these as bin edges or log10(bin edges). They must be uniformly linearly or logarithmically spaced (depending on bin_logs). If using per-array x_sizes/y_sizes lists with very different overall scales, pass explicit bins to avoid auto-bin ranges being dominated by the first array.

• bin_logs (bool, default=True) – If True, bin log10(variable) into logarithmically-spaced bins. If False, bin variable into linearly spaced bins.

• min_threshold (float, default=10) – Smallest bin edge. If bin edges are passed, this arg is ignored.

• truncation_threshold (float, default=0.5) – Float between 0 and 1. Bins with a larger fraction of truncated objects than this are omitted from the regression.

Returns:

• bin_middles (np.ndarray) – Bin middle values. If bin_logs is True, this is actually log10(bin_middles).

• nontruncated_counts (np.ndarray) – Counts of non-truncated objects in each bin.

• truncated_counts (np.ndarray) – Counts of truncated objects in each bin.

• truncation_index (int) – Index where truncated objects begin to dominate.

Notes

Variable definitions:

• ‘summed perimeter’: Sum of pixel edge lengths between all pixels within a structure and neighboring values of 0. Does not include perimeter adjacent to a nan. A donut shaped structure returns a single value.

• ‘nested perimeter’: Sum of pixel edge lengths between all pixels that are between a structure and a neighboring region of 0s. Does not include perimeter adjacent to a nan. A donut shaped structure returns two values: one for the inner circle and one for the outer.

• ‘area’: Sum of individual pixel areas constituting the structure.

• ‘length’ or ‘width’: Overall distance between the farthest two points in a structure in the x- or y- direction.

objscale.array_size_distribution(array: ndarray[tuple[int, ...], dtype[_ScalarType_co]], variable: str = 'area', bins: int | ndarray[tuple[int, ...], dtype[_ScalarType_co]] = 30, bin_logs: bool = True, structure: ndarray[tuple[int, ...], dtype[_ScalarType_co]] = array([[0, 1, 0], [1, 1, 1], [0, 1, 0]]), wrap: str | None = None, x_sizes: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, y_sizes: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None) → tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]]

Calculate size distribution for a single binary array.

Given a single binary array, calculate contiguous object sizes and compute a size distribution.

Warning

This function does not account for bias arising from object truncation by the domain edge. Prefer finite_array_* functions for most purposes.

Parameters:

• array (np.ndarray) – 2-D array where objects of interest have value 1, the background has value 0, and no data has np.nan. Nans are treated like 0’s, except the perimeter along them is not counted.

• variable (str, default='area') – Object attribute to bin by. Options: 'area', 'summed perimeter', 'nested perimeter', 'height', 'width'. See Notes for definitions. 'perimeter' is accepted but deprecated.

• bins (int or array-like, default=30) – If int, auto calculate bin locations and make that number of bins. If 1-D array: use these as bin edges.

• bin_logs (bool, default=True) – If True, bin log10(variable), else bin variable linearly.

• structure (np.ndarray, default=np.array([[0, 1, 0], [1, 1, 1], [0, 1, 0]])) – 3x3 array defining object connectivity.

• wrap (str or None, default=None) – Boundary wrapping options: None, ‘sides’, ‘both’. If ‘sides’, connect structures that span the left/right edge. If ‘both’, connect structures that span all edges.

• x_sizes (np.ndarray, optional) – Pixel sizes in x direction. If None, assume all lengths are 1.

• y_sizes (np.ndarray, optional) – Pixel sizes in y direction. If None, assume all lengths are 1.

Returns:

• bin_middles (np.ndarray) – Bin middle values. If bin_logs is True, these are log10(bin values).

• counts (np.ndarray) – Counts in each bin.

Raises:

ValueError – If variable is not one of the supported options.

Notes

Variable definitions:

• ‘summed perimeter’: Sum of pixel edge lengths between all pixels within a structure and neighboring values of 0. Does not include perimeter adjacent to a nan. A donut shaped structure returns a single value.

• ‘nested perimeter’: Sum of pixel edge lengths between all pixels that are between a structure and a neighboring region of 0s. Does not include perimeter adjacent to a nan. A donut shaped structure returns two values.

• ‘area’: Sum of individual pixel areas constituting the structure.

• ‘length’ or ‘width’: Overall distance between the farthest two points in a structure in the x- or y- direction.