Repository Mirror for your Cloud Server and Webhosting

Title:

Information Theory, Geometry and Statistics for Synthetic Aperture Radar Data

Version:

1.0.0

Description:

Statistical models, information-theoretic measures and image analysis tools for Synthetic Aperture Radar (SAR) and polarimetric SAR (PolSAR) data. It implements intensity models (Gamma, generalized Gamma and G0I) and matrix models (scaled complex Wishart, G0 polarimetric and the compound truncated Poisson and compound geometric complex Wishart laws), maximum likelihood and expectation-maximization estimation, closed-form Shannon entropies with their asymptotic variances, entropy-based hypothesis tests and change detection, entropy-based image segmentation by (stochastic) expectation-maximization, stochastic distances and a family of divergence-based classifiers (Kullback-Leibler, Jeffreys, Bhattacharyya and Renyi) for Gaussian vector features and complex Wishart matrix features. The main tools are 'R6' classes and the classifiers are available as a 'parsnip' model, so they can be used inside 'tidymodels' workflows. Methods are described in Ferreira, Coelho and Nascimento (2021) <doi:10.1080/01431161.2020.1826060>, Ferreira and Nascimento (2020) <doi:10.1109/JSTARS.2020.2997666>, Ferreira, Nascimento and Frery (2022) <doi:10.3390/rs14205083> and Nascimento, Ferreira and Frery (2023) <doi:10.1007/s11222-023-10298-0>.

License:

MIT + file LICENSE

URL:

https://github.com/jodavid/SITSAR, https://jodavid.github.io/SITSAR/

BugReports:

https://github.com/jodavid/SITSAR/issues

Depends:

R (≥ 4.1.0)

Imports:

generics, graphics, grDevices, parsnip (≥ 1.0.0), R6 (≥ 2.5.0), rlang, stats, tibble, utils

Suggests:

dials, knitr, recipes, rmarkdown, rsample, testthat (≥ 3.0.0), tune, workflows, yardstick

VignetteBuilder:

knitr

Config/testthat/edition:

Encoding:

UTF-8

Language:

en-US

LazyData:

true

LazyDataCompression:

Config/roxygen2/version:

8.1.0

NeedsCompilation:

Packaged:

2026-10-22 21:11:02 UTC; jodavid

Author:

Jodavid Ferreira

[aut, cre], Abraao Nascimento

[aut]

Maintainer:

Jodavid Ferreira <jodavid@protonmail.com>

Repository:

CRAN

Date/Publication:

2026-11-06 16:20:02 UTC

SITSAR: Information Theory, Geometry and Statistics for SAR Data

Description

Statistical models, information-theoretic measures and image analysis tools for Synthetic Aperture Radar (SAR) and polarimetric SAR (PolSAR) data, gathering the methods developed in the master's dissertation (divergence-based classifiers) and the PhD thesis (Shannon entropies, entropy-based segmentation and change detection, and compound Wishart models) of Jodavid A. Ferreira, supervised by Abraão D. C. Nascimento.

Main tools

Distributions: dg0i, dgammasar, dggamma, dwishart_sar, dg0p, compound_wishart.
R6 models: GammaSAR, G0I, GGammaSAR, WishartSAR, G0Polarimetric, CompoundWishart (estimation, entropy and asymptotic variance).
Images: SARImage, sar_features(), entropy_map(), plot_map().
Segmentation and change detection: EntropySegmenter, segment_sar(), entropy_test(), change_map().
Classification: divergences, DivergenceClassifier and the 'parsnip' model divergence_classifier().
Accuracy: kappa_statistics(), change_detection_metrics().

Author(s)

Maintainer: Jodavid Ferreira jodavid@protonmail.com (ORCID)

Authors:

Jodavid Ferreira jodavid@protonmail.com (ORCID)
Abraao Nascimento abraao@de.ufpe.br (ORCID)

Compound complex Wishart models (R6)

Description

R6 class for the compound truncated Poisson (CTPCW) and compound geometric (CGCW) complex Wishart laws of Ferreira, Nascimento and Frery (2022); see dctpcw(). Parameters are estimated by the expectation-maximisation (EM) algorithm, treating the number of scatterers N as missing data:

E-step: \hat N_i = E(N \mid S_i);
M-step: \hat\Sigma = \bar S / (L \bar N) and \hat\lambda/(1 - e^{-\hat\lambda}) = \bar N (CTPCW) or \hat p = 1/\bar N (CGCW).

The Shannon entropy has no closed form and is approximated by Monte Carlo.

Value

An R6::R6Class generator. CompoundWishart$new() returns a new CompoundWishart object; its methods are described in the Methods section below.

Super class

SARModel -> CompoundWishart

Public fields

counting: Counting law: "poisson" (zero-truncated) or "geometric".
iterations: Number of EM iterations of the last fit.

Methods

Inherited methods

`CompoundWishart$new()`

Create a compound Wishart model.

Usage

CompoundWishart$new(
  counting = c("poisson", "geometric"),
  Sigma = diag(3) + (0+0i),
  L = 4,
  lambda = 1,
  p = 0.5
)

Arguments

counting: "poisson" (CTPCW) or "geometric" (CGCW).
Sigma: Hermitian positive definite matrix.
L: Number of looks of each component.
lambda, p: Parameter of the counting law.

`CompoundWishart$density()`

(Log-)density.

Usage

CompoundWishart$density(x, log = FALSE)

Arguments

x: PolSAR observations.
log: Return log-densities?

`CompoundWishart$random()`

Simulate PolSAR observations.

Usage

CompoundWishart$random(n, output = "array")

Arguments

n: Number of observations.
output: "array" or "vec".

`CompoundWishart$fit()`

Fit by the EM algorithm.

Usage

CompoundWishart$fit(x, L, tol = 1e-06, max_iter = 500L)

Arguments

x: PolSAR observations.
L: Known number of looks of each component.
tol: Convergence tolerance (relative change of the parameters).
max_iter: Maximum number of iterations.

`CompoundWishart$entropy()`

Monte Carlo approximation of the Shannon entropy.

Usage

CompoundWishart$entropy(nsim = 2000L)

Arguments

nsim: Number of simulated observations.

`CompoundWishart$entropy_variance()`

Not available for compound models.

Usage

CompoundWishart$entropy_variance(n = self$n)

Arguments

n: Ignored.

`CompoundWishart$clone()`

The objects of this class are cloneable with this method.

Usage

CompoundWishart$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

Ferreira, J. A., Nascimento, A. D. C. and Frery, A. C. (2022). PolSAR models with multimodal intensities. Remote Sensing, 14(20), 5083. doi:10.3390/rs14205083

Examples

set.seed(1)
S <- rctpcw(200, lambda = 1.5, Sigma = polsar_example_sigma("forest"), L = 4)
m <- CompoundWishart$new(counting = "poisson")$fit(S, L = 4)
m$params$lambda
m$iterations

Divergence-based classifier for SAR/PolSAR features (R6)

Description

Implements the family of divergence-based classifiers of Ferreira, Coelho and Nascimento (2021). Each pixel is represented by the model fitted to the observations of a moving window (see sar_features()) and each class by the model fitted to its training pixels. A pixel is assigned to the class that minimises the chosen divergence between the two fitted models:

\hat\imath = \arg\min_{i \in \{1, \ldots, g\}} d(\hat\theta_h, \hat\theta_i).

Two families of features are available:

"gaussian": multivariate normal laws for the intensity vector, using the columns ⁠mean_*⁠ and ⁠cov_*⁠ of sar_features(). The class covariance combines the average local covariance and the covariance of the local means (law of total variance).
"wishart": scaled complex Wishart laws for the full PolSAR covariance matrix, using the columns c11, c12_re, c12_im, ... of sar_features(). Since all laws share the number of looks, it only rescales the divergences and does not affect the classification.

The classifier is also available as the 'parsnip' model divergence_classifier(), for use in 'tidymodels' workflows.

Value

An R6::R6Class generator. DivergenceClassifier$new() returns a new DivergenceClassifier object; its methods are described in the Methods section below.

Public fields

family: "gaussian" or "wishart".
divergence: Divergence used (see divergence_gaussian()).
order: Order of the Rényi divergence.
kind: Form (1-4) of the Rényi divergence.
classes: Class labels.
prototypes: List with the fitted model of each class.
channels: Channels (Gaussian) or matrix order (Wishart) used.

Methods

Public methods

DivergenceClassifier$new()
DivergenceClassifier$fit()
DivergenceClassifier$distances()
DivergenceClassifier$predict()
DivergenceClassifier$print()
DivergenceClassifier$clone()

`DivergenceClassifier$new()`

Create a classifier.

Usage

DivergenceClassifier$new(
  family = c("gaussian", "wishart"),
  divergence = c("renyi", "kl", "jeffreys", "bhattacharyya"),
  order = 0.5,
  kind = 1
)

Arguments

family: "gaussian" or "wishart".
divergence: "kl", "jeffreys", "bhattacharyya" or "renyi".
order: Order of the Rényi divergence, in (0, 1).
kind: Form of the Rényi divergence (1 to 4).

`DivergenceClassifier$fit()`

Fit the class prototypes.

Usage

DivergenceClassifier$fit(x, y)

Arguments

