daily_response_seascorr: daily_response_seascorr

Description

Function calculates all possible partial correlation coefficients between tree-ring chronology and daily environmental (usually climate) data. Calculations are based on moving window which is defined with two arguments: lower_limit and upper_limit. All calculated (partial) correlation coefficients are stored in a matrix. The location of stored correlation in the matrix is indicating a window width (row names) and a location in a matrix of daily sequences of environmental data (column names).

Usage

daily_response_seascorr(
  response,
  env_data_primary,
  env_data_control,
  lower_limit = 30,
  upper_limit = 90,
  fixed_width = 0,
  previous_year = FALSE,
  pcor_method = "pearson",
  remove_insignificant = TRUE,
  alpha = 0.05,
  row_names_subset = FALSE,
  aggregate_function_env_data_primary = "mean",
  aggregate_function_env_data_control = "mean",
  temporal_stability_check = "sequential",
  k = 2,
  k_running_window = 30,
  subset_years = NULL,
  ylimits = NULL,
  seed = NULL,
  tidy_env_data_primary = FALSE,
  tidy_env_data_control = FALSE,
  reference_window = "start",
  boot = FALSE,
  boot_n = 1000,
  boot_ci_type = "norm",
  boot_conf_int = 0.95,
  day_interval = ifelse(c(previous_year == TRUE, previous_year == TRUE), c(-1, 366), c(1,
    366)),
  dc_method = NULL,
  pcor_na_use = "pairwise.complete",
  skip_window_length = 1,
  skip_window_position = 1
)

Value

a list with 15 elements:

$calculations - a matrix with calculated metrics
$method - the character string of a method
$metric - the character string indicating the metric used for calculations
$analysed_period - the character string specifying the analysed period based on the information from row names. If there are no row names, this argument is given as NA
$optimized_return - data frame with two columns, response variable and aggregated (averaged) daily data that return the optimal results. This data.frame could be directly used to calibrate a model for climate reconstruction
$optimized_return_all - a data frame with aggregated daily data, that returned the optimal result for the entire env_data_primary (and not only subset of analysed years)
$transfer_function - a ggplot object: scatter plot of optimized return and a transfer line of the selected method
$temporal_stability - a data frame with calculations of selected metric for different temporal subsets
$cross_validation - not available for partial correlations
$plot_heatmap - ggplot2 object: a heatmap of calculated metrics
$plot_extreme - ggplot2 object: line plot of a row with the highest value in a matrix of calculated metrics
$type - the character string describing type of analysis: daily or monthly
$reference_window - character string, which reference window was used for calculations
$aggregated_climate_primary - matrix with all aggregated climate series of primary data
$aggregated_climate_control - matrix with all aggregated climate series of control data

Arguments

