TTR: Technical Trading Rules

#
#   TTR: Technical Trading Rules
#
#   Copyright (C) 2007-2013  Joshua M. Ulrich
#
#   This program is free software: you can redistribute it and/or modify
#   it under the terms of the GNU General Public License as published by
#   the Free Software Foundation, either version 2 of the License, or
#   (at your option) any later version.
#
#   This program is distributed in the hope that it will be useful,
#   but WITHOUT ANY WARRANTY; without even the implied warranty of
#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#   GNU General Public License for more details.
#
#   You should have received a copy of the GNU General Public License
#   along with this program.  If not, see <http://www.gnu.org/licenses/>.
#

#' Donchian Channel
#'
#' Donchian Channels were created by Richard Donchian and were used to generate
#' buy and sell signals for the Turtle Trading system.
#'
#' Donchian Channels consist of two (sometimes three) lines:
#'
#' The top line is the highest high of the past \code{n} periods.  The bottom
#' line is the lowest low of the past \code{n} periods.  The middle line is the
#' average of the top and bottom lines.
#'
#' @aliases DonchianChannel Donchian
#' @param HL Object that is coercible to xts or matrix and contains High-Low
#' prices.
#' @param n Number of periods for moving average.
#' @param include.lag Should values be lagged so that today's prices are not
#' included in the calculation? See Note.
#' @return A object of the same class as \code{HL} or a matrix (if
#' \code{try.xts} fails) containing the columns:
#'  \describe{
#'   \item{ high }{ The highest high series. }
#'   \item{ mid }{ The average of \code{high} and \code{low}. }
#'   \item{ low }{ The lowest low series. }
#'  }
#' @note The default of \code{include.lag=FALSE} makes \code{DonchainChannel}
#' consistent with other \pkg{TTR} functions, in that it includes the current
#' period in the calculation.
#'
#' The default is different than the original calculation, which would calculate
#' the indicator using periods t-1 through t-n. Setting \code{include.lag=TRUE}
#' will return the result of the original calculation.
#'
#' The default of this argument may change in the future.
#' @author Joshua Ulrich
#' @seealso See \code{\link{BBands}}.
#' @references The following site(s) were used to code/document this
#' indicator:\cr \url{https://www.linnsoft.com/techind/donchian-channels}\cr
#' @keywords ts
#' @examples
#'
#'  data(ttrc)
#'  dc <- DonchianChannel( ttrc[,c("High","Low")] )
#'
'DonchianChannel' <-
function(HL, n=10, include.lag=FALSE) {

  # Donchian Channel

  # Notes from John Bollinger:
  #
  # "In the old paper-calculation days you would calculate the numbers
  #  after the close by hand and for use in the next day's trading to gauge
  #  the "n-day" breakouts and you would have used n-days worth of data the
  #  calc. Thus an n-day calc with a lag of one would be consistent with
  #  practice in Donchian's day. (Total window of n+1.) Another example are
  #  the floor traders numbers or pivots, which are calculated from the
  #  prior period's data for use on the current period. In both case
  #  including the current period in the calculation would not be correct."

  HL <- try.xts(HL, error=as.matrix)

  if(!(NCOL(HL) %in% c(1,2))) {
    stop("Price series must be either High-Low, or Close/univariate.")
  }
  if(NCOL(HL)==2) {
      hi <- HL[,1]
      lo <- HL[,2]
  } else {
      hi <- HL
      lo <- HL
  }

  high <- runMax(hi,n)
  low  <- runMin(lo,n)
  mid  <- (high+low)/2

  result <- cbind(high,mid,low)
  colnames(result) <- c("high","mid","low")

  if(include.lag) {
    # use lag.xts in case 'result' is a matrix
    result <- lag.xts(result)
  }

  reclass(result, HL)
}