climwin (version 1.2.3)

randwin: Climate window analysis for randomised data

Description

Randomises biological data and carries out a climate window analysis. Used to help determine the chance of obtaining an observed result at random.

Usage

randwin(
  exclude = NA,
  repeats = 5,
  window = "sliding",
  xvar,
  cdate,
  bdate,
  baseline,
  stat,
  range,
  func,
  type,
  refday,
  cmissing = FALSE,
  cinterval = "day",
  spatial = NULL,
  cohort = NULL,
  upper = NA,
  lower = NA,
  binary = FALSE,
  centre = list(NULL, "both"),
  k = 0,
  weightfunc = "W",
  par = c(3, 0.2, 0),
  control = list(ndeps = c(0.01, 0.01, 0.01)),
  method = "L-BFGS-B",
  cutoff.day = NULL,
  cutoff.month = NULL,
  furthest = NULL,
  closest = NULL,
  thresh = NULL,
  cvk = NULL
)

Arguments

exclude

Two values (distance and duration) which allow users to exclude short-duration long-lag climate windows from analysis (e.g., windows with a duration of 10 days which occur over a month ago). These windows are often considered to be biologically implausible.

repeats

The number of times that data will be randomised and analysed for climate windows.

window

Whether randomisations are carried out for a sliding window ("sliding") or weighted window ("weighted") approach.

xvar

A list object containing all climate variables of interest. Please specify the parent environment and variable name (e.g. Climate$Temp).

cdate

The climate date variable (dd/mm/yyyy). Please specify the parent environment and variable name (e.g. Climate$Date).

bdate

The biological date variable (dd/mm/yyyy). Please specify the parent environment and variable name (e.g. Biol$Date).

baseline

The baseline model structure used for testing correlation. Currently known to support lm, glm, lmer and glmer objects.

stat

If window = "sliding"; The aggregate statistic used to analyse the climate data. Can currently use basic R statistics (e.g. mean, min), as well as slope. Additional aggregate statistics can be created using the format function(x) (...). See FUN in apply for more detail.

range

Two values signifying respectively the furthest and closest number of time intervals (set by cinterval) back from the cutoff date or biological record to include in the climate window search.

func

The functions used to fit the climate variable. Can be linear ("lin"), quadratic ("quad"), cubic ("cub"), inverse ("inv") or log ("log").

type

"absolute" or "relative", whether you wish the climate window to be relative (e.g. the number of days before each biological record is measured) or absolute (e.g. number of days before a set point in time).

refday

If type is absolute, the day and month respectively of the year from which the absolute window analysis will start.

cmissing

cmissing Determines what should be done if there are missing climate data. Three approaches are possible: - FALSE; the function will not run if missing climate data is encountered. An object 'missing' will be returned containing the dates of missing climate. - "method1"; missing climate data will be replaced with the mean climate of the preceding and following 2 days. - "method2"; missing climate data will be replaced with the mean climate of all records on the same date.

cinterval

The resolution at which climate window analysis will be conducted. May be days ("day"), weeks ("week"), or months ("month"). Note the units of parameter 'range' will differ depending on the choice of cinterval.

spatial

A list item containing: 1. A factor that defines which spatial group (i.e. population) each biological record is taken from. The length of this factor should correspond to the length of the biological dataset. 2. A factor that defines which spatial group (i.e. population) climate data corresponds to. This length of this factor should correspond to the length of the climate dataset.

cohort

A variable used to group biological records that occur in the same biological season but cover multiple years (e.g. southern hemisphere breeding season). Only required when type is "absolute". The cohort variable should be in the same dataset as the variable bdate.

upper

Cut-off values used to determine growing degree days or positive climate thresholds (depending on parameter thresh). Note that when values of lower and upper are both provided, climatewin will instead calculate an optimal climate zone.

lower

Cut-off values used to determine chill days or negative climate thresholds (depending on parameter thresh). Note that when values of lower and upper are both provided, climatewin will instead calculate an optimal climate zone.

binary

TRUE or FALSE. Determines whether to use values of upper and lower to calculate binary climate data (thresh = TRUE), or to use for growing degree days (thresh = FALSE).

centre

A list item containing: 1. The variable used for mean centring (e.g. Year, Site, Individual). Please specify the parent environment and variable name (e.g. Biol$Year). 2. Whether the model should include both within-group means and variance ("both"), only within-group means ("mean"), or only within-group variance ("dev").

k

If window = "sliding"; the number of folds used for k-fold cross validation. By default this value is set to 0, so no cross validation occurs. Value should be a minimum of 2 for cross validation to occur.

weightfunc

If window = "weighted"; the distribution to be used for optimisation. Can be either a Weibull ("W") or Generalised Extreme Value distribution ("G").

par

If window = "weighted"; the shape, scale and location parameters of the Weibull or GEV weight function used as start weight function. For Weibull : Shape and scale parameters must be greater than 0, while location parameter must be less than or equal to 0. For GEV : Scale parameter must be greater than 0.

control

If window = "weighted"; parameters used to determine step size for the optimisation function. Please see optim for more detail.

method

If window = "weighted"; the method used for the optimisation function. Please see optim for more detail.

cutoff.day, cutoff.month

Redundant parameters. Now replaced by refday.

furthest, closest

Redundant parameters. Now replaced by range.

thresh

Redundant parameter. Now replaced by binary.

cvk

Redundant parameter. Now replaced by k.

Value

Returns a dataframe containing information on the best climate window from each randomisation. See MassRand as an example.

Examples

# NOT RUN {
#Simple test example
#Create data from a subset of our test dataset
#Just use two years
biol_data <- Mass[1:2, ]
clim_data <- MassClimate[grep(pattern = "1979|1986", x = MassClimate$Date), ]

rand <- randwin(repeats = 1, xvar = list(Temp = clim_data$Temp),
               cdate = clim_data$Date, 
               bdate = biol_data$Date, 
               baseline = lm(Mass ~ 1, data = biol_data),
               range = c(1, 0), 
               type = "relative", stat = "mean", 
               func = c("lin"), cmissing = FALSE, cinterval = "day")

# }
# NOT RUN {
# Full working examples

## EXAMPLE 1 ##

# Test climate windows in randomised data using a sliding window approach.

data(Mass)
data(MassClimate)

# Randomise data twice
# Note all other parameters are fitted in the same way as the climatewin function.

rand <- randwin(repeats = 2, window = "sliding", 
               xvar = list(Temp = MassClimate$Temp), 
               cdate = MassClimate$Date, bdate = Mass$Date,
               baseline = lm(Mass ~ 1, data = Mass), 
               range = c(100, 0),
               stat = "mean", func = "lin", type = "absolute", 
               refday = c(20, 5),
               cmissing = FALSE, cinterval = "day")
                
# View output #

head(rand)

## EXAMPLE 2 ##

# Test climate windows in randomised data using a weighted window approach.
  
data(Offspring)
data(OffspringClimate)

# Randomise data twice
# Note all other parameters are fitted in the same way as the weightwin function.

weightrand <- randwin(repeats = 2, window = "weighted", 
                     xvar = list(Temp = OffspringClimate$Temperature), 
                     cdate = OffspringClimate$Date,
                     bdate = Offspring$Date,
                     baseline = glm(Offspring ~ 1, family = poisson, data = Offspring),
                     range = c(365, 0), func = "quad",
                     type = "relative", weightfunc = "W", cinterval = "day",
                     par = c(3, 0.2, 0), control = list(ndeps = c(0.01, 0.01, 0.01)),
                     method = "L-BFGS-B")
                   
# View output

head(weightrand)
                          
       
# }
# NOT RUN {
# }