visa: Vegetation Imaging Spectroscopy Analyzer

Description

Provides easy-to-use tools for data analysis and visualization for hyperspectral remote sensing (also known as imaging spectroscopy), with a particular focus on vegetation hyperspectral data analysis. It consists of a set of functions, ranging from the organization of hyperspectral data in the proper data structure for spectral feature selection, calculation of vegetation index, multivariate analysis, as well as to the visualization of spectra and results of analysis in the 'ggplot2' style.

Details

The visa package provides a set of functions for hyperspectral data analysis, with the main purpose of simplifying the analysis and interpretation of vegetation spectral data.

It implement two categories of important functions, including its own function and also some built on other r packages.

• vegetation indices, and

• multivariate analyses....

To know more about visa, check the vignettes: 'browseVignettes("visa")'

Vegetation Indices

Support the calculation of vegetation indices from literature, as well as creation of new indices.

Multivariate analysis

... not implemented yet The multivariate analysis use the Spectra.Dataframe format.

Author(s)

Kang Yu

See Also

Useful links:

• https://github.com/kang-yu/visa

• Report bugs at https://github.com/kang-yu/visa/issues

Example data in the Spectra.Dataframe format

Description

A dataset containing the plant Nitrogen content and spectra. The Spectra matrix is stored as a variable (in a column) of a data.frame.

Usage

NSpec.DF

Format

A data frame with 19 rows and 2 variables:

N

Plant nitrogen content

spectra

A variable of Matrix of plant spectra

...

See Also

data.frame and NSpec.Lib

Examples

library(visa)
data(NSpec.DF)
str(NSpec.DF)

Example data in the Spectra/SpectraLibrary format.

Description

A S4 data structure containing the plant spectra and nitorgen (N) content. Spectra is organized as a matrix and is stored as a slot, named 'spectra'. The corresponding N content is stored in the slot 'data', which is a data.frame used for storing supporting data and plant/vegetation traits, such as here the plant N content.

Usage

NSpec.Lib

Format

A Spectra object with 19 rows and 4 slots (spectra, wavelength, w.unit, data).

spectra

A matrix of plant spectral data

wavelength

A vector of wavelength for the 'spectra' data

w.unit

A character string of wavelength unit (default "nm")

data

A data.frame of vegetation traits, here plant nitrogen content

...{currently not used}

Examples

library(visa)
data(NSpec.Lib)
str(NSpec.Lib)

Create a Spectra or SpectraLibrary

Description

Constructor as.spectra creates a Spectra object.

Constructor as.spectra.library creates a SpectraLibrary object.

Usage

as.spectra(
  spectra = matrix(0),
  wavelength = numeric(0),
  w.unit = "nm",
  data = data.frame(),
  ...
)

as.spectra.library(
  spectra = matrix(0),
  wavelength = numeric(0),
  w.unit = "nm",
  data = data.frame(),
  ...
)

Arguments

Slots

spectra

A matrix

wavelength

A numeric vector

w.unit

A character string

data

A data.frame

Examples

s <- as.spectra(matrix(1:100, 4), 1:25, "nm", data.frame(x = letters[1:4]))
str(s)

s <- as.spectra.library(matrix(1:100, 4), 1:25, "nm", data.frame(x = letters[1:4]))
str(s)

Class 'SpectraDataframe'

Description

SpectraDataframe is an extended 'Spectra' class, with associated vegetation data ('data') in a data.frame.

Slots

spectra

A matrix

wavelength

A numeric vector

w.unit

A character string

data

A data.frame of vegetation data corresponding to the spectra

Class 'SpectraLibrary'

Description

SpectraLibrary is an extended 'Spectra' class, with associated vegetation data ('data') in a data.frame.

Slots

spectra

A matrix

wavelength

A numeric vector

w.unit

A character string

data

A data.frame of vegetation data corresponding to the spectra

Class 'SpectraMatrix'

Description

SpectraMatrix is a extended 'Spectra' class.

Constructor as.spectra.matrix creates a SpectraMatrix object.

Usage

as.spectra.matrix(
  spectra = matrix(0),
  wavelength = numeric(0),
  w.unit = character(0)
)

Arguments

Value

Examples

smatrix <- as.spectra.matrix(matrix(1:10, 1), 1:10, "nm")
str(smatrix)

Create a SpectraDataframe

Description

Constructor as.spectra.dataframe function creates a SpectraDataframe object, which is equivalent to the use of as.specdf.

Usage

as.spectra.dataframe(
  spectra = matrix(0),
  wavelength = numeric(0),
  w.unit = character(0),
  data = data.frame(0),
  ...
)

Arguments

Value

Examples

