kingchenc
32e18cb3a3
Fills the two empty r-universe tabs (**Articles**, **Datasets**) for the R package and gives R users a runnable onboarding path. ## What - **`vignettes/getting-started.Rmd`** — Articles tab. Walks through batch vs streaming (and that they're equivalent), multi-output MACD, candle ATR, and `reset()`, all over the bundled sample series. Built strictly from the already-proven README quick-start + golden-test API (`Sma`/`Ema`/`Rsi`/`Atr`/`MacdIndicator`, `batch`/`update`/`reset`) — no new indicator logic. - **`data/sample_ohlcv.rda`** (+ `data-raw/sample_ohlcv.R` generator) — Datasets tab. A deterministic, seeded synthetic daily OHLCV series (250 rows × `date/open/high/low/close/volume`); documented via `R/data.R` + `man/sample_ohlcv.Rd`. `LazyData: true` → available right after `library(wickra)`. - **`DESCRIPTION`** — `Suggests: knitr, rmarkdown`, `VignetteBuilder: knitr`, `LazyData: true`. - **`ci.yml`** — the R job now knits the vignette (executes its R chunks, no pandoc needed) so a broken example is caught **in CI** before r-universe / CRAN `R CMD check`. The main job otherwise only `R CMD INSTALL`s. ## Verified locally (R 4.6.0 + Rtools45) - Package installs with the dev C-ABI override; dataset moves to the lazyload DB. - Vignette **knits cleanly** — every chunk runs, `batch == streaming` holds, MACD/ATR/RSI produce sensible values. ## Notes - No version bump — metadata/docs only; rides the next release. Merging triggers an r-universe rebuild → Articles + Datasets populate **and** (now that `support@wickra.org` is verified) the maintainer avatar resolves. - `data-raw/` is `.Rbuildignore`d (generator, not shipped). The `.rda` is XZ-compressed (~3 KB). Not merging — for review.
114 lines
2.9 KiB
Plaintext
114 lines
2.9 KiB
Plaintext
---
|
|
title: "Getting started with wickra"
|
|
output: rmarkdown::html_vignette
|
|
vignette: >
|
|
%\VignetteIndexEntry{Getting started with wickra}
|
|
%\VignetteEngine{knitr::rmarkdown}
|
|
%\VignetteEncoding{UTF-8}
|
|
---
|
|
|
|
```{r setup, include = FALSE}
|
|
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
|
|
```
|
|
|
|
`wickra` exposes the Wickra technical-analysis library in R over its C ABI hub.
|
|
Every indicator is a constructor returning a `wickra_indicator`; you feed it data
|
|
one observation at a time with `update()` (an O(1) streaming step) or run a whole
|
|
series at once with `batch()`. Both paths share the exact same Rust core, so a
|
|
live feed and a historical backtest compute identical values.
|
|
|
|
```{r}
|
|
library(wickra)
|
|
```
|
|
|
|
## A sample series
|
|
|
|
The package ships a small synthetic OHLCV series, `sample_ohlcv`, for examples
|
|
(a seeded random walk — not real market data).
|
|
|
|
```{r}
|
|
head(sample_ohlcv)
|
|
```
|
|
|
|
## Batch: a whole series at once
|
|
|
|
Scalar indicators run over a vector with `batch()`. Warmup positions are `NA`.
|
|
|
|
```{r}
|
|
sma <- Sma(20)
|
|
sma_values <- batch(sma, sample_ohlcv$close)
|
|
tail(sma_values)
|
|
```
|
|
|
|
## Streaming: one observation at a time
|
|
|
|
The same indicator fed tick-by-tick with `update()` returns the identical
|
|
values — an equivalence the test suite enforces for every indicator.
|
|
|
|
```{r}
|
|
sma_stream <- Sma(20)
|
|
streamed <- vapply(sample_ohlcv$close, function(p) update(sma_stream, p), numeric(1))
|
|
|
|
same_warmup <- all(is.na(streamed) == is.na(sma_values))
|
|
same_values <- all(streamed == sma_values, na.rm = TRUE)
|
|
c(batch_equals_streaming = same_warmup && same_values)
|
|
```
|
|
|
|
A typical streaming loop reacts to each value as it arrives:
|
|
|
|
```{r}
|
|
rsi <- Rsi(14)
|
|
overbought_days <- 0L
|
|
for (price in sample_ohlcv$close) {
|
|
v <- update(rsi, price) # NA during warmup
|
|
if (!is.na(v) && v > 70) overbought_days <- overbought_days + 1L
|
|
}
|
|
overbought_days
|
|
```
|
|
|
|
## Multi-output indicators
|
|
|
|
Indicators with several outputs return a *named* numeric vector (`NA` while
|
|
warming up). MACD is the classic example — line, signal, and histogram:
|
|
|
|
```{r}
|
|
macd <- MacdIndicator(12, 26, 9)
|
|
last_macd <- c(macd = NA, signal = NA, histogram = NA)
|
|
for (price in sample_ohlcv$close) last_macd <- update(macd, price)
|
|
last_macd
|
|
```
|
|
|
|
## Candle indicators
|
|
|
|
Indicators that need the whole bar take the OHLCV fields plus a timestamp:
|
|
|
|
```{r}
|
|
atr <- Atr(14)
|
|
last_atr <- NA_real_
|
|
for (i in seq_len(nrow(sample_ohlcv))) {
|
|
last_atr <- update(
|
|
atr,
|
|
sample_ohlcv$open[i], sample_ohlcv$high[i], sample_ohlcv$low[i],
|
|
sample_ohlcv$close[i], sample_ohlcv$volume[i], i - 1
|
|
)
|
|
}
|
|
last_atr
|
|
```
|
|
|
|
## Resetting state
|
|
|
|
`reset()` returns an indicator to its warmup state so the same object can be
|
|
reused on a fresh series:
|
|
|
|
```{r}
|
|
reset(sma)
|
|
update(sma, 100) # NaN — warming up again
|
|
```
|
|
|
|
## Next steps
|
|
|
|
- Full indicator catalogue, guides, and per-indicator reference:
|
|
<https://docs.wickra.org>.
|
|
- Every constructor (`Sma()`, `Rsi()`, `MacdIndicator()`, `Atr()`, …) is listed
|
|
in this package's help index.
|