Skip to content

Connectivity analysis

JAXScape provides connectivity and sensitivity analysis utilities, based on the opiniated definition of ecological connectivity as the sum of ecological proximity, which can process large rasters efficiently using windowed operations. Users who want to obtain a finer control over the definition of ecological connectivity can use the lower-level window operations directly (see Window operations).

jaxscape.connectivity_analysis.ConnectivityAnalysis ¤

Compute landscape connectivity metrics for large rasters.

Quantifies connectivity by suming pairwise proximity in the graph. When quality-weighted, retrieves the quantity:

\[C = \sum_i \sum_{j \neq i} q_i \, K_{ij} \, q_j\]

where \(q_i\) is habitat quality at pixel \(i\) and \(K_{ij} = f(d_{ij})\) is the proximity between pixels based on distance \(d_{ij}\).

Uses windowed processing for memory efficiency. See WindowedAnalysis for windowing parameters and strategy.

Example

from jaxscape import ConnectivityAnalysis, LCPDistance import
jax.numpy as jnp

# Setup landscape D = 20  # Dispersal range distance = LCPDistance()
proximity = lambda dist: jnp.exp(-dist / D)

# Pad rasters to avoid edge effects quality_padded = jnp.pad(quality, D,
constant_values=0) permeability_padded = jnp.pad(permeability, D,
constant_values=0)

# Initialize analysis conn = ConnectivityAnalysis(
    quality_raster=quality_padded,
    permeability_raster=permeability_padded, distance=distance,
    proximity=proximity, dependency_range=D, coarsening_factor=0.2,
    batch_size=50
)

# Compute connectivity connectivity_index = conn.run(q_weighted=True)

Contiguity

The underlying graph is constructed using rook contiguity (4-neighbor connectivity), and edge weights are computed as the average permeability between adjacent pixels.

run(q_weighted: bool = True) -> Array ¤

Compute the connectivity metric across the landscape.

Arguments:

  • q_weighted: If True, compute quality-weighted connectivity (expected habitat amount). If False, compute unweighted proximity sum.

Returns:

Scalar landscape connectivity value.

jaxscape.connectivity_analysis.SensitivityAnalysis ¤

Compute connectivity sensitivity via automatic differentiation.

Calculates gradients \(\partial C / \partial q_i\) or \(\partial C / \partial p_i\) showing how connectivity responds to changes in habitat quality or permeability at each pixel. Uses JAX's automatic differentiation for efficient gradient computation.

Parameters and windowing strategy are identical to ConnectivityAnalysis.

Example

from jaxscape import SensitivityAnalysis, ResistanceDistance
import jax.numpy as jnp

# Setup (same as ConnectivityAnalysis)
D = 20
distance = ResistanceDistance()
proximity = lambda dist: jnp.exp(-dist / D)

sens = SensitivityAnalysis(
    quality_raster=quality_padded,
    permeability_raster=permeability_padded,
    distance=distance,
    proximity=proximity,
    dependency_range=D,
    coarsening_factor=0.2,
    batch_size=50
)

# Compute sensitivity gradients
d_quality = sens.run("quality", q_weighted=True)
d_permeability = sens.run("permeability", q_weighted=True)

# Identify conservation priorities
high_impact = d_quality > jnp.percentile(d_quality, 90)
run(var: str = 'quality', q_weighted: bool = True) -> Array ¤

Compute connectivity gradients with respect to a landscape parameter.

Arguments:

  • var: Parameter to differentiate: "quality" or "permeability".
  • q_weighted: If True, compute quality-weighted connectivity gradients. If False, compute unweighted gradients.

Returns:

Gradient raster with the same shape as the input, showing sensitivity at each pixel.