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/>.
#

#' Arms' Ease of Movement Value
#'
#' Arms' Ease of Movement Value (EMV) emphasizes days where the security moves
#' easily and minimizes days where the security does not move easily.  Developed
#' by Richard W. Arms, Jr.
#'
#' The EMV is calculated by dividing the midpoint ([high + low]/2) move by the
#' 'Box Ratio' (volume divided by the high minus low).
#'
#' @param HL Object that is coercible to xts or matrix and contains High-Low
#' prices.
#' @param volume Vector or matrix of volume observations corresponding to the
#' \code{HL} object.
#' @param n Number of periods for moving average.
#' @param maType A function or a string naming the function to be called.
#' @param vol.divisor An increment to make the results larger and easier to work
#' with.
#' @param \dots Other arguments to be passed to the \code{maType} function.
#' @return A object of the same class as \code{HL} and \code{volume} or a matrix
#' (if \code{try.xts} fails) containing the columns:
#'  \describe{
#'   \item{ emv }{ The ease of movement values. }
#'   \item{ maEMV }{ The smoothed (as specified by \code{ma}) ease of movement values. }
#'  }
#' @note A buy/sell signal is generated when the EMV crosses above/below zero.
#' When the EMV hovers around zero, there are small price movements and/or high
#' volume, and the price is not moving easily.
#' @author Joshua Ulrich
#' @seealso See \code{\link{EMA}}, \code{\link{SMA}}, etc. for moving average
#' options; and note Warning section.
#' @references The following site(s) were used to code/document this
#' indicator:\cr \url{https://www.fmlabs.com/reference/ArmsEMV.htm}\cr
#' \url{https://www.metastock.com/Customer/Resources/TAAZ/?p=51}\cr
#' \url{https://www.linnsoft.com/techind/arms-ease-movement}\cr
#' @keywords ts
#' @examples
#'
#'  data(ttrc)
#'  emv <- EMV(ttrc[,c("High","Low")], ttrc[,"Volume"])
#'
"EMV" <-
function(HL, volume, n=9, maType, vol.divisor=10000, ...) {

  # Arms' Ease of Movement Value

  if( missing(HL) || missing(volume) )
    stop("High-Low matrix (HL) and volume vector must be specified.")

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

  if(!(is.xts(HL) && is.xts(volume))) {
    HL <- as.matrix(HL)
    volume <- as.matrix(volume)
  }

  mid     <- ( HL[,1] + HL[,2] ) / 2
  volume  <- volume / vol.divisor

  emv    <- momentum(mid, n=1, na.pad=TRUE) / ( volume / ( HL[,1] - HL[,2] ) )

  maArgs <- list(n=n, ...)
  # Default MA
  if(missing(maType)) {
    maType <- 'SMA'
  }

  maEMV <- do.call( maType, c( list(emv), maArgs ) )

  result <- cbind(emv,maEMV)
  colnames(result) <- c('emv','maEMV')

  reclass( result, HL )
}