x: Data frame of features (see sar_features()); other columns are ignored.
y: Factor (or vector) of class labels.

`DivergenceClassifier$distances()`

Divergence between every row of x and every class.

Usage

DivergenceClassifier$distances(x)

Arguments

x: Data frame of features.

`DivergenceClassifier$predict()`

Predict classes, pseudo-probabilities or distances.

Usage

DivergenceClassifier$predict(x, type = c("class", "prob", "distance"))

Arguments

x: Data frame of features.
type: "class", "prob" (softmax of minus the divergences) or "distance".

`DivergenceClassifier$print()`

Print the classifier.

Usage

DivergenceClassifier$print(...)

Arguments

...: Ignored.

`DivergenceClassifier$clone()`

The objects of this class are cloneable with this method.

Usage

DivergenceClassifier$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

Ferreira, J. A., Coelho, H. and Nascimento, A. D. C. (2021). A family of divergence-based classifiers for polarimetric synthetic aperture radar (PolSAR) imagery vector and matrix features. International Journal of Remote Sensing, 42(4), 1201–1229. doi:10.1080/01431161.2020.1826060

Examples

img <- SARImage$new(SanFrancisco150)$crop(1:80, 1:80)
feats <- sar_features(img, window = 5)
feats$class <- factor(as.vector(SanFrancisco150_gt[1:80, 1:80]),
                      labels = c("ocean", "forest", "urban"))
set.seed(1)
train <- feats[sample(nrow(feats), 300), ]

clf <- DivergenceClassifier$new(family = "wishart", divergence = "renyi",
                                order = 0.5, kind = 3)
clf$fit(train, train$class)
pred <- clf$predict(feats)
mean(pred == feats$class)
head(clf$predict(feats, type = "distance"))

Entropy-based segmentation by (stochastic) EM (R6)

Description

Unsupervised segmentation of SAR/PolSAR images from maps of estimated Shannon entropies (Ferreira and Nascimento, 2020; Nascimento, Ferreira and Frery, 2023). By the asymptotic normality of the entropy estimators, the entropy vector of a pixel of the g-th region is approximately Gaussian, so the image is modelled as a finite mixture of Gaussian laws (with diagonal covariance matrices) fitted by the expectation-maximisation algorithm (method = "em") or by its stochastic version (method = "sem"), in which the E-step is followed by a random allocation of every pixel to a class drawn from its posterior probabilities. Pixels are then labelled by the maximum a posteriori rule.

Value

An R6::R6Class generator. EntropySegmenter$new() returns a new EntropySegmenter object; its methods are described in the Methods section below.

Public fields

k: Number of classes.
method: "em" or "sem".
weights: Mixture weights.
means: Matrix (⁠k x features⁠) of class means.
variances: Matrix (⁠k x features⁠) of class variances.
posterior: Matrix of posterior probabilities.
labels: Integer vector of labels (classes ordered by the mean of the first feature).
loglik: Trace of the log-likelihood.
iterations: Number of iterations.
converged: Logical convergence flag.
dim: Spatial dimensions when fitted to a map (NULL otherwise).

Methods

Public methods

EntropySegmenter$new()
EntropySegmenter$fit()
EntropySegmenter$predict()
EntropySegmenter$label_map()
EntropySegmenter$print()
EntropySegmenter$clone()

`EntropySegmenter$new()`

Create a segmenter.

Usage

EntropySegmenter$new(
  k = 2,
  method = c("em", "sem"),
  max_iter = 200L,
  tol = 1e-08
)

Arguments

k: Number of classes.
method: "em" or "sem".
max_iter: Maximum number of iterations.
tol: Tolerance for the relative change of the log-likelihood.

`EntropySegmenter$fit()`

Fit the mixture.

Usage

EntropySegmenter$fit(x, init = NULL, is_map = TRUE)

Arguments

x: Entropy features: a matrix (one map, or pixels in rows and features in columns when is_map = FALSE), an array ⁠nrow x ncol x features⁠ (several maps), or a numeric vector.
init: Initial labels (integer vector) or NULL for k-means.
is_map: Treat a matrix x as a single map? Default TRUE.

`EntropySegmenter$predict()`

Labels of new observations (maximum a posteriori).

Usage

EntropySegmenter$predict(x, is_map = TRUE)

Arguments

x: Entropy features in the same format used in ⁠$fit()⁠.
is_map: Treat a matrix x as a single map?

`EntropySegmenter$label_map()`

Labels as a matrix with the spatial dimensions of the fitted map.

Usage

EntropySegmenter$label_map()

`EntropySegmenter$print()`

Print a summary.

Usage

EntropySegmenter$print(...)

Arguments

...: Ignored.

`EntropySegmenter$clone()`

The objects of this class are cloneable with this method.

Usage

EntropySegmenter$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

Ferreira, J. A. and Nascimento, A. D. C. (2020). Shannon entropy for the G0I model: a new segmentation approach. IEEE Journal of Selected Topics in Applied Earth Observations and Remote Sensing, 13, 2547–2553. doi:10.1109/JSTARS.2020.2997666

Nascimento, A. D. C., Ferreira, J. A. and Frery, A. C. (2023). Unsupervised segmentation of PolSAR data with complex Wishart and G0m distributions and Shannon entropy. Statistics and Computing, 33, 129. doi:10.1007/s11222-023-10298-0

Examples

H <- entropy_map(SanFrancisco150, model = "wishart", window = 7, L = 4)
set.seed(1)
seg <- EntropySegmenter$new(k = 3)$fit(H)
seg
plot_map(seg$label_map(), main = "Entropy-based segmentation")
kappa_statistics(SanFrancisco150_gt, seg$label_map())

G0I model for SAR intensities (R6)

Description

R6 class for the \mathcal{G}_I^0(\alpha, \gamma, L) law (see dg0i()) with maximum likelihood estimation (analytic score, quasi-Newton optimisation on a transformed scale with several starting points), closed-form Shannon entropy (Ferreira and Nascimento, 2020) and the asymptotic variance of its estimator.

Value

An R6::R6Class generator. G0I$new() returns a new G0I object; its methods are described in the Methods section below.

Super class

SARModel -> G0I

Methods

Public methods

G0I$new()
G0I$density()
G0I$random()
G0I$fit()
G0I$entropy()
G0I$clone()

Inherited methods

`G0I$new()`

Create a G0I model.

Usage

G0I$new(alpha = -2, gamma = 1, L = 1)

Arguments

alpha: Roughness (< 0).
gamma: Scale (> 0).
L: Number of looks (> 0).

`G0I$density()`

(Log-)density.

Usage

G0I$density(x, log = FALSE)

Arguments

x: Numeric vector of intensities.
log: Return log-densities?

`G0I$random()`

Simulate intensities.

Usage

G0I$random(n)

Arguments

n: Number of observations.

`G0I$fit()`

Fit by maximum likelihood.

Usage

G0I$fit(x, L = NULL, start = NULL)

Arguments

x: Numeric vector of positive intensities.
L: Known number of looks. If NULL (default) it is estimated.
start: Optional named vector of starting values (alpha, gamma and, if estimated, L).

`G0I$entropy()`

Shannon entropy.

Usage

G0I$entropy()

`G0I$clone()`

The objects of this class are cloneable with this method.

Usage

G0I$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

Examples

set.seed(1)
z <- rg0i(1000, alpha = -3, gamma = 2, L = 4)
m <- G0I$new()$fit(z, L = 4)
m
m$entropy_variance()
G0I$new()$fit(z)$params # L estimated

G0 polarimetric model for PolSAR data (R6)

Description

R6 class for the \mathcal{G}^0_m(\alpha, \Sigma, L) law (see dg0p()). Following Nascimento, Ferreira and Frery (2023), \Sigma is estimated by the sample mean (since E(Z) = \Sigma) and (\alpha, L) by maximising the likelihood (analytic score). The variance of the entropy estimator combines the inverse observed information of (\alpha, L) with a moment estimate of the variance of m\log|\hat\Sigma|.

Value

An R6::R6Class generator. G0Polarimetric$new() returns a new G0Polarimetric object; its methods are described in the Methods section below.

Super class

SARModel -> G0Polarimetric

Methods

Public methods

G0Polarimetric$new()
G0Polarimetric$density()
G0Polarimetric$random()
G0Polarimetric$fit()
G0Polarimetric$entropy()
G0Polarimetric$clone()

Inherited methods

`G0Polarimetric$new()`

Create a G0 polarimetric model.

Usage

G0Polarimetric$new(alpha = -3, Sigma = diag(3) + (0+0i), L = 4)

Arguments

alpha: Roughness (< -1).
Sigma: Hermitian positive definite matrix.
L: Number of looks.

`G0Polarimetric$density()`

(Log-)density.

Usage

G0Polarimetric$density(x, log = FALSE)

Arguments

x: PolSAR observations.
log: Return log-densities?

`G0Polarimetric$random()`

Simulate PolSAR observations.

Usage

G0Polarimetric$random(n, output = "array")

Arguments

n: Number of observations.
output: "array" or "vec".

`G0Polarimetric$fit()`

Fit by maximum likelihood.

Usage

G0Polarimetric$fit(x, L = NULL)

Arguments

x: PolSAR observations.
L: Known number of looks. If NULL (default) it is estimated.

