+## Installation[^1]
-## Indicators
+Install the release version from CRAN:
-Every indicator follows the same interface: pass an OHLCV `data.frame`
-or `matrix` and get the same type back. The return type always matches
-the input.
+``` r
+install.packages("talib")
+```
+
+Install the development version from GitHub:
``` r
-## compute Bollinger Bands
-## on BTC OHLCV data
-tail(
- talib::bollinger_bands(BTC)
-)
-#> UpperBand MiddleBand LowerBand
-#> 2024-12-26 01:00:00 100487.38 96698.61 92909.83
-#> 2024-12-27 01:00:00 100670.65 96512.96 92355.27
-#> 2024-12-28 01:00:00 100632.13 96581.91 92531.69
-#> 2024-12-29 01:00:00 99628.77 95576.60 91524.43
-#> 2024-12-30 01:00:00 96403.53 94231.31 92059.09
-#> 2024-12-31 01:00:00 95441.13 93774.23 92107.34
+pak::pak("serkor1/ta-lib-R")
```
-## Candlestick Patterns
+## Quick start
-{talib} recognizes 61 candlestick patterns—from single-candle formations
-like Doji and Hammer to multi-candle patterns like Morning Star and
-Three White Soldiers. Each pattern returns a normalized score: `1`
-(bullish), `-1` (bearish), or `0` (no pattern).
+All functions provide S3 methods for `
+## Charting
-Multiple indicators can share a sub-panel by passing them as calls:
+[{talib}](https://serkor1.github.io/ta-lib-R/) comes with a composable
+charting API built on two core functions: `indicator()` and
+`chart()`—both functions are built on `model.frame` for maximum
+flexibility:
``` r
+## subset data and
+## store as 'BTC'
+BTC <- talib::BTC[1:75, ]
+
+## construct chart in a brace block
+## alternatively use `|>`
{
- talib::chart(BTC)
- talib::indicator(talib::BBANDS)
+ ## initialize main chart
+ talib::chart(
+ x = BTC,
+ title = "Bitcoin"
+ )
- ## pass multiple calls to combine
- ## them on a single sub-panel
+ ## add Bollinger Bands to
+ ## the existing chart
+ talib::indicator(
+ talib::BBANDS
+ )
+
+ ## add Simple Moving Averages (SMA)
+ ## to the chart in a loop
+ for (n in seq(5, 15, by = 3)) {
+ talib::indicator(
+ talib::SMA,
+ n = n
+ )
+ }
+
+ ## similar subchart indicators
+ ## like the Relative Strength Index
+ ## can be grouped to avoid repeated
+ ## subpanels
talib::indicator(
talib::RSI(n = 10),
talib::RSI(n = 14),
talib::RSI(n = 21)
)
-}
-```
-
-
-The charting system ships with 5 built-in themes: `default`,
-`hawks_and_doves`, `payout`, `tp_slapped`, and `trust_the_process`.
-Switch themes with `set_theme()`. Both
-[{plotly}](https://github.com/plotly/plotly.R) (interactive, default)
-and [{ggplot2}](https://ggplot2.tidyverse.org/) (static) backends are
-supported:
-
-``` r
-{
- ## switch to ggplot2 backend with
- ## the "Hawks and Doves" theme
- talib::set_theme("hawks_and_doves")
- talib::chart(BTC, title = "Bitcoin (BTC)")
- talib::indicator(talib::BBANDS)
- talib::indicator(talib::RSI)
- talib::indicator(talib::trading_volume)
+ ## identify Doji patterns
+ ## and add them to the chart
+ talib::indicator(
+ talib::doji
+ )
}
```
-
-
-## Column selection
+
-Indicators use the columns they need automatically. When your data has
-non-standard column names, remap them with formula syntax:
-
-``` r
-## remap 'price' to the close column
-talib::RSI(x, cols = ~price)
-
-## remap hi, lo, last to high, low, close
-talib::stochastic(x, cols = ~ hi + lo + last)
-```
-
-## Naming
+## Implementation: {talib} vs upstream (TA-Lib Core)
Functions use descriptive snake_case names, but every function is
-aliased to its TA-Lib shorthand for compatibility with the broader
-ecosystem:
+aliased to its [TA-Lib](https://github.com/TA-Lib/ta-lib) shorthand for
+compatibility with the broader ecosystem:
@@ -188,52 +185,79 @@ ecosystem:
-``` r
-## snake_case and TA-Lib aliases
-## are identical
-all.equal(
- target = talib::bollinger_bands(BTC),
- current = talib::BBANDS(BTC)
-)
-#> [1] TRUE
-```
+### Interface: R vs Python
-## Installation[^1]
+The main difference between the R and Python interfaces is how OHLCV
+series are passed into each indicator function. Below is an example of
+identifying `Doji` patterns in R and Python.
-Install the release version from CRAN:
+In Python, each series is passed independently:
-``` r
-install.packages("talib")
-```
+``` python
+import numpy as np
+import talib
-Install the development version from GitHub:
+o = np.array([1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1], dtype=float)
+h = np.array([2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2], dtype=float)
+l = np.array([1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1], dtype=float)
+c = np.array([2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 1], dtype=float)
-``` r
-pak::pak("serkor1/ta-lib-R")
+print(
+ talib.CDLDOJI(o, h, l, c)
+)
```
-### Aggressive optimizations
-
-Unknown flags passed to `configure` are forwarded verbatim to both the
-CMake build of the vendored TA-Lib and the R wrapper compile step.
-Rebuild from source with any compiler flags you like:
+In R the series are passed as a tabular container:
``` r
-install.packages(
- "talib",
- type = "source",
- configure.args = "-O3 -march=native"
+ohlc <- data.frame(
+ open = c(1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1),
+ high = c(2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2),
+ low = c(1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1),
+ close = c(2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 1)
+)
+
+talib::CDLDOJI(
+ ohlc
)
```
-Or from a local clone:
+All default series arguments are handled internally, and the `R`
+interface is therefore higher-level: users pass one OHLC container
+rather than manually splitting the series.
+
+## Contributing and cloning
+
+Contributions are welcome. For non-trivial changes, please open an issue
+first to discuss the proposed design, API impact, and testing approach.
+
+This repository vendors [TA-Lib](https://github.com/TA-Lib/ta-lib) as a
+Git submodule. Clone the repository with submodules enabled:
-``` shell
-git clone --recursive https://github.com/serkor1/ta-lib-R.git
+``` sh
+git clone --recurse-submodules https://github.com/serkor1/ta-lib-R.git
cd ta-lib-R
-R CMD INSTALL . --configure-args="-O3 -march=native"
```
+If you already cloned the repository without submodules, initialize them
+with:
+
+``` sh
+git submodule update --init --recursive
+```
+
+Most indicator wrappers, helper functions, documentation fragments, and
+unit tests are generated from the scripts in `codegen/`. The charting
+interface is maintained separately.
+
+Common development tasks are exposed through Make targets:
+
+``` sh
+make help
+```
+
+See CONTRIBUTING.md for the full development workflow.
+
## Code of Conduct
Please note that [{talib}](https://serkor1.github.io/ta-lib-R/) is
@@ -241,7 +265,7 @@ released with a [Contributor Code of
Conduct](https://contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html).
By contributing to this project, you agree to abide by its terms.
-[^1]: [TA-Lib](https://github.com/TA-Lib/ta-lib) is vendored via
- `CMake`, so a pre-installed TA-Lib is not required. Some systems
- (Windows in particular) may require `CMake` to be explicitly
- installed.
+[^1]: `{talib}` is a compiled package. CRAN binaries are available for
+ standard platforms when provided by CRAN. Source installation
+ requires a working compiler toolchain and
+ [CMake](https://cmake.org/).
diff --git a/dev/README.Rmd b/dev/README.Rmd
index 3012f9491..500215ba9 100644
--- a/dev/README.Rmd
+++ b/dev/README.Rmd
@@ -22,18 +22,9 @@ knitr::opts_chunk$set(
warning = FALSE,
echo = FALSE
)
-
-# indicator counts from codegen metadata
-source(file.path(knitr::opts_knit$get("base.dir"), "codegen", "gen_code", "indicators.R"))
-families <- vapply(indicators, function(x) x$family, character(1))
-n_patterns <- sum(families == "Pattern Recognition")
-n_indicators <- sum(families != "Pattern Recognition")
-
-# subset BTC to last 150 rows for cleaner charts
-BTC <- tail(talib::BTC, 150)
```
-# {talib}: A Technical Analysis and Candlestick Pattern Library in R 
+# {talib}: Fast TA-Lib indicators and candlestick patterns for R
[](https://github.com/serkor1/ta-lib-R/actions/workflows/R-CMD-check.yaml)
@@ -43,125 +34,126 @@ BTC <- tail(talib::BTC, 150)
[](https://r-pkg.org/pkg/talib)
-[{talib}](https://serkor1.github.io/ta-lib-R/) is an R package for technical analysis, candlestick pattern recognition, and interactive financial charting---built on the [TA-Lib](https://github.com/TA-Lib/ta-lib) C library. It provides `r n_indicators` technical indicators, `r n_patterns` candlestick patterns, and a composable charting system powered by [{plotly}](https://github.com/plotly/plotly.R) and [{ggplot2}](https://ggplot2.tidyverse.org/). All indicator computations are implemented in C via `.Call()` for minimal overhead.
+[{talib}](https://serkor1.github.io/ta-lib-R/) provides fast R bindings
+to the [TA-Lib](https://github.com/TA-Lib/ta-lib) C library for OHLCV data: technical indicators, candlestick pattern recognition, rolling-window utilities, and composable financial charts. It is designed for researchers, analysts, and quant developers who need technical-analysis features in R without building a heavy dependency stack. Core computations are executed in C through `.Call()`, while charting support is available through optional [{plotly}](https://github.com/plotly/plotly.R) and [{ggplot2}](https://ggplot2.tidyverse.org/) integrations.
-Alongside [{TTR}](https://github.com/joshuaulrich/TTR), [{talib}](https://serkor1.github.io/ta-lib-R/) adds candlestick pattern recognition and interactive charts to the R technical analysis ecosystem.
+The API covers 150+ [TA-Lib](https://github.com/TA-Lib/ta-lib)-backed functions across momentum, overlap, volatility, volume, cycle, price-transform, rolling-statistics, and candlestick-pattern families, including 61 candlestick pattern detectors.
-```{r hero, fig.align = 'center', echo = TRUE}
-{
- ## create a candlestick chart
- talib::chart(BTC, title = "Bitcoin (BTC)")
+## Why {talib}?
- ## overlay Bollinger Bands on
- ## the price panel
- talib::indicator(talib::bollinger_bands)
+
- ## mark Engulfing candlestick
- ## patterns on the chart
- talib::indicator(talib::engulfing, data = BTC)
+| Need | {talib}|
+|:----------------------|:-----------------------------------------------------------------------------------------|
+| Technical indicators | TA-Lib-backed moving averages, momentum, volatility, volume, cycle, and overlap studies |
+| Candlestick patterns | Built-in Japanese candlestick pattern recognition |
+| OHLCV workflows | Works directly with open, high, low, close, and volume columns |
+| Performance | Computation delegated to C routines through `.Call()` |
+| Dependencies | Minimal required R dependencies; plotting packages are optional |
+| Charts | Composable financial charts with optional `{plotly}` and `{ggplot2}` support |
- ## add RSI and volume as
- ## separate sub-panels
- talib::indicator(talib::RSI)
- talib::indicator(talib::trading_volume)
-}
-```
+
-## Indicators
+## Installation[^1]
-Every indicator follows the same interface: pass an OHLCV `data.frame` or `matrix` and get the same type back. The return type always matches the input.
+Install the release version from CRAN:
-```{r indicators, echo = TRUE}
-## compute Bollinger Bands
-## on BTC OHLCV data
-tail(
- talib::bollinger_bands(BTC)
-)
+```{r install-cran, echo = TRUE, eval = FALSE}
+install.packages("talib")
```
-## Candlestick Patterns
-
-{talib} recognizes `r n_patterns` candlestick patterns---from single-candle formations like Doji and Hammer to multi-candle patterns like Morning Star and Three White Soldiers. Each pattern returns a normalized score: `1` (bullish), `-1` (bearish), or `0` (no pattern).
+Install the development version from GitHub:
-```{r patterns, echo = TRUE}
-## detect Engulfing patterns:
-## 1 = bullish, -1 = bearish, 0 = none
-tail(
- talib::engulfing(BTC)
-)
+```{r install-dev, echo = TRUE, eval = FALSE}
+pak::pak("serkor1/ta-lib-R")
```
-## Charts
-
-Charts are built in two steps: `chart()` creates the price chart, then `indicator()` layers on technical indicators. Overlap indicators (moving averages, Bollinger Bands) draw on the price panel; oscillators (RSI, MACD) get their own sub-panels.
-
-```{r charting, fig.align = 'center', fig.height = 7, echo = TRUE}
-{
- ## price chart with two moving
- ## averages and MACD below
- talib::chart(BTC)
- talib::indicator(talib::SMA, n = 7)
- talib::indicator(talib::SMA, n = 14)
- talib::indicator(talib::MACD)
-}
-```
+## Quick start
-Multiple indicators can share a sub-panel by passing them as calls:
+All functions provide S3 methods for `
@@ -177,51 +169,73 @@ Functions use descriptive snake_case names, but every function is aliased to its
-```{r alias, echo = TRUE}
-## snake_case and TA-Lib aliases
-## are identical
-all.equal(
- target = talib::bollinger_bands(BTC),
- current = talib::BBANDS(BTC)
-)
-```
+### Interface: R vs Python
-## Installation[^1]
+The main difference between the R and Python interfaces is how OHLCV series are passed into each indicator function.
+Below is an example of identifying `Doji` patterns in R and Python.
-Install the release version from CRAN:
+In Python, each series is passed independently:
-```{r install-cran, echo = TRUE, eval = FALSE}
-install.packages("talib")
-```
+```python
+import numpy as np
+import talib
-Install the development version from GitHub:
+o = np.array([1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1], dtype=float)
+h = np.array([2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2], dtype=float)
+l = np.array([1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1], dtype=float)
+c = np.array([2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 1], dtype=float)
-```{r install-dev, echo = TRUE, eval = FALSE}
-pak::pak("serkor1/ta-lib-R")
+print(
+ talib.CDLDOJI(o, h, l, c)
+)
```
-### Aggressive optimizations
+In R the series are passed as a tabular container:
-Unknown flags passed to `configure` are forwarded verbatim to both the CMake build of the vendored TA-Lib and the R wrapper compile step. Rebuild from source with any compiler flags you like:
+```{r r-vs-python-block, echo = TRUE, eval = FALSE}
+ohlc <- data.frame(
+ open = c(1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1),
+ high = c(2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2),
+ low = c(1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1),
+ close = c(2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 1)
+)
-```{r install-native, echo = TRUE, eval = FALSE}
-install.packages(
- "talib",
- type = "source",
- configure.args = "-O3 -march=native"
+talib::CDLDOJI(
+ ohlc
)
```
-Or from a local clone:
+All default series arguments are handled internally, and the `R` interface is therefore higher-level: users pass one OHLC container rather than manually splitting the series.
+
+## Contributing and cloning
+
+Contributions are welcome. For non-trivial changes, please open an issue first to discuss the proposed design, API impact, and testing approach.
+
+This repository vendors [TA-Lib](https://github.com/TA-Lib/ta-lib) as a Git submodule. Clone the repository with submodules enabled:
-```shell
-git clone --recursive https://github.com/serkor1/ta-lib-R.git
+```sh
+git clone --recurse-submodules https://github.com/serkor1/ta-lib-R.git
cd ta-lib-R
-R CMD INSTALL . --configure-args="-O3 -march=native"
```
+If you already cloned the repository without submodules, initialize them with:
+
+```sh
+git submodule update --init --recursive
+```
+
+Most indicator wrappers, helper functions, documentation fragments, and unit tests are generated from the scripts in `codegen/`. The charting interface is maintained separately.
+
+Common development tasks are exposed through Make targets:
+
+```sh
+make help
+```
+
+See CONTRIBUTING.md for the full development workflow.
+
## Code of Conduct
Please note that [{talib}](https://serkor1.github.io/ta-lib-R/) is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.
-[^1]: [TA-Lib](https://github.com/TA-Lib/ta-lib) is vendored via `CMake`, so a pre-installed TA-Lib is not required. Some systems (Windows in particular) may require `CMake` to be explicitly installed.
+[^1]: `{talib}` is a compiled package. CRAN binaries are available for standard platforms when provided by CRAN. Source installation requires a working compiler toolchain and [CMake](https://cmake.org/).
\ No newline at end of file
diff --git a/man/figures/README-charting-1.png b/man/figures/README-charting-1.png
deleted file mode 100644
index 652182972..000000000
Binary files a/man/figures/README-charting-1.png and /dev/null differ
diff --git a/man/figures/README-charting-example-1.png b/man/figures/README-charting-example-1.png
new file mode 100644
index 000000000..67ea5c625
Binary files /dev/null and b/man/figures/README-charting-example-1.png differ
diff --git a/man/figures/README-combined-1.png b/man/figures/README-combined-1.png
deleted file mode 100644
index 94090cb88..000000000
Binary files a/man/figures/README-combined-1.png and /dev/null differ
diff --git a/man/figures/README-ggplot2-1.png b/man/figures/README-ggplot2-1.png
deleted file mode 100644
index e19832cb9..000000000
Binary files a/man/figures/README-ggplot2-1.png and /dev/null differ
diff --git a/man/figures/README-hero-1.png b/man/figures/README-hero-1.png
deleted file mode 100644
index 23ee8409b..000000000
Binary files a/man/figures/README-hero-1.png and /dev/null differ