sdf <- as.spectra.dataframe(matrix(1:10, 1), 1:10, "nm", data.frame(a = 1, b =2))
str(sdf)

Selecting the best 2-Band combinations for Normalized Simple Ratio (NSR)

Description

This function develops an optimization algorithm based on correlation analysis between the spectral matrix spectra and the vegetation variable of interest x. It determines the best spectral band combinations (i, j) of the full spectrum that are most predictive for x.

Usage

cm.nsr(S, x, w = wavelength(S), w.unit = NULL, cm.plot = FALSE)

Arguments

Details

For every possible pair of distinct bands (i, j), the function calculates

\mathrm{NSR} = \frac{R_j - R_i}{R_j + R_i}

and then computes the squared Pearson correlation (R^2) between x and the resulting NSR values.

If the two bands are identical or the standard deviation of computed VI (for a given band combination) is zero, the correlation is set to 0, thereby avoiding warnings.

Value

See Also

cor

Examples

## Not run: 
  library(visa)
  data(NSpec.DF)
  X <- NSpec.DF$spectra[, seq(1, ncol(NSpec.DF$spectra), 5)]  # resampled to 5 nm steps
  y <- NSpec.DF$N  # nitrogen
  cm <- cm.nsr(X, y, cm.plot = TRUE)

## End(Not run)

Calculate 3-Band Correlation Array for Spectral Data correlating with another variable x

Description

This function computes the squared Pearson correlation (R^2) between a response vector x and a derived variable V for every possible combination of three distinct spectral bands. The derived variable V is calculated using the formula:

V = \frac{R_k - R_j}{R_j - R_i}

where R_i, R_j, and R_k represent the reflectance values at bands i, j, and k, respectively.

Usage

cm.rbd3(
  S,
  x,
  w = wavelength(S),
  w.unit = NULL,
  cm.plot = FALSE,
  plot.method = "default"
)

Arguments

Details

The function prints the maximum R^2 value and the corresponding band wavelengths. Optionally, it can produce a 3D slice plot of the correlation array using plot3D::slice3D.

For every combination of three distinct bands (i, j, k), the function computes

V = \frac{R_k - R_j}{R_j - R_i}

and then calculates the squared Pearson correlation between x and V. The maximum R^2 value and its associated band combination are printed.

If cm.plot is set to TRUE, the function generates a 3D slice plot of the correlation array using the best band combination, where the slices correspond to the wavelengths of the bands.

Value

A 3-dimensional array of squared correlation (R^2) values with dimensions corresponding to the combinations of bands i, j, and k.

Examples

## Not run: 
  library(visa)
  data(NSpec.DF)
  x <- NSpec.DF$N # nitrogen
  # Below resamples spectra to 20 nm for fast computation
  S <- NSpec.DF$spectra[, seq(1, ncol(NSpec.DF$spectra), 20)]
  # S is a spectral data object and x is a numeric vector.
  Rsq3 <- cm.rbd3(S, x, cm.plot = TRUE)

## End(Not run)

Selecting the best 2-Band combinations for Simple Ratio (SR)

Description

This function develops an optimization algorithm based on correlation analysis between the spectral matrix spectra and the vegetation variable of interest x. It determines the best spectral band combinations of the full spectrum that are most predictive for x.

Usage

cm.sr(S, x, w = wavelength(S), w.unit = NULL, cm.plot = FALSE)

Arguments

Details

This function runs a calculation of

SR = \lambda_i / \lambda_j

using the spectra data for all the possible pairs/combinations of any two bands (i, j) within the full spectrum range. Next, correlation analysis is then performed between all possible SR values and another vector variable y, and it returns the squared Pearson correlation (R^2) which indicates the predictive performance of each SR and its corresponding two-band combination. The output is the wavelength (nm) indicating the best two bands that produce the highest value of R^2.

Value

See Also

cm.nsr

Examples

## Not run: 
  library(visa)
  data(NSpec.DF)
  # Using the example spectra matrix of the spectra.dataframe
  X <- NSpec.DF$spectra[, seq(1, ncol(NSpec.DF$spectra), 10)]  # resampled to 10 nm steps
  y <- NSpec.DF$N  # nitrogen
  cm <- cm.sr(X, y, cm.plot = FALSE)

## End(Not run)

Find Best Band Combinations

Description

This function identifies the best band combination from the cm.nsr or cm.sr calculated correlation coefficients - a numeric matrix (2D), or the cm.rbd3 returned array (3D) by locating the maximum value in the input R and returning the corresponding wavelengths from w. For a 2D matrix, it returns a two-element vector (i, j); for a 3D array, a three-element vector (i, j, k).

Usage

find.bestBands(R, w)

Arguments

Details