`G0Polarimetric$entropy()`

Shannon entropy.

Usage

G0Polarimetric$entropy()

`G0Polarimetric$clone()`

The objects of this class are cloneable with this method.

Usage

G0Polarimetric$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Examples

set.seed(1)
Z <- rg0p(400, alpha = -4, Sigma = polsar_example_sigma("urban"), L = 4)
m <- G0Polarimetric$new()$fit(Z, L = 4)
m
m$entropy_variance()

Generalized Gamma model for SAR intensities (R6)

Description

R6 class for the generalized Gamma law (see dggamma()). Estimation is carried out by profiling: for a given power \alpha, the maximum likelihood estimates of \phi and \mu are available in closed form (up to a one-dimensional root), so the profile likelihood is maximised over \alpha only.

Value

An R6::R6Class generator. GGammaSAR$new() returns a new GGammaSAR object; its methods are described in the Methods section below.

Super class

SARModel -> GGammaSAR

Methods

Public methods

GGammaSAR$new()
GGammaSAR$density()
GGammaSAR$random()
GGammaSAR$fit()
GGammaSAR$entropy()
GGammaSAR$clone()

Inherited methods

`GGammaSAR$new()`

Create a generalized Gamma model.

Usage

GGammaSAR$new(alpha = 1, phi = 1, mu = 1)

Arguments

alpha: Power (> 0).
phi: Shape (> 0).
mu: Inverse scale (> 0).

`GGammaSAR$density()`

(Log-)density.

Usage

GGammaSAR$density(x, log = FALSE)

Arguments

x: Numeric vector of intensities.
log: Return log-densities?

`GGammaSAR$random()`

Simulate intensities.

Usage

GGammaSAR$random(n)

Arguments

n: Number of observations.

`GGammaSAR$fit()`

Fit by (profile) maximum likelihood.

Usage

GGammaSAR$fit(x, phi = NULL)

Arguments

x: Numeric vector of positive intensities.
phi: Known shape (number of looks). If NULL it is estimated.

`GGammaSAR$entropy()`

Shannon entropy.

Usage

GGammaSAR$entropy()

`GGammaSAR$clone()`

The objects of this class are cloneable with this method.

Usage

GGammaSAR$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Examples

set.seed(1)
z <- rggamma(1000, alpha = 1.5, phi = 3, mu = 2)
m <- GGammaSAR$new()$fit(z)
m

Gamma model for SAR intensities (R6)

Description

R6 class for the multilook Gamma law \Gamma(\mu, L); see dgammasar(). The maximum likelihood estimator of \mu is the sample mean and L solves \log L - \psi^{(0)}(L) = \log\bar z - \overline{\log z}.

Value

An R6::R6Class generator. GammaSAR$new() returns a new GammaSAR object; its methods are described in the Methods section below.

Super class

SARModel -> GammaSAR

Methods

Public methods

GammaSAR$new()
GammaSAR$density()
GammaSAR$random()
GammaSAR$fit()
GammaSAR$entropy()
GammaSAR$entropy_variance()
GammaSAR$clone()

Inherited methods

`GammaSAR$new()`

Create a Gamma model.

Usage

GammaSAR$new(mu = 1, L = 1)

Arguments

mu: Mean.
L: Number of looks.

`GammaSAR$density()`

(Log-)density.

Usage

GammaSAR$density(x, log = FALSE)

Arguments

x: Numeric vector of intensities.
log: Return log-densities?

`GammaSAR$random()`

Simulate intensities.

Usage

GammaSAR$random(n)

Arguments

n: Number of observations.

`GammaSAR$fit()`

Fit by maximum likelihood.

Usage

GammaSAR$fit(x, L = NULL)

Arguments

x: Numeric vector of positive intensities.
L: Known number of looks. If NULL (default) it is estimated.

`GammaSAR$entropy()`

Shannon entropy.

Usage

GammaSAR$entropy()

`GammaSAR$entropy_variance()`

Asymptotic variance of the entropy estimator (closed form).

Usage

GammaSAR$entropy_variance(n = self$n)

Arguments

n: Sample size.

`GammaSAR$clone()`

The objects of this class are cloneable with this method.

Usage

GammaSAR$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Examples

set.seed(1)
z <- rgammasar(500, mu = 2, L = 4)
m <- GammaSAR$new()$fit(z)
m
m$entropy()
m$entropy_variance()
generics::tidy(m)

SAR and PolSAR images (R6)

Description

SARImage stores a SAR image as an array of dimension ⁠nrow x ncol x layers⁠. Two types are supported:

"polsar": a complex array whose p = m(m+1)/2 layers are the distinct entries of the m \times m covariance matrix of each pixel, in the order C_{11}, \ldots, C_{mm}, C_{12}, C_{13}, \ldots (for m = 3: ⁠HH, HV, VV, HH.HV*, HH.VV*, HV.VV*⁠), as in SanFrancisco150;
"intensity": a real (or real-valued complex) array whose layers are intensity channels.

The class offers cropping, Pauli colour composition, plotting, local (moving-window) features for classification, entropy maps and conversion to tibbles.

Value

An R6::R6Class generator. SARImage$new() returns a new SARImage object; its methods are described in the Methods section below.

Public fields

data: The image array.
type: "polsar" or "intensity".
channels: Names of the intensity channels.
looks: Nominal number of looks (optional, NULL if unknown).

Active bindings

nrow: Number of rows (read-only).
ncol: Number of columns (read-only).
m: Number of channels; matrix order for PolSAR images (read-only).

Methods

Public methods

SARImage$new()
SARImage$intensity()
SARImage$intensities()
SARImage$crop()
SARImage$pixel()
SARImage$window()
SARImage$pauli()
SARImage$plot()
SARImage$features()
SARImage$entropy_map()
SARImage$as_tibble()
SARImage$print()
SARImage$clone()

`SARImage$new()`

Create a SAR image.

Usage

SARImage$new(data, type = NULL, looks = NULL, channels = NULL)

Arguments

data: Array ⁠nrow x ncol x layers⁠ (a matrix is treated as a single intensity channel).
type: "polsar" or "intensity". Guessed when NULL: complex arrays with m(m+1)/2 layers (m >= 2) and non-zero imaginary parts are PolSAR images.
looks: Nominal number of looks.
channels: Names of the intensity channels.

`SARImage$intensity()`

Intensity of one channel.

Usage

SARImage$intensity(channel = 1)

Arguments

channel: Channel index or name.

`SARImage$intensities()`

All intensity channels as a real array.

Usage

SARImage$intensities()

`SARImage$crop()`

Crop the image.

Usage

SARImage$crop(rows, cols)

Arguments

rows, cols: Row and column indices to keep.

`SARImage$pixel()`

Observation at a pixel: the Hermitian covariance matrix (PolSAR) or the vector of intensities.

Usage

SARImage$pixel(row, col)

Arguments

row, col: Pixel position.

`SARImage$window()`

Observations inside a square window centred at a pixel (truncated at the borders). Returns an ⁠n x layers⁠ matrix.

Usage

SARImage$window(row, col, window = 3)

Arguments

row, col: Pixel position.
window: Odd window side.

`SARImage$pauli()`

Pauli RGB composition scaled to [0, 1] (PolSAR images with three channels); for other images the first three intensities are used.

Usage

SARImage$pauli(stretch = 0.98, gamma = 0.5)

Arguments

stretch: Upper quantile used for linear stretching.
gamma: Gamma correction exponent.

`SARImage$plot()`

Plot the image (Pauli composition or one channel in dB).

Usage

SARImage$plot(type = c("pauli", "intensity"), channel = 1, main = NULL, ...)

Arguments

type: "pauli" or "intensity".
channel: Channel for type = "intensity".
main: Title.
...: Passed to graphics::rasterImage().

`SARImage$features()`

Local features for classification; see sar_features().

Usage

SARImage$features(window = 3, type = c("all", "gaussian", "wishart"))

Arguments

window: Odd window side.
type: Which features: "all", "gaussian" or "wishart".

`SARImage$entropy_map()`

Entropy map; see entropy_map().

Usage

SARImage$entropy_map(...)

Arguments

...: Passed to entropy_map().

`SARImage$as_tibble()`

Convert to a tibble with one row per pixel.

Usage

SARImage$as_tibble()

`SARImage$print()`

Print a summary.

Usage

SARImage$print(...)

Arguments

...: Ignored.

`SARImage$clone()`

The objects of this class are cloneable with this method.

Usage

SARImage$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Examples

img <- SARImage$new(SanFrancisco150, looks = 4)
img
small <- img$crop(1:40, 1:40)
dim(small$intensities())
small$pixel(1, 1)
head(small$features(window = 3))

img$plot()

Base R6 class for SAR and PolSAR statistical models

Description

SARModel is the abstract parent of all model classes of SITSAR (GammaSAR, G0I, GGammaSAR, WishartSAR, G0Polarimetric and CompoundWishart). Every model can evaluate densities, simulate data, be fitted by maximum likelihood (⁠$fit()⁠) and report its Shannon entropy and the asymptotic variance of the entropy estimator.

Fitted models work with the generics verbs tidy(), glance(), as well as with stats::logLik() and stats::AIC().

Value

An R6::R6Class generator. SARModel$new() returns a new SARModel object; its methods are described in the Methods section below.

