Title: Simple Process-Led Algorithms for Simulating Habitats
Version: 1.0.2
Description: This program calculates bioclimatic indices and fluxes (radiation, evapotranspiration, soil moisture) for use in studies of ecosystem function, species distribution, and vegetation dynamics under changing climate scenarios. Predictions are based on a minimum of required inputs: latitude, precipitation, air temperature, and cloudiness. Davis et al. (2017) <doi:10.5194/gmd-10-689-2017>.
License: GPL-3
Encoding: UTF-8
RoxygenNote: 7.2.1
Depends: R (≥ 3.2.3)
Language: en-GB
URL: https://github.com/villegar/splash/, https://splash.robertovillegas-diaz.com/, https://bitbucket.org/labprentice/splash/
BugReports: https://github.com/villegar/splash/issues/
NeedsCompilation: no
Packaged: 2022-10-12 13:15:30 UTC; robertovillegas-diaz
Author: Tyler W. Davis ORCID iD [aut], Iain Colin Prentice ORCID iD [aut], Benjamin D. Stocker ORCID iD [aut], Rebecca T. Thomas [aut], Rhys J. Whitley [aut], Han Wang ORCID iD [aut], Bradley J. Evans [aut], Angela V. Gallego-Sala [aut], Martin T. Sykes [aut], Wolfgang Cramer ORCID iD [aut], Roberto Villegas-Diaz ORCID iD [cre]
Maintainer: Roberto Villegas-Diaz <r.villegas-diaz@outlook.com>
Repository: CRAN
Date/Publication: 2022-10-12 15:20:05 UTC

splash: Simple Process-Led Algorithms for Simulating Habitats

Description

This program calculates bioclimatic indices and fluxes (radiation, evapotranspiration, soil moisture) for use in studies of ecosystem function, species distribution, and vegetation dynamics under changing climate scenarios. Predictions are based on a minimum of required inputs: latitude, precipitation, air temperature, and cloudiness. Davis et al. (2017) doi:10.5194/gmd-10-689-2017.

Author(s)

Maintainer: Roberto Villegas-Diaz r.villegas-diaz@outlook.com (ORCID)

Authors:

See Also

Useful links:


Calculate true anomaly and true longitude

Description

Calculate true anomaly and true longitude

Usage

berger_tls(n, N, ke = 0.0167, keps = 23.44, komega = 283, pir = pi/180)

Arguments

n

Numeric, day of year.

N

Numeric, days in a year.

ke

double, eccentricity of earth's orbit. Default: 0.01670, 2000CE (Berger, 1978).

keps

double, obliquity of earth's elliptic. Default: 23.44, 2000CE (Berger, 1978).

komega

double, lon. of perihelion, degrees Default: 283, 2000CE (Berger, 1978).

pir

\pi (~ 0.017453) in radians.

Value

True anomaly and true longitude for a given day.

References

Berger, A.L., 1978. Long-term variations of daily insolation and Quaternary climatic changes. Journal of Atmospheric Sciences, 35(12), pp.2362-2367. doi:10.1175/1520-0469(1978)035<2362:LTVODI>2.0.CO;2


Calculate daily evaporation fluxes

Description

This function calculates daily radiation, condensation, and evaporation fluxes.

Usage

calc_daily_evap(
  lat,
  n,
  elv = 0,
  y = 0,
  sf = 1,
  tc = 23,
  sw = 1,
  ke = 0.0167,
  keps = 23.44,
  komega = 283,
  kw = 0.26
)

Arguments

lat

double, decimal degrees.

n

double, day of year.

elv

double, elevation, m A.S.L. Default: 0.

y

double, year. Default: 0.

sf

double, fraction of sunshine hours. Default: 1.

tc

double, mean daily air temperature, degrees C. Default: 23.0.

sw

double, evaporative supply rate, mm/hr. Default: 1.0.

ke

double, eccentricity of earth's orbit. Default: 0.01670, 2000CE (Berger, 1978).

keps

double, obliquity of earth's elliptic. Default: 23.44, 2000CE (Berger, 1978).

komega

double, lon. of perihelion, degrees Default: 283, 2000CE (Berger, 1978).

kw

double, PET entrainment, (1 + kw) * EET Default: 0.26 (Priestley-Taylor, 1972)

Value

Returns a list object with the following variables:

References

Berger, A.L., 1978. Long-term variations of daily insolation and Quaternary climatic changes. Journal of Atmospheric Sciences, 35(12), pp.2362-2367. doi:10.1175/1520-0469(1978)035<2362:LTVODI>2.0.CO;2