The function first verifies that R has dimensions. It then computes the maximum value in R, retrieves the indices corresponding to that value, and extracts the wavelengths from w based on the dimensionality of R. If R is 2D, the order is assumed to be (i, j); if R is 3D, the order is (i, j, k).

Value

A vector of wavelengths corresponding to the best band combination.

Examples

# Example for a 2D matrix:
R_mat <- matrix(c(0.2, 0.8, 0.5, 0.3), nrow = 2)
wavelengths <- c(450, 550)
bestBands <- find.bestBands(R_mat, wavelengths)

# Example for a 3D array:
R_arr <- array(runif(27), dim = c(3, 3, 3))
wavelengths <- c(400, 450, 500)
bestBands <- find.bestBands(R_arr, wavelengths)

Plot functions

Description

This function plots a linear model fit using ggplot2. It creates a scatter plot with a regression line, and displays the regression equation along with the R² value.

Usage

## S3 method for class 'lmfit'
ggplot(data, mapping = NULL, ..., environment = parent.frame())

Arguments

Details

When provided with two numeric vectors, the function treats them as x and y values, respectively, constructs a data frame, and applies a default mapping. Alternatively, if a data frame is provided, an aesthetic mapping (or default mapping) will be used.

Value

A ggplot object.

Examples

## Not run: 
  library(visa)
  # Using numeric vectors for x and y:
  ggplot.lmfit(1:10, 2:11)

  # Using a data frame:
  df <- data.frame(x = runif(10, 1, 10), y = runif(10, 2, 11) + 0.5)
  ggplot.lmfit(df, aes(x, y))

## End(Not run)

Create a ggplot Plot from Correlation Coefficients (Deprecated)

Description

**Deprecated:** This function is deprecated and will be removed in a future release. Please use plt.2dcm for 2D correlation matrices or the appropriate new functions for 3D plots.

Usage

## S3 method for class 'cm'
ggplot(
  data,
  mapping = NULL,
  ...,
  show.stat = TRUE,
  environment = parent.frame()
)

Arguments

Details

This function creates a ggplot visualization from a 2D correlation matrix. It attempts to extract numeric wavelengths from the column names of the input matrix.

This function extracts numeric wavelengths from the column names of data. If these cannot be determined, sequential indices are used instead.

Value

A ggplot object visualizing the correlation matrix. For 3D arrays, returns NULL.

Examples

## Not run: 
  library(visa)
  data(NSpec.DF)
  x <- NSpec.DF$N  # nitrogen
   # resampled to 10 nm steps
  S <- NSpec.DF$spectra[, seq(1, ncol(NSpec.DF$spectra), 10)]
  cm2d <- cm.sr(S, x, cm.plot = FALSE)
  p2d <- ggplot.cm(cm2d)
  print(p2d)


## End(Not run)

Create a new ggplot plot with a geom_line() layer from spectra data

Description

ggplot() initializes a ggplot object. It can be used to declare the input spectra object for a graphic and to optionally specify the set of plot aesthetics intended to be common throughout all subsequent layers unless specifically overridden.

Usage

## S3 method for class 'spectra'
ggplot(
  data,
  mapping = NULL,
  ...,
  wl = NULL,
  w.unit = "nm",
  environment = parent.frame()
)

Arguments

Details

ggplot() is typically used to construct a plot incrementally, using the + operator to add layers to the existing ggplot object. This is advantageous in that the code is explicit about which layers are added and the order in which they are added. For complex graphics with multiple layers, initialization with ggplot is recommended.

Note

Current implementation does not merge default mapping with user supplied mapping. If user supplies a mapping, it is used as is. To add to the default mapping, aes() can be used by itself to compose the ggplot.

See Also

?ggpmisc::ggplot()

Examples

library(visa)
library(ggplot2)
ggplot.spectra(NSpec.DF)

Calculate and plot a 2-band NDVI.

Description

This function calculates a 2-band NDVI using the nsr function.

Usage

ndvi2(s, b1, b2)

Arguments

Details

Calculate a NDVI with two specific bands of choice. The new NDVI follows the the standard formula

NDVI = (\lambda_i + \lambda_j)/(\lambda_i - \lambda_j)

. Bands i and j correspond to the b1 and b2 input arguments, respectively. Wavelength indexes are determined based on the first argument 's'.

Value

Examples

library(visa)
s <- NSpec.DF$spectra
ndvi2(s, 780, 680)

Calculate Normalized Simple Ratio (NSR) index.

Description

It is a normalization of SR by doing NSR = (1-SR)/(1+SR), with the same two spectral bands.

Usage

nsr(s, b1, b2)

lm.nsr(s, b1, b2, y)

Arguments

Details

As it exactly reads in its name, it is a normalization of the SR and ranges in (0,1).