Public fields

name: Model name.
params: Named list of parameters.
fixed: Names of parameters held fixed during estimation.
n: Sample size used in the last fit (NULL if not fitted).
loglik: Maximised log-likelihood (NULL if not fitted).
converged: Logical convergence flag of the last fit.

Methods

Public methods

SARModel$new()
SARModel$density()
SARModel$random()
SARModel$fit()
SARModel$log_likelihood()
SARModel$entropy()
SARModel$entropy_variance()
SARModel$n_parameters()
SARModel$tidy()
SARModel$glance()
SARModel$print()
SARModel$clone()

`SARModel$new()`

Abstract constructor.

Usage

SARModel$new(...)

Arguments

...: Ignored.

`SARModel$density()`

(Log-)density of observations.

Usage

SARModel$density(x, log = FALSE)

Arguments

x: Observations.
log: Return log-densities?

`SARModel$random()`

Generate random observations.

Usage

SARModel$random(n)

Arguments

n: Number of observations.

`SARModel$fit()`

Fit the model by maximum likelihood.

Usage

SARModel$fit(x, ...)

Arguments

x: Observations.
...: Model specific arguments.

`SARModel$log_likelihood()`

Log-likelihood of a sample.

Usage

SARModel$log_likelihood(x)

Arguments

x: Observations.

`SARModel$entropy()`

Shannon entropy at the current parameters.

Usage

SARModel$entropy()

`SARModel$entropy_variance()`

Asymptotic variance of the entropy estimator (delta method with the inverse observed Fisher information).

Usage

SARModel$entropy_variance(n = self$n)

Arguments

n: Sample size. Defaults to the size of the fitted sample.

`SARModel$n_parameters()`

Number of free parameters.

Usage

SARModel$n_parameters()

`SARModel$tidy()`

Parameters as a tibble.

Usage

SARModel$tidy()

`SARModel$glance()`

One-row summary of the fit.

Usage

SARModel$glance()

`SARModel$print()`

Print the model.

Usage

SARModel$print(...)

Arguments

...: Ignored.

`SARModel$clone()`

The objects of this class are cloneable with this method.

Usage

SARModel$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

San Francisco PolSAR image (150 x 150 pixels)

Description

A 150 \times 150 crop of the fully polarimetric L-band AIRSAR image of the San Francisco Bay area (nominal 4 looks), used in the dissertation and thesis of J. A. Ferreira. The scene contains ocean, vegetation (forest/park) and urban areas; see SanFrancisco150_gt.

Usage

SanFrancisco150

Format

A complex array of dimension ⁠150 x 150 x 6⁠. For each pixel the six layers are the distinct entries of the 3 \times 3 Hermitian covariance matrix: |S_{HH}|^2, |S_{HV}|^2, |S_{VV}|^2 (real intensities), S_{HH}S_{HV}^*, S_{HH}S_{VV}^* and S_{HV}S_{VV}^* (complex products).

Source

NASA/JPL AIRSAR mission.

Examples

dim(SanFrancisco150)
img <- SARImage$new(SanFrancisco150, looks = 4)
img$plot()

Ground truth of the San Francisco image

Description

Reference map of the SanFrancisco150 image with three classes.

Usage

SanFrancisco150_gt

Format

An integer matrix ⁠150 x 150⁠ with values 1 (ocean), 2 (vegetation) and 3 (urban area).

Examples

table(SanFrancisco150_gt)
plot_map(SanFrancisco150_gt)

Scaled complex Wishart model for PolSAR data (R6)

Description

R6 class for the scaled complex Wishart law \mathcal{W}_m(\Sigma, L) (see dwishart_sar()). The maximum likelihood estimator of \Sigma is the sample mean and L solves m\log L - \psi^{(0)}_m(L) = \log|\bar Z| - \overline{\log|Z|} (Anfinsen et al., 2009). The entropy variance is available in closed form (Nascimento, Ferreira and Frery, 2023).

Value

An R6::R6Class generator. WishartSAR$new() returns a new WishartSAR object; its methods are described in the Methods section below.

Super class

SARModel -> WishartSAR

Methods

Public methods

WishartSAR$new()
WishartSAR$density()
WishartSAR$random()
WishartSAR$fit()
WishartSAR$entropy()
WishartSAR$entropy_variance()
WishartSAR$clone()

Inherited methods

`WishartSAR$new()`

Create a Wishart model.

Usage

WishartSAR$new(Sigma = diag(3) + (0+0i), L = 4)

Arguments

Sigma: Hermitian positive definite matrix (default identity 3x3).
L: Number of looks.

`WishartSAR$density()`

(Log-)density.

Usage

WishartSAR$density(x, log = FALSE)

Arguments

x: PolSAR observations (array ⁠m x m x n⁠ or vec matrix).
log: Return log-densities?

`WishartSAR$random()`

Simulate PolSAR observations.

Usage

WishartSAR$random(n, output = "array")

Arguments

n: Number of observations.
output: "array" or "vec".

`WishartSAR$fit()`

Fit by maximum likelihood.

Usage

WishartSAR$fit(x, L = NULL)

Arguments

x: PolSAR observations (array ⁠m x m x n⁠ or vec matrix).
L: Known number of looks. If NULL (default) it is estimated.

`WishartSAR$entropy()`

Shannon entropy.

Usage

WishartSAR$entropy()

`WishartSAR$entropy_variance()`

Asymptotic variance of the entropy estimator (closed form).

Usage

WishartSAR$entropy_variance(n = self$n)

Arguments

n: Sample size.

`WishartSAR$clone()`

The objects of this class are cloneable with this method.

Usage

WishartSAR$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

Anfinsen, S. N., Doulgeris, A. P. and Eltoft, T. (2009). Estimation of the equivalent number of looks in polarimetric synthetic aperture radar imagery. IEEE Transactions on Geoscience and Remote Sensing, 47(11), 3795–3809.

Examples

set.seed(1)
Z <- rwishart_sar(300, polsar_example_sigma("forest"), L = 4)
m <- WishartSAR$new()$fit(Z)
m
m$entropy_variance()

Accuracy measures for change detection

Description

Computes the usual accuracy measures of binary change maps: detection rate (DR, percentage of true changes that were detected), false alarm rate (FA, percentage of unchanged pixels flagged as changed), and the percentages of false positives (FP) and false negatives (FN) with respect to all pixels.

Usage

change_detection_metrics(truth, estimate)

Arguments

truth

Logical (or 0/1) vector/matrix of true changes.

estimate

Logical (or 0/1) vector/matrix of detected changes.

Value

A tibble with DR, FA, FP, FN (in percent) and the overall accuracy OA (in percent).

Examples

truth <- c(TRUE, TRUE, FALSE, FALSE, FALSE)
est <- c(TRUE, FALSE, TRUE, FALSE, FALSE)
change_detection_metrics(truth, est)

Entropy-based change detection between two images

Description

Applies the entropy test of entropy_test() pixel by pixel, using the observations of a moving window in two co-registered images, and returns the map of p-values and the binary change map.

Usage

change_map(
  image1,
  image2,
  model = c("gamma", "g0i", "ggamma", "wishart", "g0p"),
  window = 5,
  L = NULL,
  channel = 1,
  level = 0.01
)

Arguments

image1, image2

Co-registered images (SARImage objects or arrays) of the same size.

model

One of "gamma", "g0i", "ggamma" (intensity models, applied to each channel) or "wishart", "g0p" (matrix models, for PolSAR images).

window

Odd side of the moving window.

L

Known number of looks. If NULL (default) it is estimated in every window.

channel

Channel used by intensity models.

level

Significance level used to declare a change.

Value

A list of class sitsar_change with the matrices statistic, p_value and change (logical), and the level.

Examples

set.seed(1)
a <- matrix(rgammasar(40 * 40, mu = 1, L = 4), 40)
b <- a
b[11:30, 11:30] <- rgammasar(400, mu = 4, L = 4)
cd <- change_map(a, b, model = "gamma", window = 5, L = 4)
cd
plot_map(cd$change, main = "Detected changes")

Compound complex Wishart distributions

Description

Density and random generation for the compound truncated Poisson complex Wishart (CTPCW) and compound geometric complex Wishart (CGCW) laws (Ferreira, Nascimento and Frery, 2022). They describe the PolSAR return as a random sum S = \sum_{i=1}^N Z_i of independent (unscaled) complex Wishart matrices Z_i \sim \mathcal{W}^C_m(\Sigma, L) with E(Z_i) = L\Sigma, where the number of scatterers N follows a zero-truncated Poisson law with mean parameter \lambda (CTPCW) or a geometric law on \{1, 2, \ldots\} with success probability p (CGCW). Their densities are

f(S) = \sum_{k=1}^{\infty} P(N = k) \frac{|S|^{kL - m}}{|\Sigma|^{kL}\Gamma_m(kL)} \exp\{-\mathrm{tr}(\Sigma^{-1}S)\},

which are able to describe multimodal intensities. The series is evaluated in log-scale and truncated when the terms become negligible.

Usage

dctpcw(x, lambda, Sigma, L, log = FALSE, kmax = 500L)

rctpcw(n, lambda, Sigma, L, output = c("array", "vec"))

dcgcw(x, p, Sigma, L, log = FALSE, kmax = 500L)

