parammadrz 2.5.1

Parallel Rao's Q Visualization and Analysis — Spectral indices, Rao's Q diversity, raster visualization

PaRaVis

Parallel Rao's Q Visualization and Analysis

A cross-platform Python library and desktop GUI for spectral index computation, Rao's Q diversity analysis, and raster data visualization. PaRaVis combines a professional PySide6 interface with a lightweight headless API — equally at home in interactive exploration and automated HPC batch pipelines.

---

Features

• 190+ Spectral Indices — NDVI, EVI, SAVI, NDWI, NBR, BAI, and more via Spyndex. Register custom indices with the @register_index decorator.
• Rao's Q Diversity — Moving-window quadratic entropy with three backends: CPU (NumPy), multi-core parallel (ProcessPoolExecutor), and GPU-accelerated (CuPy + custom CUDA RawKernel).
• 6 Distance Metrics — Euclidean, Manhattan, Chebyshev, Minkowski, Canberra, and Bray-Curtis — all supported on every backend.
• Raster I/O — Automatic downsampling for large files, LZW-compressed GeoTIFF output, multi-band support.
• Desktop GUI — Three-panel layout, drag-and-drop, light/dark themes, splash screen, full-screen mode, and persistent settings.
• Headless API — Zero-Qt core modules usable in scripts, notebooks, and HPC clusters.

---

Quick Start

pip install paravis[gui]         # install with GUI
paravis                          # launch the desktop app

from paravis.api import compute_indices, compute_rao_q

# Compute vegetation indices
results = compute_indices("scene.tif", indices=["NDVI", "EVI"])
print(results["NDVI"].mean())

# Rao's Q diversity (auto-selects GPU if available)
diversity = compute_rao_q("scene.tif", window_size=15, backend="auto")

---

Installation

pip install paravis               # headless (scripts, notebooks, HPC)
pip install paravis[gui]          # + desktop GUI
pip install paravis[gpu]          # + GPU acceleration (needs NVIDIA + CUDA)
pip install paravis[gui,gpu,dev]  # everything

Dependencies

Package	Minimum	Needed for
numpy	≥1.21	Core arrays
rasterio	≥1.3	GeoTIFF I/O
spyndex	≥0.4	Spectral index formulas
matplotlib	≥3.5	Plotting
seaborn	≥0.12	Statistical visualisations
psutil	≥5.0	CPU/RAM detection
PySide6	≥6.5	Desktop GUI ([gui])
cupy	≥12.0	GPU Rao's Q ([gpu])

Note: rasterio requires the GDAL system library. On Linux: apt install libgdal-dev. On Windows/macOS the pip wheel includes it.

---

How Rao's Q Works

Rao's Quadratic Entropy measures spectral diversity using a species-abundance approach: identical spectral profiles in a window are treated as the same "species", their frequencies counted, and pairwise spectral distances are weighted by relative abundance:

$$Q = \sum_{i=1}^{S} \sum_{j=1}^{S} d_{ij} \cdot p_i \cdot p_j$$

Where $S$ = unique profiles (species), $d_{ij}$ = spectral distance between species $i$ and $j$, $p_i$ = relative abundance of species $i$.

The simplify parameter controls input truncation precision before species identification — higher precision means more distinct species detected, yielding a more detailed diversity map but at greater computational cost.

Six distance metrics are available: Euclidean, Manhattan, Chebyshev, Minkowski (tunable $p$), Canberra, and Bray-Curtis. All work on every backend.

→ Full theory, formulas, and parameter details in docs/user_guide.md

---

Backends

Backend	Command	Best for
CPU (NumPy)	backend="cpu"	Small rasters, any hardware
Parallel CPU	backend="parallel"	Multi-core workstations, HPC nodes
GPU (CUDA kernel)	backend="gpu" or "auto"	Large rasters, NVIDIA GPUs

All three implement the identical species-abundance formula, producing bitwise-comparable results. The GPU uses three automatic paths: a fast shared-memory CUDA kernel, a per-thread fallback kernel, and a pure CuPy fallback if compilation fails.

→ Full backend comparison and GPU architecture in docs/user_guide.md

---

API Overview

from paravis.api import (
    compute_indices,      # → dict of 2D arrays
    compute_index,        # → single 2D array
    compute_rao_q,        # → 2D Rao's Q map
    plot_raster,          # → (figure, axes)
    plot_comparison,      # → (figure, axes)
    list_available_indices, # → list of index names
)

# Spectral indices with custom band mapping
compute_indices("sentinel2.tif", indices=["NDVI", "NDWI"],
                band_mapping={4: "R", 8: "N"})

# Rao's Q with full control
compute_rao_q("scene.tif", window_size=11, na_tolerance=0.3,
              backend="parallel", n_workers=8,
              simplify=2, distance_metric="braycurtis")

# Read / write rasters
from paravis.core.raster import read_raster, write_geotiff
data, transform, crs = read_raster("input.tif")
write_geotiff(result, "output.tif", transform=transform, crs=crs)

→ Full API reference with all parameters in docs/user_guide.md

---

Desktop GUI

paravis                    # launch
python -m paravis.gui.app  # or via module

Three-panel layout: Left — controls and index selection, Centre — Rao's Q processing, Right — visualisation with five plot modes (individual, stats, diff+heatmap, split comparison, time series with GIF export). Light/dark themes, keyboard shortcuts, persistent settings.

→ Full GUI walkthrough in docs/user_guide.md

---

System Requirements

• Python ≥ 3.9
• RAM: 4 GB minimum, 8 GB recommended for GUI
• GPU (optional): NVIDIA with Compute Capability 6.0+, driver ≥ 450.0, CuPy ≥ 12.0

---

Citation

@software{paravis2026,
  author = {{PaRaVis Contributors}},
  title = {PaRaVis: Parallel Rao's Q Visualization and Analysis},
  year = {2026},
  version = {2.0.1},
  url = {https://github.com/mmadrz/paravis}
}