R/dsp_plot_map.R

In kkdey/ecostructure: Visualizing Structure in ecological site-species abundance data

#' @title Create geographical heatmaps from a dispersion field list
#'
#' @description Creates simple geographical heatmaps for easily visualizing 
#'  dispersion fields. Uses a dispersion field list generated by 
#'  the \code{dsp_create_from_survey} and global shapefiles 
#'  of coastlines and country boundaries to sketch the background.
#'
#' @param disp_fld_list The list of dispersion fields generated by the
#'                      \code{dsp_create_from_survey} function. Objects in the list
#'                      can be RasterLayers, it which case proj and boundings 
#'                      from the rasters are used for plotting, or matrices, 
#'                      in which case proj and boundings must be provided. 
#' @param scale Type of scale to be used for the legend. One of 
#'              c("count","percentage"). Defaults "count".
#' @param color_ramp Color palette to be used for the heat map. 
#' @param raster_latlim If disp_fld_list is a list of matrices, the latitudinal range 
#'                      of the dispersion fields must be provided as a vector. 
#' @param raster_longlim If disp_fld_list is a list of matrices, the longitudinal range 
#'                      of the dispersion fields must be provided as a vector. 
#' @param outline_col The outline color of the projected map.
#' @param proj A character string of projection arguments; the arguments must be entered 
#'            exactly as in the PROJ.4 documentation. To be evaluated by sp::CRS(). 
#'            default '+proj=longlat +ellps=WGS84'. 
#'            
#' @return Returns a heatmap of the dispersion field using the specified raster
#'
#' @examples
#' data("dispersion_field_ex")
#' maps <- dsp_plot_map(dispersion_field_ex, 
#'                      scale = "percentage",
#'                      raster_latlim = c(5,50),
#'                      raster_longlim = c(50,120))
#' maps[[1]]
#'
#' @importFrom raster extent raster 
#' @importFrom rasterVis rasterTheme levelplot
#' @importFrom sp sp.lines CRS spTransform
#' @importFrom latticeExtra layer
#' @import grDevices
#' @export

##########  Create a set of maps from dispersion field data ##################

dsp_plot_map = function(disp_fld_list,
                        scale = "count",
                        color_ramp = c("darkseagreen3","orange","red"),
                        raster_latlim = c(5,50),
                        raster_longlim = c(50,120),
                        outline_col = "black",
                        proj = '+proj=longlat +ellps=WGS84'){
  
  global_boundaries <- sf::st_read(system.file("extdata","ne_110m_admin_0_boundary_lines_land",
                                               "ne_110m_admin_0_boundary_lines_land.shp",
                                               package = "ecostructure"),quiet=T)
  
  ext_gbl_bnd <- raster::extent(global_boundaries)
  
  global_coast <- sf::st_read(system.file("extdata","ne_110m_coastline",
                                          "ne_110m_coastline.shp",
                                          package = "ecostructure"),quiet=T)
  
  ext_gbl_cst <- raster::extent(global_coast)
  
  if(!proj=='+proj=longlat +ellps=WGS84'){
    global_boundaries <- st_transform(global_boundaries, proj)
    global_coast <- st_transform(global_coast, proj)
    
    global_boundaries <- as(global_boundaries,'Spatial')
    global_boundaries@bbox <- as.matrix(ext_gbl_bnd)
    global_coast <- as(global_coast,'Spatial')
    global_coast@bbox <- as.matrix(ext_gbl_cst)
  } else {
    global_boundaries <- as(global_boundaries,'Spatial')
    global_coast <- as(global_coast,'Spatial')
  }
  
  
  newtheme <- rasterVis::rasterTheme(region = grDevices::colorRampPalette(color_ramp)( 100 ))
  
  obj_class <- class(disp_fld_list[[1]])[[1]]
  
  if(scale=="count"){
    col_key <- list(space='right')
  } else if(scale=="percentage"){
    col_key <- list(at=seq(0, 100, 1),
                    labels=list(at=c(25,50,75,100),
                                labels=c("25%", "50%", "75%", "100%")))
  }
  ADF <- list()
  for (i in 1:length(disp_fld_list)){
    if (obj_class=="matrix"){
      r <- raster::raster(disp_fld_list[[i]],
                          xmn=raster_longlim[1],
                          xmx=raster_longlim[2],
                          ymn=raster_latlim[1],
                          ymx=raster_latlim[2],
                          crs=sp::CRS(proj))
    } else if (obj_class=="RasterLayer"){
      r <- disp_fld_list[[i]]
    } else {
      stop("disp_fld_list must be a list of objects with class 'matrix' or 'RasterLayer'")
    }
    ADF[[i]] <- rasterVis::levelplot(r, par.settings = newtheme,
                                     contour=F, margin=FALSE,
                                     at=seq(0, raster::maxValue(r), length.out=100),
                                     colorkey = col_key) +
      latticeExtra::layer(sp::sp.lines(global_boundaries,col =outline_col, lwd=0.5),
                          data=list(outline_col = outline_col,
                                    global_boundaries = global_boundaries)) +
      latticeExtra::layer(sp::sp.lines(global_coast,col =outline_col, lwd=0.5),
                          data=list(outline_col = outline_col,
                                    global_coast = global_coast))
  }
  names(ADF)<-names(disp_fld_list)
  return(ADF)
}