Package 'spectralR'

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

sf_data	polygons of surface classes as a sf object, created through prepare.vector.data
startday	starting day for Sentinel image collection, as "YYYY-MM-DD". See Note 1 below
endday	final day for Sentinel image collection, as "YYYY-MM-DD"
cloud_threshold	maximum percent of cloud-covered pixels per image by which individual
scale_value	the scale of resulting satellite images in meters (pixel size). See Note 2 below

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

shapefile_name	shapefile name (should be within working directory, using absolute paths were not tested)
label_field	name of the field which contains class labels

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

data	reflectance data as dataframe with pixel values for Sentinel optical bands B2, B3, B4, B5, B6, B7, B8, B8A, B11, B12
target_classes	list of the classes of surface which should be highlighted, others will be turned in gray, as a background. Defaults is NULL.

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")
  )

---

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 [email protected]

Other contributors:

• Dariia Shyriaieva [email protected] [contributor]

• Vladimir Mikryukov [email protected] [contributor]

See Also

Useful links:

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

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

---

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

data	reflectance data as dataframe with pixel values for Sentinel optical bands B2, B3, B4, B5, B6, B7, B8, B8A, B11, B12
target_classes	list of the classes of surface which should be highlighted, others will be turned in gray, as a background. Defaults is NULL.
point_size	Size of points on a plot
fatten	A multiplicative factor used to increase the size of points in comparison with standard deviation lines
x_dodge	Position adjustment of points along the X-axis

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

data	reflectance data as dataframe with pixel values for Sentinel optical bands B2, B3, B4, B5, B6, B7, B8, B8A, B11, B12

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()

---