paravis 2.0.0

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

PaRaVis

Parallel Rao's Q Visualization

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

• 200+ 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 — Downsampling for large files, LZW-compressed GeoTIFF output, multi-band support.
• Desktop GUI — Three-panel layout, light/dark themes, splash screen, and full-screen mode for a better experience.
• 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 (see note below)
pip install paravis[gui,gpu,dev]  # everything

> **GPU prerequisite:** `paravis[gpu]` installs [CuPy](https://github.com/cupy/cupy), which requires the **NVIDIA CUDA Toolkit** on your system. Check your CUDA version with `nvcc --version`, then install the matching variant manually if `pip install paravis[gpu]` fails:
> ```bash
> pip install cupy-cuda12x   # for CUDA 12.x
> pip install cupy-cuda11x   # for CUDA 11.x
> ```
> See the [CuPy installation guide](https://docs.cupy.dev/en/stable/install.html) for details.

---

Dependencies

Core	Optional

[!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 within a local neighbourhood using a moving-window approach: for each window, the spectral distance between every pair of pixels is weighted by their relative abundances:

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

Where $N$ = total number of pixels within a window, $p_i$ and $p_j$ = relative abundances for pixel $i$ and $j$, and $d_{ij}$ = pairwise spectral distance between pixel $i$ and $j$.

Instead of comparing every pair of pixels directly, PaRaVis first groups pixels with identical spectral profiles, then computes distances between unique profiles weighted by how many pixels share each profile. This is far more efficient — a 15×15 window (225 pixels) may have only 10 unique spectral profiles, requiring just $\binom{10}{2}=45$ distance calculations instead of $\binom{225}{2}=25{,}200$.

The simplify Parameter

The simplify parameter (range 0–6, default 2) controls how precisely pixel values must match before being considered spectrally identical. Before grouping, all values are truncated (not rounded) to the given number of decimal places — so 0.1234567 becomes 0.12 at simplify=2. Two pixels are only grouped together if their spectral profiles match exactly after truncation.

• 0 — no truncation; keeps full float32 precision → most distinct spectral profiles, slowest computation, finest detail
• 1 — most aggressive truncation → fewest distinct profiles, fastest computation, coarsest diversity map
• 2 (default) — good balance for most analyses
• 3–6 — progressively more decimal places retained → more distinct profiles detected, richer detail, slower computation

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/guide.md

---

Backends

Backend	Command	Use case
CPU (NumPy)	backend="cpu"	Small rasters (< 1000×1000 px), any hardware, limited RAM
Parallel CPU	backend="parallel"	Multi-core workstations, HPC nodes, medium-to-large rasters
GPU (CUDA kernel)	backend="gpu" or "auto"	Large rasters (> 1000×1000 px), NVIDIA GPUs, batch processing

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/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/guide.md

---

Desktop GUI

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

Left	Centre	Right
Browse 200+ spectral indices from Spyndex, configure band-to-raster mapping, set output options and parallel workers, then run batch index computation with progress tracking.	Compute Rao's Quadratic Entropy diversity maps in single or batch mode. Choose GPU/CPU backend, configure distance metric, window size, simplify precision, and NA tolerance with real-time speed feedback.	Load computed rasters and generate individual plots, statistics (box/histogram/KDE/violin), difference heatmaps, side-by-side split views, or time-series GIF animations. Customise colormaps, DPI, and output format.

Light/dark themes, keyboard shortcuts, persistent settings.

→ Full GUI walkthrough in docs/guide.md

---

Platform Support

Linux	Windows	macOS
✅ Full support (GUI, CPU, GPU). Requires libgdal-dev for raster I/O.	✅ Full support (GUI, CPU, GPU). Self-contained pip wheels.	✅ GUI, CPU, and headless API work. GPU acceleration not available (no NVIDIA GPUs) — falls back to CPU. Self-contained pip wheels.

[!NOTE] GPU acceleration requires the NVIDIA CUDA Toolkit. On Linux/Windows, install the matching CuPy variant (e.g. cupy-cuda12x).

---

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

If PaRaVis contributes to your research, please cite:

@article{FATHI2024102739,
  title = {PaRaVis: An automatic Python graphical package for ensemble analysis of plant beta diversity using remote sensing proxies},
  journal = {Ecological Informatics},
  volume = {82},
  pages = {102739},
  year = {2024},
  issn = {1574-9541},
  doi = {10.1016/j.ecoinf.2024.102739},
  url = {https://www.sciencedirect.com/science/article/pii/S1574954124002814},
  author = {Mohammad Reza Fathi and Hooman Latifi and Hamed Gholizadeh and Siddhartha Khare},
}