\name{Trend}
\alias{Trend}
\title{
  Computes Trends and more
}
\description{
  Computes linear trend or higher order polynomial along the posTR dimension of tensor 
  var with the method of least squares, and estimates the associated error interval.
  Provides also the detrended or residual (after removing fitted polynomial) data.
  The confidence interval relies on a student-t distribution.
}
\usage{
  Trend(var, posTR=2, interval=1, pldegree=1)
}
\arguments{
  \item{var}{
    Tensor of any number of dimensions up to 10.
  }
  \item{posTR}{
    Position along which to compute trends or polynomial fits.
  }
  \item{interval}{
    Number of months between 2 points along posTR dimension.
    Default = 1 (assumes monthly data).
  }
  \item{pldegree}{
    The degree/order of the polynomial to be fitted and removed
    (keep in mind that the degree must be smaller than the number 
    of points along posTR dimension). Default = 1 (linear fit)
  }
}
\value{
  \item{$trend}{ 
    Same dimensions as var except along posTR dimension which is replaced
    by a dimension with length 3*(pldegree + 1) showing for
    i) pldegree=1: a^(lo)_1, a_1 (slope or trend), a^(hi)_1, a_0 (intercept), 
       a^(lo)_0, and a^(hi)_0 due to backward compatiliblity requirement, 
    ii) pldegree>1: a^(lo)_pldegree, a_pldegree, a^(hi)_pldegree, 
       a^(lo)_(pldegree-1), a_(pldegree-1), a^(hi)_(pldegree-1), ...
       a^(lo)_0, a_0, and a^(hi)_0, where (lo) is the lower limit of the 
    95% confidence interval and (hi) is the upper limit of the 95% confidence
    interval for each point of the tensor var along all other dimensions.  
  }
  \item{$detrended}{
    Same dimensions as var with residual values (after removing polynomial
    fit of pldegree order) along the posTR dimension.
  }
}
\examples{
  # A test of the default linear fit:
  startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101')
  sampleData <- Load('tos', c('i00k'), c('ERSST'), startDates, nleadtime = 124, 
                     leadtimemin = 1, leadtimemax = 60, output = 'areave', 
                     latmin = 30, latmax = 45, lonmin = 0, lonmax = 40)
  months_between_startdates <- 60
  trend <- Trend(sampleData$obs, 3, months_between_startdates)
##PlotVsLTime(trend$trend, toptitle = "trend", ytitle = "K / (5 year)",
##            monini = 11, limits = c(-1,1), listexp = c('CMIP5 IC3'),
##            listobs = c('ERSST'), biglab = FALSE, hlines = 0,
##            fileout = 'tos_obs_trend.eps') -> there is an error in this step, but eps file is produced?
  PlotAno(trend$detrended, NULL, startDates, 
          toptitle = 'detrended anomalies (along the startdates)', ytitle = 'K',
          legends = 'ERSST', biglab = FALSE, fileout = 'tos_detrended_obs.eps') # there are warnings in this step!
  # A simple test of a nonlinear fit:
  y0 <- c(10.1, 8.8, 7.3, 4.12, -0.314, -5, -10.6, -18.2)
  y1 <- Trend(var=y0, posTR=1)               # linear fit
  y2 <- Trend(var=y0, posTR=1, pldegree=2)   # quadratic fit
  plot(y0)
  lines(y0 - y1$detrended, col='blue')       # linear fit
  lines(y0 - y2$detrended, col='red')        # quadratic fit
}
\author{
  History:
  0.1  -  2011-05  (V. Guemas, \email{virginie.guemas@ic3.cat})    -  Original code
  1.0  -  2013-09  (N. Manubens, \email{nicolau.manubens@ic3.cat}) -  Formatting to CRAN
  1.1  -  2015-01  (N.S. Fuckar, \email{neven.fuckar@ic3.cat})     -  Upgrade to polynomial fit
          -> modified to include fit of a raw polynomial with an arbitrary 
          (but constrained) degree/order and a more complete $trend output.
}
\keyword{datagen}
