[serkor1]

📚 What?

This version brings many changes to the R package.
The entire code generating backend have been rewritten so it closely follows the upstream naming of parameters and it uses X-macros so it also installs way fastert than before - but it also means that there is alot of breaking changes.
The update is a big leap towards a stable release.

improvements

• A new function for pre-calculating the lookback-period has been implemented. It can be used as follows:

talib::lookback(
  FUN        = talib::SMA,
  timePeriod = 10,
  x          = talib::BTC
)
#> [1] 9

The function returns the required lookback for calculating the indicator. A lookback of 0 means the indicator is computable from the first observation (talib::balance_of_power(), for example).
Its use-case is customized control-flows for downstream wrappers and/or packages that declares dependency on {talib}.

• Each calculated indicator carries a lookback attribute: the total number of leading rows that are not computed. The attribute is cumulative, so chaining indicators sums each stage's lookback, and it is used internally to chain indicators deterministically at full input length:

tail(
  output <- talib::BBANDS(
    talib::SMA(
      talib::RSI(
        talib::GOOGL
      )
    )
  )
)
#>            UpperBand MiddleBand LowerBand
#> 2021-12-22  57.50571   54.51537  51.52503
#> 2021-12-23  57.26401   54.23193  51.19985
#> 2021-12-27  57.02005   53.97461  50.92918
#> 2021-12-28  56.75847   53.71577  50.67306
#> 2021-12-29  56.55065   53.47299  50.39534
#> 2021-12-30  56.40837   53.25097  50.09356

stopifnot(
  nrow(talib::GOOGL) == nrow(output)
)

attr(
  output,
  "lookback"
)
#> [1] 62

The chain carries RSI (14), SMA (29) and BBANDS (19)—attr(output, "lookback") is their sum, the leading-NA head of the final series. The per-indicator lookback remains available via talib::lookback().

• The source code have been re-written so it generates the underlying TA-Lib wrappers using preprocessors and X-Macros, which compiles much faster than before.

• <xts>-methods:—All indicators now supports <xts>-objects. These methods are considered the primary entry point for all indicators, and can be considered stable from v1.0.0, where changes—if any—will be implemented gradually after a deprecation period. The method uses the same signature as before, see the example below:

library(xts)

tail(
  x <- talib::bollinger_bands(
    talib::GOOGL
  )
)
#>            UpperBand MiddleBand LowerBand
#> 2021-12-22  149.1432   144.4920  139.8408
#> 2021-12-23  149.2513   144.5318  139.8124
#> 2021-12-27  149.6263   144.8180  140.0097
#> 2021-12-28  149.7444   144.8758  140.0072
#> 2021-12-29  149.8398   145.1137  140.3876
#> 2021-12-30  149.7308   145.3711  141.0115

class(x)
#> [1] "xts" "zoo"

• MAVP: Moving Average Variable Periods—The function calculates a moving average with variable periods between candles. See below:

talib::variable_moving_average_period(
  x = 1:10,
  periods = c(1, 1, 1, 2, 2, 2, 3, 4, 4, 4),
  minimumPeriod = 2,
  maximumPeriod = 4
)

#> [1]  NA  NA  NA 3.5 4.5 5.5 6.0 6.5 7.5 8.5
#> attr(,"lookback")

• AVGDEV: Averge deviation—The function calculates the average deviation of a series. See below:

talib::average_deviation(
x = 1:10,
periods = c(1, 1, 1, 2, 2, 2, 3, 4, 4, 4),
timePeriod = 5
)
#>  [1]  NA  NA  NA  NA 1.2 1.2 1.2 1.2 1.2 1.2
#> attr(,"lookback")
#> [1] 4

• CMF: Chaikin Money Flow—The function calculates the chaikin money flow of HLC-V series. See below:

tail(
  talib::CMF(
    x = talib::GOOGL,
    timePeriod = 20L,
    cols = ~ high + low + close + volume
  )
)
#>                   CMF
#> 2021-12-22 0.08511277
#> 2021-12-23 0.03979116
#> 2021-12-27 0.08378773
#> 2021-12-28 0.05341346
#> 2021-12-29 0.12197905
#> 2021-12-30 0.16362414

