R/percentRank.R

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

#'Percent Rank over a Moving Window
#'
#'This function computes a running/rolling percentage rank.
#'
#'The computation for a percentage rank can vary depending on the weight given
#'to values in the window that are equal to the value being ranked. This weight
#'can be set using the \code{exact.multiplier} argument which defaults to 0.5.
#'
#'\code{exact.multiplier = 0} scores equal values in the lookback window as
#'always being greater than the value being ranked. \code{exact.multiplier = 1}
#'scores equal values as being below the value being ranked. Any multiplier
#'between 0 and 1 counts that proportion of the equal values as being below
#'the value being ranked.
#'
#'The value of \code{exact.multiplier} has the most impact when the window is
#'relatively small or when the number of discrete values in the window is
#'small. For non-repeating values, changing \code{exact.multiplier = 0} to
#'\code{exact.multiplier = 1} for a window of size \code{N} will shift the
#'resulting percentile rankings by \code{1/N}. It is equivalent to changing
#'the question from, "how many values are < the value" to "how many values
#'are <= the value".
#'
#'@aliases runPercentRank percentRank PercentRank
#'@param x Object coercible to xts or matrix.
#'@param n Number of periods to use in the window or, if
#'\code{cumulative=TRUE}, the number of observations to use before the first
#'result is returned. Must be between 1 and \code{nrow(x)}, inclusive.
#'@param cumulative Logical, use from-inception calculation?
#'@param exact.multiplier The weight applied to identical values in the window.
#'Must be between 0 and 1, inclusive. See details.
#'
#'@return A object of percent ranks over a n-period moving window of the same
#'class as \code{x} and \code{y} or a vector (if \code{try.xts} fails).
#'
#'@note This computation is different from the one used in Microsoft Excel's
#'\code{PERCENTRANK} formula. Excel's computation is rather strange and gives
#'inconsistent results as it uses interpolation to rank values that are not
#'found within the lookback window.
#'
#'@author Charlie Friedemann
#'
#'@references The following site(s) were used to code/document this
#'indicator:\cr \url{https://en.wikipedia.org/wiki/Percentile_rank}\cr
#'
#'@keywords ts
runPercentRank <- function(x, n=260, cumulative = FALSE, exact.multiplier = 0.5) {
  x <- try.xts(x, error = as.matrix)

  if (n < 1 || n > NROW(x))
    stop(sprintf("n = %d is outside valid range: [1, %d]", n, NROW(x)))
  if (exact.multiplier < 0 || exact.multiplier > 1)
    stop(sprintf("exact.multiplier = %d is outside valid range: [0, 1]", exact.multiplier))

  NAs <- sum(is.na(x))
  if (NAs > 0) {
    if (any(is.na(x[-(1:NAs)]))) stop("Series contains non-leading NAs")
  }

  if (!isTRUE(cumulative) && identical(as.integer(n), 1L)) {
    result <- double(NROW(x))
    result[] <- exact.multiplier
  } else {
    result <- .Call("ttr_rollPercentRank", x, n, isTRUE(cumulative),
                    exact.multiplier, PACKAGE = "TTR")
  }

  reclass(result, x)
}