rsaga.pisr: Potential incoming solar radiation

Description

This function calculates the potential incoming solar radiation in an area using different atmospheric models; module available in SAGA GIS 2.0.6+.

Usage

rsaga.pisr(
  in.dem,
  in.svf.grid = NULL,
  in.vapour.grid = NULL,
  in.latitude.grid = NULL,
  in.longitude.grid = NULL,
  out.direct.grid,
  out.diffuse.grid,
  out.total.grid = NULL,
  out.ratio.grid = NULL,
  out.duration,
  out.sunrise,
  out.sunset,
  local.svf = TRUE,
  latitude,
  unit = c("kWh/m2", "kJ/m2", "J/cm2"),
  solconst = 1367,
  enable.bending = FALSE,
  bending.radius = 6366737.96,
  bending.lat.offset = "user",
  bending.lat.ref.user = 0,
  bending.lon.offset = "center",
  bending.lon.ref.user = 0,
  method = c("height", "components", "lumped"),
  hgt.atmosphere = 12000,
  hgt.water.vapour.pressure = 10,
  cmp.pressure = 1013,
  cmp.water.content = 1.68,
  cmp.dust = 100,
  lmp.transmittance = 70,
  time.range = c(0, 24),
  time.step = 0.5,
  start.date = list(day = 21, month = 3),
  end.date = NULL,
  day.step = 5,
  env = rsaga.env(),
  ...
)

Value

The type of object returned depends on the intern argument passed to the rsaga.geoprocessor(). For intern=FALSE it is a numerical error code (0: success), or otherwise (default) a character vector with the module's console output.

Arguments

in.dem: name of input digital elevation model (DEM) grid in SAGA grid format (default extension: .sgrd)
in.svf.grid: Optional input grid in SAGA format: Sky View Factor; see also local.svf
in.vapour.grid: Optional input grid in SAGA format: Water vapour pressure (mbar); see also argument hgt.water.vapour.pressure
in.latitude.grid: Optional input grid in SAGA format: Latitude (degree) of each grid cell
in.longitude.grid: see in.latitude.grid
out.direct.grid: Output grid: Direct insolation (unit selected by unit argument)
out.diffuse.grid: Output grid: Diffuse insolation
out.total.grid: Optional output grid: Total insolation, i.e. sum of direct and diffuse incoming solar radiation
out.ratio.grid: Optional output grid: Direct to diffuse ratio
out.duration: Optional output grid: Duration of insolation
out.sunrise: Optional output grid: time of sunrise; only calculated if time span is set to single day
out.sunset: Time of sunset; see out.sunrise
local.svf: logical (default: TRUE; if TRUE, use sky view factor based on local slope (after Oke, 1988), if no sky view factor grid is provided in in.svf.grid
latitude: Geographical latitude in degree North (negative values indicate southern hemisphere)
unit: unit of insolation output grids: "kWh/m2" (default) "kJ/m2", or "J/cm2"
solconst: solar constant, defaults to 1367 W/m2
enable.bending: logical (default: FALSE): incorporate effects of planetary bending?
bending.radius: Planetary radius, default 6366737.96
bending.lat.offset: if bending is enabled: latitudinal reference is "user"-defined (default), or relative to "top", "center" or "bottom" of grid?
bending.lat.ref.user: user-defined lat. reference for bending, see bending.lat.offset
bending.lon.offset: longitudinal reference, i.e. local time, is "user"-defined, or relative to "top", "center" (default) or "bottom" of grid?
bending.lon.ref.user: user-defined reference for local time (Details??)
method: specifies how the atmospheric components should be accounted for: either based on the height of atmosphere and vapour pressure ("height", or numeric code 0), or air pressure, water and dust content ("components", code 1), or lumped atmospheric transmittance ("lumped", code 0)
hgt.atmosphere: Height of atmosphere (in m); default 12000 m
hgt.water.vapour.pressure: Water vapour pressure in mbar (default 10 mbar); This value is used if no vapour pressure grid is given in argument in.vapour.grid
cmp.pressure: atmospheric pressure in mbar, defaults to 1013 mbar
cmp.water.content: water content of a vertical slice of the atmosphere in cm: between 1.5 and 1.7cm, average 1.68cm (default)
cmp.dust: dust factor in ppm; defaults to 100 ppm
lmp.transmittance: transmittance of the atmosphere in percent; usually between 60 (humid areas) and 80 percent (deserts)
time.range: numeric vector of length 2: time span (hours of the day) for numerical integration
time.step: time step in hours for numerical integration
start.date: list of length two, giving the start date in day and month components as numbers; these numbers are one-based (SAGA_CMD uses zero-based numbers internally), i.e. Jan. 1st is list(day=1,month=1)
end.date: see start.date
day.step: if days indicates a range of days, this specifies the time step (number of days) for calculating the incoming solar radiation
env: RSAGA geoprocessing environment obtained with rsaga.env(); this argument is required for version control (see Note)
...: optional arguments to be passed to rsaga.geoprocessor()

Author

Alexander Brenning (R interface), Olaf Conrad (SAGA module)

Details

According to SAGA GIS 2.0.7 documentation, "Most options should do well, but TAPES-G based diffuse irradiance calculation ("Atmospheric Effects" methods 2 and 3) needs further revision!" I.e. be careful with method = "components" and method = "lumped".

References

Boehner, J., Antonic, O. (2009): Land surface parameters specific to topo-climatology. In: Hengl, T. and Reuter, H. I. (eds.): Geomorphometry - Concepts, Software, Applications. Elsevier.

Oke, T.R. (1988): Boundary layer climates. London, Taylor and Francis.

Wilson, J.P., Gallant, J.C. (eds.), 2000: Terrain analysis - principles and applications. New York, John Wiley and Sons.