Priestley, C.H.B. and Taylor, R.J., 1972. On the assessment of surface heat flux and evaporation using large-scale parameters. Monthly weather review, 100(2), pp.81-92. doi:10.1175/1520-0493(1972)100<0081:OTAOSH>2.3.CO;2

Examples

evap <- splash::calc_daily_evap(lat = 37.7,
                                n = 172,
                                elv = 142,
                                y = 2000,
                                sf = 1,
                                tc = 23.0,
                                sw = 0.9)
cat(sprintf("Evaporation values:\n"))
cat(sprintf("  s: %0.6f Pa/K\n", evap$s_pa.k))
cat(sprintf("  Lv: %0.6f MJ/kg\n", (1e-6) * evap$lv_j.kg))
cat(sprintf("  Patm: %0.6f bar\n", (1e-5) * evap$patm_pa))
cat(sprintf("  pw: %0.6f kg/m^3\n", evap$pw_kg.m3))
cat(sprintf("  gamma: %0.6f Pa/K\n", evap$gam_pa.k))
cat(sprintf("  Econ: %0.6f mm^3/J\n", (1e9) * evap$econ_m3.j))
cat(sprintf("  Cn: %0.6f mm\n", evap$cond_mm))
cat(sprintf("  rx: %0.6f\n", evap$rx))
cat(sprintf("  hi: %0.6f degrees\n", evap$hi_deg))
cat(sprintf("  EET: %0.6f mm\n", evap$eet_mm))
cat(sprintf("  PET: %0.6f mm\n", evap$pet_mm))
cat(sprintf("  AET: %0.6f mm\n", evap$aet_mm))

Calculate daily solar radiation fluxes

Description

This function calculates daily solar radiation fluxes.

Usage

calc_daily_solar(
  lat,
  n,
  elv = 0,
  y = 0,
  sf = 1,
  tc = 23,
  ke = 0.0167,
  keps = 23.44,
  komega = 283,
  kA = 107,
  kalb_sw = 0.17,
  kalb_vis = 0.03,
  kb = 0.2,
  kc = 0.25,
  kd = 0.5,
  kfFEC = 2.04,
  kGsc = 1360.8
)

Arguments

lat

double, decimal degrees.

n

double, day of year.

elv

double, elevation, m A.S.L. Default: 0.

y

double, year. Default: 0.

sf

double, fraction of sunshine hours. Default: 1.

tc

double, mean daily air temperature, degrees C. Default: 23.0.

ke

double, eccentricity of earth's orbit. Default: 0.01670, 2000CE (Berger, 1978).

keps

double, obliquity of earth's elliptic. Default: 23.44, 2000CE (Berger, 1978).

komega

double, lon. of perihelion, degrees Default: 283, 2000CE (Berger, 1978).

kA

double, empirical constant, degrees Celsius. Default: 107 (Monteith and Unsworth, 1990).

kalb_sw

double, shortwave albedo. Default: 0.17 (Federer, 1968).

kalb_vis

double, visible light albedo. Default: 0.03 (Sellers, 1985).

kb

double, empirical constant. Default: 0.20 (Linacre, 1968).

kc

double, cloudy transmittivity. Default: 0.25 (Linacre, 1968).

kd

double, angular coefficient of transmittivity. Default: 0.50 (Linacre, 1968).

kfFEC

double, flux-to-energy conversion, umol/J. Default: 2.04 (Meek et al., 1984).

kGsc

double, solar constant, W/m^2. Default: 1360.8 (Kopp and Lean, 2011).

Value

Returns a list object with the following variables:

References

Berger, A.L., 1978. Long-term variations of daily insolation and Quaternary climatic changes. Journal of Atmospheric Sciences, 35(12), pp.2362-2367. doi:10.1175/1520-0469(1978)035<2362:LTVODI>2.0.CO;2

Federer, C.A., 1968. Spatial variation of net radiation, albedo and surface temperature of forests. Journal of Applied Meteorology and Climatology, 7(5), pp.789-795. doi:10.1175/1520-0450(1968)007<0789:SVONRA>2.0.CO;2

Kopp, G. and Lean, J.L., 2011. A new, lower value of total solar irradiance: Evidence and climate significance. Geophys. Res. Lett. 38, L01706. doi:10.1029/2010GL045777

Linacre, E.T., 1968. Estimating the net-radiation flux. Agricultural meteorology, 5(1), pp.49-63. doi:10.1016/0002-1571(68)90022-8

Meek, D.W., Hatfield, J.L., Howell, T.A., Idso, S.B. and Reginato, R.J., 1984. A generalized relationship between photosynthetically active radiation and solar radiation 1. Agronomy journal, 76(6), pp.939-945. doi:10.2134/agronj1984.00021962007600060018x

