% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/monthly_response_seascorr.R
\name{monthly_response_seascorr}
\alias{monthly_response_seascorr}
\title{monthly_response_seascorr}
\usage{
monthly_response_seascorr(
  response,
  env_data_primary,
  env_data_control,
  previous_year = FALSE,
  number_previous_years = NULL,
  pcor_method = "pearson",
  remove_insignificant = TRUE,
  lower_limit = 1,
  upper_limit = 12,
  fixed_width = 0,
  alpha = 0.05,
  row_names_subset = FALSE,
  reference_window = "start",
  aggregate_function_env_data_primary = "mean",
  quantile_prob_env_data_primary = 0.5,
  aggregate_function_env_data_control = "mean",
  quantile_prob_env_data_control = 0.5,
  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,
  boot = FALSE,
  boot_n = 1000,
  boot_ci_type = "norm",
  boot_conf_int = 0.95,
  month_interval = NULL,
  dc_method = NULL,
  pcor_na_use = "pairwise.complete"
)
}
\arguments{
\item{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.}

\item{env_data_primary}{primary data frame of monthly 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, Month 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.}

\item{env_data_control}{a data frame of monthly 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, Month 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.}

\item{previous_year}{logical. If TRUE, previous-year climate data are included
in the analysis. If FALSE, no previous-year climate data are included and
number_previous_years is ignored.}

\item{number_previous_years}{integer between 1 and 5 specifying how many
previous years should be included in the environmental matrices when
previous_year = TRUE. For example, number_previous_years = 2 uses climate
data from years t - 2, t - 1 and t for response year t. If NULL and
previous_year = TRUE, one previous year is included.}

\item{pcor_method}{a character string indicating which partial correlation
coefficient is to be computed. One of "pearson" (default), "kendall", or
"spearman", can be abbreviated.}

\item{remove_insignificant}{if set to TRUE, removes all correlations bellow
the significant threshold level, based on a selected alpha.}

\item{lower_limit}{lower limit of window width (i.e. number of consecutive months
to be used for calculations)}

\item{upper_limit}{upper limit of window width (i.e. number of consecutive months
to be used for calculations)}

\item{fixed_width}{fixed width used for calculations (i.e. number of consecutive
months to be used for calculations)}

\item{alpha}{significance level used to remove insignificant calculations.}

\item{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.}

\item{reference_window}{character string, the reference_window argument describes,
how each calculation is referred. There are two different options: 'start'
(default) and 'end'. If the reference_window argument is set to 'start',
then each calculation is related to the starting month of window. If the
reference_window argument is set to 'end', then each calculation is related
to the ending day of window calculation.}

\item{aggregate_function_env_data_primary}{character string specifying how the
monthly data from env_data_primary should be aggregated. The default is 'mean',
the other options are 'median', 'sum' and 'quantile'.}

\item{quantile_prob_env_data_primary}{numeric value between 0 and 1 specifying
the quantile probability used when aggregate_function_env_data_primary =
'quantile'. For example, 0.95 calculates the 95th percentile. The default is 0.5.}

\item{aggregate_function_env_data_control}{character string specifying how the
monthly data from env_data_control should be aggregated. The default is 'mean',
the other options are 'median', 'sum' and 'quantile'.}

\item{quantile_prob_env_data_control}{numeric value between 0 and 1 specifying
the quantile probability used when aggregate_function_env_data_control =
'quantile'. For example, 0.95 calculates the 95th percentile. The default is 0.5.}

\item{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.}

\item{k}{integer, number of breaks (splits) for temporal stability}

\item{k_running_window}{the length of running window for temporal stability check.
Applicable only if temporal_stability argument is set to running window.}

\item{subset_years}{a subset of years to be analyzed. Should be given in the form of
subset_years = c(1980, 2005)}

\item{ylimits}{limit of the y axes for plot_extreme. It should be given in
the form of: ylimits = c(0,1)}

\item{seed}{optional seed argument for reproducible results}

\item{tidy_env_data_primary}{if set to TRUE, env_data_primary should be inserted as a
data frame with three columns: "Year", "Month", "Precipitation/Temperature/etc."}

\item{tidy_env_data_control}{if set to TRUE, env_data_control should be inserted as a
data frame with three columns: "Year", "Month", "Precipitation/Temperature/etc."}

\item{boot}{logical, if TRUE, bootstrap procedure will be used to calculate
partial correlation coefficients}

\item{boot_n}{The number of bootstrap replicates}

\item{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").}

\item{boot_conf_int}{A scalar or vector containing the confidence level(s) of
the required interval(s)}

\item{month_interval}{a vector of two values defining the interval of months
used for calculations. Positive values indicate months in the current year.
Negative values indicate months in the previous-year block and are used only
when previous_year = TRUE. If previous_year = FALSE and negative values are
supplied, month_interval is ignored and the analysis is performed for the
current year only using month_interval = c(1, 12). If number_previous_years > 1,
the previous-year block starts with the earliest included previous year. For
example, previous_year = TRUE, number_previous_years = 2 and
month_interval = c(-1, 12) analyses the full sequence from January of year
t - 2 to December of year t.}

\item{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}

\item{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}
}
\value{
a list with 17 elements:
\enumerate{
 \item $calculations - a matrix with calculated metrics
 \item $method - the character string of a method
 \item $metric - the character string indicating the metric used for calculations
 \item $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
 \item $optimized_return - data frame with two columns, response variable and aggregated (averaged) monthly data that return the optimal results. This data.frame could be directly used to calibrate a model for climate reconstruction
 \item $optimized_return_all - a data frame with aggregated monthly data, that returned the optimal result for the entire env_data_primary (and not only subset of analysed years)
 \item $transfer_function - a ggplot object: scatter plot of optimized return and a transfer line of the selected method
 \item $temporal_stability - a data frame with calculations of selected metric for different temporal subsets
 \item $cross_validation - not available for partial correlation method
 \item $plot_heatmap - ggplot2 object: a heatmap of calculated metrics
 \item $plot_extreme - ggplot2 object: line plot of a row with the highest value in a matrix of calculated metrics
 \item $type - the character string describing type of analysis: monthly or monthly
 \item $reference_window - character string, which reference window was used for calculations
 \item $aggregated_climate_primary - matrix with all aggregated climate series of primary data
 \item $aggregated_climate_control - matrix with all aggregated climate series of control data
 \item $previous_year - logical indicating whether previous-year climate data were used
 \item $number_previous_years - integer indicating how many previous years were used
}
}
\description{
Function calculates all possible partial correlation coefficients between
tree-ring chronology and monthly environmental (usually climate) data.
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 monthly sequences of
environmental data (column names).
}
\examples{
\donttest{
# 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_monthly_temperatures)
data(LJ_monthly_precipitation)

# 1 Basic example
example_basic <- monthly_response_seascorr(response = data_MVA,
   fixed_width = 11,
   env_data_primary = LJ_monthly_temperatures,
   env_data_control = LJ_monthly_precipitation,
   row_names_subset = TRUE,
   remove_insignificant = TRUE,
   reference_window = "start",
   aggregate_function_env_data_primary = 'median',
   aggregate_function_env_data_control = 'median',
   alpha = 0.05, pcor_method = "spearman",
   tidy_env_data_primary = FALSE,
   tidy_env_data_control = TRUE,
   previous_year = TRUE)

# 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 Extended example
example_extended <- monthly_response_seascorr(response = data_MVA,
   env_data_primary = LJ_monthly_temperatures,
   env_data_control = LJ_monthly_precipitation,
   row_names_subset = TRUE, dc_method = "SLD",
   remove_insignificant = FALSE,
   aggregate_function_env_data_primary = 'mean',
   aggregate_function_env_data_control = 'mean',
   alpha = 0.05, pcor_na_use = "pairwise.complete",
   reference_window = "end",
   tidy_env_data_primary = FALSE,
   tidy_env_data_control = TRUE)

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

# 3 Example using quantiles for primary and control variables
example_quantile <- monthly_response_seascorr(
   response = data_MVA,
   env_data_primary = LJ_monthly_temperatures,
   env_data_control = LJ_monthly_precipitation,
   row_names_subset = TRUE,
   fixed_width = 3,
   previous_year = TRUE,
   aggregate_function_env_data_primary = "quantile",
   quantile_prob_env_data_primary = 0.50,
   aggregate_function_env_data_control = "quantile",
   quantile_prob_env_data_control = 0.50,
   tidy_env_data_primary = FALSE,
   tidy_env_data_control = TRUE)

 # summary(example_quantile)

}
}