• CMOU: Chande Momentum Oscillator (Unsmoothed)—This function calculates the unsmoothed chande momentum oscillator of a series. See below:

tail(
  talib::CMOU(
    x = talib::GOOGL,
    timePeriod = 20L,
    cols = ~close
  )
)
#>                 CMOU
#> 2021-12-22  1.650705
#> 2021-12-23  2.068290
#> 2021-12-27 16.093739
#> 2021-12-28  3.458882
#> 2021-12-29 15.946284
#> 2021-12-30 17.488048

• HMA: Hull Moving Average—This function calculates the hull moving average of a series. See below:

tail(
  talib::HMA(
    talib::GOOGL,
    timePeriod = 20L,
    cols = ~open
  )
)
#>                 HMA
#> 2021-12-22 143.4272
#> 2021-12-23 143.1059
#> 2021-12-27 143.3396
#> 2021-12-28 144.0303
#> 2021-12-29 144.8070
#> 2021-12-30 145.5167

• NVI: Negative Volume Index—This function calculates the negative volume index of a C-V series. See below:

tail(
  talib::NVI(
    talib::GOOGL,
    cols = ~ close + volume
  )
)
#>                 NVI
#> 2021-12-22 3087.244
#> 2021-12-23 3087.244
#> 2021-12-27 3108.047
#> 2021-12-28 3108.047
#> 2021-12-29 3107.369
#> 2021-12-30 3097.739

• PVI: Positive Volume Index—This function calculates the positive volume index of a C-V series. See below:

tail(
  talib::PVI(
    talib::GOOGL,
    cols = ~ close + volume
  )
)
#>                 PVI
#> 2021-12-22 899.3401
#> 2021-12-23 902.4205
#> 2021-12-27 902.4205
#> 2021-12-28 894.9800
#> 2021-12-29 894.9800
#> 2021-12-30 894.9800

• VWMA: Volume Weighted Moving Average—This function calculates the volume weighted moving average of a series. See below:

tail(
  talib::VWMA(
    x = talib::GOOGL,
    timePeriod = 20L,
    cols = ~ close + volume
  )
)
#>                VWMA
#> 2021-12-22 144.1797
#> 2021-12-23 144.2380
#> 2021-12-27 144.4321
#> 2021-12-28 144.4406
#> 2021-12-29 144.6905
#> 2021-12-30 144.9503

• All indicators have gotten a camelCase alias to introduce a form of consistency across R's finance ecosystem and oldschool coding schemes.
  The indicators below produces the same output:

talib::bollinger_bands()
talib::BBANDS()
talib::bollingerBands()

Each UPPERCASE and camelCase function is an alias of its underlying snake_case function, so the functions behaves the same.

breaking changes

• General: All functions now follows the naming convention of TA-Lib. All function signatures are on the following form:

indicator(
  x,          ## unchanged
  cols,       ## unchanged
  ## additional/optional TA-Lib parameters
  ## are now camelCase mined upstream
  timePeriod, ## was 'n' before
  fooBar,     ## was 'foo_bar' or 'foobar' before
  fooBaz,     ## was 'foo_baz' or 'foobaz' before
  na.bridge = FALSE ## unchanged
)

This has the benefit of being transparent when comparing or reading the source code.

• MATypes: Functions that used MATypes in the indicator function are now significantly different. See the bollinger_bands() below:

talib::bollinger_bands(
		talib::BTC,
		timePeriod = 20,
		maType = talib::EMA()
)

Prior to this update, the correct call was:

talib::bollinger_bands(
		talib::BTC,
    ma = talib::EMA(n = 20)
)

While the above function call is aestethically pleasing, it did introduce some ambigiuites in other calls. See, for example, APO() (v0.9.2) below:

absolute_price_oscillator(
  x,
  cols,
  fast = 12,
  slow = 26,
  ma = SMA(n = 9),
  na.bridge = FALSE,
  ...
)

In this specific case the function has three different n - the underlying function were discarding n = 9 while keeping the MAType.
The new call is given as:

