objscale 0.2.2__tar.gz → 1.0.0__tar.gz

{objscale-0.2.2 → objscale-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: objscale
-Version: 0.2.2
+Version: 1.0.0
 Summary: Object-based analysis functions for fractal dimensions and size distributions
 Author-email: Thomas DeWitt <thomas.dewitt@utah.edu>
 License: MIT
@@ -39,6 +39,9 @@ Requires-Dist: sphinx-rtd-theme; extra == "docs"
 Requires-Dist: numpydoc; extra == "docs"
 Dynamic: license-file
 
+![Correlation dimension example from DeWitt et al. (2025)](docs/images/correlation_dimension_example-1.png)
+*Figure from DeWitt et al. (2025)*
+
 # objscale
 
 Object-based analysis functions for fractal dimensions and size distributions in atmospheric sciences and beyond. Optimized for large datasets.
@@ -52,6 +55,8 @@ The package implements methods from two main papers:
 - [DeWitt & Garrett (2024)](https://acp.copernicus.org/articles/24/8457/2024/acp-24-8457-2024.html) - finite domain effects in size distributions  
 - [DeWitt et al. (2025)](https://egusphere.copernicus.org/preprints/2025/egusphere-2025-3486/) - fractal dimensions for cloud field characterization
 
+See the [interactive scaling explorer](https://thomasddewitt.com/visuals-and-tools/scaling-explorer/index.html) to visualize how the correlation dimension is computed.
+
 ## Key Functions
 
 ### `finite_array_powerlaw_exponent`
@@ -98,8 +103,6 @@ mkdir -p ~/.codex/skills/objscale
 cp .claude/skills/objscale/SKILL.md ~/.codex/skills/objscale/
 ```
 
-
-
 ## Quick Example
 
 ```python
@@ -157,7 +160,7 @@ ind_dim, ind_error = objscale.individual_fractal_dimension(arrays)
 - `get_structure_props` - Calculate perimeter, area, width, height of structures
 - `total_perimeter` - Total perimeter of all objects
 - `total_number` - Count number of structures
-- `isolate_largest_structure` - Extract the largest connected structure
+- `isolate_nth_largest_structure` - Extract the Nth largest connected structure
 - `remove_structures_touching_border_nan` - Remove border-touching structures
 - `remove_structure_holes` - Fill holes in structures
 - `clear_border_adjacent` - Clear structures touching array edges

{objscale-0.2.2 → objscale-1.0.0}/README.md

@@ -1,3 +1,6 @@
+![Correlation dimension example from DeWitt et al. (2025)](docs/images/correlation_dimension_example-1.png)
+*Figure from DeWitt et al. (2025)*
+
 # objscale
 
 Object-based analysis functions for fractal dimensions and size distributions in atmospheric sciences and beyond. Optimized for large datasets.
@@ -11,6 +14,8 @@ The package implements methods from two main papers:
 - [DeWitt & Garrett (2024)](https://acp.copernicus.org/articles/24/8457/2024/acp-24-8457-2024.html) - finite domain effects in size distributions  
 - [DeWitt et al. (2025)](https://egusphere.copernicus.org/preprints/2025/egusphere-2025-3486/) - fractal dimensions for cloud field characterization
 
+See the [interactive scaling explorer](https://thomasddewitt.com/visuals-and-tools/scaling-explorer/index.html) to visualize how the correlation dimension is computed.
+
 ## Key Functions
 
 ### `finite_array_powerlaw_exponent`
@@ -57,8 +62,6 @@ mkdir -p ~/.codex/skills/objscale
 cp .claude/skills/objscale/SKILL.md ~/.codex/skills/objscale/
 ```
 
-
-
 ## Quick Example
 
 ```python
@@ -116,7 +119,7 @@ ind_dim, ind_error = objscale.individual_fractal_dimension(arrays)
 - `get_structure_props` - Calculate perimeter, area, width, height of structures
 - `total_perimeter` - Total perimeter of all objects
 - `total_number` - Count number of structures
-- `isolate_largest_structure` - Extract the largest connected structure
+- `isolate_nth_largest_structure` - Extract the Nth largest connected structure
 - `remove_structures_touching_border_nan` - Remove border-touching structures
 - `remove_structure_holes` - Fill holes in structures
 - `clear_border_adjacent` - Clear structures touching array edges

{objscale-0.2.2 → objscale-1.0.0}/objscale/__init__.py

@@ -7,15 +7,15 @@ from ._size_distributions import (
 
 from ._fractal_dimensions import (
     individual_fractal_dimension,
+    individual_correlation_dimension,
     ensemble_correlation_dimension,
     ensemble_box_dimension,
     total_perimeter,
     total_number,
-    isolate_largest_structure,
+    isolate_nth_largest_structure,
     coarsen_array,
     get_coords_of_boundaries,
     get_locations_from_pixel_sizes,
-    correlation_integral,
     label_size,
 )
 
@@ -39,15 +39,15 @@ __all__ = [
     'finite_array_powerlaw_exponent',
     'array_size_distribution',
     'individual_fractal_dimension',
+    'individual_correlation_dimension',
     'ensemble_correlation_dimension',
     'ensemble_box_dimension',
     'total_perimeter',
     'total_number',
-    'isolate_largest_structure',
+    'isolate_nth_largest_structure',
     'coarsen_array',
     'get_coords_of_boundaries',
     'get_locations_from_pixel_sizes',
-    'correlation_integral',
     'label_size',
     'get_structure_props',
     'get_every_boundary_perimeter',
@@ -60,7 +60,7 @@ __all__ = [
     'set_num_threads',
 ]
 
-__version__ = "0.2.2"
+__version__ = "1.0.0"
 __author__ = "Thomas DeWitt"
 __email__ = "thomas.dewitt@utah.edu"
 __description__ = "Object-based analysis functions for fractal dimensions and size distributions"

{objscale-0.2.2 → objscale-1.0.0}/objscale/_fractal_dimensions.py

@@ -24,7 +24,8 @@ __all__ = [
     'coarsen_array',
     'total_perimeter',
     'total_number',
-    'isolate_largest_structure',
+    'individual_correlation_dimension',
+    'isolate_nth_largest_structure',
     'label_size',
 ]
 
@@ -183,7 +184,24 @@ def ensemble_correlation_dimension(
         if len(circle_centers) == 0:
             continue
 
-        C_l += correlation_integral(circle_centers, all_boundary_coordinates, locations_x, locations_y, bins)
+        # Convert index coordinates to physical coordinates for bounding box
+        boundary_phys_x = locations_x[all_boundary_coordinates[:, 0], all_boundary_coordinates[:, 1]]
+        boundary_phys_y = locations_y[all_boundary_coordinates[:, 0], all_boundary_coordinates[:, 1]]
+        boundary_phys = np.column_stack([boundary_phys_x, boundary_phys_y])
+
+        center_phys_x = locations_x[circle_centers[:, 0], circle_centers[:, 1]]
+        center_phys_y = locations_y[circle_centers[:, 0], circle_centers[:, 1]]
+        center_phys = np.column_stack([center_phys_x, center_phys_y])
+
+        # Sort boundary points by physical y for binary-search bounding box
+        sort_order = np.argsort(boundary_phys[:, 1])
+        sorted_boundary_phys = boundary_phys[sort_order]
+
+        max_bin = bins[-1]
+        bins_sq = bins ** 2
+
+        C_l += correlation_integral(center_phys, sorted_boundary_phys,
+                                    bins_sq, max_bin)
 
     # Perform linear regression to estimate dimension
     x, y = np.log10(bins), np.log10(C_l)
@@ -204,6 +222,137 @@ def ensemble_correlation_dimension(
         return dimension, error
 
 
+def individual_correlation_dimension(
+    array: NDArray,
+    n: int = 1,
+    x_sizes: NDArray | None = None,
+    y_sizes: NDArray | None = None,
+    minlength: str | float = 'auto',
+    maxlength: str | float = 'auto',
+    return_C_l: bool = False,
+    point_reduction_factor: float = 1,
+    nbins: int = 50,
+) -> tuple[float, float] | tuple[float, float, NDArray, NDArray]:
+    """
+    Calculate the correlation dimension of the Nth largest structure in an array.
+
+    Removes border-touching structures, isolates the Nth largest remaining
+    structure, crops to its bounding box, and computes the correlation dimension
+    via :func:`ensemble_correlation_dimension`.
+
+    Parameters
+    ----------
+    array : np.ndarray
+        2-D binary array. May optionally have np.nan at borders; if not, a NaN
+        border is added internally.
+    n : int, default=1
+        Which structure to analyze, ranked by pixel count (1 = largest).
+    x_sizes : np.ndarray, optional
+        Pixel sizes in the x direction. If None, assume all pixel dimensions are 1.
+    y_sizes : np.ndarray, optional
+        Pixel sizes in the y direction. If None, assume all pixel dimensions are 1.
+    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.33 * max(bbox_height, bbox_width)`` of the isolated structure in
+        physical units.
+    return_C_l : bool, default=False
+        If True, return dimension, error, bins, C_l. Otherwise, return dimension,
+        error.
+    point_reduction_factor : float, default=1
+        Draw N/point_reduction_factor circles, where N is the total number of
+        available circles. Must be >= 1.
+    nbins : int, default=50
+        Number of logarithmically spaced bins for the correlation integral.
+
+    Returns
+    -------
+    dimension : float
+        The correlation dimension.
+    error : float
+        Error estimate for the dimension (95% confidence interval).
+    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.
+
+    Raises
+    ------
+    ValueError
+        If array is not 2-D, n < 1, or n exceeds the number of available
+        structures after border removal.
+    """
+    if array.ndim != 2:
+        raise ValueError('array must be 2-dimensional')
+    if n < 1:
+        raise ValueError('n must be >= 1')
+
+    # Pad with NaN border if not already present
+    if not np.any(np.isnan(array)):
+        array = np.pad(array.astype(float), pad_width=1, mode='constant',
+                       constant_values=np.nan)
+        if x_sizes is not None:
+            x_sizes = np.pad(x_sizes, pad_width=1, mode='edge')
+        if y_sizes is not None:
+            y_sizes = np.pad(y_sizes, pad_width=1, mode='edge')
+
+    # Remove border-touching structures and clean NaN
+    cleaned = remove_structures_touching_border_nan(array)
+    binary = np.nan_to_num(cleaned, nan=0.0).astype(bool)
+
+    # Isolate the Nth largest structure
+    isolated = isolate_nth_largest_structure(binary, n=n)
+
+    # Crop to bounding box
+    rows = np.any(isolated, axis=1)
+    cols = np.any(isolated, axis=0)
+    rmin, rmax = np.where(rows)[0][[0, -1]]
+    cmin, cmax = np.where(cols)[0][[0, -1]]
+    cropped = isolated[rmin:rmax + 1, cmin:cmax + 1].astype(np.float64)
+
+    # Pad with 1px of zeros to prevent toroidal wrap artifacts
+    padded = np.pad(cropped, pad_width=1, mode='constant', constant_values=0)
+
+    # Handle pixel sizes
+    if x_sizes is not None:
+        cropped_x = x_sizes[rmin:rmax + 1, cmin:cmax + 1]
+        cropped_x = np.pad(cropped_x, pad_width=1, mode='edge')
+    else:
+        cropped_x = None
+
+    if y_sizes is not None:
+        cropped_y = y_sizes[rmin:rmax + 1, cmin:cmax + 1]
+        cropped_y = np.pad(cropped_y, pad_width=1, mode='edge')
+    else:
+        cropped_y = None
+
+    # Compute maxlength from crop dimensions if auto
+    if maxlength == 'auto':
+        if cropped_x is not None and cropped_y is not None:
+            locs_x, locs_y = get_locations_from_pixel_sizes(cropped_x, cropped_y)
+            h, w = cropped_x.shape
+            phys_width = locs_x[h // 2, w - 1] - locs_x[h // 2, 0]
+            phys_height = locs_y[h - 1, w // 2] - locs_y[0, w // 2]
+            maxlength = 0.33 * max(phys_width, phys_height)
+        else:
+            crop_h, crop_w = cropped.shape
+            maxlength = 0.33 * float(max(crop_h, crop_w))
+
+    return ensemble_correlation_dimension(
+        [padded],
+        x_sizes=cropped_x,
+        y_sizes=cropped_y,
+        minlength=minlength,
+        maxlength=maxlength,
+        interior_circles_only=False,
+        return_C_l=return_C_l,
+        point_reduction_factor=point_reduction_factor,
+        nbins=nbins,
+    )
+
+
 def ensemble_box_dimension(
     binary_arrays: NDArray | list[NDArray],
     set: str = 'edge',
@@ -597,56 +746,81 @@ def get_locations_from_pixel_sizes(
 
 
 @numba.njit(parallel=True)
-def correlation_integral(coordinates_to_check, coordinates_to_count, locations_x, locations_y, bins):
+def correlation_integral(centers_phys, sorted_boundary_phys, bins_sq, max_bin):
     """
     Calculate correlation integral for boundary coordinates.
 
-    For each coordinates_to_check, calculate how many coordinates_to_count are
-    less than a distance bin_i of the chosen coordinate, for each bin_i in bins.
+    For each center, count how many boundary points are within each distance
+    threshold. Uses physical coordinates directly for correct bounding on any
+    grid geometry (including non-uniform and 2D-varying pixel sizes).
 
     Parameters
     ----------
-    coordinates_to_check : np.ndarray
-        Array of coordinates of boundaries of shape [[x1,y1], [x2,y2], [x3,y3], ...].
-    coordinates_to_count : np.ndarray
-        Array of coordinates to count within distance bins.
-    locations_x : np.ndarray
-        X locations of each pixel.
-    locations_y : np.ndarray
-        Y locations of each pixel.
-    bins : np.ndarray
-        1-D array of distances to bin.
+    centers_phys : np.ndarray
+        Physical (x, y) coordinates of circle centers, shape (N, 2).
+    sorted_boundary_phys : np.ndarray
+        Physical (x, y) coordinates of boundary points, shape (M, 2),
+        sorted by y coordinate.
+    bins_sq : np.ndarray
+        1-D array of squared distance thresholds (bins**2), sorted ascending.
+    max_bin : float
+        Maximum bin distance (sqrt of bins_sq[-1]).
 
     Returns
     -------
     C_l : np.ndarray
-        Correlation integral values, same shape as bins.
+        Correlation integral values, same shape as bins_sq.
 
     Notes
     -----
-    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.
+    Uses three optimizations over the naive approach:
+    1. Bounding box in physical space via sort + binary search on y coordinate.
+    2. Squared distances to avoid sqrt in the inner loop.
+    3. Binary-search binning with forward cumulative sum instead of linear scan.
     """
-    # Each thread gets its own copy to eliminate race condition during parallelization
-    C_l_per_thread = np.zeros((numba.config.NUMBA_NUM_THREADS, bins.shape[0]))
+    sorted_y = sorted_boundary_phys[:, 1].copy()
+    num_bins = bins_sq.shape[0]
 
-    for i in numba.prange(coordinates_to_check.shape[0]):
+    # Each thread gets its own histogram to eliminate race conditions
+    hist_per_thread = np.zeros((numba.config.NUMBA_NUM_THREADS, num_bins))
+
+    for i in numba.prange(centers_phys.shape[0]):
         thread_id = numba.get_thread_id()
-        for j in range(coordinates_to_count.shape[0]):
-            p, q = coordinates_to_check[i]
-            r, s = coordinates_to_count[j]
+        cx = centers_phys[i, 0]
+        cy = centers_phys[i, 1]
+
+        # Binary search for physical y bounding box
+        lo = np.searchsorted(sorted_y, cy - max_bin, side='left')
+        hi = np.searchsorted(sorted_y, cy + max_bin, side='right')
+
+        for j in range(lo, hi):
+            bx = sorted_boundary_phys[j, 0]
+
+            # Physical x bounding box check
+            if abs(bx - cx) > max_bin:
+                continue
+
+            dx = cx - bx
+            dy = cy - sorted_boundary_phys[j, 1]
+            dist_sq = dx * dx + dy * dy
 
-            dx = (locations_x[p, q] - locations_x[r, s])
-            dy = (locations_y[p, q] - locations_y[r, s])
+            # Binary search: find first bin where bins_sq[bin_idx] > dist_sq
+            bin_idx = np.searchsorted(bins_sq, dist_sq, side='right')
+            if bin_idx < num_bins:
+                hist_per_thread[thread_id, bin_idx] += 1
 
-            distance = np.sqrt((dx ** 2) + (dy ** 2))
-            for bin_index, bin in enumerate(bins):
-                if distance < bin:
-                    C_l_per_thread[thread_id, bin_index] += 1
+    # Sum across threads
+    hist = np.sum(hist_per_thread, axis=0)
 
-    # Return total over all threads
-    return np.sum(C_l_per_thread, axis=0)
+    # Forward cumulative sum: convert histogram to cumulative counts
+    # hist[k] = count of pairs whose first qualifying bin index is k
+    # C_l[k] = count of pairs with dist_sq < bins_sq[k] = sum of hist[0..k]
+    C_l = np.zeros(num_bins)
+    cumsum = 0.0
+    for k in range(num_bins):
+        cumsum += hist[k]
+        C_l[k] = cumsum
+    return C_l
 
 
 def coarsen_array(array: NDArray, factor: int) -> NDArray:
@@ -773,37 +947,54 @@ def total_number(
     return n_structures
 
 
-def isolate_largest_structure(
+def isolate_nth_largest_structure(
     binary_array: NDArray,
+    n: int = 1,
     structure: NDArray = np.array([[0, 1, 0], [1, 1, 1], [0, 1, 0]])
 ) -> NDArray[np.bool_]:
     """
-    Isolate the largest connected structure in a binary array.
+    Isolate the Nth largest connected structure in a binary array.
 
     Parameters
     ----------
     binary_array : np.ndarray
         Binary input array.
+    n : int, default=1
+        Which structure to return, ranked by pixel count (1 = largest).
     structure : np.ndarray, default=np.array([[0, 1, 0], [1, 1, 1], [0, 1, 0]])
         Connectivity structure.
 
     Returns
     -------
     np.ndarray
-        Boolean array with only the largest structure set to True.
+        Boolean array with only the Nth largest structure set to True.
 
     Raises
     ------
     ValueError
-        If ``binary_array`` contains no structures (no non-zero pixels).
+        If ``binary_array`` contains no structures or ``n`` exceeds the number
+        of structures.
     """
+    if n < 1:
+        raise ValueError('n must be >= 1')
     labelled_array = label(binary_array, structure)[0]
     cloud_values = labelled_array[labelled_array != 0]  # remove background
     if cloud_values.size == 0:
         raise ValueError('binary_array contains no structures')
     values, counts = np.unique(cloud_values, return_counts=True)
-    most_common = values[np.argmax(counts)]
-    return labelled_array == most_common
+    sorted_indices = np.argsort(counts)[::-1]
+    if n > len(values):
+        raise ValueError(f'Requested n={n} but only {len(values)} structures exist')
+    selected = values[sorted_indices[n - 1]]
+    return labelled_array == selected
+
+
+def isolate_largest_structure(*args, **kwargs):
+    """Removed. Use :func:`isolate_nth_largest_structure` instead."""
+    raise NotImplementedError(
+        'isolate_largest_structure has been renamed to '
+        'isolate_nth_largest_structure(binary_array, n=1)'
+    )
 
 
 def label_size(

{objscale-0.2.2 → objscale-1.0.0}/objscale.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: objscale
-Version: 0.2.2
+Version: 1.0.0
 Summary: Object-based analysis functions for fractal dimensions and size distributions
 Author-email: Thomas DeWitt <thomas.dewitt@utah.edu>
 License: MIT
@@ -39,6 +39,9 @@ Requires-Dist: sphinx-rtd-theme; extra == "docs"
 Requires-Dist: numpydoc; extra == "docs"
 Dynamic: license-file
 
+![Correlation dimension example from DeWitt et al. (2025)](docs/images/correlation_dimension_example-1.png)
+*Figure from DeWitt et al. (2025)*
+
 # objscale
 
 Object-based analysis functions for fractal dimensions and size distributions in atmospheric sciences and beyond. Optimized for large datasets.
@@ -52,6 +55,8 @@ The package implements methods from two main papers:
 - [DeWitt & Garrett (2024)](https://acp.copernicus.org/articles/24/8457/2024/acp-24-8457-2024.html) - finite domain effects in size distributions  
 - [DeWitt et al. (2025)](https://egusphere.copernicus.org/preprints/2025/egusphere-2025-3486/) - fractal dimensions for cloud field characterization
 
+See the [interactive scaling explorer](https://thomasddewitt.com/visuals-and-tools/scaling-explorer/index.html) to visualize how the correlation dimension is computed.
+
 ## Key Functions
 
 ### `finite_array_powerlaw_exponent`
@@ -98,8 +103,6 @@ mkdir -p ~/.codex/skills/objscale
 cp .claude/skills/objscale/SKILL.md ~/.codex/skills/objscale/
 ```
 
-
-
 ## Quick Example
 
 ```python
@@ -157,7 +160,7 @@ ind_dim, ind_error = objscale.individual_fractal_dimension(arrays)
 - `get_structure_props` - Calculate perimeter, area, width, height of structures
 - `total_perimeter` - Total perimeter of all objects
 - `total_number` - Count number of structures
-- `isolate_largest_structure` - Extract the largest connected structure
+- `isolate_nth_largest_structure` - Extract the Nth largest connected structure
 - `remove_structures_touching_border_nan` - Remove border-touching structures
 - `remove_structure_holes` - Fill holes in structures
 - `clear_border_adjacent` - Clear structures touching array edges

{objscale-0.2.2 → objscale-1.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "objscale"
-version = "0.2.2"
+version = "1.0.0"
 description = "Object-based analysis functions for fractal dimensions and size distributions"
 readme = "README.md"
 authors = [