Monteith, J., and Unsworth, M., 1990. Principles of Environmental Physics, Butterworth-Heinemann, Oxford.

Sellers, P.J., 1985. Canopy reflectance, photosynthesis and transpiration, International Journal of Remote Sensing, 6:8, 1335-1372, doi:10.1080/01431168508948283

Examples

solar <- splash::calc_daily_solar(lat = 37.7,
                                  n = 172,
                                  elv = 142,
                                  y = 2000,
                                  sf = 1,
                                  tc = 23.0)
cat(sprintf("Solar values:\n"))
cat(sprintf("  kn: %d\n", solar$kN))
cat(sprintf("  nu: %0.6f degrees\n", solar$nu_deg))
cat(sprintf("  lambda: %0.6f degrees\n", solar$lambda_deg))
cat(sprintf("  rho: %0.6f\n", solar$rho))
cat(sprintf("  dr: %0.6f\n", solar$dr))
cat(sprintf("  delta: %0.6f degrees\n", solar$delta_deg))
cat(sprintf("  ru: %0.6f\n", solar$ru))
cat(sprintf("  rv: %0.6f\n", solar$rv))
cat(sprintf("  rw: %0.6f\n", solar$rw))
cat(sprintf("  hs: %0.6f degrees\n", solar$hs_deg))
cat(sprintf("  hn: %0.6f degrees\n", solar$hn_deg))
cat(sprintf("  tau_o: %0.6f\n", solar$tau_o))
cat(sprintf("  tau: %0.6f\n", solar$tau))
cat(sprintf("  Qn: %0.6f mol/m^2\n", solar$ppfd_mol.m2))
cat(sprintf("  Rnl: %0.6f w/m^2\n", solar$rnl_w.m2))
cat(sprintf("  Ho: %0.6f MJ/m^2\n", (1.0e-6) * solar$ra_j.m2))
cat(sprintf("  Hn: %0.6f MJ/m^2\n", (1.0e-6) * solar$rn_j.m2))
cat(sprintf("  Hnn: %0.6f MJ/m^2\n", (1.0e-6) * solar$rnn_j.m2))

Calculate cosine of an angle

Description

Calculates the cosine of an angle (d) given in degrees.

Usage

dcos(d, pir = pi/180)

Arguments

d

Numeric, angle in degrees.

Value

Cosine of an angle.

References

C. Johnson, Theoretical Physicist, Univ of Chicago


Calculate density of water at 1 atm, g/cm^3

Description

This function calculates the temperature and pressure dependent density of pure water.

Usage

density_h2o(tc, pa)

Arguments

tc

double, air temperature, degrees C.

pa

double, atm pressure, Pa.

Value

double, kg/m^3.

References

Chen, C.T., Fine, R.A. and Millero, F.J., 1977. The equation of state of pure water determined from sound speeds. The Journal of Chemical Physics, 66(5), pp.2142-2144. doi:10.1063/1.434179


Calculate sine of an angle

Description

Calculates the sine of an angle (d) given in degrees.

Usage

dsin(d, pir = pi/180)

Arguments

d

Numeric, angle in degrees.

Value

Sine of an angle.


Elevation to pressure

Description

Calculates atmospheric pressure for a given elevation.

Usage

elv2pres(
  z,
  kG = 9.80665,
  kL = 0.0065,
  kMa = 0.028963,
  kPo = 101325,
  kR = 8.31447,
  kTo = 288.15
)

Arguments

z

Elevation, m.

kG

Gravitational acceleration, m/s^2. Default: 9.80665 (Allen, 1973)

kL

Adiabatic lapse rate, K/m. Default: 0.0065 (Allen, 1973)

kMa

Molecular weight of dry air, kg/mol. Default: 0.028963 (Tsilingiris, 2008)

kPo

Standard atmosphere, Pa. Default: 101325 (Allen, 1973)

kR

Universal gas constant, J/mol/K. Default: 8.31447 (Moldover et al., 1988)

kTo

Base temperature, K. Default: 288.15 (Berberan-Santos et al., 1997)

Value

Atmospheric pressure for the given elevation, Pa.

References

Allen, R.G., Pereira, L.S., Raes, D. and Smith, M., 1998. Crop evapotranspiration-Guidelines for computing crop water requirements-FAO Irrigation and drainage paper 56. Food and Agriculture Organization of the United Nations, Rome, 300(9), p.D05109. Available: http://www.fao.org/docrep/x0490e/x0490e07.htm

Berberan-Santos, M.N., Bodunov, E.N. and Pogliani, L., 1997. On the barometric formula. American Journal of Physics, 65(5), pp.404-412. doi:10.1119/1.18555