absolute_price_oscillator(
	x,
	cols,
	fastPeriod = 12,
	slowPeriod = 26,
	maType = 0,
	na.bridge = FALSE,
	...
) 

In this call the role of each argument is should be clearer than before.

• Moving Average (MA) signatures:—the generic S3 signature of the MAs has been changed in response to the new TA-Lib (upstream) release. The release introduced the volume weighted moving average which uses the volume in its calculation.
  This deviates from the generic x + timePeriod signature, and breaks the numeric-method.
  One solution is to do the following:

VWMA.numeric(x, cols, timePeriod, na.bridge = FALSE, volume, ...)

To avoid breaking the S3 signature. However, given the importance of the volume-argument and the fact that cols is rarely used, the signature has been changed to accommodate future additions of MAs which take additional series. The new signature is as follows:

foo(x, [series], timePeriod, [optional], cols, na.bridge = FALSE, ...)

Additional series (the volume) lead directly after x, while additional optional parameters keep their place after timePeriod. In the case of VWMA this becomes:

VWMA(
	x,
	volume,
	timePeriod = 30,
	cols,
	na.bridge = FALSE,
	...
)

And for the remaining MAs:

foo(
	x,
	timePeriod = 30,
	cols,
	na.bridge = FALSE,
	...
)

MAs with additional optional parameters retain them after timePeriod, e.g. MAMA(x, timePeriod, fastLimit, slowLimit, cols, na.bridge, ...) and T3(x, timePeriod, volumeFactor, cols, na.bridge, ...).

The volume-argument is not required when x carries a volume column: VWMA(x) selects it via the default formula ~close + volume as before. An explicitly passed vector takes precedence, in which case only the close-column is required:

## volume from the 'volume'-column of x
VWMA(x)

## explicitly passed volume; only 'close' required
VWMA(x, volume = my_volume)

## fully positional on vectors
VWMA(price, volume, 20)

NOTE: passing cols positionally as the second argument no longer works for the MAs—it has to be passed by name, ie. SMA(x, cols = ~open).

bug-fixes

• CCI: Incorrect charting—The indicator were incorrectly classified as a main chart indicator—

• One-dimensional indicators: incorrect return <class>—Indicators that returns a one-dimensional indicator (MA, RSI, etc.) were returning a <matrix> or <data.frame> instead of <numeric>.

• Merged indicators: overlapping last-values—On the plotly backend, merging indicators onto one panel stacked every last-value label on the panel's top-right corner. The labels are now collapsed into a single evenly spaced label, mirroring the merged subtitle of the ggplot2 backend.

• Merged indicators: indistinguishable last-values—Merged last-value labels used the bare output column name, so merging the same indicator with different parameters displayed identical labels. The labels now carry the full indicator specification, including its parameters, as the ggplot2 backend already did.

[codecov]

Codecov Report

❌ Patch coverage is 98.43470% with 70 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.06%. Comparing base (11ed302) to head (f9f67d0).
⚠️ Report is 121 commits behind head on CRAN.

Files with missing lines	Patch %	Lines
R/lookback.R	66.66%	20 Missing ⚠️
R/helper.R	61.90%	8 Missing ⚠️
R/ta_DEMA.R	87.69%	8 Missing ⚠️
R/series.R	94.77%	7 Missing ⚠️
R/ta_CMOU.R	96.75%	6 Missing ⚠️
R/chart_build.R	63.63%	4 Missing ⚠️
R/chart_indicator.R	94.28%	4 Missing ⚠️
R/ta_CMF.R	97.61%	4 Missing ⚠️
R/ta_BBANDS.R	96.47%	3 Missing ⚠️
R/ta_AVGDEV.R	97.22%	2 Missing ⚠️
... and 3 more

Additional details and impacted files

@@            Coverage Diff             @@
##             CRAN      #65      +/-   ##
==========================================
- Coverage   96.58%   96.06%   -0.53%     
==========================================
  Files         280      162     -118     
  Lines       21012    21965     +953     
==========================================
+ Hits        20294    21100     +806     
- Misses        718      865     +147     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.