rcgcw(n, p, Sigma, L, output = c("array", "vec"))

Arguments

x

PolSAR observations: a complex array ⁠m x m x n⁠, a single Hermitian matrix or an ⁠n x m(m+1)/2⁠ matrix (see as_polsar_vec()).

lambda

Mean parameter of the zero-truncated Poisson law (\lambda > 0).

Sigma

Hermitian positive definite ⁠m x m⁠ matrix (the mean).

L

Number of looks of each Wishart component (L > m - 1).

log

Logical; if TRUE the log-density is returned.

kmax

Maximum number of terms of the series.

n

Number of observations.

output

Format of the generated sample: "array" (⁠m x m x n⁠) or "vec" (⁠n x m(m+1)/2⁠).

p

Success probability of the geometric law (0 < p < 1).

Value

dctpcw()/dcgcw() return (log-)densities; rctpcw()/rcgcw() return the simulated sample, with the simulated numbers of components in the attribute "N".

References

Ferreira, J. A., Nascimento, A. D. C. and Frery, A. C. (2022). PolSAR models with multimodal intensities. Remote Sensing, 14(20), 5083. doi:10.3390/rs14205083

Examples

Sigma <- polsar_example_sigma("forest")
set.seed(1)
S <- rctpcw(3, lambda = 2, Sigma = Sigma, L = 4)
attr(S, "N")
dctpcw(S, lambda = 2, Sigma = Sigma, L = 4, log = TRUE)
S2 <- rcgcw(3, p = 0.6, Sigma = Sigma, L = 4)
dcgcw(S2, p = 0.6, Sigma = Sigma, L = 4, log = TRUE)

The G0I distribution for SAR intensities

Description

Density, distribution function, quantile function and random generation for the \mathcal{G}_I^0(\alpha, \gamma, L) distribution, the multiplicative model for multilook SAR intensities with reciprocal gamma backscatter and gamma speckle (Frery et al., 1997).

Usage

dg0i(x, alpha, gamma, L, log = FALSE)

pg0i(q, alpha, gamma, L, lower.tail = TRUE, log.p = FALSE)

qg0i(p, alpha, gamma, L, lower.tail = TRUE, log.p = FALSE)

rg0i(n, alpha, gamma, L)

Arguments

x, q

Vector of quantiles.

alpha

Roughness parameter (\alpha < 0).

gamma

Scale parameter (\gamma > 0).

L

Number of looks (L > 0).

log, log.p

Logical; if TRUE, probabilities/densities are given as logarithms.

lower.tail

Logical; if TRUE (default) probabilities are P(X \le x), otherwise P(X > x).

p

Vector of probabilities.

n

Number of observations.

Details

The density is

f(z) = \frac{L^L \Gamma(L - \alpha)}{\gamma^{\alpha} \Gamma(-\alpha) \Gamma(L)} \frac{z^{L - 1}}{(\gamma + L z)^{L - \alpha}}, \quad z > 0,

with roughness \alpha < 0, scale \gamma > 0 and number of looks L > 0. If Z \sim \mathcal{G}_I^0(\alpha, \gamma, L) then -\alpha Z / \gamma follows a Snedecor F distribution with 2L and -2\alpha degrees of freedom, which is used to compute the distribution and quantile functions exactly.

Value

dg0i() gives the density, pg0i() the distribution function, qg0i() the quantile function and rg0i() generates random deviates.

References

Frery, A. C., Muller, H.-J., Yanasse, C. C. F. and Sant'Anna, S. J. S. (1997). A model for extremely heterogeneous clutter. IEEE Transactions on Geoscience and Remote Sensing, 35(3), 648–659.

Nascimento, A. D. C., Cintra, R. J. and Frery, A. C. (2010). Hypothesis testing in speckled data with stochastic distances. IEEE Transactions on Geoscience and Remote Sensing, 48(1), 373–385.

Examples

set.seed(1)
z <- rg0i(5, alpha = -1.5, gamma = 2, L = 8)
dg0i(z, alpha = -1.5, gamma = 2, L = 8)
pg0i(c(0.5, 1, 2), alpha = -1.5, gamma = 2, L = 8)
qg0i(c(0.1, 0.5, 0.9), alpha = -1.5, gamma = 2, L = 8)

The G0 polarimetric distribution

Description

Density and random generation for the polarimetric \mathcal{G}^0_m(\alpha, \Sigma, L) law (also known as \mathcal{G}^0_P), obtained from the multiplicative model Z = X Y with Y \sim \mathcal{W}_m(\Sigma, L) and reciprocal gamma texture X \sim \Gamma^{-1}(-\alpha, -\alpha - 1) with unit mean (Freitas et al., 2005):

f(Z) = \frac{L^{mL}\Gamma(mL - \alpha)|Z|^{L-m}} {|\Sigma|^L \Gamma_m(L) \Gamma(-\alpha)(-\alpha-1)^{\alpha}} \left[L\,\mathrm{tr}(\Sigma^{-1}Z) - \alpha - 1\right]^{\alpha - mL},

with \alpha < -1. When \alpha \to -\infty it converges to the scaled complex Wishart law.

Usage

dg0p(x, alpha, Sigma, L, log = FALSE)

rg0p(n, alpha, Sigma, L, output = c("array", "vec"))

Arguments

x

PolSAR observations: a complex array ⁠m x m x n⁠, a single Hermitian matrix or an ⁠n x m(m+1)/2⁠ matrix (see as_polsar_vec()).

alpha

Roughness parameter (\alpha < -1).

Sigma

Hermitian positive definite ⁠m x m⁠ matrix (the mean).

L

Number of looks (L > m - 1).

log

Logical; if TRUE the log-density is returned.

n

Number of observations.

output

Format of the generated sample: "array" (⁠m x m x n⁠) or "vec" (⁠n x m(m+1)/2⁠).

Value

dg0p() returns (log-)densities and rg0p() the simulated sample.

References

Freitas, C. C., Frery, A. C. and Correia, A. H. (2005). The polarimetric G distribution for SAR data analysis. Environmetrics, 16(1), 13–31.

Examples

Sigma <- polsar_example_sigma("urban")
set.seed(1)
Z <- rg0p(3, alpha = -3, Sigma = Sigma, L = 4)
dg0p(Z, alpha = -3, Sigma = Sigma, L = 4, log = TRUE)

The Gamma distribution for SAR intensities

Description

Density, distribution function, quantile function and random generation for the multilook intensity Gamma law parametrised by its mean \mu and number of looks L:

f(z) = \frac{L^L}{\mu^L \Gamma(L)} z^{L-1} \exp(-L z / \mu), \quad z > 0.

This is the model for homogeneous areas (fully developed speckle).

Usage

dgammasar(x, mu, L, log = FALSE)

pgammasar(q, mu, L, lower.tail = TRUE, log.p = FALSE)

qgammasar(p, mu, L, lower.tail = TRUE, log.p = FALSE)

rgammasar(n, mu, L)

Arguments

x, q

Vector of quantiles.

mu

Mean (\mu > 0).

L

Number of looks (L > 0).

log, log.p

Logical; if TRUE, probabilities/densities are given as logarithms.

lower.tail

Logical; if TRUE (default) probabilities are P(X \le x), otherwise P(X > x).

p

Vector of probabilities.

n

Number of observations.

Value

Density, distribution function, quantile function or random deviates.

Examples

dgammasar(c(0.5, 1, 2), mu = 1, L = 4)
rgammasar(3, mu = 1, L = 4)

The generalized Gamma distribution for SAR intensities

Description

Density, distribution function, quantile function and random generation for the generalized Gamma (Stacy) law with power \alpha > 0, shape \phi > 0 and inverse-scale \mu > 0:

f(z) = \frac{\alpha \mu^{\alpha\phi}}{\Gamma(\phi)} z^{\alpha\phi - 1} \exp\{-(\mu z)^\alpha\}, \quad z > 0.

For \alpha = 1 it reduces to the Gamma law with shape \phi and rate \mu; in SAR applications \phi plays the role of the number of looks.

Usage

dggamma(x, alpha, phi, mu, log = FALSE)

pggamma(q, alpha, phi, mu, lower.tail = TRUE, log.p = FALSE)

qggamma(p, alpha, phi, mu, lower.tail = TRUE, log.p = FALSE)

rggamma(n, alpha, phi, mu)

Arguments

x, q

Vector of quantiles.

alpha

Power parameter (\alpha > 0).

phi

Shape parameter (\phi > 0).

mu

Inverse-scale parameter (\mu > 0).

log, log.p

Logical; if TRUE, probabilities/densities are given as logarithms.

lower.tail

Logical; if TRUE (default) probabilities are P(X \le x), otherwise P(X > x).

p

Vector of probabilities.

n

Number of observations.

Value

Density, distribution function, quantile function or random deviates.

References

Li, H.-C., Hong, W., Wu, Y.-R. and Fan, P.-Z. (2011). On the empirical- statistical modeling of SAR images with generalized gamma distribution. IEEE Journal of Selected Topics in Signal Processing, 5(3), 386–397.

Examples

dggamma(c(0.5, 1, 2), alpha = 1.5, phi = 2, mu = 1)
rggamma(3, alpha = 1.5, phi = 2, mu = 1)

