zsplit 1.0.0__tar.gz → 1.0.2__tar.gz

zsplit-1.0.2/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: zsplit
+Version: 1.0.2
+Summary: Z-Split Normalization: Zero-Preserving Split Normalization for bipolar spectral indices
+Author-email: Abdulrhman Almoadi <aalmoadi@kacst.edu.sa>
+License: MIT License
+        
+        Copyright (c) 2026 Abdulrhman Almoadi
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/aalmoadi/endwi
+Project-URL: Repository, https://github.com/aalmoadi/endwi
+Project-URL: Documentation, https://github.com/aalmoadi/endwi/tree/main/Z-Split_Normalization
+Project-URL: Bug Tracker, https://github.com/aalmoadi/endwi/issues
+Project-URL: DOI, https://doi.org/10.5281/zenodo.20602710
+Project-URL: Paper, https://doi.org/10.5194/egusphere-2026-672
+Keywords: normalization,remote-sensing,flood-detection,spectral-index,ENDWI,NDWI,bipolar,zero-preserving,Otsu,GIS,GeoAI,machine-learning,deep-learning,SAR,Sentinel-2
+Classifier: Development Status :: 5 - Production/Stable
+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: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Provides-Extra: raster
+Requires-Dist: rasterio>=1.2; extra == "raster"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: rasterio>=1.2; extra == "dev"
+Requires-Dist: matplotlib; extra == "dev"
+Dynamic: license-file
+
+# Z-Split Normalization (Zero-Preserving Split Normalization)
+
+**Version:** 1.0.1  
+**License:** MIT
+
+---
+
+## What is Z-Split?
+
+Z-Split **preserves zero as a fixed physical boundary** while **expanding narrow distributions clustered around zero** into the full [−1, 1] range — normalizing and expanding in a single operation. This prevents the low-contrast output common with near-zero indices and creates a well-formed distribution suitable for Otsu thresholding and multi-temporal analysis.
+
+---
+
+## Core Idea and Motivation
+
+Spectral indices and remote sensing operations often produce values clustered tightly around zero due to radiometric constraints, surface reflectance properties, or normalized difference formulations. Standard normalization compresses these values further, producing low-contrast images and unstable thresholds.
+
+Z-Split expands each side of zero independently into [−1, 0] and [0, 1], simultaneously normalizing and stretching narrow distributions. This preserves distributional contrast for reliable thresholding, maintains the zero boundary across scenes for stable multi-temporal comparison, and broadens the practical utility of spectral indices in analytical workflows where near-zero clustering would otherwise limit accuracy.
+
+---
+
+## The Problem
+
+Bipolar remote sensing indices share one property: **zero is a physical class boundary** (water/non-water, uplift/subsidence). Standard methods destroy it: Min-Max shifts zero into [0, 1]; Z-Score centers on the mean and produces an unbounded range. Both fail when values cluster near zero, making thresholding unreliable, multi-temporal comparisons artifact-driven, and in the worst case producing entirely empty, white, or black images due to values compressed around zero.
+
+---
+
+## The Solution — Z-Split
+
+Z-Split normalizes each side of zero **independently**, stretching the full negative range to [−1, 0] and the full positive range to [0, 1].
+
+### Formula
+
+$$
+Z\text{-}Split(x) =
+\begin{cases}
+x \;/\; \max(X^+) & \text{if } x > 0 \\
+0 & \text{if } x = 0 \\
+x \;/\; |\min(X^-)| & \text{if } x < 0
+\end{cases}
+$$
+
+where $X^+$ is the set of positive values and $X^-$ is the set of negative values.  
+**Output range:** [−1, 1] with zero strictly preserved.
+
+---
+
+## Why Z-Split?
+
+| Property | Min-Max | Z-Score | Z-Split |
+|----------|:-------:|:-------:|:-------:|
+| Preserves zero as class boundary | ❌ | ❌ | ✅ |
+| Expands narrow near-zero distributions | ❌ | ⚠️ | ✅ |
+| Stable on skewed distributions | ❌ | ⚠️ | ✅ |
+| Suitable for Otsu thresholding | ❌ | ⚠️ | ✅ |
+| Multi-temporal direction preserved | ❌ | ❌ | ✅ |
+| Output range | [0, 1] | Unbounded | [−1, 1] |
+
+---
+
+## Installation
+
+```bash
+pip install zsplit
+```
+
+## Quick Start
+
+```python
+from zsplit import normalize
+
+result = normalize(your_bipolar_index)
+```
+
+---
+
+## Practical Applications in Remote Sensing
+
+Z-Split addresses a critical problem in any workflow involving bipolar indices across time or sensors:
+
+**1. Change Detection**  
+Applying Min-Max before change detection introduces artificial trends that appear as land cover change but reflect only normalization artifacts. A report showing "15% vegetation decline" may be entirely attributable to normalization, not reality.
+
+**2. Time Series Analysis**  
+Studies tracking floods, drought, or urban expansion over time require a clean temporal signal. Min-Max corrupts this signal by rescaling each scene independently to [0, 1], making year-to-year comparisons unreliable.
+
+**3. Multi-temporal Machine Learning**  
+Models trained on Min-Max normalized multi-year data learn spurious patterns introduced by normalization rather than real spectral change. Z-Split ensures the training signal reflects actual surface conditions.
+
+**4. InSAR and Displacement Monitoring**  
+In LOS displacement data, zero means no movement. Shifting zero through Min-Max misclassifies stable pixels as deforming, directly corrupting subsidence or uplift maps.
+
+---
+
+## Validation
+
+### 1. NDWI — Optical Remote Sensing
+
+Tested on Sentinel-2 NDWI data. Z-Split successfully expanded near-zero clustered values while preserving the original image structure, producing contrast-enhanced output suitable for thresholding and multi-temporal comparison.
+
+### 2. Multi-Temporal Change Analysis — NDVI, Riyadh 2018–2024
+
+Validated on four Sentinel-2 NDVI scenes (March–April, 2018–2020–2022–2024) over Riyadh, Saudi Arabia (scale: 10 m, 5603 × 5129 pixels per scene) across 11,424 spatial patches.
+
+#### A. Normalization Artifact Analysis
+
+The figure below shows the deviation of each normalization method from the raw temporal signal. Min-Max introduces large artificial trends across the entire scene (colored map). Z-Split introduces virtually no deviation (near-white map).
+
+![Deviation Analysis](https://raw.githubusercontent.com/aalmoadi/endwi/main/Figures/deviation_analysis.png)
+
+| Method | Mean Absolute Deviation | Std |
+|--------|:-----------------------:|:---:|
+| Min-Max | 0.1858 | 0.2091 |
+| **Z-Split** | **0.0013** | **0.0017** |
+
+Z-Split preserves the temporal signal with **143× greater fidelity** than Min-Max.
+
+#### B. Linear Trend (Slope per pixel, 2018–2024)
+
+| Method | Mean Slope | Std | Correlation with Raw |
+|--------|:----------:|:---:|:--------------------:|
+| Raw (no normalization) | 0.000894 | 0.0165 | — |
+| Min-Max | 0.027454 | 0.2170 | r = 0.511 |
+| **Z-Split** | **−0.000120** | **0.0167** | **r = 0.995** |
+
+#### C. Multi-Temporal Change Maps
+
+The figure below compares Linear Trend, Anomaly, and Coefficient of Variation maps across all three methods. Z-Split maps are visually and statistically consistent with raw data; Min-Max maps show spatially inverted anomaly patterns and 5.5× inflated variability.
+
+![Change Analysis](https://raw.githubusercontent.com/aalmoadi/endwi/main/Figures/change_analysis.png)
+
+| Method | Mean CV |
+|--------|:-------:|
+| Raw | 0.150 |
+| **Z-Split** | **0.173** |
+| Min-Max | 0.832 |
+
+#### D. Threshold Stability (Otsu across 11,424 patches)
+
+| Method | Threshold Std |
+|--------|:-------------:|
+| Min-Max | 0.0882 |
+| Z-Split | 0.2220 |
+| Z-Score | 1.2012 |
+
+> **Note:** For strongly unipolar NDVI in arid urban areas, Min-Max threshold stability is comparable to Z-Split. Z-Split's primary advantage is in bipolar indices with narrow near-zero distributions (NDWI, InSAR LOS), consistent with its design objective.
+
+---
+
+## Application Scope
+
+Most effective when:
+- Values cluster near zero (NDWI in arid regions, InSAR LOS over stable terrain)
+- Multi-temporal consistency is required (change detection, time series analysis)
+- Otsu or zero-based thresholding is applied
+- Cross-scene or cross-sensor comparisons are performed
+
+---
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `zsplit_normalization.ipynb` | Jupyter Notebook with visual demonstration |
+| `zsplit_arcpy.py` | ArcGIS Pro implementation |
+| `Z-Split_Normalization/Validation/` | Multi-temporal NDVI change analysis |
+| `Validation/01_Optical_ENDWI/` | Optical NDWI validation |
+
+---
+
+## Author
+
+**Abdulrhman Almoadi**  
+King Abdulaziz City for Science and Technology (KACST)
+
+---
+
+## Citation
+
+If you use Z-Split, please cite:
+
+> Almoadi, A.: Reducing False Alarms in Urban Flood Detection: An Enhanced NDWI (ENDWI) with Hybrid Max Fusion on Sentinel-2 Data, EGUsphere [preprint], https://doi.org/10.5194/egusphere-2026-672, 2026.

zsplit-1.0.2/README.md

@@ -0,0 +1,182 @@
+# Z-Split Normalization (Zero-Preserving Split Normalization)
+
+**Version:** 1.0.1  
+**License:** MIT
+
+---
+
+## What is Z-Split?
+
+Z-Split **preserves zero as a fixed physical boundary** while **expanding narrow distributions clustered around zero** into the full [−1, 1] range — normalizing and expanding in a single operation. This prevents the low-contrast output common with near-zero indices and creates a well-formed distribution suitable for Otsu thresholding and multi-temporal analysis.
+
+---
+
+## Core Idea and Motivation
+
+Spectral indices and remote sensing operations often produce values clustered tightly around zero due to radiometric constraints, surface reflectance properties, or normalized difference formulations. Standard normalization compresses these values further, producing low-contrast images and unstable thresholds.
+
+Z-Split expands each side of zero independently into [−1, 0] and [0, 1], simultaneously normalizing and stretching narrow distributions. This preserves distributional contrast for reliable thresholding, maintains the zero boundary across scenes for stable multi-temporal comparison, and broadens the practical utility of spectral indices in analytical workflows where near-zero clustering would otherwise limit accuracy.
+
+---
+
+## The Problem
+
+Bipolar remote sensing indices share one property: **zero is a physical class boundary** (water/non-water, uplift/subsidence). Standard methods destroy it: Min-Max shifts zero into [0, 1]; Z-Score centers on the mean and produces an unbounded range. Both fail when values cluster near zero, making thresholding unreliable, multi-temporal comparisons artifact-driven, and in the worst case producing entirely empty, white, or black images due to values compressed around zero.
+
+---
+
+## The Solution — Z-Split
+
+Z-Split normalizes each side of zero **independently**, stretching the full negative range to [−1, 0] and the full positive range to [0, 1].
+
+### Formula
+
+$$
+Z\text{-}Split(x) =
+\begin{cases}
+x \;/\; \max(X^+) & \text{if } x > 0 \\
+0 & \text{if } x = 0 \\
+x \;/\; |\min(X^-)| & \text{if } x < 0
+\end{cases}
+$$
+
+where $X^+$ is the set of positive values and $X^-$ is the set of negative values.  
+**Output range:** [−1, 1] with zero strictly preserved.
+
+---
+
+## Why Z-Split?
+
+| Property | Min-Max | Z-Score | Z-Split |
+|----------|:-------:|:-------:|:-------:|
+| Preserves zero as class boundary | ❌ | ❌ | ✅ |
+| Expands narrow near-zero distributions | ❌ | ⚠️ | ✅ |
+| Stable on skewed distributions | ❌ | ⚠️ | ✅ |
+| Suitable for Otsu thresholding | ❌ | ⚠️ | ✅ |
+| Multi-temporal direction preserved | ❌ | ❌ | ✅ |
+| Output range | [0, 1] | Unbounded | [−1, 1] |
+
+---
+
+## Installation
+
+```bash
+pip install zsplit
+```
+
+## Quick Start
+
+```python
+from zsplit import normalize
+
+result = normalize(your_bipolar_index)
+```
+
+---
+
+## Practical Applications in Remote Sensing
+
+Z-Split addresses a critical problem in any workflow involving bipolar indices across time or sensors:
+
+**1. Change Detection**  
+Applying Min-Max before change detection introduces artificial trends that appear as land cover change but reflect only normalization artifacts. A report showing "15% vegetation decline" may be entirely attributable to normalization, not reality.
+
+**2. Time Series Analysis**  
+Studies tracking floods, drought, or urban expansion over time require a clean temporal signal. Min-Max corrupts this signal by rescaling each scene independently to [0, 1], making year-to-year comparisons unreliable.
+
+**3. Multi-temporal Machine Learning**  
+Models trained on Min-Max normalized multi-year data learn spurious patterns introduced by normalization rather than real spectral change. Z-Split ensures the training signal reflects actual surface conditions.
+
+**4. InSAR and Displacement Monitoring**  
+In LOS displacement data, zero means no movement. Shifting zero through Min-Max misclassifies stable pixels as deforming, directly corrupting subsidence or uplift maps.
+
+---
+
+## Validation
+
+### 1. NDWI — Optical Remote Sensing
+
+Tested on Sentinel-2 NDWI data. Z-Split successfully expanded near-zero clustered values while preserving the original image structure, producing contrast-enhanced output suitable for thresholding and multi-temporal comparison.
+
+### 2. Multi-Temporal Change Analysis — NDVI, Riyadh 2018–2024
+
+Validated on four Sentinel-2 NDVI scenes (March–April, 2018–2020–2022–2024) over Riyadh, Saudi Arabia (scale: 10 m, 5603 × 5129 pixels per scene) across 11,424 spatial patches.
+
+#### A. Normalization Artifact Analysis
+
+The figure below shows the deviation of each normalization method from the raw temporal signal. Min-Max introduces large artificial trends across the entire scene (colored map). Z-Split introduces virtually no deviation (near-white map).
+
+![Deviation Analysis](https://raw.githubusercontent.com/aalmoadi/endwi/main/Figures/deviation_analysis.png)
+
+| Method | Mean Absolute Deviation | Std |
+|--------|:-----------------------:|:---:|
+| Min-Max | 0.1858 | 0.2091 |
+| **Z-Split** | **0.0013** | **0.0017** |
+
+Z-Split preserves the temporal signal with **143× greater fidelity** than Min-Max.
+
+#### B. Linear Trend (Slope per pixel, 2018–2024)
+
+| Method | Mean Slope | Std | Correlation with Raw |
+|--------|:----------:|:---:|:--------------------:|
+| Raw (no normalization) | 0.000894 | 0.0165 | — |
+| Min-Max | 0.027454 | 0.2170 | r = 0.511 |
+| **Z-Split** | **−0.000120** | **0.0167** | **r = 0.995** |
+
+#### C. Multi-Temporal Change Maps
+
+The figure below compares Linear Trend, Anomaly, and Coefficient of Variation maps across all three methods. Z-Split maps are visually and statistically consistent with raw data; Min-Max maps show spatially inverted anomaly patterns and 5.5× inflated variability.
+
+![Change Analysis](https://raw.githubusercontent.com/aalmoadi/endwi/main/Figures/change_analysis.png)
+
+| Method | Mean CV |
+|--------|:-------:|
+| Raw | 0.150 |
+| **Z-Split** | **0.173** |
+| Min-Max | 0.832 |
+
+#### D. Threshold Stability (Otsu across 11,424 patches)
+
+| Method | Threshold Std |
+|--------|:-------------:|
+| Min-Max | 0.0882 |
+| Z-Split | 0.2220 |
+| Z-Score | 1.2012 |
+
+> **Note:** For strongly unipolar NDVI in arid urban areas, Min-Max threshold stability is comparable to Z-Split. Z-Split's primary advantage is in bipolar indices with narrow near-zero distributions (NDWI, InSAR LOS), consistent with its design objective.
+
+---
+
+## Application Scope
+
+Most effective when:
+- Values cluster near zero (NDWI in arid regions, InSAR LOS over stable terrain)
+- Multi-temporal consistency is required (change detection, time series analysis)
+- Otsu or zero-based thresholding is applied
+- Cross-scene or cross-sensor comparisons are performed
+
+---
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `zsplit_normalization.ipynb` | Jupyter Notebook with visual demonstration |
+| `zsplit_arcpy.py` | ArcGIS Pro implementation |
+| `Z-Split_Normalization/Validation/` | Multi-temporal NDVI change analysis |
+| `Validation/01_Optical_ENDWI/` | Optical NDWI validation |
+
+---
+
+## Author
+
+**Abdulrhman Almoadi**  
+King Abdulaziz City for Science and Technology (KACST)
+
+---
+
+## Citation
+
+If you use Z-Split, please cite:
+
+> Almoadi, A.: Reducing False Alarms in Urban Flood Detection: An Enhanced NDWI (ENDWI) with Hybrid Max Fusion on Sentinel-2 Data, EGUsphere [preprint], https://doi.org/10.5194/egusphere-2026-672, 2026.

{zsplit-1.0.0 → zsplit-1.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "zsplit"
-version = "1.0.0"
+version = "1.0.2"
 description = "Z-Split Normalization: Zero-Preserving Split Normalization for bipolar spectral indices"
 readme = "README.md"
 license = { file = "LICENSE" }

zsplit-1.0.2/zsplit.egg-info/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: zsplit
+Version: 1.0.2
+Summary: Z-Split Normalization: Zero-Preserving Split Normalization for bipolar spectral indices
+Author-email: Abdulrhman Almoadi <aalmoadi@kacst.edu.sa>
+License: MIT License
+        
+        Copyright (c) 2026 Abdulrhman Almoadi
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/aalmoadi/endwi
+Project-URL: Repository, https://github.com/aalmoadi/endwi
+Project-URL: Documentation, https://github.com/aalmoadi/endwi/tree/main/Z-Split_Normalization
+Project-URL: Bug Tracker, https://github.com/aalmoadi/endwi/issues
+Project-URL: DOI, https://doi.org/10.5281/zenodo.20602710
+Project-URL: Paper, https://doi.org/10.5194/egusphere-2026-672
+Keywords: normalization,remote-sensing,flood-detection,spectral-index,ENDWI,NDWI,bipolar,zero-preserving,Otsu,GIS,GeoAI,machine-learning,deep-learning,SAR,Sentinel-2
+Classifier: Development Status :: 5 - Production/Stable
+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: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Provides-Extra: raster
+Requires-Dist: rasterio>=1.2; extra == "raster"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: rasterio>=1.2; extra == "dev"
+Requires-Dist: matplotlib; extra == "dev"
+Dynamic: license-file
+
+# Z-Split Normalization (Zero-Preserving Split Normalization)
+
+**Version:** 1.0.1  
+**License:** MIT
+
+---
+
+## What is Z-Split?
+
+Z-Split **preserves zero as a fixed physical boundary** while **expanding narrow distributions clustered around zero** into the full [−1, 1] range — normalizing and expanding in a single operation. This prevents the low-contrast output common with near-zero indices and creates a well-formed distribution suitable for Otsu thresholding and multi-temporal analysis.
+
+---
+
+## Core Idea and Motivation
+
+Spectral indices and remote sensing operations often produce values clustered tightly around zero due to radiometric constraints, surface reflectance properties, or normalized difference formulations. Standard normalization compresses these values further, producing low-contrast images and unstable thresholds.
+
+Z-Split expands each side of zero independently into [−1, 0] and [0, 1], simultaneously normalizing and stretching narrow distributions. This preserves distributional contrast for reliable thresholding, maintains the zero boundary across scenes for stable multi-temporal comparison, and broadens the practical utility of spectral indices in analytical workflows where near-zero clustering would otherwise limit accuracy.
+
+---
+
+## The Problem
+
+Bipolar remote sensing indices share one property: **zero is a physical class boundary** (water/non-water, uplift/subsidence). Standard methods destroy it: Min-Max shifts zero into [0, 1]; Z-Score centers on the mean and produces an unbounded range. Both fail when values cluster near zero, making thresholding unreliable, multi-temporal comparisons artifact-driven, and in the worst case producing entirely empty, white, or black images due to values compressed around zero.
+
+---
+
+## The Solution — Z-Split
+
+Z-Split normalizes each side of zero **independently**, stretching the full negative range to [−1, 0] and the full positive range to [0, 1].
+
+### Formula
+
+$$
+Z\text{-}Split(x) =
+\begin{cases}
+x \;/\; \max(X^+) & \text{if } x > 0 \\
+0 & \text{if } x = 0 \\
+x \;/\; |\min(X^-)| & \text{if } x < 0
+\end{cases}
+$$
+
+where $X^+$ is the set of positive values and $X^-$ is the set of negative values.  
+**Output range:** [−1, 1] with zero strictly preserved.
+
+---
+
+## Why Z-Split?
+
+| Property | Min-Max | Z-Score | Z-Split |
+|----------|:-------:|:-------:|:-------:|
+| Preserves zero as class boundary | ❌ | ❌ | ✅ |
+| Expands narrow near-zero distributions | ❌ | ⚠️ | ✅ |
+| Stable on skewed distributions | ❌ | ⚠️ | ✅ |
+| Suitable for Otsu thresholding | ❌ | ⚠️ | ✅ |
+| Multi-temporal direction preserved | ❌ | ❌ | ✅ |
+| Output range | [0, 1] | Unbounded | [−1, 1] |
+
+---
+
+## Installation
+
+```bash
+pip install zsplit
+```
+
+## Quick Start
+
+```python
+from zsplit import normalize
+
+result = normalize(your_bipolar_index)
+```
+
+---
+
+## Practical Applications in Remote Sensing
+
+Z-Split addresses a critical problem in any workflow involving bipolar indices across time or sensors:
+
+**1. Change Detection**  
+Applying Min-Max before change detection introduces artificial trends that appear as land cover change but reflect only normalization artifacts. A report showing "15% vegetation decline" may be entirely attributable to normalization, not reality.
+
+**2. Time Series Analysis**  
+Studies tracking floods, drought, or urban expansion over time require a clean temporal signal. Min-Max corrupts this signal by rescaling each scene independently to [0, 1], making year-to-year comparisons unreliable.
+
+**3. Multi-temporal Machine Learning**  
+Models trained on Min-Max normalized multi-year data learn spurious patterns introduced by normalization rather than real spectral change. Z-Split ensures the training signal reflects actual surface conditions.
+
+**4. InSAR and Displacement Monitoring**  
+In LOS displacement data, zero means no movement. Shifting zero through Min-Max misclassifies stable pixels as deforming, directly corrupting subsidence or uplift maps.
+
+---
+
+## Validation
+
+### 1. NDWI — Optical Remote Sensing
+
+Tested on Sentinel-2 NDWI data. Z-Split successfully expanded near-zero clustered values while preserving the original image structure, producing contrast-enhanced output suitable for thresholding and multi-temporal comparison.
+
+### 2. Multi-Temporal Change Analysis — NDVI, Riyadh 2018–2024
+
+Validated on four Sentinel-2 NDVI scenes (March–April, 2018–2020–2022–2024) over Riyadh, Saudi Arabia (scale: 10 m, 5603 × 5129 pixels per scene) across 11,424 spatial patches.
+
+#### A. Normalization Artifact Analysis
+
+The figure below shows the deviation of each normalization method from the raw temporal signal. Min-Max introduces large artificial trends across the entire scene (colored map). Z-Split introduces virtually no deviation (near-white map).
+
+![Deviation Analysis](https://raw.githubusercontent.com/aalmoadi/endwi/main/Figures/deviation_analysis.png)
+
+| Method | Mean Absolute Deviation | Std |
+|--------|:-----------------------:|:---:|
+| Min-Max | 0.1858 | 0.2091 |
+| **Z-Split** | **0.0013** | **0.0017** |
+
+Z-Split preserves the temporal signal with **143× greater fidelity** than Min-Max.
+
+#### B. Linear Trend (Slope per pixel, 2018–2024)
+
+| Method | Mean Slope | Std | Correlation with Raw |
+|--------|:----------:|:---:|:--------------------:|
+| Raw (no normalization) | 0.000894 | 0.0165 | — |
+| Min-Max | 0.027454 | 0.2170 | r = 0.511 |
+| **Z-Split** | **−0.000120** | **0.0167** | **r = 0.995** |
+
+#### C. Multi-Temporal Change Maps
+
+The figure below compares Linear Trend, Anomaly, and Coefficient of Variation maps across all three methods. Z-Split maps are visually and statistically consistent with raw data; Min-Max maps show spatially inverted anomaly patterns and 5.5× inflated variability.
+
+![Change Analysis](https://raw.githubusercontent.com/aalmoadi/endwi/main/Figures/change_analysis.png)
+
+| Method | Mean CV |
+|--------|:-------:|
+| Raw | 0.150 |
+| **Z-Split** | **0.173** |
+| Min-Max | 0.832 |
+
+#### D. Threshold Stability (Otsu across 11,424 patches)
+
+| Method | Threshold Std |
+|--------|:-------------:|
+| Min-Max | 0.0882 |
+| Z-Split | 0.2220 |
+| Z-Score | 1.2012 |
+
+> **Note:** For strongly unipolar NDVI in arid urban areas, Min-Max threshold stability is comparable to Z-Split. Z-Split's primary advantage is in bipolar indices with narrow near-zero distributions (NDWI, InSAR LOS), consistent with its design objective.
+
+---
+
+## Application Scope
+
+Most effective when:
+- Values cluster near zero (NDWI in arid regions, InSAR LOS over stable terrain)
+- Multi-temporal consistency is required (change detection, time series analysis)
+- Otsu or zero-based thresholding is applied
+- Cross-scene or cross-sensor comparisons are performed
+
+---
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `zsplit_normalization.ipynb` | Jupyter Notebook with visual demonstration |
+| `zsplit_arcpy.py` | ArcGIS Pro implementation |
+| `Z-Split_Normalization/Validation/` | Multi-temporal NDVI change analysis |
+| `Validation/01_Optical_ENDWI/` | Optical NDWI validation |
+
+---
+
+## Author
+
+**Abdulrhman Almoadi**  
+King Abdulaziz City for Science and Technology (KACST)
+
+---
+
+## Citation
+
+If you use Z-Split, please cite:
+
+> Almoadi, A.: Reducing False Alarms in Urban Flood Detection: An Enhanced NDWI (ENDWI) with Hybrid Max Fusion on Sentinel-2 Data, EGUsphere [preprint], https://doi.org/10.5194/egusphere-2026-672, 2026.

zsplit-1.0.0/PKG-INFO

@@ -1,135 +0,0 @@
-Metadata-Version: 2.4
-Name: zsplit
-Version: 1.0.0
-Summary: Z-Split Normalization: Zero-Preserving Split Normalization for bipolar spectral indices
-Author-email: Abdulrhman Almoadi <aalmoadi@kacst.edu.sa>
-License: MIT License
-        
-        Copyright (c) 2026 Abdulrhman Almoadi
-        
-        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.
-        
-Project-URL: Homepage, https://github.com/aalmoadi/endwi
-Project-URL: Repository, https://github.com/aalmoadi/endwi
-Project-URL: Documentation, https://github.com/aalmoadi/endwi/tree/main/Z-Split_Normalization
-Project-URL: Bug Tracker, https://github.com/aalmoadi/endwi/issues
-Project-URL: DOI, https://doi.org/10.5281/zenodo.20602710
-Project-URL: Paper, https://doi.org/10.5194/egusphere-2026-672
-Keywords: normalization,remote-sensing,flood-detection,spectral-index,ENDWI,NDWI,bipolar,zero-preserving,Otsu,GIS,GeoAI,machine-learning,deep-learning,SAR,Sentinel-2
-Classifier: Development Status :: 5 - Production/Stable
-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: Programming Language :: Python :: 3.12
-Classifier: Topic :: Scientific/Engineering :: GIS
-Classifier: Topic :: Scientific/Engineering :: Image Processing
-Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: numpy>=1.20
-Provides-Extra: raster
-Requires-Dist: rasterio>=1.2; extra == "raster"
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: rasterio>=1.2; extra == "dev"
-Requires-Dist: matplotlib; extra == "dev"
-Dynamic: license-file
-
-# zsplit — Zero-Preserving Split Normalization
-
-[![PyPI version](https://badge.fury.io/py/zsplit.svg)](https://pypi.org/project/zsplit/)
-[![DOI](https://zenodo.org/badge/1037018439.svg)](https://doi.org/10.5281/zenodo.20602709)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-A normalization technique for **bipolar spectral indices** where **zero carries physical meaning as a class boundary** (e.g., water vs. non-water in flood detection).
-
-## Installation
-
-```bash
-pip install zsplit
-```
-
-With raster support:
-
-```bash
-pip install zsplit[raster]
-```
-
-## Quick Start
-
-```python
-import numpy as np
-from zsplit import normalize
-
-# Simulated raw ENDWI values (DN scale — extremely narrow range)
-arr = np.array([-0.00041, -0.00020, 0.0, 0.00008, 0.00015])
-
-result = normalize(arr)
-print(result)
-# [-1.     -0.488   0.      0.533   1.   ]
-```
-
-## Raster Support
-
-```python
-from zsplit import normalize_raster
-
-normalize_raster('ENDWI_raw.tif', 'ENDWI_zsplit.tif')
-```
-
-## Formula
-
-```
-         ⎧  x / max(X⁺)    if x > 0   →  [0,  1]
-Z(x)  =  ⎨  0               if x = 0   →  0 (preserved)
-         ⎩  x / |min(X⁻)|  if x < 0   →  [-1, 0]
-```
-
-## Why Z-Split?
-
-| Property | Min-Max | Z-Score | **Z-Split** |
-|---|---|---|---|
-| Preserves zero as class boundary | ❌ | ❌ | ✅ |
-| Stable on narrow near-zero ranges | ❌ | ⚠️ | ✅ |
-| Suitable for Otsu thresholding | ❌ | ⚠️ | ✅ |
-| Handles skewed distributions | ❌ | ⚠️ | ✅ |
-| Multi-temporal direction preserved | ❌ | ❌ | ✅ |
-| Output range | [0, 1] | Unbounded | **[−1, 1]** |
-
-## Citation
-
-```bibtex
-@article{almoadi2026endwi,
-  author  = {Almoadi, Abdulrhman},
-  title   = {Reducing False Alarms in Urban Flood Detection: An Enhanced NDWI (ENDWI)
-             with Hybrid Max Fusion on Sentinel-2 Data},
-  journal = {EGUsphere [preprint]},
-  year    = {2026},
-  doi     = {10.5194/egusphere-2026-672}
-}
-```
-
-## License
-
-MIT License

zsplit-1.0.0/README.md

@@ -1,77 +0,0 @@
-# zsplit — Zero-Preserving Split Normalization
-
-[![PyPI version](https://badge.fury.io/py/zsplit.svg)](https://pypi.org/project/zsplit/)
-[![DOI](https://zenodo.org/badge/1037018439.svg)](https://doi.org/10.5281/zenodo.20602709)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-A normalization technique for **bipolar spectral indices** where **zero carries physical meaning as a class boundary** (e.g., water vs. non-water in flood detection).
-
-## Installation
-
-```bash
-pip install zsplit
-```
-
-With raster support:
-
-```bash
-pip install zsplit[raster]
-```
-
-## Quick Start
-
-```python
-import numpy as np
-from zsplit import normalize
-
-# Simulated raw ENDWI values (DN scale — extremely narrow range)
-arr = np.array([-0.00041, -0.00020, 0.0, 0.00008, 0.00015])
-
-result = normalize(arr)
-print(result)
-# [-1.     -0.488   0.      0.533   1.   ]
-```
-
-## Raster Support
-
-```python
-from zsplit import normalize_raster
-
-normalize_raster('ENDWI_raw.tif', 'ENDWI_zsplit.tif')
-```
-
-## Formula
-
-```
-         ⎧  x / max(X⁺)    if x > 0   →  [0,  1]
-Z(x)  =  ⎨  0               if x = 0   →  0 (preserved)
-         ⎩  x / |min(X⁻)|  if x < 0   →  [-1, 0]
-```
-
-## Why Z-Split?
-
-| Property | Min-Max | Z-Score | **Z-Split** |
-|---|---|---|---|
-| Preserves zero as class boundary | ❌ | ❌ | ✅ |
-| Stable on narrow near-zero ranges | ❌ | ⚠️ | ✅ |
-| Suitable for Otsu thresholding | ❌ | ⚠️ | ✅ |
-| Handles skewed distributions | ❌ | ⚠️ | ✅ |
-| Multi-temporal direction preserved | ❌ | ❌ | ✅ |
-| Output range | [0, 1] | Unbounded | **[−1, 1]** |
-
-## Citation
-
-```bibtex
-@article{almoadi2026endwi,
-  author  = {Almoadi, Abdulrhman},
-  title   = {Reducing False Alarms in Urban Flood Detection: An Enhanced NDWI (ENDWI)
-             with Hybrid Max Fusion on Sentinel-2 Data},
-  journal = {EGUsphere [preprint]},
-  year    = {2026},
-  doi     = {10.5194/egusphere-2026-672}
-}
-```
-
-## License
-
-MIT License

zsplit-1.0.0/zsplit.egg-info/PKG-INFO

@@ -1,135 +0,0 @@
-Metadata-Version: 2.4
-Name: zsplit
-Version: 1.0.0
-Summary: Z-Split Normalization: Zero-Preserving Split Normalization for bipolar spectral indices
-Author-email: Abdulrhman Almoadi <aalmoadi@kacst.edu.sa>
-License: MIT License
-        
-        Copyright (c) 2026 Abdulrhman Almoadi
-        
-        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.
-        
-Project-URL: Homepage, https://github.com/aalmoadi/endwi
-Project-URL: Repository, https://github.com/aalmoadi/endwi
-Project-URL: Documentation, https://github.com/aalmoadi/endwi/tree/main/Z-Split_Normalization
-Project-URL: Bug Tracker, https://github.com/aalmoadi/endwi/issues
-Project-URL: DOI, https://doi.org/10.5281/zenodo.20602710
-Project-URL: Paper, https://doi.org/10.5194/egusphere-2026-672
-Keywords: normalization,remote-sensing,flood-detection,spectral-index,ENDWI,NDWI,bipolar,zero-preserving,Otsu,GIS,GeoAI,machine-learning,deep-learning,SAR,Sentinel-2
-Classifier: Development Status :: 5 - Production/Stable
-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: Programming Language :: Python :: 3.12
-Classifier: Topic :: Scientific/Engineering :: GIS
-Classifier: Topic :: Scientific/Engineering :: Image Processing
-Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: numpy>=1.20
-Provides-Extra: raster
-Requires-Dist: rasterio>=1.2; extra == "raster"
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: rasterio>=1.2; extra == "dev"
-Requires-Dist: matplotlib; extra == "dev"
-Dynamic: license-file
-
-# zsplit — Zero-Preserving Split Normalization
-
-[![PyPI version](https://badge.fury.io/py/zsplit.svg)](https://pypi.org/project/zsplit/)
-[![DOI](https://zenodo.org/badge/1037018439.svg)](https://doi.org/10.5281/zenodo.20602709)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-A normalization technique for **bipolar spectral indices** where **zero carries physical meaning as a class boundary** (e.g., water vs. non-water in flood detection).
-
-## Installation
-
-```bash
-pip install zsplit
-```
-
-With raster support:
-
-```bash
-pip install zsplit[raster]
-```
-
-## Quick Start
-
-```python
-import numpy as np
-from zsplit import normalize
-
-# Simulated raw ENDWI values (DN scale — extremely narrow range)
-arr = np.array([-0.00041, -0.00020, 0.0, 0.00008, 0.00015])
-
-result = normalize(arr)
-print(result)
-# [-1.     -0.488   0.      0.533   1.   ]
-```
-
-## Raster Support
-
-```python
-from zsplit import normalize_raster
-
-normalize_raster('ENDWI_raw.tif', 'ENDWI_zsplit.tif')
-```
-
-## Formula
-
-```
-         ⎧  x / max(X⁺)    if x > 0   →  [0,  1]
-Z(x)  =  ⎨  0               if x = 0   →  0 (preserved)
-         ⎩  x / |min(X⁻)|  if x < 0   →  [-1, 0]
-```
-
-## Why Z-Split?
-
-| Property | Min-Max | Z-Score | **Z-Split** |
-|---|---|---|---|
-| Preserves zero as class boundary | ❌ | ❌ | ✅ |
-| Stable on narrow near-zero ranges | ❌ | ⚠️ | ✅ |
-| Suitable for Otsu thresholding | ❌ | ⚠️ | ✅ |
-| Handles skewed distributions | ❌ | ⚠️ | ✅ |
-| Multi-temporal direction preserved | ❌ | ❌ | ✅ |
-| Output range | [0, 1] | Unbounded | **[−1, 1]** |
-
-## Citation
-
-```bibtex
-@article{almoadi2026endwi,
-  author  = {Almoadi, Abdulrhman},
-  title   = {Reducing False Alarms in Urban Flood Detection: An Enhanced NDWI (ENDWI)
-             with Hybrid Max Fusion on Sentinel-2 Data},
-  journal = {EGUsphere [preprint]},
-  year    = {2026},
-  doi     = {10.5194/egusphere-2026-672}
-}
-```
-
-## License
-
-MIT License