objscale 0.2.3__tar.gz → 1.1.0__tar.gz

{objscale-0.2.3 → objscale-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: objscale
-Version: 0.2.3
+Version: 1.1.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.3 → objscale-1.1.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.3 → objscale-1.1.0}/objscale/__init__.py

@@ -7,11 +7,12 @@ 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,
@@ -38,11 +39,12 @@ __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',
@@ -58,7 +60,7 @@ __all__ = [
     'set_num_threads',
 ]
 
-__version__ = "0.2.3"
+__version__ = "1.1.0"
 __author__ = "Thomas DeWitt"
 __email__ = "thomas.dewitt@utah.edu"
 __description__ = "Object-based analysis functions for fractal dimensions and size distributions"

{objscale-0.2.3 → objscale-1.1.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',
 ]
 
@@ -221,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',
@@ -448,6 +580,7 @@ def individual_fractal_dimension(
     y_sizes: NDArray | list[NDArray] | None = None,
     min_a: float = 10,
     max_a: float = np.inf,
+    bins: int | None = 30,
     return_values: bool = False
 ) -> tuple[float, float] | tuple[float, float, NDArray, NDArray]:
     """
@@ -473,6 +606,10 @@ def individual_fractal_dimension(
         Minimum structure area to include in calculation.
     max_a : float, default=np.inf
         Maximum structure area to include in calculation.
+    bins : int or None, default=30
+        Number of bins along log10(sqrt(area)) for averaging. The regression
+        is performed on the bin-averaged values. If None, fit on all individual
+        points without binning.
     return_values : bool, default=False
         If True, return additional data used in the calculation.
 
@@ -483,9 +620,11 @@ def 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 of sqrt(area) values (bin centers if bins is not None).
+        Only returned if return_values=True.
     log10_p : np.ndarray, optional
-        Log10 of perimeter values. Only returned if return_values=True.
+        Log10 of perimeter values (bin means if bins is not None).
+        Only returned if return_values=True.
 
     Raises
     ------
@@ -524,10 +663,25 @@ def individual_fractal_dimension(
     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))
+    log_sqrt_a = np.log10(np.sqrt(areas))
+    log_p = np.log10(perimeters)
+
+    if bins is not None:
+        bin_edges = np.linspace(log_sqrt_a.min(), log_sqrt_a.max(), bins + 1)
+        bin_indices = np.digitize(log_sqrt_a, bin_edges) - 1
+        bin_indices = np.clip(bin_indices, 0, bins - 1)
+        bin_centers = 0.5 * (bin_edges[:-1] + bin_edges[1:])
+        bin_means = np.array([log_p[bin_indices == i].mean()
+                              if np.any(bin_indices == i) else np.nan
+                              for i in range(bins)])
+        valid = np.isfinite(bin_means)
+        log_sqrt_a = bin_centers[valid]
+        log_p = bin_means[valid]
+
+    (slope, _), (err, _) = linear_regression(log_sqrt_a, log_p)
 
     if return_values:
-        return slope, err, np.log10(np.sqrt(areas)), np.log10(perimeters)
+        return slope, err, log_sqrt_a, log_p
     else:
         return slope, err
 
@@ -815,37 +969,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.3 → objscale-1.1.0}/objscale.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: objscale
-Version: 0.2.3
+Version: 1.1.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.3 → objscale-1.1.0}/pyproject.toml

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