runauto: Function for automatically generating microclimate surfaces...

In ilyamaclean/microclima: microclimate modelling with R

Function for automatically generating microclimate surfaces for anywhere in the word

Description

This function generating microclimate temperature surfaces for anywhere in the word. If hourly weather data are not provided, it first downloads coarse-resolution climate and radiation data from the NCEP-NCAR or NCEP–DOE Atmospheric Model Intercomparison Project (Kanamitso et al 2002) and interpolates these data to hourly. It calculates mesoclimatic effects and derives parameters for fitting the microclimate model using the NicheMapR package (Kearny & Porter 2016). Using digital elevation data either downloaded or provided by the user, and canopy characteristics either specified by the user, or derived from habitat, it runs the microclimate model in hourly timesteps to generate an array of temperatures.

Usage

runauto(
  r,
  dstart,
  dfinish,
  hgt = 0.05,
  l,
  x,
  habitat = NA,
  hourlydata = NA,
  dailyprecip = NA,
  use.raster = FALSE,
  coastal = TRUE,
  r.is.dem = TRUE,
  save = 0,
  albg = 0.15,
  albr = 0.15,
  albc = 0.23,
  mesoresolution = 100,
  zmin = 0,
  slope = NA,
  aspect = NA,
  windthresh = 4.5,
  emthresh = 0.78,
  reanalysis2 = FALSE,
  steps = 8,
  plot.progress = TRUE,
  continuous = TRUE,
  summarydata = TRUE,
  save.memory = FALSE,
  weather.elev = "ncep",
  cad.effects = TRUE,
  run.gads = 1
)

Arguments

r	a SpatRaster object defining the extent and resolution for which microclimate temperature data are required. Supplied raster must have a projection such that the units of x, y and z are identical, and grid cells are square. NA values are assumed to be sea, which is important in the calculation of coastal and cold air drainage effects.
dstart	start date as character of time period required in format DD/MM/YYYY
dfinish	end date as character of time period required in format DD/MM/YYYY
hgt	the height (in m) above or below ground for which temperature estimates are required. If negative, below-ground temperatures are derived (range -2 to 2).
l	an optional single numeric value, vector, SpatRaster, matrix or array of leaf area index values. If a single numeric value, the same leaf area is assumed at all locations and times. If a vector, the same leaf area is assumed at all locations, but leaf area is assumed ot vary through time. If a matrix or SpatRaster, leaf area is assumed to vary by location, but is assumed static in time. If an array, variable leaf areas in time and space are assumed.
x	a single numeric value, matrix or SpatRaster representing the ratio of vertical to horizontal projections of foliage as, for example, returned by leaf_geometry(). if a single numeric value, the same value of x is assumed at all locations. Varying x through time is not supported.
habitat	a character string, numeric value or matrix or SpatRaster of numeric values of habitat type(s). See habitats(). Ignored if l or x are provided. If a single numeric value, the same habitat is assumed at all locations. Varying habitats in time are not supported.
hourlydata	an optional dataframe of hourly climate forcing variables. If not supplied downloaded using hourlyNCEP() obs_time POSIXlt object of times in UTC temperature Temperatures at 2 m (ºC) humidity Specific humidity at 2m (Kg / Kg) pressure Surface pressure (Pa) windspeed Wind speed at 2 m (metres per second) winddir Wind direction (degrees from N) emissivity Emissivity of the atmosphere (0 - 1, downlong / uplong) netlong Net longwave radiation (MJ m-2 hr-1) uplong Upward longwave radiation (MJ m-2 hr-1) downlong Downward longwave radiation (MJ m-2 hr-1) rad_dni Direct radiation normal to the solar beam (MJ m-2 hr-1) rad_dif Diffuse radiation (MJ m-2 hr-1) szenith The zenith angle (degrees) cloudcover Cloud cover (Percentage)
dailyprecip	Optional data.frame of daily precipitation data as returned by dailyprecipNCEP()
use.raster	optional logical value indicating whether to use r in the calculation of coastal effects. If used, NAs or values corresponding to zmin must represent sea.
coastal	optional logical value indicating whether or not to calculate coastal effects.
r.is.dem	optional logical value indicating whether 'r' is a digital elevation dataset used for calculating microclimatic effects. If FALSE, then a dem is downloaded.
save	optional integer: don't save forcing data (0), save the forcing data (1) or read previously saved data (2).
albg	an optional single value, SpatRaster object, two-dimensional array or matrix of values representing the albedo(s) of the ground as returned by albedo2().
albr	albr an optional single value, SpatRaster object, two-dimensional array or matrix of values representing the albedo(s) of adjacent surfaces as returned by albedo_reflected().
albc	an optional single value, SpatRaster object, two-dimensional array or matrix of values representing the albedo(s) of the vegetated canopy as returned by albedo2().
mesoresolution	optional numeric value indicating resolution of the dem used for modelling mesoclimate.
zmin	assumed sea-level height. Values below this are set to zmin (see details).
slope	an optional slope value for the location in decimal degrees. If not specified, then the slope is calculated from the retrieved dem.
aspect	an optional aspect value for the location in decimal degrees. If not specified, then the slope is calculated from the retrieved dem.
windthresh	an optional threshold wind value (m /s) above which cold air drainage is assumed not to occur.
emthresh	an optional threshold emissivity value above which cold air drainage is assumed not to occur.
reanalysis2	Optional logical. Should data be obtained from the Reanalysis II dataset (default) or from Reanalysis I (data prior to 1979).
steps	an optional integer. Coastal effects are calculated in specified directions upwind. Steps defines the total number of directions used. If the default 8 is specified, coastal effects are calculated at 45º intervals.
plot.progress	an optional logical indicating whether to produce plots to track progress.
continuous	an optional logical value indicating whether to treat wind speed as a continuous variable
summarydata	an optional logical indicating whether to calculate summary data (frost hours and maximum, minimum and mean temperature) for each pixel and return these to the output.
save.memory	An optional logical indicatign whether to save
weather.elev	optional value indicating the elevation of values in hourlydata. Either a numeric value, corresponding to the elevation in (m) of the location from which hourlydata were obtained, or one of ncep (default, data derive from NOAA-NCEP reanalysis) project or era5 (derived from Copernicus ERA5 climate reanalysis).
cad.effects	optional logical indicating whether to calaculate cold air drainage effects (TRUE = Yes, slower. FALSE = No, quicker) memory by storing temperature x 1000 as an integer values.
run.gads	NicheMapR parameter controlling if/how the Global Aerosol Database is used to derive solar radiation (1=yes (Fortran version), 2=yes (R version), 0=no). If program is crashing, try run.gads = 2.