Moldover, M.R., Trusler, J.M., Edwards, T.J., Mehl, J.B. and Davis, R.S., 1988. Measurement of the universal gas constant R using a spherical acoustic resonator. Physical review letters, 60(4), p.249. doi:10.1103/PhysRevLett.60.249

Tsilingiris, P.T., 2008. Thermophysical and transport properties of humid air at temperature range between 0 and 100 C. Energy Conversion and Management, 49(5), pp.1098-1110. doi:10.1016/j.enconman.2007.09.015


Calculate enthalpy of vaporization

Description

This function calculates the temperature-dependent enthalpy of vaporization (latent heat of vaporization).

Usage

enthalpy_vap(tc)

Arguments

tc

double, air temperature, degrees C.

Value

double, J/kg.

References

Eq. 8, Henderson‐Sellers, B., 1984. A new formula for latent heat of vaporization of water as a function of temperature. Quarterly Journal of the Royal Meteorological Society, 110(466), pp.1186-1190. doi:10.1002/qj.49711046626


Calculate Julian day

Description

This function converts a date in the Gregorian calendar to a Julian day number (i.e., a method of consecutive numbering of days—does not have anything to do with the Julian calendar!)

Usage

julian_day(y, m, i)

Arguments

y

double, year.

m

double, month.

i

double, day of month.

Details

Value

double, Julian day.

References

Meeus, J. 1991. Chapter 7 "Julian Day". Astronomical Algorithms. Willmann-Bell.


Calculate psychrometric constant

Description

This function calculates the temperature and pressure dependent psychrometric constant.

Usage

psychro(tc, pa, kMa = 0.028963, kMv = 0.01802)

Arguments

tc

double, air temperature, degrees C.

pa

double, atm pressure, Pa.

kMa

double, molecular weight of dry air, kg/mol. Default: 0.028963 (Tsilingiris, 2008)

kMv

double, molecular weight of water vapor, kg/mol. Default: 0.01802 (Tsilingiris, 2008)

Value

double, Pa/K.

References

Allen, R.G., Pereira, L.S., Raes, D. and Smith, M., 1998. Crop evapotranspiration-Guidelines for computing crop water requirements-FAO Irrigation and drainage paper 56. Food and Agriculture Organization of the United Nations, Rome, 300(9), p.D05109. Available: http://www.fao.org/docrep/x0490e/x0490e07.htm


Calculate daily soil moisture and runoff

Description

Calculate daily soil moisture and runoff

Usage

quick_run(lat, elv, n, y, wn, sf, tc, pn, kCw = 1.05, kWm = 150)

Arguments

lat

double, decimal degrees.

elv

double, elevation, m A.S.L. Default: 0.

n

double, day of year.

y

double, year. Default: 0.

sf

double, fraction of sunshine hours. Default: 1.

tc

double, mean daily air temperature, degrees C. Default: 23.0.

pn

double, daily precipitation, mm/day.

kCw

double, supply constant, mm/hr. Default: 1.05 (Federer, 1982)

kWm

double, soil moisture capacity, mm. Default: 150 (Cramer-Prentice, 1988)

Value

Returns daily soil moisture and runoff.

References

Cramer, W. and Prentice, I.C., 1988. Simulation of regional soil moisture deficits on a European scale. Norsk Geografisk Tidsskrift - Norwegian Journal of Geography, 42(2-3), pp.149–151. doi:10.1080/00291958808552193

Federer, C.A., 1982. Transpirational supply and demand: plant, soil, and atmospheric effects evaluated by simulation. Water Resources Research, 18(2), pp.355-362. doi:10.1029/WR018i002p00355


Read CSV file

Description

Reads all three daily input variables (sf, tair, and pn) for a single year from a CSV file that includes a header.

Usage

read_csv(fname, y = -1)

Arguments

fname

String, file name.

y

Numeric, year.

Value

List with the following properties:

$file_name

File name.

$sf

Sunshine fraction.

$tair

Air temperature.

$pn

Precipitation.

$num_lines

Number of data points.

$year

Year of data.


Read plain text file

Description

Reads plain text file (no header) of one of the input arrays.

Usage

read_txt(my_data, fname, var, y = -1)

Arguments

my_data

List same as the output from read_csv.

fname

String, file name.

var

String, variable name.

y

Numeric, year.

Value

List with the following properties:

$file_name

File name.

$sf

Sunshine fraction.

$tair

Air temperature.

$pn

Precipitation.

$num_lines

Number of data points.

$year

Year of data.


Runs SPLASH at a single location for one day

Description

Runs SPLASH at a single location for one day

