ts_flow_frames: Create a series of charts of a raster time series

Description

Create a series of charts of a raster time series

Usage

ts_flow_frames(
  r_list,
  positions = NULL,
  position_names = NULL,
  band_names = NULL,
  band_colors = NULL,
  val_min = NULL,
  val_max = NULL,
  val_by = NULL,
  plot_size = 1,
  position_legend = NULL,
  legend_position = "right",
  band_legend = NULL,
  band_legend_title = NULL,
  position_legend_title = NULL,
  pbuffer = NULL,
  plot_function = "line",
  aes_by_pos = TRUE,
  FUN = NULL,
  return_df = FALSE,
  ...
)

Arguments

r_list

list of rasters, as generated by ts_raster.

positions

(Optional) object containing the coordinates. One of

A two-column matrix of coordinates where the first column corresponds to the longitude and the second column corresponds to the latitude.
A SpatialPolygonsDataFrame
A SpatialPointsDataFrame
An sf object containing POINTS,POLYGONS or MULTIPOLYGONS

If no positions are specified, one position is assumed to be the entire extent of the rasters.

position_names

(Optional) character, names of the positions to be added in legend or text. By default, will create placeholder names by combining the object type and Id (Example: "Polygon 3")

band_names

(Optional) character, names of the bands to be added in legend, if band_legend. By default, will create placeholder names by band index (Example: "Band 3").

band_colors

(Optional) character, colors which represent the bands in the plot. Must be in matching order to band_names. If r_list is discrete, the colors will be mapped to the different levels. By default will use ggplot colors.

val_min

(Optional) numeric, minimum value of the y-axis. By default chooses a rounded minimum value of the rasters contained within r_list.

val_max

(Optional) numeric, maximum value of the y-axis. By default chooses a rounded maximum value of the rasters contained within r_list.

val_by

(Optional) numeric, interval value of the y-axis. Default is 0.1.

plot_size

(Optional) numeric, size for the ggplot objects. Default is 1.

position_legend

(Optional) logical. If TRUE: Add a legend for the positions. Only recommended if aes_by_pos is also TRUE.

legend_position

(Optional) character, position of the legend. Use "none" to disable all legends. Default is "right".

band_legend

(Optional) logical. If TRUE: Add a legend for the bands. Default is TRUE.

band_legend_title

(Optional) character, title of the band legend. Default is "Bands".

position_legend_title

(Optional) character, title of the band legend. Default is "Positions".

pbuffer

(Optional) numeric. The radius of a buffer around each object which will be applied before extraction. By default, no buffer is used.

plot_function

(Optional) character or function, type of the plots to produce. Currently supported are 'line', 'line2', 'vio', 'dens', 'dens2', 'bar_stack', 'bar_fill', 'pie'.One of

'line' A line chart, suited for comparing trends between bands
'line2' A line chart, suited for comparing trends between positions
'vio' A density chart, suited for comparing of distributions across bands and positions
'dens' A density chart, suited for comparing of distributions across positions
'dens2' A density chart, suited for comparing of distributions across bands
'bar_stack' A horizontal bar chart, suited for visualizing counts and proportions among discrete data.
'bar_fill' A horizontal bar chart, suited for visualizing proportions among discrete data.
'pie' A pie chart, suited for visualizing rough proportions among discrete data with few categories.

Alternatively, a custom function with similar structure and arguments can be passed to create other types of plots. Default is "line".

aes_by_pos

(Optional) logical. If TRUE: vary the linetype aesthetic to be different for each position? If FALSE, this also disables the position_legend, as no notable classes will be plotted. Ignored by some plot types which inherently map position to facets. Default is TRUE.

FUN

(Optional) function to summarize the values (e.g. mean) during the extraction. See extract for more details. Default is "NULL". Summarizing in this way is not sensible for many plot types which visualize distribution or count. Note that usually, summarize statistics will be calculated in an appropriate way by the plot_function rather than during the extraction.

return_df

(Optional) logical. Return a dataframe with the extracted values instead of a plot? This can be useful for experimenting with plot creation. Default is FALSE.

...

(Optional) additional arguments for plot_function.

Value

A list of ggplots, one for each element of r_list.

Details

Values are extracted using extract and plotted on a ggplot. The type of the ggplot is specified by plot_function. Currently supported are "line" and "violin" as well as custom functions which accept similar inputs. The function may fail for large polygons and long time series. Be aware that if ts_raster is used with fade, interpolation may be used to generate raster values.

Examples

Run this code

# NOT RUN {
#' #Setup
library(rtsVis)
# Load example dataset at a greatly increased interval
x_list <- MODIS_SI_ds[seq(1,length(MODIS_SI_ds),30)]
x_dates <- do.call(c, lapply(MODIS_SI_ds,attr,"time") )[seq(1,length(MODIS_SI_ds),30)]

#Fill NAs
x_list_filled <- ts_fill_na(x_list)

#Make a sequence of output dates, double the length of input dates
out_dates <-seq.POSIXt(from = x_dates[1],
                       to = x_dates[length(x_dates)],length.out = length(x_dates)*2 )

#For each output date, interpolate a raster image from the input files
r_list_out <- ts_raster(r_list = x_list_filled,
                        r_times = x_dates,
                        out_times = out_dates,
                        fade_raster = TRUE)
#Create the frames 
# as from the desired layers
r_frames <- ts_makeframes(x_list = r_list_out,samplesize = 10,
                          l_indices = c(1,4,3))

# Create a line plot from the data extracted over points
points <- SI_positions$points #Polygons of Slovenian municipalities covered by the raster
flow_frames_point_line <- rtsVis::ts_flow_frames(r_list = r_list_out,
 position_names = c("Ljubljana","Ivancna Gorica","Dolenjske Toplice","Loski Potok"),
 band_names = c("620 - 670","841 - 876","459 - 479","545 - 565"),
 positions = points,
 band_colors = c("firebrick3","darkorchid3","dodgerblue3","olivedrab3"),
           band_legend_title = "Wavelength [nm]",
           position_legend_title = "Obcina",
           legend_position = "bottom",
           position_legend = FALSE,
           band_legend=TRUE,aes_by_pos = TRUE)

#Check one of the frames
flow_frames_point_line[[5]]


# Create a violin plot from the data extracted over polygons
# polygons <- SI_positions$polygons
#flow_frames_poly_vio <-
#rtsVis::ts_flow_frames(r_list = r_list_out,
#           position_names = c("Radece","Ljubljana","Kocevje"),
#           band_names = c("620 - 670","841 - 876","459 - 479","545 - 565"),
#           positions = polygons,
#           band_colors = c("firebrick3","darkorchid3","dodgerblue3","olivedrab3"),
#           band_legend_title = "Wavelength [nm]",
#           position_legend_title = "Obcina",
#           position_legend = FALSE,
#          legend_position = "left",
#           band_legend=TRUE,aes_by_pos = FALSE,
#          plot_function = "vio")
#Check one of the frames
# flow_frames_poly_vio[[5]]

# }