spectralR: A package for obtaining and visualizing spectral reflectance data for earth surface polygons

Description

This package aims to obtain, process, and visualize spectral reflectance data for the user-defined land or water surface classes for visual exploring in which wavelength the classes differ. Input should be a shapefile with polygons of surface classes (it might be different habitat types, crops, vegetation, etc.). The Sentinel-2 L2A satellite mission optical bands pixel data are obtained through the Google Earth Engine service and used as a source of spectral data.

Currently spectralR package provides several main functions

get.pixel.data prepare.vector.data spectral.curves.plot stat.summary.plot violin.plot

Author(s)

Maintainer: Oleh Prylutskyi oleh.prylutskyi@gmail.com

Other contributors:

• Dariia Shyriaieva darshyr@gmail.com [contributor]

• Vladimir Mikryukov vladimir.mikryukov@ut.ee [contributor]

See Also

Useful links:

• https://github.com/olehprylutskyi/spectralR/

• Report bugs at https://github.com/olehprylutskyi/spectralR/issues

Obtain Sentinel-2 spectral reflectance data for user-defined vector polygons

Description

The function takes sf polygon object, created through prepare.vector.data function, and retrieves data frame with brightness values for each pixel intersected with polygons, for each optical band of Sentinel-2 sensor, marked according to the label of surface class from the polygons.

Usage

get.pixel.data(sf_data, startday, endday, cloud_threshold, scale_value)

Arguments

Value

A dataframe (non-spatial) with unscaled reflectance data for each pixel of median satellite image, for each optical band of Sentinel-2 sensor, marked according to the label of surface class from the polygons.

Note 1. Particular satellite imagery is typically not ready for instant analysis - it contains clouds, cloud shadows, athmospheric aerosols, and may cover not all the territory of your interest. Another issue is that each particular pixel slightly differs in reflectance between images taken on different days due to differences in atmospheric conditions and angle of sunlight at the moments images were taken. Google Earth Engine has its own build-in algorithms for image pre-processing, atmospheric corrections and mosaicing, which allows to obtain a ready-to-use, rectified image. The approach used in this script is to find a median value for each pixel between several images within each of 10 optical bands and thereby make a composite image. To define a set of imageries between which we will calculate the median, we should set a timespan defining starting and final days. Sentinel-2 apparatus takes a picture once a 5 days, so if you set up a month-long timesnap, you can expect each pixel value to be calculated based on 5 to 6 values.

Note 2. You may set up any image resolution (pixel size) for satellite imagery with GEE, but this is hardly reasonable to set the finer resolution than the finest for satellite source. The finest resolution for Sentinel data is 10 m, while using higher scale_value requires less computational resources and returns a smaller resulting dataframe. Although sampling satellite data performs in a cloud, there are some memory limitations placed by GEE itself. If you are about to sample really large areas, consider setting a higher 'scale' value (100, 1000). More about GEE best practices: https://developers.google.com/earth-engine/guides/best_practices

Examples

## Not run: 
# Downlad spectral reflectance data
reflectance <-  get.pixel.data(
  sf_data = sf_df,
  startday = "2019-05-15",
  endday = "2019-06-30",
  cloud_threshold = 10,
  scale_value = 100)

head(reflectance)

## End(Not run)

Prepare vector data for further reflectance data sampling

Description

The function takes shapefile with polygons of different surface classes (habitats, crops, vegetation, etc.), and retrieves ready-for-sampling sf object.

Usage

prepare.vector.data(shapefile_name, label_field)

Arguments

Value

sf object with label (characters) and class (integer) variables, as well as geometry of each polygon, ready to further processing by rgee.

Examples

# Load example data
load(system.file("testdata/reflectance_test_data.RData", package = "spectralR"))

# Prepare vector data
sf_df <- prepare.vector.data(
  shapefile_name = system.file("extdata/test_shapefile.shp", package = "spectralR"),
  label_field = "veget_type")

head(sf_df)

Make spectral reflectance curves for defined classes of surface

Description

Make spectral reflectance curves for defined classes of surface

Usage

spectral.curves.plot(data, target_classes = NULL)

Arguments

Value

ggplot2 object with basic visual aesthetics, represents smoother lines with confidence intervals for each surface class. Default aesthetic is smoother curve (geom_smooth). May be time-consuming depending on input dataframe size. See https://ggplot2.tidyverse.org/reference/geom_smooth.html for more details.

Examples

# Load example data
load(system.file("testdata/reflectance_test_data.RData", package = "spectralR"))

# Create a plot
p <- spectral.curves.plot(data = reflectance)

# Customize a plot
p +
  ggplot2::labs(x = 'Wavelength, nm', y = 'Reflectance',
      colour = "Surface classes",
      fill = "Surface classes",
      title = "Spectral reflectance curves for different classes of surface",
      caption = 'Data: Sentinel-2 Level-2A')+
  ggplot2::theme_minimal()

# Highlight only specific target classes
spectral.curves.plot(
  data = reflectance,
  target_classes = list("meadow", "coniferous_forest")
  )

Statistical summary plot of reflectance values

Description

Make a plot with statistical summary of reflectance values (mean, mean-standard deviation, mean+standard deviation) for defined classes of surface.

Usage

stat.summary.plot(
  data,
  target_classes = NULL,
  point_size = 0.6,
  fatten = 4,
  x_dodge = 0.2
)

Arguments

Value

ggplot2 object with basic visual aesthetics. Default aesthetics are line with statistical summary for each satellite band ([geom_line()] + [geom_pointrange()]). See [geom_linerange](https://ggplot2.tidyverse.org/reference/geom_linerange.html) and [geom_path](https://ggplot2.tidyverse.org/reference/geom_path.html) documentation for more details.

Wavelengths values (nm) acquired from mean known value for each optical band of Sentinel 2 sensor https://en.wikipedia.org/wiki/Sentinel-2

Examples

# Load example data
load(system.file("testdata/reflectance_test_data.RData", package = "spectralR"))

# Create a summary plot
p <- stat.summary.plot(data = reflectance)

# Customize a plot
p +
  ggplot2::labs(x = 'Sentinel-2 bands', y = 'Reflectance',
      colour = "Surface classes",
      title = "Reflectance for different surface classes",
      caption='Data: Sentinel-2 Level-2A\nmean ± standard deviation')+
  ggplot2::theme_minimal()

# Highlight only specific target classes
stat.summary.plot(
   data = reflectance,
   target_classes = list("meadow", "coniferous_forest")
  )

Create violin plots of reflectance per band for each surface class

Description

Create violin plots of reflectance per band for each surface class

Usage

violin.plot(data)

Arguments

Value

ggplot2 object with basic visual aesthetics. Default aesthetics is violin plot for each satellite band (geom_violin). See https://ggplot2.tidyverse.org/reference/geom_violin.html for more details.

Examples

# Load example data
load(system.file("testdata/reflectance_test_data.RData", package = "spectralR"))

# Create a plot
p3 <- violin.plot(data = reflectance)

# Customize a plot
p3 +
  ggplot2::labs(x='Surface class',y='Reflectance',
      fill="Surface classes",
      title = "Reflectance for different surface classes",
      caption='Data: Sentinel-2 Level-2A')+
  ggplot2::theme_minimal()