response: a data frame with tree-ring proxy variable and (optional) years as row names. Row.names should be matched with those from env_data_primary and env_data_control data frame. If not, set the row_names_subset argument to TRUE.
env_data_primary: primary data frame of daily sequences of environmental data as columns and years as row names. Each row represents a year and each column represents a day of a year. Row.names should be matched with those from the response data frame. If not, set the argument row_names_subset to TRUE. Alternatively, env_data_primary could be a tidy data with three columns, i.e. Year, DOY and third column representing values of mean temperatures, sum of precipitation etc. If tidy data is passed to the function, set the argument tidy_env_data_primary to TRUE.
env_data_control: a data frame of daily sequences of environmental data as columns and years as row names. This data is used as control for calculations of partial correlation coefficients. Each row represents a year and each column represents a day of a year. Row.names should be matched with those from the response data frame. If not, set the row_names_subset argument to TRUE. Alternatively, env_data_control could be a tidy data with three columns, i.e. Year, DOY and third column representing values of mean temperatures, sum of precipitation etc. If tidy data is passed to the function, set the argument tidy_env_data_control to TRUE.
lower_limit: lower limit of window width
upper_limit: upper limit of window width
fixed_width: fixed width used for calculation. If fixed_width is assigned a value, upper_limit and lower_limit will be ignored
previous_year: if set to TRUE, env_data_primary, env_data_control and response variables will be rearranged in a way, that also previous year will be used for calculations of selected statistical metric.
pcor_method: a character string indicating which partial correlation coefficient is to be computed. One of "pearson" (default), "kendall", or "spearman", can be abbreviated.
remove_insignificant: if set to TRUE, removes all correlations bellow the significant threshold level, based on a selected alpha.
alpha: significance level used to remove insignificant calculations.
row_names_subset: if set to TRUE, row.names are used to subset env_data_primary, env_data_control and response data frames. Only years from all three data frames are kept.
aggregate_function_env_data_primary: character string specifying how the daily data from env_data_primary should be aggregated. The default is 'mean', the other options are 'median', 'sum', 'min' and 'max'
aggregate_function_env_data_control: character string specifying how the daily data from env_data_control should be aggregated. The default is 'mean', the other options are 'median', 'sum', 'min' and 'max'
temporal_stability_check: character string, specifying, how temporal stability between the optimal selection and response variable(s) will be analysed. Current possibilities are "sequential", "progressive" and "running_window". Sequential check will split data into k splits and calculate selected metric for each split. Progressive check will split data into k splits, calculate metric for the first split and then progressively add 1 split at a time and calculate selected metric. For running window, select the length of running window with the k_running_window argument.
k: integer, number of breaks (splits) for temporal stability
k_running_window: the length of running window for temporal stability check. Applicable only if temporal_stability argument is set to running window.
subset_years: a subset of years to be analyzed. Should be given in the form of subset_years = c(1980, 2005)
ylimits: limit of the y axes for plot_extreme It should be given in the form of: ylimits = c(0,1)
seed: optional seed argument for reproducible results
tidy_env_data_primary: if set to TRUE, env_data_primary should be inserted as a data frame with three columns: "Year", "DOY", "Precipitation/Temperature/etc."
tidy_env_data_control: if set to TRUE, env_data_control should be inserted as a data frame with three columns: "Year", "DOY", "Precipitation/Temperature/etc."
reference_window: character string, the reference_window argument describes, how each calculation is referred. There are three different options: 'start' (default), 'end' and 'middle'. If the reference_window argument is set to 'start', then each calculation is related to the starting day of window. If the reference_window argument is set to 'middle', each calculation is related to the middle day of window calculation. If the reference_window argument is set to 'end', then each calculation is related to the ending day of window calculation. For example, if we consider correlations with window from DOY 15 to DOY 35. If reference window is set to 'start', then this calculation will be related to the DOY 15. If the reference window is set to 'end', then this calculation will be related to the DOY 35. If the reference_window is set to 'middle', then this calculation is related to DOY 25. The optimal selection, which describes the optimal consecutive days that returns the highest calculated metric and is obtained by the $plot_extreme output, is the same for all three reference windows.
boot: logical, if TRUE, bootstrap procedure will be used to calculate partial correlation coefficients
boot_n: The number of bootstrap replicates
boot_ci_type: A character string representing the type of bootstrap intervals required. The value should be any subset of the values c("norm","basic", "stud", "perc", "bca").
boot_conf_int: A scalar or vector containing the confidence level(s) of the required interval(s)
day_interval: a vector of two values: lower and upper time interval of days that will be used to calculate statistical metrics. Negative values indicate previous growing season days. This argument overwrites the calculation limits defined by lower_limit and upper_limit arguments.
dc_method: a character string to determine the method to detrend climate data. Possible values are "none" (default) and "SLD" which refers to Simple Linear Detrending
pcor_na_use: an optional character string giving a method for computing covariances in the presence of missing values for partial correlation coefficients. This must be (an abbreviation of) one of the strings "all.obs", "everything", "complete.obs", "na.or.complete", or "pairwise.complete.obs" (default). See also the documentation for the base partial.r in psych R package
skip_window_length: an integer specifying the frequency of window selection for the calculations of climate-growth relationships. The default value is 1, indicating that every window is included in the calculations. When set to a value greater than 1, the function selectively processes windows at regular intervals defined by this parameter. For instance, if skip_window_length = 2, the function processes every second window. Similarly, if skip_window_length = 3, every third window is processed, skipping two windows in between each selected one. This parameter allows for controlling the granularity of the analysis and can help in reducing computation time by focusing on a subset of the data.
skip_window_position: an integer specifying the frequency of window positions used in the calculations of climate-growth relationships. The default value is 1, indicating that every window position is included in the calculations. When set to a value greater than 1, the function selectively processes window positions at regular intervals defined by this parameter. For instance, if skip_window_position = 2, the function processes every second window position. Similarly, if skip_window_position = 3, every third window position is processed, skipping two positions in between each selected one. This parameter allows for controlling the granularity of the analysis and can help in reducing computation time by focusing on a subset of the data.

Examples

Run this code

# \donttest{

# The examples below are enclosed within donttest{} to minimize the execution
# time during R package checks. Additionally, all examples include the
# parameters `skip_window_length` and `skip_window_position`, which limit the
# number of combinations evaluated in climate-growth correlation calculations.
# To explore all possible combinations, users should set both parameters to 1.

# Load the dendroTools R package
library(dendroTools)

# Load data
data(data_MVA)
data(data_TRW)
data(data_TRW_1)
data(example_proxies_individual)
data(example_proxies_1)
data(LJ_daily_temperatures)
data(LJ_daily_precipitation)

# 1 Basic example using the partial correlation coefficient
example_basic <- daily_response_seascorr(response = data_MVA,
                          env_data_primary = LJ_daily_temperatures,
                          env_data_control = LJ_daily_precipitation,
                          row_names_subset = TRUE,
                          fixed_width = 25,
                          lower_limit = 35, upper_limit = 45,
                          remove_insignificant = FALSE,
                          aggregate_function_env_data_primary = 'mean',
                          aggregate_function_env_data_control = 'mean',
                          tidy_env_data_primary = FALSE,
                          tidy_env_data_control = TRUE,
                          alpha = 0.05, pcor_method = "spearman",
                          previous_year = FALSE, boot = TRUE,
                          boot_n = 10,
                          reference_window = "end", k = 5,
                          dc_method = "SLD",
                          day_interval = c(-100, 250),
                          skip_window_position = 50,
                          skip_window_length= 50
                          )
# summary(example_basic)
# plot(example_basic, type = 1)
# plot(example_basic, type = 2)
# example_basic$optimized_return
# example_basic$optimized_return_all
# example_basic$temporal_stability

# 2 Example with fixed temporal time window
example_fixed_width <- daily_response_seascorr(response = data_MVA,
                          env_data_primary = LJ_daily_temperatures,
                          env_data_control = LJ_daily_precipitation,
                          row_names_subset = TRUE,
                          remove_insignificant = TRUE,
                          aggregate_function_env_data_primary = 'mean',
                          aggregate_function_env_data_control = 'mean',
                          alpha = 0.05,
                          dc_method = "SLD",
                          fixed_width = 45,
                          tidy_env_data_primary = FALSE,
                          tidy_env_data_control = TRUE,
                          reference_window = "end",
                          skip_window_position = 50,
                          skip_window_length= 50)

# summary(example_fixed_width)
# plot(example_fixed_width, type = 1)
# plot(example_fixed_width, type = 2)
# example_fixed_width$optimized_return
# example_fixed_width$optimized_return_all

# }

Run the code above in your browser using DataLab