Stochastic distances between G0I distributions

Description

Computes stochastic distances between two \mathcal{G}_I^0 laws by numerical integration (Nascimento, Cintra and Frery, 2010).

Usage

distancesg0i(
  par_1,
  par_2,
  p = 1/2,
  type = c("KL", "Renyi", "Bhattacharyya", "Hellinger", "Arithmetic-Geometric",
    "Triangular", "Harmonic-Mean")
)

Arguments

par_1, par_2

Parameter vectors c(alpha, gamma, L).

p

Order of the Rényi distance, in (0, 1).

type

One of "KL", "Renyi", "Bhattacharyya", "Hellinger", "Arithmetic-Geometric", "Triangular" or "Harmonic-Mean".

Value

An object of class distancesg0i with the parameters, the type and the distance_value.

References

Nascimento, A. D. C., Cintra, R. J. and Frery, A. C. (2010). Hypothesis testing in speckled data with stochastic distances. IEEE Transactions on Geoscience and Remote Sensing, 48(1), 373–385.

Examples

distancesg0i(c(-1.5, 2, 4), c(-1.5, 2, 4))
res <- distancesg0i(c(-1.5, 2, 8), c(-3, 2, 4), type = "Hellinger")
res

Table of G0I stochastic distances between two image regions

Description

Fits the \mathcal{G}_I^0 law to each intensity channel of two rectangular regions of an image and computes all the stochastic distances of distancesg0i() between them.

Usage

distancesg0itable(image, marks1, marks2, p = 1/2, L = NULL)

Arguments

image

A SARImage or an array (⁠nrow x ncol x layers⁠).

marks1, marks2

Region limits as c(left, right, up, down), i.e. first and last column, first and last row.

p

Order of the Rényi distance.

L

Known number of looks; estimated when NULL.

Value

An object of class distancesg0itable with the marks and the table of distances (distancestable, channels in rows).

Examples


res <- distancesg0itable(SanFrancisco150, c(10, 30, 10, 30),
                         c(10, 30, 120, 140), L = 4)
res

Divergence-based classifier as a 'parsnip' model

Description

divergence_classifier() defines the divergence-based classifier of Ferreira, Coelho and Nascimento (2021) as a 'parsnip' model specification, so it can be used with 'workflows', 'recipes', 'rsample', 'tune' and 'yardstick'. The engine selects the family of features: "gaussian" (multivariate normal intensity features, the default) or "wishart" (complex Wishart PolSAR matrix features). The predictors must be in the format of sar_features(); extra columns such as row/col are ignored by the engine (it is good practice to give them an "id" role in a recipe).

Usage

divergence_classifier(
  mode = "classification",
  divergence = NULL,
  order = NULL,
  kind = NULL,
  engine = "gaussian"
)

## S3 method for class 'divergence_classifier'
update(
  object,
  parameters = NULL,
  divergence = NULL,
  order = NULL,
  kind = NULL,
  fresh = FALSE,
  ...
)

Arguments

mode

A single character string for the type of model. The only possible value is "classification".

divergence

Divergence: "renyi" (default), "kl", "jeffreys" or "bhattacharyya".

order

Order of the Rényi divergence, in (0, 1). Tunable with renyi_order().

kind

Form of the Rényi divergence (1 to 4); see divergences.

engine

"gaussian" or "wishart".

object

A divergence_classifier model specification.

parameters

A 1-row tibble or named list with the main parameters.

fresh

Replace the arguments instead of updating them?

...

Not used.

Value

A model specification object with classes divergence_classifier and model_spec.

Examples

spec <- divergence_classifier(divergence = "renyi", order = 0.5) |>
  parsnip::set_engine("wishart")
spec

feats <- sar_features(SARImage$new(SanFrancisco150)$crop(1:60, 1:60), window = 5)
feats$class <- factor(as.vector(SanFrancisco150_gt[1:60, 1:60]))
fit <- parsnip::fit(spec, class ~ ., data = feats)
head(predict(fit, feats))
head(predict(fit, feats, type = "prob"))

Divergences between Gaussian and complex Wishart models

Description

Closed-form divergences between two multivariate normal laws N_p(\mu_1, \Sigma_1) and N_p(\mu_2, \Sigma_2), and between two scaled complex Wishart laws \mathcal{W}_m(\Sigma_1, L) and \mathcal{W}_m(\Sigma_2, L) with a common number of looks. They are the building blocks of the divergence-based classifiers of Ferreira, Coelho and Nascimento (2021).

Usage

divergence_gaussian(
  mu1,
  Sigma1,
  mu2,
  Sigma2,
  type = c("kl", "jeffreys", "bhattacharyya", "renyi"),
  order = 0.5,
  kind = 1
)

divergence_wishart(
  Sigma1,
  Sigma2,
  L,
  type = c("kl", "jeffreys", "bhattacharyya", "renyi"),
  order = 0.5,
  kind = 1
)

Arguments

mu1, mu2

Mean vectors.

Sigma1, Sigma2

Covariance matrices (real symmetric for Gaussian laws, Hermitian for Wishart laws).

type

Divergence: "kl", "jeffreys", "bhattacharyya" or "renyi".

order

Order \alpha \in (0, 1) of the Rényi divergence.

kind

Form of the Rényi divergence (1 to 4).

L

Number of looks (common to both Wishart laws).

Details

Available measures (type):

"kl": Kullback-Leibler divergence D_{KL}(\theta_1 \| \theta_2).
"jeffreys": Jeffreys divergence D_{KL}(\theta_1 \| \theta_2) + D_{KL}(\theta_2 \| \theta_1).
"bhattacharyya": Bhattacharyya distance -\log \int \sqrt{f_1 f_2}.
"renyi": Rényi divergence of order \alpha (order), in one of four forms (kind): 1, D^\alpha_R(\theta_1\|\theta_2); 2, D^\alpha_R(\theta_2\|\theta_1); 3, the symmetrised mean [D^\alpha_R(\theta_1\|\theta_2) + D^\alpha_R(\theta_2\|\theta_1)]/2; and 4, c \log\{[K(\theta_1\|\theta_2) + K(\theta_2\|\theta_1)]/2\}, where K(\theta_1\|\theta_2) = \int f_1^\alpha f_2^{1-\alpha}.

For Gaussian laws the Rényi divergence uses the normalisation of Pardo (2006), c = 1/[\alpha(\alpha - 1)], which gives

D^\alpha_R = \frac{1}{2}\Delta^\top M^{-1}\Delta - \frac{1}{2\alpha(\alpha-1)}\log\frac{|M|}{|\Sigma_1|^{1-\alpha} |\Sigma_2|^{\alpha}},

with \Delta = \mu_1 - \mu_2 and M = \alpha\Sigma_2 + (1-\alpha)\Sigma_1. For Wishart laws the normalisation of Frery, Nascimento and Cintra (2014), c = 1/(\alpha - 1), is used:

D^\alpha_R = \frac{L}{\alpha - 1}\log\frac{|(\alpha\Sigma_1^{-1} + (1-\alpha)\Sigma_2^{-1})^{-1}|}{|\Sigma_1|^\alpha|\Sigma_2|^{1-\alpha}}.

Both converge to the Kullback-Leibler divergence when \alpha \to 1.

Value

A single non-negative number.

References

Frery, A. C., Nascimento, A. D. C. and Cintra, R. J. (2014). Analytic expressions for stochastic distances between relaxed complex Wishart distributions. IEEE Transactions on Geoscience and Remote Sensing, 52(2), 1213–1226.

Pardo, L. (2006). Statistical Inference Based on Divergence Measures. Chapman & Hall/CRC.

Examples

S1 <- diag(3); S2 <- diag(c(2, 1, 0.5))
divergence_gaussian(c(0, 0, 0), S1, c(1, 0, 0), S2, type = "kl")
divergence_gaussian(c(0, 0, 0), S1, c(1, 0, 0), S2, type = "renyi",
                    order = 0.5, kind = 3)

W1 <- polsar_example_sigma("forest"); W2 <- polsar_example_sigma("urban")
divergence_wishart(W1, W2, L = 4, type = "jeffreys")
divergence_wishart(W1, W2, L = 4, type = "renyi", order = 0.9)

The scaled complex Wishart distribution

Description

Density and random generation for the scaled complex Wishart law \mathcal{W}_m(\Sigma, L), the reference model for multilook PolSAR covariance (coherency) matrices in homogeneous areas:

f(Z) = \frac{L^{mL} |Z|^{L-m}}{|\Sigma|^L \Gamma_m(L)} \exp\{-L\, \mathrm{tr}(\Sigma^{-1} Z)\},

where \Gamma_m(L) = \pi^{m(m-1)/2}\prod_{i=0}^{m-1}\Gamma(L-i) and E(Z) = \Sigma.

Usage

dwishart_sar(x, Sigma, L, log = FALSE)

rwishart_sar(n, Sigma, L, output = c("array", "vec"))

Arguments

x

PolSAR observations: a complex array ⁠m x m x n⁠, a single Hermitian matrix or an ⁠n x m(m+1)/2⁠ matrix (see as_polsar_vec()).

Sigma

Hermitian positive definite ⁠m x m⁠ matrix (the mean).

L

Number of looks (L > m - 1).

log

