map_ereefs_movie: Create a series of map image files for an animation of eReefs...

In BarbaraRobson/ereefs: Useful Functions to Handle eReefs and EMS model Output

Create a series of map image files for an animation of eReefs model output AND calculate temporal mean values.

Description

Creates and saves to disk a sequential series of colour map images showing concentrations of a specified eReefs model output variable at a specified model layer (by default, the surface layer). ALSO CALCULATES THE TEMPORAL MEAN value of each cell over the specified time (visualisation of maps can be suppressed by setting suppress_print to TRUE if this is the primary desired output). Maps produced are optionally overlain on a map of Queensland. Can be more efficient than calling map_ereefs multiple times if you want to produce an animation because it loads a month at a time for GBR4 runs (unless selected via catalog). If output files contain multiple outputs per day, chooses the step closest to midday and uses only daily output. To stitch together the images into an animation, you will need other software such as ImageMagick (recommended) or imageJ. Barbara Robson (AIMS).

Usage

map_ereefs_movie(
  var_name = "true_colour",
  start_date = c(2015, 12, 1),
  end_date = c(2016, 3, 31),
  layer = "surface",
  output_dir = "ToAnimate",
  Land_map = FALSE,
  input_file = "catalog",
  input_grid = NA,
  scale_col = c("ivory", "coral4"),
  scale_lim = c(NA, NA),
  zoom = 6,
  box_bounds = c(NA, NA, NA, NA),
  suppress_print = TRUE,
  stride = "daily",
  verbosity = 0,
  label_towns = TRUE,
  strict_bounds = FALSE,
  mark_points = NULL,
  gbr_poly = FALSE,
  add_arrows = FALSE,
  max_u = NA,
  scale_arrows = NA,
  show_bathy = FALSE,
  contour_breaks = c(5, 10, 20)
)

Arguments

var_name	Short name of the variable to plot. This can be any variable in the eReefs netcdf file that you are accessing (refer to eReefs model documentation or extract variable names from the netcdf file for a full list). In addition, two special var_name values are supported: 'true_colour' and 'plume'. 'true_colour' provides a simulated MODIS true colour image (refer to Baird et al., 2016 for en explanation).'plume' provides a map of calculated plume colour class as per Devlin et al. (2012) and Baird et al. (2017). Defaults to true_colour.
start_date	date for animation. Can either be a) a vector of integers in the format c(year, month, day, hour), c(year, month, day) or (year, month); b) a date obtained e.g. from as.Date(); or c) a character string formatted for input to as.Date(). Defaults to c(2015,2,1).
layer	Either an integer layer number or 'surface' to choose the surface layer. Defaults to 'surface'.
output_dir	Path to directory in which to store images for animation. Created if necessary. Defaults to 'ToAnimate'. Images are created in this directory with input_files beginning with var_name, followed by an underscore and then sequential numbers beginning with 100001.
Land_map	Set to TRUE to show a land map of Queensland. Default now FALSE.
input_file	is the URL or file location of any of the EMS output files or a THREDDS catalog URI. Defaults to a menu selection based on current NCI catalogs. Can also be set to "nci", "menu" or "catalog" for the same behaviour. Set to "old_menu" to provide old menu options instead of menu options from the NCI catalog. Numeric values are interpreted as references to selections available from the old menu. Short codes can be used for some options (codenames as used in https://research.csiro.au/ereefs/models/model-outputs/access-to-raw-model-output/ )
input_grid	Name of the locally-stored or opendap-served netcdf file that contains the grid coordinates for the cell corners (x_grid and y_grid). If not specified, the function will first look for x_grid and y_grid can be found in the first INPUT_STEM file, and if not found, will check whether the size of the variables in the input file corresponds to the size expected for GBR4 or GBR1, and load appropriate x and y grids from data files stored in this package. Alternatively, you can provide the location of a full (not simple-format) ereefs netcdf output file such as "http://dapds00.nci.org.au/thredds/dodsC/fx3/gbr4_hydro_all/gbr4_all_2016-09.nc"
scale_col	Vector of colours to use for the colour scale. This can be colours from the ggplot colour palette or a RGB hash code. Ignored for true_colour plots. If set to "spectral", uses a colour spectrum from bluish to red (similar to jet but less vivid). Otherwise: If one value is given, low colour is set to ivory and high colour to the value given. If two values are given, these are used as low and high limit colours. If three values are given, the middle value is used to set the mid-point of the scale. Defaults to c('ivory', 'coral4').
box_bounds	Minimum and maximum latitude and longitude coordinates to map. Defaults to the entire extent of the model output (though modified by the value of zoom). Format: c(longitude_min, longitude_max, latitude_min, latitude_max). It is recommended to also specify an appropriate value for zoom if specifying box_bounds.
suppress_print	Set to TRUE if you don't want the plots generated and saved. Defaults to TRUE.
stride	Default 'daily', but can otherwise be set to a numeric interval indicating how many time-steps to step forward for each frame.
verbosity	Set 0 for just a waitbar, 1 for more updates, 2 for debugging information. Default 0.
label_towns	Add labels for town locations to the figure. Default TRUE
strict_bounds	Obsolescent: ignored
mark_points	Data frame containing longitude and latitude of geolocations to mark with crosses (or a vector containing one location). Default NULL.
gbr_poly	TRUE to show contours of approximate reef areas. Default FALSE.
add_arrows	TRUE to show arrows indicating magnitude and direction of flow. Default FALSE.
max_u	Velocity at which to show maximum arrow length. Default NA, in which case it will use the maximum observed velocity.
scale_arrows	Factor by which to scale arrows. Values >1 result in longer arrows. Values <1 result in shorter arrows. Default 1.
show_bathy	TRUE to show contours based on the bathymetry as represented in the model. Default FALSE. Requires model file to contain botz (this requirement may be dropped in future versions for GBR1 and GBR4 runs).
contour_breaks	Depths in metres to show with show_bathy. Default c(5, 10, 20).
end	date for animation. Can either be a) a vector of integers in the format c(year, month, day); b) a date obtained e.g. from as.Date(); or c) a character string formatted for input to as.Date(). Defaults to c(2016,3,31).

Details

TODO: Update to use chron dates as has been done for functions in data_extraction_functions.R

Value

a list that includes data.frame formatted for use in ggplot2::geom_polygon, containing a map of the temporally averaged value of the variable specified in VAR_NAME over the selected interval, plus the actual values and cell centre latitudes and longitudes.

Examples

## Not run: 
map_ereefs_movie(start_date=c(2016,2,1),end_date=c(2016,2,15))

## End(Not run)

BarbaraRobson/ereefs documentation built on April 23, 2023, 5:47 a.m.