objscale 0.1.0__tar.gz

objscale-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2024 Thomas D. DeWitt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

objscale-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: objscale
+Version: 0.1.0
+Summary: Object-based analysis functions for fractal dimensions and size distributions
+Author-email: Thomas DeWitt <thomas.dewitt@utah.edu>
+License: MIT
+Project-URL: Homepage, https://github.com/thomasdewitt/objscale
+Project-URL: Repository, https://github.com/thomasdewitt/objscale
+Project-URL: Documentation, https://objscale.readthedocs.io
+Project-URL: Issues, https://github.com/thomasdewitt/objscale/issues
+Keywords: fractal,dimensions,size-distributions,object-analysis,perimeter,area
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: scikit-image>=0.18.0
+Requires-Dist: numba>=0.56.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=4.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Requires-Dist: numpydoc; extra == "docs"
+Dynamic: license-file
+
+# objscale
+
+Object-based analysis functions for fractal dimensions and size distributions in atmospheric sciences and beyond. Optimized for large datasets.
+
+## Description
+
+`objscale` provides computational tools for analyzing the scaling properties of objects in 2D binary arrays. The package consolidates methods for calculating size distributions and fractal dimensions that account for finite domain effects and complex boundary conditions. Originally developed for atmospheric science applications, these methods apply broadly to any field where object scaling properties matter.
+
+The package implements methods from two main papers:
+
+- [DeWitt & Garrett (2024)](https://acp.copernicus.org/articles/24/8457/2024/) - finite domain effects in size distributions  
+- DeWitt et al. (in prep) - fractal dimensions for cloud field characterization
+
+## Key Functions
+
+### `finite_array_powerlaw_exponent`
+
+Calculate power-law exponents for size distributions while accounting for finite domain truncation effects. Essential for accurate scaling analysis in bounded domains.
+
+### `individual_fractal_dimension`
+
+Fractal dimension of individual objects using the perimeter-area relationship, with proper handling of interior holes and resolution effects.
+
+### `ensemble_correlation_dimension`
+
+Correlation dimension for characterizing the collective scaling properties of object ensembles. Uses point-pair correlation analysis across multiple length scales.
+
+### `ensemble_box_dimension`
+
+Box-counting dimension for object ensembles. New analyses should prefer `ensemble_correlation_dimension`. Counts boxes containing object boundaries at varying spatial scales.
+
+### `ensemble_coarsening_dimension`
+
+Novel fractal dimension based on how total object perimeter changes under spatial coarsening operations. New analyses should prefer `ensemble_correlation_dimension`. Used in [Rees et. al., 2024](https://npg.copernicus.org/articles/31/497/2024/)
+
+## Installation
+
+```bash
+pip install objscale
+```
+
+## Quick Example
+
+```python
+import objscale
+import numpy as np
+
+# Create binary array (e.g., cloud mask, percolation lattice)
+arrays = [(np.random.random((1000, 1000)) < 0.3).astype(int) for _ in range(4)]
+
+# Size distribution with finite domain corrections
+(exponent, error), (log10_sizes, log10_counts) = objscale.finite_array_powerlaw_exponent(
+    arrays, 'area', return_counts=True
+)
+
+# Ensemble fractal dimensions
+corr_dim, corr_error = objscale.ensemble_correlation_dimension(arrays)
+box_dim, box_error = objscale.ensemble_box_dimension(arrays)
+
+# Individual object analysis  
+ind_dim, ind_error = objscale.individual_fractal_dimension(arrays)
+```
+
+## Features
+
+- **Finite domain corrections**: Proper handling of truncation effects at domain boundaries as recommended by [DeWitt & Garrett (2024)]([ACP - Finite domains cause bias in measured and modeled distributions of cloud sizes](https://acp.copernicus.org/articles/24/8457/2024/))
+- **Multiple size metrics**: Area, perimeter, width, height, nested perimeter
+- **Arbitrary boundaries**: Support for NaN-demarcated non-rectangular domains  
+- **Individual and Ensemble methods**: Characterize both individual and collective properties of object fields
+- **Performance optimized**: Numba acceleration for computational efficiency. Can handle billions of individual objects on a mid-range laptop.
+
+## Requirements
+
+- Python ≥ 3.8
+- NumPy ≥ 1.20.0
+- SciPy ≥ 1.7.0  
+- scikit-image ≥ 0.18.0
+- Numba ≥ 0.56.0
+
+## Support Statement
+
+This package consolidates research code developed over several years. While functional and tested, it should be considered research software with limited ongoing support. Users are encouraged to understand the underlying methods through the referenced papers before applying to their data.
+
+## References
+
+If you use this package, please cite:
+
+DeWitt, T. D. and Garrett, T. J.: Finite domains cause bias in measured and modeled 
+distributions of cloud sizes, Atmos. Chem. Phys., 24, 8457–8472, 
+https://doi.org/10.5194/acp-24-8457-2024, 2024.
+
+## Author
+
+Thomas D. DeWitt  
+University of Utah Department of Atmospheric Sciences
+Sonnet 4 with Claude Code
+Anthropic
+
+## License
+
+MIT License

objscale-0.1.0/README.md

@@ -0,0 +1,101 @@
+# objscale
+
+Object-based analysis functions for fractal dimensions and size distributions in atmospheric sciences and beyond. Optimized for large datasets.
+
+## Description
+
+`objscale` provides computational tools for analyzing the scaling properties of objects in 2D binary arrays. The package consolidates methods for calculating size distributions and fractal dimensions that account for finite domain effects and complex boundary conditions. Originally developed for atmospheric science applications, these methods apply broadly to any field where object scaling properties matter.
+
+The package implements methods from two main papers:
+
+- [DeWitt & Garrett (2024)](https://acp.copernicus.org/articles/24/8457/2024/) - finite domain effects in size distributions  
+- DeWitt et al. (in prep) - fractal dimensions for cloud field characterization
+
+## Key Functions
+
+### `finite_array_powerlaw_exponent`
+
+Calculate power-law exponents for size distributions while accounting for finite domain truncation effects. Essential for accurate scaling analysis in bounded domains.
+
+### `individual_fractal_dimension`
+
+Fractal dimension of individual objects using the perimeter-area relationship, with proper handling of interior holes and resolution effects.
+
+### `ensemble_correlation_dimension`
+
+Correlation dimension for characterizing the collective scaling properties of object ensembles. Uses point-pair correlation analysis across multiple length scales.
+
+### `ensemble_box_dimension`
+
+Box-counting dimension for object ensembles. New analyses should prefer `ensemble_correlation_dimension`. Counts boxes containing object boundaries at varying spatial scales.
+
+### `ensemble_coarsening_dimension`
+
+Novel fractal dimension based on how total object perimeter changes under spatial coarsening operations. New analyses should prefer `ensemble_correlation_dimension`. Used in [Rees et. al., 2024](https://npg.copernicus.org/articles/31/497/2024/)
+
+## Installation
+
+```bash
+pip install objscale
+```
+
+## Quick Example
+
+```python
+import objscale
+import numpy as np
+
+# Create binary array (e.g., cloud mask, percolation lattice)
+arrays = [(np.random.random((1000, 1000)) < 0.3).astype(int) for _ in range(4)]
+
+# Size distribution with finite domain corrections
+(exponent, error), (log10_sizes, log10_counts) = objscale.finite_array_powerlaw_exponent(
+    arrays, 'area', return_counts=True
+)
+
+# Ensemble fractal dimensions
+corr_dim, corr_error = objscale.ensemble_correlation_dimension(arrays)
+box_dim, box_error = objscale.ensemble_box_dimension(arrays)
+
+# Individual object analysis  
+ind_dim, ind_error = objscale.individual_fractal_dimension(arrays)
+```
+
+## Features
+
+- **Finite domain corrections**: Proper handling of truncation effects at domain boundaries as recommended by [DeWitt & Garrett (2024)]([ACP - Finite domains cause bias in measured and modeled distributions of cloud sizes](https://acp.copernicus.org/articles/24/8457/2024/))
+- **Multiple size metrics**: Area, perimeter, width, height, nested perimeter
+- **Arbitrary boundaries**: Support for NaN-demarcated non-rectangular domains  
+- **Individual and Ensemble methods**: Characterize both individual and collective properties of object fields
+- **Performance optimized**: Numba acceleration for computational efficiency. Can handle billions of individual objects on a mid-range laptop.
+
+## Requirements
+
+- Python ≥ 3.8
+- NumPy ≥ 1.20.0
+- SciPy ≥ 1.7.0  
+- scikit-image ≥ 0.18.0
+- Numba ≥ 0.56.0
+
+## Support Statement
+
+This package consolidates research code developed over several years. While functional and tested, it should be considered research software with limited ongoing support. Users are encouraged to understand the underlying methods through the referenced papers before applying to their data.
+
+## References
+
+If you use this package, please cite:
+
+DeWitt, T. D. and Garrett, T. J.: Finite domains cause bias in measured and modeled 
+distributions of cloud sizes, Atmos. Chem. Phys., 24, 8457–8472, 
+https://doi.org/10.5194/acp-24-8457-2024, 2024.
+
+## Author
+
+Thomas D. DeWitt  
+University of Utah Department of Atmospheric Sciences
+Sonnet 4 with Claude Code
+Anthropic
+
+## License
+
+MIT License

objscale-0.1.0/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"