Logical; if TRUE the log-density is returned.

n

Number of observations.

output

Format of the generated sample: "array" (⁠m x m x n⁠) or "vec" (⁠n x m(m+1)/2⁠).

Details

Random matrices are generated with the complex Bartlett decomposition, so non-integer numbers of looks L > m - 1 are allowed.

Value

dwishart_sar() returns a vector of (log-)densities; rwishart_sar() returns the simulated sample.

References

Goodman, N. R. (1963). Statistical analysis based on a certain multivariate complex Gaussian distribution. The Annals of Mathematical Statistics, 34(1), 152–177.

Lee, J.-S., Grunes, M. R. and Kwok, R. (1994). Classification of multi-look polarimetric SAR imagery based on complex Wishart distribution. International Journal of Remote Sensing, 15(11), 2299–2311.

Examples

Sigma <- polsar_example_sigma("forest")
set.seed(1)
Z <- rwishart_sar(3, Sigma, L = 4)
dim(Z)
dwishart_sar(Z, Sigma, L = 4, log = TRUE)

Shannon entropies of SAR and PolSAR models

Description

Closed-form Shannon entropies H = E\{-\log f(Z)\} for the models used in SAR (intensity) and PolSAR (matrix) image analysis. All functions are vectorised in the scalar parameters.

Usage

entropy_gamma(mu, L)

entropy_g0i(alpha, gamma, L)

entropy_ggamma(alpha, phi, mu)

entropy_wishart(Sigma, L)

entropy_g0p(alpha, Sigma, L)

Arguments

mu

Mean of the Gamma law, or inverse scale of the generalized Gamma law.

L

Number of looks.

alpha

Roughness (G0I, G0 polarimetric) or power (generalized Gamma) parameter.

gamma

Scale parameter of the G0I law.

phi

Shape parameter of the generalized Gamma law.

Sigma

Hermitian positive definite covariance matrix.

Details

Gamma: H = L - \log L + \log\mu + \log\Gamma(L) + (1 - L)\psi^{(0)}(L).
G0I: (Ferreira and Nascimento, 2020) H = -\log\frac{L^L\Gamma(L-\alpha)}{\Gamma(-\alpha)\gamma^\alpha \Gamma(L)} + (1 - L)[\psi^{(0)}(L) - \log L + \log\gamma - \psi^{(0)}(-\alpha)] + (L - \alpha)[\psi^{(0)}(L - \alpha) + \log\gamma - \psi^{(0)}(-\alpha)].
Generalized Gamma: H = -\log\alpha + \log\Gamma(\phi) + \phi - (\phi - 1/\alpha)\psi^{(0)}(\phi) - \log\mu.
Scaled complex Wishart: (Nascimento, Ferreira and Frery, 2023) H = m\log|\Sigma| - m^2\log L + \log\Gamma_m(L) + mL + (m - L)\psi^{(0)}_m(L), with \psi^{(0)}_m(L) = \sum_{i=0}^{m-1}\psi^{(0)}(L - i).
G0 polarimetric: (Nascimento, Ferreira and Frery, 2023) obtained from E\log|Z| = m[\log(-\alpha-1) - \psi^{(0)}(-\alpha)] + \log|\Sigma| - m\log L + \psi^{(0)}_m(L) and E\log[L\,\mathrm{tr}(\Sigma^{-1}Z) - \alpha - 1] = \log(-\alpha-1) + \psi^{(0)}(mL - \alpha) - \psi^{(0)}(-\alpha).

Value

Numeric vector of entropies.

References

Examples

entropy_gamma(mu = 1, L = 4)
entropy_g0i(alpha = -3, gamma = 2, L = 4)
entropy_ggamma(alpha = 1, phi = 4, mu = 4) # equals the Gamma entropy
S <- polsar_example_sigma("forest")
entropy_wishart(S, L = 4)
entropy_g0p(alpha = -5, Sigma = S, L = 4)

Shannon entropy maps

Description

Estimates, at every pixel, the parameters of a SAR/PolSAR model with the observations inside a square moving window and returns the map of Shannon entropies (Ferreira and Nascimento, 2020; Nascimento, Ferreira and Frery, 2023). Optionally, the map of asymptotic variances of the entropy estimators is returned as well.

Usage

entropy_map(
  image,
  model = c("gamma", "g0i", "ggamma", "wishart", "g0p"),
  window = 7,
  L = NULL,
  channels = NULL,
  variance = FALSE
)

Arguments

image

A SARImage or an array accepted by SARImage$new().

model

One of "gamma", "g0i", "ggamma" (intensity models, applied to each channel) or "wishart", "g0p" (matrix models, for PolSAR images).

window

Odd side of the moving window.

L

Known number of looks. If NULL (default) it is estimated in every window.

channels

Channels used by intensity models (default: all).

variance

Also return the variance map?

Details

For the Gamma and Wishart models the computations are fully vectorised (local sufficient statistics are obtained from integral images), so the maps are computed in a fraction of a second. The G0I, generalized Gamma and G0 polarimetric models require a numerical maximisation per pixel and are therefore slower (use small images or crops to explore them).

Value

A matrix (one channel or matrix model) or an array ⁠nrow x ncol x channels⁠ of entropies. If variance = TRUE, a list with elements entropy, variance and n (window sizes).

References

Examples

img <- SARImage$new(SanFrancisco150)
H <- entropy_map(img, model = "wishart", window = 7, L = 4)
dim(H)
plot_map(H, main = "Wishart entropy")

Hg <- entropy_map(img, model = "gamma", window = 7, channels = "HV")

small <- img$crop(1:15, 1:15)
Hi <- entropy_map(small, model = "g0i", window = 5, L = 4, channels = 1)

Entropy-based test for two SAR samples

Description

Tests whether two samples come from the same distribution by comparing their estimated Shannon entropies. Under the null hypothesis of equal entropies, and by the asymptotic normality of the maximum likelihood estimator of the entropy,

S = \frac{(\hat H_1 - \hat H_2)^2}{\widehat{\mathrm{Var}}(\hat H_1) + \widehat{\mathrm{Var}}(\hat H_2)}

follows asymptotically a \chi^2_1 distribution. This statistic is the basis of the entropy-based change detectors of the thesis of J. A. Ferreira (2021).

Usage

entropy_test(
  x,
  y,
  model = c("gamma", "g0i", "ggamma", "wishart", "g0p"),
  L = NULL
)

Arguments

x, y

Samples: numeric vectors of intensities (intensity models) or PolSAR observations (matrix models).

model

One of "gamma", "g0i", "ggamma", "wishart", "g0p".

L

Known number of looks; estimated when NULL.

Value

An object of class htest.

References

Ferreira, J. A. (2021). Entropias e somas compostas para matrizes estocásticas aplicadas a sistemas PolSAR. PhD thesis, Universidade Federal de Pernambuco.

Examples

set.seed(1)
x <- rg0i(200, alpha = -3, gamma = 2, L = 4)
y <- rg0i(200, alpha = -3, gamma = 2, L = 4)
z <- rg0i(200, alpha = -1.5, gamma = 1, L = 4)
entropy_test(x, y, model = "g0i", L = 4)
entropy_test(x, z, model = "g0i", L = 4)$p.value

Estimation of G0I parameters

Description

Maximum likelihood estimation of the \mathcal{G}_I^0 parameters. This is a convenience wrapper around G0I⁠$fit()⁠, kept for compatibility with previous versions of the package.

Usage

g0iestimation(Theta, x, L_fixed = FALSE)

Arguments

Theta

Initial values c(alpha, gamma, L). When L_fixed = TRUE, Theta[3] is the known number of looks.

x

Vector of observations.

L_fixed

Logical; if TRUE, L is held fixed at Theta[3].

Value

Named vector c(alpha, gamma, L) of estimates.

Examples

set.seed(1)
y <- rg0i(1000, alpha = -1.5, gamma = 2, L = 8)
g0iestimation(c(-1, 1, 1), y)
g0iestimation(c(-1, 1, 8), y, L_fixed = TRUE)

Kappa coefficient and overall accuracy

Description

Computes Cohen's kappa coefficient of agreement, its asymptotic variance (Congalton and Green, 2009) and the overall accuracy from a confusion matrix or from two vectors (or matrices) of labels. Unlike yardstick::kap(), the variance of the estimator is also returned, which allows comparing classifiers with Z tests.

Usage

kappa_statistics(truth, estimate = NULL, match = FALSE)

Arguments

truth

Either a square confusion matrix (estimates in rows, truth in columns) or a vector/matrix of reference labels.

estimate

Vector/matrix of estimated labels (when truth is not a confusion matrix).

match

Relabel the estimated classes to maximise agreement?

Details

Labels of unsupervised methods are arbitrary: use match = TRUE to relabel the estimated classes so that they best agree with the truth (an exhaustive search over permutations for up to 8 classes).

Value

A tibble with kappa, variance, std_error, overall_accuracy and the number of observations n.

References

Congalton, R. G. and Green, K. (2009). Assessing the Accuracy of Remotely Sensed Data: Principles and Practices. CRC Press.

Examples

truth <- c(1, 1, 2, 2, 3, 3, 3)
est <- c(1, 2, 2, 2, 3, 3, 1)
kappa_statistics(truth, est)
kappa_statistics(table(est, truth))