Value

a list with the following objects: (1) temps: an array of temperatures for each pixel of r and hour of the time sequence. (2) e: a terra::ext object given the extent of temps. Generally the same as terra::ext(r) though note that edge cells are NA as slopes cannot be calculated for these cells. (3) units: the units of temps. Either deg C or dec C * 1000 if save.memory is TRUE. (4) tmax: If summarydata is TRUE, a matrix of maximum temperatures (5) tmin: If summarydata is TRUE, a matrix of minimum temperatures (6) tmean: If summarydata is TRUE, a matrix of mean temperatures (7) frosthours: If summarydata is TRUE, a matrix of hours below 0 deg C.

References

Kearney MR, Porter WP (2016) NicheMapR – an R package for biophysical modelling: the microclimate model. Ecography 40: 664-674.

Kanamitsu M, Ebisuzaki W, Woollen J, Yang SK, Hnilo JJ, Fiorino M, Potter GL (2002) Ncep–doe amip-ii reanalysis (r-2). Bulletin of the American Meteorological Society 83: 1631-1644.

Examples

library(terra)
require(NicheMapR)
# Get DEM for Pico, Azores
r <- get_dem(lat = 38.467429, long = -28.398995, resolution = 30)
plot(r)
# Takes ~ c. 5 minutes to run
temps <- runauto(r, "10/06/2010", "15/06/2010", hgt = 0.1, l = NA, x = NA,
                     habitat = "Barren or sparsely vegetated")
mypal <- colorRampPalette(c("darkblue", "blue", "green", "yellow", "orange",
                          "red"))(255)
meantemp <- temps$tmean
par(mfrow = c(1, 1))
plot(meantemp, main = "Mean temperature", col = mypal)
# Interactive 3D plot
require(plotly)
zrange<-list(range = c(0, 3000))
plot_ly(z = ~is_raster(r)) %>%
add_surface(surfacecolor = ~is_raster(meantemp)) %>%
layout(scene = list(zaxis = zrange))

ilyamaclean/microclima documentation built on Sept. 5, 2024, 8:37 p.m.