%
%   Copyright 2001-2026 by the individuals mentioned in the source code history
%
%   Licensed under the Apache License, Version 2.0 (the "License");
%   you may not use this file except in compliance with the License.
%   You may obtain a copy of the License at
% 
%        http://www.apache.org/licenses/LICENSE-2.0
% 
%   Unless required by applicable law or agreed to in writing, software
%   distributed under the License is distributed on an "AS IS" BASIS,
%   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
%   See the License for the specific language governing permissions and
%   limitations under the License.

\name{wccAggregate}
\alias{wccAggregate}

\title{wccAggregate}

\description{
This function runs wccCalc and peakpicking on a pair of time series and returns aggregate statistics.
}

\usage{
wccAggregate(inSeries1=NA, inSeries2=NA, wMax=50, tMax=50, wInc=1, tInc=1, Lsize=8,
     pspan=.25, type="Max", samplespersecond=1, windcross=TRUE, embedD=9) 
}

\arguments{
\item{inSeries1}{A vector of numeric values. This is the first time series on which windowed cross correlation is calculated.  Must be of the same length as inSeries2}
\item{inSeries2}{A vector of numeric values. This is the second time series on which windowed cross correlation is calculated. Must be of the same length as inSeries1}
\item{wMax}{A numeric indicating the number of samples in a window.  This must be greater or equal to 5 samples.  It is recommended that wMax be greater than 15.}
\item{tMax}{The maximum number of samples to lag the windows.  The cross correlation is calculated for windows that are time lagged against each other, allowing for processes than require some time to evolve.  For instance, if the two time series are from motion capture of two individuals conversing with one another, the speaker's movements are likely to occur prior to the responses of the listener.  tMax should be set to be greater than the number of samples that represents the maximum time lag that is likely to occur. }
\item{wInc}{The number of samples incremented between successive windows.  This is most often set to 1.  If the sample rate is very high and the time series is long, wInc may be increased.  However, wccCalc's maximum sensitivity to nonstationary change in the time series occurs when wInc is 1.}
\item{tInc}{The number of samples incremented between successive lags.  This is most often set to 1.  If the sample rate is high and the maximum lag is high then tInc may be increased.  However, wccCalc's maximum sensitivity to changes in lags occurs when the tInc is set to 1.}
\item{Lsize}{An integer specifying the width required for a peak to be identified by wccPeakPick.  An Lsize that is too small may find spurious peaks that are just noise, whereas an Lsize that is too large may miss actual peaks.}
\item{pspan}{A numeric specifying the amount of smoothing applied by the loess function within wccPeakPick.}
\item{type}{A character string indicating whether a maximum, \sQuote{Max}, or minimum, \sQuote{Min}, should be detected by wccPeakPick.}
\item{samplespersecond}{A numeric indicating the sampling rate of the time series.  This will determine the units of the first derivative aggregate statistics.}
\item{windcross}{The default \sQuote{TRUE} then the compiled windcross binary is used.  If \sQuote{FALSE} then native R code is used to calculate the windowed cross correlation.  The native R code is the most portable across many machines and operating systems.  However, the compiled windcross library runs about 2 times faster, so if the binary is available on your machine, it is recommended.}
\item{embedD}{A numeric indicating the embedding dimension passed to GLLAEmbed to calculate derivatives of the peak picking lag timeseries.  The default (9) will provide a medium smooth at the cost of some loss of resolution in the timing of jumps in the second derivative.  The smallest legal value is 5, which provides less smooth and the best time resolution.  If your sampling rate is low, then a smaller value of embedD is useful, while if your sampling rate is high, a larger value of embedD will provide better noise rejection by smoothing.}
}

\details{
wccAggregate is a wrapper for the wccCalc and wccPeakpick functions.  The returns from these two function calls are then aggregated into 10 different statistics representing characteristics of wccCalc and wccPeakpick for the pair of input time series.  wccAggregate also must be called with a filename in the \sQuote{savefile} argument prior to calling wccPlot so that the raw results can be plotted.  The wccAggregate function returns a single row dataframe so that it can be called repeatedly by the wccSurrogateDyad function to create a distribution of surrogate Windowed Cross Correlation results.  The arguments are also saved in this dataframe so that the wccFindDyadParam function can explore the space of arguments to find appropriate values from a hold-out set of timeseries to then be used to calculate surrogate distributions for the full data set.
}
    
\value{
wccAggregate returns a data frame with one row and the following columns:
\tabular{ll}{
\sQuote{wMax}   \tab  The value of wMax in the argument passed to wccCalc.\cr

\sQuote{tMax}   \tab  The value of tMax in the argument passed to wccCalc. \cr

\sQuote{wInc}   \tab  The value of wInc in the argument passed to wccCalc. \cr

\sQuote{tInc}   \tab   The value of tInc in the argument passed to wccCalc.\cr

\sQuote{Lsize}   \tab  The value of Lsize in the argument passed to wccPeakPick. \cr

\sQuote{pspan}   \tab  The value of pspan in the argument passed to wccPeakPick. \cr

\sQuote{type}   \tab   The value of type as a numeric translation of the type argument passed to wccPeakPick.  This is +1 when type = \sQuote{Max} and -1 when type = \sQuote{Min}.\cr

\sQuote{samples}   \tab  Length of the time series inSeries1 and inSeries2\cr

\sQuote{windows}   \tab  The number of windows returned by wccCalc.\cr

\sQuote{pctMissing}   \tab  Percent missing values in the matrix returned by wccCalc\cr

\sQuote{pctMissingWindows}   \tab  Percent missing windows in the matrix returned by wccCalc\cr

\sQuote{maxMean}   \tab  Mean of the Fischer's Z transform of the maximum correlation vector returned returned by wccPeakPick\cr

\sQuote{maxVar}   \tab   Variance of the Fischer's Z transform of the maximum correlation vector returned returned by wccPeakPick\cr

\sQuote{totalMean}   \tab  Mean of the Fischer's Z transform of all values in the matrix returned by wccCalc\cr

\sQuote{totalVar}   \tab  Variance of the Fischer's Z transform of all values in the matrix returned by wccCalc \cr

\sQuote{zeroLagMean}   \tab  Mean of the Fischer's Z transform of all values in the zero lag column of the matrix returned by wccCalc\cr

\sQuote{zeroLagVar}   \tab Variance of the Fischer's Z transform of all values in the zero lag column of the matrix returned by wccCalc \cr

\sQuote{lagMean}   \tab  Mean of the lag vector returned by wccPeakPick\cr

\sQuote{lagVar}   \tab  Variance of the lag vector returned by wccPeakPick\cr

\sQuote{dlagMean}   \tab Mean of the first derivative of the lag vector returned by wccPeakPick \cr

\sQuote{dlagVar}   \tab  Variance of the first derivative of the lag vector returned by wccPeakPick\cr

\sQuote{d2lagMean}   \tab Mean of the second derivative of the lag vector returned by wccPeakPick \cr

\sQuote{d2lagVar}   \tab  Variance of the second derivative of the lag vector returned by wccPeakPick\cr

\sQuote{elapsedSeconds}   \tab  Total elapsed seconds required to perform all calculations and function calls\cr

}
}

\references{
Boker, S. M., Rotondo, J. L., Xu, M., & King, K. (2002). Windowed cross-correlation and peak picking for the analysis of variability in the association between behavioral time series. Psychological methods, 7(3), 338.}

\seealso{
\link{wccCalc}, \link{wccPeakPick}. 
}

\examples{
#Calculate aggregated statistics for windowed cross correlation between two time series
tSeries1 <- sin(c(1:1000)/10) + rnorm(1000, mean=0, sd=.5)
tSeries2 <- sin(c(1:1000)/15) + rnorm(1000, mean=0, sd=.5)
wccAggregate(inSeries1=tSeries1, inSeries2=tSeries2, wMax=50, tMax=50, wInc=1, tInc=1,
     Lsize=8, pspan=.25, type="Max", samplespersecond=10, windcross=TRUE)

}