Plot a map

Description

Displays a matrix as an image with the first row on top: continuous maps (e.g. entropy maps) use a sequential palette and integer/factor maps (e.g. segmentation or classification results) use a qualitative one.

Usage

plot_map(x, palette = NULL, main = NULL, legend = FALSE)

Arguments

x

A numeric, integer, logical or factor matrix.

palette

Optional vector of colours.

main

Title.

legend

Add a legend for discrete maps?

Value

Invisibly, x.

Examples

plot_map(SanFrancisco150_gt, main = "Ground truth", legend = TRUE)
plot_map(matrix(rnorm(100), 10), main = "Noise")

Convert between PolSAR storage formats

Description

PolSAR observations are Hermitian positive definite matrices. SITSAR accepts them either as a complex array of dimension ⁠m x m x n⁠ or as an ⁠n x p⁠ complex matrix in which each row stores the p = m(m+1)/2 distinct entries in the order C_{11}, \ldots, C_{mm} (the intensities) followed by the upper triangle C_{12}, C_{13}, \ldots, C_{23}, \ldots. For m = 3 this is the usual layer order ⁠HH, HV, VV, HH.HV*, HH.VV*, HV.VV*⁠ of the SanFrancisco150 image.

Usage

as_polsar_array(x)

as_polsar_vec(x)

Arguments

x

A complex array (⁠m x m x n⁠), a single ⁠m x m⁠ matrix, or an ⁠n x p⁠ complex matrix (or vector of length p).

Value

as_polsar_array() returns a complex array ⁠m x m x n⁠; as_polsar_vec() returns an ⁠n x p⁠ complex matrix.

Examples

S <- diag(3) + 0i
S[1, 2] <- 0.2 + 0.1i
S[2, 1] <- Conj(S[1, 2])
v <- as_polsar_vec(S)
v
as_polsar_array(v)[, , 1]

Example PolSAR covariance matrices

Description

Typical 3 \times 3 covariance matrices (scaled to unit magnitude) for urban, forest and pasture areas, taken from the simulation studies of the authors' dissertation and thesis. They are handy to simulate PolSAR data.

Usage

polsar_example_sigma(type = c("urban", "forest", "pasture"))

Arguments

type

One of "urban", "forest" or "pasture".

Value

A complex Hermitian positive definite 3 \times 3 matrix.

Examples

polsar_example_sigma("forest")

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

generics: glance(), tidy()
tibble: as_tibble()

Tuning parameters for the divergence classifier

Description

'dials' parameter objects for divergence_classifier(): renyi_order() for the order of the Rényi divergence and divergence_type() for the divergence measure. Both require the 'dials' package.

Usage

renyi_order(range = c(0.05, 0.95), trans = NULL)

divergence_type(values = c("renyi", "kl", "jeffreys", "bhattacharyya"))

renyi_kind(range = c(1L, 4L))

Arguments

range

Range of the Rényi order.

trans

A transformation object (or NULL).

values

Candidate divergences.

Value

A 'dials' parameter object.

Examples

if (requireNamespace("dials", quietly = TRUE)) {
  renyi_order()
  divergence_type()
}

Local features of SAR images for pixel classification

Description

Computes moving-window statistics around every pixel, in the format used by DivergenceClassifier and the divergence_classifier() 'parsnip' model. Window statistics are computed with integral images, so the cost does not depend on the window size. Windows are truncated at the image borders.

Usage

sar_features(image, window = 3, type = c("all", "gaussian", "wishart"))

Arguments

image

A SARImage or an array accepted by SARImage$new().

window

Odd window side.

type

Which features: "all", "gaussian" or "wishart".

Details

Two groups of columns are produced:

Gaussian features: ⁠mean_<ch>⁠: local mean of each intensity channel; ⁠cov_<ch1>_<ch2>⁠: local (unbiased) covariance between the intensities. Together they define the multivariate normal fitted to the intensity vector in the window.
Wishart features (PolSAR only): ⁠c<i><i>⁠ and ⁠c<i><j>_re⁠/⁠c<i><j>_im⁠: entries of the local mean covariance matrix, i.e. the maximum likelihood estimate of \Sigma for the scaled complex Wishart law in the window.

Value

A tibble with the columns row, col and the features.

Examples

img <- SARImage$new(SanFrancisco150)$crop(1:20, 1:20)
f <- sar_features(img, window = 3)
names(f)

Tidy and glance methods for SITSAR models

Description

Tidy and glance methods for SITSAR models

Usage

## S3 method for class 'SARModel'
tidy(x, ...)

## S3 method for class 'SARModel'
glance(x, ...)

## S3 method for class 'SARModel'
logLik(object, ...)

Arguments

x

A fitted SARModel object.

...

Not used.

object

A fitted SARModel object.

Value

tidy() returns a tibble with one row per scalar parameter; glance() a one-row tibble; logLik() an object of class logLik.

Examples

set.seed(1)
m <- G0I$new()$fit(rg0i(300, -2, 1, 4), L = 4)
generics::tidy(m)
generics::glance(m)
logLik(m)

Entropy-based segmentation of a SAR/PolSAR image

Description

Convenience wrapper that computes the entropy map(s) with entropy_map() and segments them with EntropySegmenter.

Usage

segment_sar(
  image,
  k = 2,
  model = c("wishart", "g0p", "gamma", "g0i", "ggamma"),
  window = 7,
  L = NULL,
  channels = NULL,
  method = c("em", "sem"),
  ...
)

Arguments

image

A SARImage or an array accepted by SARImage$new().

k

Number of classes.

model

One of "gamma", "g0i", "ggamma" (intensity models, applied to each channel) or "wishart", "g0p" (matrix models, for PolSAR images).

window

Odd side of the moving window.

L

Known number of looks. If NULL (default) it is estimated in every window.

channels

Channels used by intensity models (default: all).

method

"em" or "sem".

...

Passed to EntropySegmenter$new().

Value

A fitted EntropySegmenter; the labels are available with ⁠$label_map()⁠.

Examples

set.seed(1)
seg <- segment_sar(SanFrancisco150, k = 3, model = "gamma", window = 7, L = 4)
table(seg$label_map(), SanFrancisco150_gt)

Engine fit function for `divergence_classifier()`

Description

Internal fit function used by the 'parsnip' engines; it is exported only so that 'parsnip' can call it.

Usage

sitsar_divergence_fit(
  x,
  y,
  family = "gaussian",
  divergence = "renyi",
  order = 0.5,
  kind = 1
)

Arguments

x

Data frame of predictors.

y

Factor of classes.

family

"gaussian" or "wishart".

divergence, order, kind

See divergence_classifier().

Value

A fitted DivergenceClassifier.

Package {SITSAR}

SITSAR: Information Theory, Geometry and Statistics for SAR Data

Description

Main tools

Author(s)

See Also

Compound complex Wishart models (R6)

Description

Value

Super class

Public fields

Methods

Public methods

CompoundWishart$new()

Usage

Arguments

CompoundWishart$density()

Usage

Arguments

CompoundWishart$random()

Usage

Arguments

CompoundWishart$fit()

Usage

Arguments

CompoundWishart$entropy()

Usage

Arguments

CompoundWishart$entropy_variance()

Usage

Arguments

CompoundWishart$clone()

Usage

Arguments

References

Examples

Divergence-based classifier for SAR/PolSAR features (R6)

Description

Value

Public fields

Methods

Public methods

DivergenceClassifier$new()

Usage

Arguments

DivergenceClassifier$fit()

Usage

Arguments

DivergenceClassifier$distances()

Usage

Arguments

DivergenceClassifier$predict()

Usage

Arguments

DivergenceClassifier$print()

Usage

Arguments

DivergenceClassifier$clone()

Usage

Arguments

References

Examples

Entropy-based segmentation by (stochastic) EM (R6)

Description

Value

Public fields

Methods

Public methods

EntropySegmenter$new()

Usage

Arguments

EntropySegmenter$fit()

Usage

Arguments

EntropySegmenter$predict()

Usage

Arguments

EntropySegmenter$label_map()

Usage

EntropySegmenter$print()

`CompoundWishart$new()`

`CompoundWishart$density()`

`CompoundWishart$random()`

`CompoundWishart$fit()`

`CompoundWishart$entropy()`

`CompoundWishart$entropy_variance()`

`CompoundWishart$clone()`

`DivergenceClassifier$new()`

`DivergenceClassifier$fit()`

`DivergenceClassifier$distances()`

`DivergenceClassifier$predict()`

`DivergenceClassifier$print()`

`DivergenceClassifier$clone()`

`EntropySegmenter$new()`

`EntropySegmenter$fit()`

`EntropySegmenter$predict()`

`EntropySegmenter$label_map()`

`EntropySegmenter$print()`

`EntropySegmenter$clone()`

`G0I$new()`

`G0I$density()`

`G0I$random()`

`G0I$fit()`

`G0I$entropy()`

`G0I$clone()`

`G0Polarimetric$new()`

`G0Polarimetric$density()`

`G0Polarimetric$random()`

`G0Polarimetric$fit()`

`G0Polarimetric$entropy()`

`G0Polarimetric$clone()`

`GGammaSAR$new()`

`GGammaSAR$density()`

`GGammaSAR$random()`