Usage

run_one_day(lat, elv, n, y, wn, sf, tc, pn, kCw = 1.05, kWm = 150)

Arguments

lat

double, decimal degrees.

elv

double, elevation, m A.S.L. Default: 0.

n

double, day of year.

y

double, year. Default: 0.

wn

double, daily soil moisture content, mm (wn).

sf

double, fraction of sunshine hours. Default: 1.

tc

double, mean daily air temperature, degrees C. Default: 23.0.

pn

double, daily precipitation, mm/day.

kCw

double, supply constant, mm/hr. Default: 1.05 (Federer, 1982)

kWm

double, soil moisture capacity, mm. Default: 150 (Cramer-Prentice, 1988)

Value

List with the following components:

References

Cramer, W. and Prentice, I.C., 1988. Simulation of regional soil moisture deficits on a European scale. Norsk Geografisk Tidsskrift - Norwegian Journal of Geography, 42(2-3), pp.149–151. doi:10.1080/00291958808552193

Federer, C.A., 1982. Transpirational supply and demand: plant, soil, and atmospheric effects evaluated by simulation. Water Resources Research, 18(2), pp.355-362. doi:10.1029/WR018i002p00355

Examples

soil <- run_one_day(lat = 37.7,
                    elv = 142,
                    n = 172,
                    y = 2000,
                    wn = 75,
                    sf = 1,
                    tc = 23,
                    pn = 5)
cat(sprintf("Soil moisture (run one day):\n"))
cat(sprintf("  Ho: %0.6f J/m2\n", soil$ho))
cat(sprintf("  Hn: %0.6f J/m2\n", soil$hn))
cat(sprintf("  PPFD: %0.6f mol/m2\n", soil$ppfd))
cat(sprintf("  EET: %0.6f mm/d\n", soil$eet))
cat(sprintf("  PET: %0.6f mm/d\n", soil$pet))
cat(sprintf("  AET: %0.6f mm/d\n", soil$aet))
cat(sprintf("  Cn: %0.6f mm/d\n", soil$cond))
cat(sprintf("  Wn: %0.6f mm\n", soil$wn))
cat(sprintf("  RO: %0.6f mm\n", soil$ro))

Calculate the temperature-dependent slope

Description

This function calculates the temperature-dependent slope of the saturation pressure temperature curve using the methodology presented in the eMast energy.cpp script.

Usage

sat_slope(tc)

Arguments

tc

double, air temperature, degrees C.

Value

double, Pa/K.

References

Allen, R.G., Pereira, L.S., Raes, D. and Smith, M., 1998. Crop evapotranspiration-Guidelines for computing crop water requirements-FAO Irrigation and drainage paper 56. Food and Agriculture Organization of the United Nations, Rome, 300(9), p.D05109. Available: http://www.fao.org/docrep/x0490e/x0490e07.htm

Prentice, I.C., Sykes, M.T. and Cramer, W., 1993. A simulation model for the transient effects of climate change on forest landscapes. Ecological modelling, 65(1-2), pp.51-70. doi:10.1016/0304-3800(93)90126-D


Calculate specific heat

Description

This function calculates the specific heat of moist air.

Usage

specific_heat(tc)

Arguments

tc

double, air temperature, degrees C.

Value

double, specific heat of moist air, J/kg/K.

References

Tsilingiris, P.T., 2008. Thermophysical and transport properties of humid air at temperature range between 0 and 100 C. Energy Conversion and Management, 49(5), pp.1098-1110. doi:10.1016/j.enconman.2007.09.015


Calculate daily totals

Description

Calculate daily totals updating the soil moisture until equilibrium.

Usage

spin_up(mdat, dtot)

Arguments

mdat

list with meteorological data (see the details section).

dtot

list with daily totals (see the details section).

Details

The list with meteorological data, mdat, should have the following components:

The list with daily totals, dtot, should have the following component:

Value

list, daily totals

Examples

daily_totals <- matrix(data = rep(0, 366), nrow = 366, ncol = 1)
daily_totals <- as.data.frame(daily_totals)
names(daily_totals) <- c("wn")
my_file <- system.file("extdata/example_data.csv", package = "splash")
my_data <- splash::read_csv(my_file, 2000)
my_data$lat_deg <- 37.7
my_data$elv_m <- 142
daily_totals <- splash::spin_up(my_data, daily_totals)
cat(sprintf("Spin-Up:\n"))
for (i in seq(from = 1, to = my_data$num_lines, by = 1)) {
  if (i == 1) cat(sprintf("Day\tWn (mm)\n"))
  cat(sprintf("%d\t%0.6f\n", i, daily_totals$wn[i]))
}