Value

Examples

s <- NSpec.DF$spectra
nsr1 <- nsr(s, 480, 550)

s <- NSpec.DF
y <- NSpec.DF$N
lm.nsr(s,600,500,y)

Create a ggplot Plot from a 2D Correlation Matrix

Description

This function creates a ggplot visualization from a 2D correlation matrix, such as those produced by cm.sr or cm.nsr. The function attempts to extract numeric wavelengths from the column names. If the extraction fails, sequential indices are used.

Usage

plt.2dcm(
  data,
  mapping = NULL,
  ...,
  show.stat = TRUE,
  environment = parent.frame()
)

Arguments

Details

It replaces the former ggplot.cm().

The function extracts numeric wavelengths from the column names of data. If these cannot be determined, sequential indices are used instead.

Value

A ggplot object visualizing the correlation matrix.

Examples

## Not run: 
  library(visa)
  data(NSpec.DF)
  x <- NSpec.DF$N  # nitrogen
  S <- NSpec.DF$spectra[, seq(1, ncol(NSpec.DF$spectra), 10)]  # resampled to 10 nm steps
  cm2d <- cm.sr(S, x, cm.plot = FALSE)
  p2d <- plt.2dcm(cm2d)
  print(p2d)

## End(Not run)

Create a 3D Slice Plot of Correlation Array

Description

This function creates an interactive Plotly 3D slice plot from a 3D correlation array. The function uses the array's dimnames to define the coordinate values. If no dimnames are present, a warning is issued and sequential indices are used. The plot displays three surfaces corresponding to slices along each dimension (i, j, k) at the best band combination (where the correlation value is maximal).

Usage

plt.3dcm_best(R3, colorscale = "Spectral")

Arguments

Details

The function first checks if the input 3D array has proper dimnames. If not, it issues a warning and assigns sequential indices as dimnames. It then melts the array to find the best band combination based on the maximum correlation value. Using the dimnames, it finds the numeric indices for the best bands and creates grid matrices for each slice. A custom colorscale is built when colorscale = "Spectral", and the Plotly figure is constructed with a single color bar.

Value

An interactive Plotly figure showing three surfaces corresponding to constant slices along dimensions i, j, and k.

Examples

## Not run: 
  # Assume cm3d is a 3D correlation array with proper dimnames.
  plt.3dcm_best(cm3d)

## End(Not run)

Access the spectra data of 'SpectraLibrary'.

Description

Functions to access slot data of the Class Spectra.

Usage

spectra(object, ...)

## S4 method for signature 'Spectra'
spectra(object, ...)

## S4 method for signature 'data.frame'
spectra(object, ...)

## S4 method for signature 'matrix'
spectra(object, ...)

Arguments

Details

Construct generic functions for the Spectra object, spectra.data.frame, and spectra.matrix.

Examples

# For the S4 class 'Spectra'
library(visa)
data(NSpec.Lib)
spectra_matrix <- spectra(NSpec.Lib)
# For the spectra data.frame
data(NSpec.DF)
spectra_matrix <- spectra(NSpec.DF)

Calculate Simple Ratio (SR).

Description

Simple Ratio is the ratio of the spectra (mostly reflectance) between two bands in the format of

SR = \lambda_i/\lambda_j

Usage

sr(s, b1, b2)

lm.sr(s, b1, b2, y)

Arguments

Details

Simple ratio and NDVI looking indices are the two groups of mostly used spectral indices in remote sensing.

Value

Examples

library(visa)
s <- NSpec.DF$spectra
sr1 <- sr(s, 480, 550)

s <- NSpec.DF
y <- NSpec.DF$N
lm.sr(s,600,500,y)

Retrieve Wavelength Information from Spectra Objects

Description

This function extracts the wavelength information from various representations of spectra. It supports the S4 class Spectra, as well as data.frame and matrix representations.

Usage

wavelength(object, ...)

## S4 method for signature 'Spectra'
wavelength(object, ...)

## S4 method for signature 'data.frame'
wavelength(object, ...)

## S4 method for signature 'matrix'
wavelength(object, ...)

Arguments

Details

For an object of class Spectra, the method returns the value stored in the wavelength slot. For a data.frame or matrix, it extracts numeric values from the column names (by removing non-digit characters) of the spectra data.

Value

A numeric vector representing the wavelength information extracted from the object.

Examples

## Not run: 
  library(visa)

  # For an S4 Spectra object
  wavelengths <- wavelength(NSpec.Lib)

  # For spectra stored in a data.frame
  wavelengths <- wavelength(NSpec.DF)

  # For spectra stored in a matrix
  wavelengths <- wavelength(spectra_matrix)

## End(Not run)