Added Donchian Channels

A new mainchart-indicator has been introduced to library: Donchian Channels. See more here https://www.investopedia.com/terms/d/donchianchannels.asp
NEWS has been updated accordingly.

Minor additions:

Minor typos in NEWS.md has been fixed.

NAMESPACE

@@ -8,6 +8,7 @@ export(bollinger_bands)
 export(calibrate_window)
 export(chart)
 export(dema)
+export(donchian_channel)
 export(ema)
 export(evwma)
 export(fgi)

NEWS.md

@@ -11,6 +11,7 @@
 ### New features
 
 * `smi()`-function, a `subchart`-indicator built on the `TTR::SMI()`-function.
+* `donchian_channel()`-function, a `main chart`-indicator built on the `TTR::DonchianChannel()`-function
 
 ### Expanded Support
 
@@ -55,7 +56,7 @@ needs to be resolved on `stable`- and `experimental`-functions.
 * Fixed a bug in the `limitations`-article where the desired number of observations werent compatible with the `kraken`-exchange.
 * Fixed a warning in the `get_lsratio()`-function with `source = "binance"`
 * Fixed a bug in the `lsr()`-indicator which broke the `chart()`-function when included.
-* Fixed a bug in the `get_quote()`-function where if `to = NULL` and `from != NULL` the returned `quote` would be filtered according to `UCT` and not `Sys.timezone()`
+* Fixed a bug in the `get_quote()`-function where if `to = NULL` and `from != NULL` the returned `quote` would be filtered according to `UTC` and not `Sys.timezone()`
 * Fixed a bug in the `chart()`-function where the inferred intervals would be incorrect for leap years, and months different from 30 days.
 
 # cryptoQuotes 1.3.0

R/chart_donchian.R

@@ -0,0 +1,181 @@
+# script: Donchian Channel
+# author: Serkan Korkmaz, [email protected]
+# date: 2024-05-30
+# objective: Charting the Donchian Channel. This was originally
+# an example in the vignette custom_indicators - but has now been permanently
+# added as a tribute to the turtle trading system
+# script start;
+
+#' @title
+#' Add Donchian Channels
+#' to the chart
+#'
+#' @description
+#' `r lifecycle::badge("experimental")`
+#'
+#' A high-level [plotly::add_lines()]-wrapper function that interacts
+#' with the [TTR::DonchianChannel()]-function. The function adds Donchian Channels
+#' to the main [chart()].
+#'
+#' @usage donchian_channel(
+#'  n = 10,
+#'  include.lag = FALSE,
+#'  color = '#4682b4',
+#'  ...
+#' )
+#'
+#' @inheritParams TTR::DonchianChannel
+#' @param color A [character]-vector of [length] 1. "#4682b4" by default.
+#'
+#' @inherit kline
+#'
+#' @family chart indicators
+#' @family main chart indicators
+#' @author Serkan Korkmaz
+#' @export
+donchian_channel <- function(
+    ## these arguments are the
+  ## available arguments in the TTR::DonchianChannel
+  ## function
+  n = 10,
+  include.lag = FALSE,
+  color = '#4682b4',
+  ...
+) {
+
+  check_indicator_call()
+
+  structure(
+    .Data = {
+
+      ## 1) define args
+      ## as a list from the ellipsis
+      ## which is how the chart-function
+      ## communicates with the indicators
+      args <- list(
+        ...
+      )
+
+      ## 2) define the data, which in this
+      ## case is the indicator. The indicator
+      ## function streamlines the data so it works
+      ## with plotly
+      data <- indicator(
+        ## this is just the ticker
+        ## that is passed into the chart-function
+        x = args$data,
+
+        ## columns are the columns of the ohlc
+        ## which the indicator is calculated on
+        columns = c("high", "low"),
+
+        ## the function itself
+        ## can be a custom function
+        ## too.
+        .f = TTR::DonchianChannel,
+
+        ## all other arguments
+        ## passed into .f
+        n = n,
+        include.lag = include.lag
+      )
+
+      ## each layer represents
+      ## each output from the indicator
+      ## in this case we have
+      ## high, mid and low.
+      ##
+      ## The lists represents a plotly-function
+      ## and its associated parameters.
+      layers <- list(
+        ## high
+        list(
+          type = "add_lines",
+          params = list(
+            showlegend = FALSE,
+            legendgroup = "DC",
+            name = "high",
+            inherit = FALSE,
+            data = data,
+            x    = ~index,
+            y    = ~high,
+            line = list(
+              color = color,
+              width = 0.9
+            )
+          )
+        ),
+
+        ## mid
+        list(
+          type = "add_lines",
+          params = list(
+            showlegend = FALSE,
+            legendgroup = "DC",
+            name = "mid",
+            inherit = FALSE,
+            data = data,
+            x    = ~index,
+            y    = ~mid,
+            line = list(
+              color = color,
+              dash ='dot',
+              width = 0.9
+            )
+          )
+        ),
+
+        ## low
+        list(
+          type = "add_lines",
+          params = list(
+            showlegend = FALSE,
+            legendgroup = "DC",
+            name = "low",
+            inherit = FALSE,
+            data = data,
+            x    = ~index,
+            y    = ~low,
+            line = list(
+              color = color,
+              width = 0.9
+            )
+          )
+        )
+      )
+
+      ## we can add ribbons
+      ## to the main plot to give
+      ## it a more structured look.
+      plot <- plotly::add_ribbons(
+        showlegend = TRUE,
+        legendgroup = 'DC',
+        p = args$plot,
+        inherit = FALSE,
+        x = ~index,
+        ymin = ~low,
+        ymax = ~high,
+        data = data,
+        fillcolor = as_rgb(alpha = 0.1, hex_color = color),
+        line = list(
+          color = "transparent"
+        ),
+        name = paste0("DC(", paste(c(n), collapse = ", "), ")")
+      )
+
+      ## the plot has to be build
+      ## using the cryptoQuotes::build-function
+      invisible(
+        build(
+          plot,
+          layers = layers
+        )
+      )
+
+    }
+  )
+
+}
+
+
+# script end;