Get started

MATH

TR Utility Library v6 ForkTR Utility Helpers v6 Fork is an open-source Pine Script v6 compatibility fork based on the publicly available Traders_Reality_Lib originally published by TradersReality. This publication is not the original Traders Reality library and is not presented as an official update from the original author. All original concept credit, authorship credit, and recognition for the underlying Traders Reality workflow belong to TradersReality and the original creator(s). Original source reference: Traders_Reality_Lib by TradersReality. Purpose of this publication: The purpose of this fork is to provide a Pine Script v6-compatible utility library structure for scripts that require reusable helper functions related to PVSRA-style candle classification, ADR/range calculations, session handling, labels, lines, pivots, vector candle zones, psychological levels, and market-session countdown utilities. This is a developer utility library. It is not a standalone trading indicator, not a signal system, and not a strategy. Main function groups: 1. PVSRA-style candle classification The library includes helper functions for classifying candles using volume and candle-spread behavior. These functions can return candle colors, alert flags, average volume, volume-spread values, and related classification data. 2. ADR and range helpers The library includes Average Daily Range helper functions and ADR-based high/low projection functions. These can support scripts that need daily range reference levels or range-based chart tools. 3. Session calculation utilities The library includes functions for parsing session strings, calculating session start and end timestamps, and handling sessions that cross midnight. 4. Session drawing helpers The library includes reusable drawing helpers for opening ranges, session highs/lows, midpoint lines, labels, and shaded session boxes. 5. Daily open and timeframe utilities The library includes helper functions for detecting new bars on selected resolutions, retrieving the daily open, and converting price movement into pips. 6. Label, line, and pivot helpers The library contains reusable functions for right-aligned labels, last-bar labels, dynamic horizontal lines, daily-open lines, and pivot-style chart levels. 7. Vector candle zone helpers The library includes helper functions for creating, updating, trimming, and cleaning vector candle zone boxes. 8. Psychological level helpers The library includes functions for calculating psychological high/low reference levels based on selected timing logic and market type. 9. Session countdown helpers The library includes functions for formatting milliseconds into readable time strings and calculating countdown text for market-session timing. How to use this library: This library is intended for Pine developers who want to import reusable helper functions into their own open-source or private scripts. Example use cases include: * PVSRA-style candle tools * ADR and daily range tools * Session high/low indicators * Opening range indicators * Pivot and level drawing tools * Vector candle zone tools * Market-session countdown panels This library does not generate buy or sell signals by itself. Any trading logic, alerts, entries, exits, or visual systems must be implemented in the script that imports this library. Originality and reuse clarification: This publication is primarily a compatibility fork and utility organization resource. It is not presented as a new original trading methodology. The underlying Traders Reality concepts and original library work are credited to the original creator(s). This fork is published open-source so users can inspect the code and verify the changes. Limitations: This library is a developer utility and should not be interpreted as financial advice. It does not provide buy or sell recommendations, does not execute trades, and does not guarantee any trading result. Users and developers are responsible for testing any script that imports this library and for verifying that all calculations, visual outputs, and trading decisions fit their own requirements.
Pine Script® library
by Inoffensive
AuditProtocolAuditProtocol Every indicator makes claims. "This signal has edge." "Price stays inside these bands." Almost none of them keep score. I built this library so keeping score becomes a three line habit: import it, register your claims, and let the tape settle them. Any indicator can wear a live, lookahead free audit of itself. What's inside Prequal is a prequential tracker for probability forecasts. You register a probability before the outcome and resolve it after the outcome is real, never the other way around. It tracks hit rate and the Brier score, the proper scoring rule for probability forecasts, plus Brier skill against a coin flip. Coverage is for bands and intervals. If your band claims 90% containment, this tracks what it actually delivered, target next to realized, recent and lifetime. Conformal learns the width multiplier that makes any band honest. Feed it your normalized residuals and ask it for k(). Your band, resized until the coverage is real. This is the split conformal quantile method, applied to whatever band you already draw. Barrier settles setups by first touch: target barrier or stop barrier, whichever the tape hits first. A nod to triple barrier labeling. Ties inside a single bar go to the stop, conservative by design. The Audit Score compresses it into one 0 to 100 number. Calibration earns up to 50 points. Demonstrated skill earns the other 50. So an honest indicator with zero edge sits near 50. That's the anchor: 50 is sea level, everything above it is earned, and anything well below it is miscalibrated. The Receipt is the standard panel. Claims on the left, reality on the right. How to use it import YOUR_HANDLE/AuditProtocol/1 as ap var pq = ap.newPrequal() var c90 = ap.newCoverage(90) if barstate.isconfirmed ap.resolve(pq, close > close ) // settle yesterday's call ap.resolveInterval(c90, close) // settle yesterday's band ap.predict(pq, myProbabilityUp) // register today's call ap.setInterval(c90, myLo, myHi) // register today's band ap.panel(pq, c90, na, position.top_right) ////////////////////////////////////////////////////////////////////// Library "AuditProtocol" newPrequal(emaAlpha)   Creates a prequential tracker.   Parameters:      emaAlpha (float) : EMA rate for the live (recent) readings. Default 0.02.   Returns: A fresh Prequal tracker. method predict(this, p)   Registers a probability forecast (P of the outcome being TRUE) for the NEXT resolution. Call AFTER resolve() in the same confirmed-bar block.   Namespace types: Prequal   Parameters:      this (Prequal)      p (float) method resolve(this, outcome)   Resolves the pending forecast against the realized outcome. Call once per confirmed bar BEFORE registering the next forecast.   Namespace types: Prequal   Parameters:      this (Prequal)      outcome (bool) method hitRate(this)   Lifetime hit rate in percent, or na before any resolution.   Namespace types: Prequal   Parameters:      this (Prequal) method skill(this)   Brier skill score vs the coin-flip baseline: 1 - Brier/0.25. 0 = no skill, 1 = perfect, negative = worse than guessing.   Namespace types: Prequal   Parameters:      this (Prequal) newCoverage(targetPct, emaAlpha)   Creates a coverage tracker for a band claiming `targetPct` percent containment.   Parameters:      targetPct (float)      emaAlpha (float) method setInterval(this, lo, hi)   Registers the band that should contain the NEXT observation.   Namespace types: Coverage   Parameters:      this (Coverage)      lo (float)      hi (float) method resolveInterval(this, x)   Resolves the pending band against the realized value.   Namespace types: Coverage   Parameters:      this (Coverage)      x (float) method realized(this)   Lifetime realized coverage in percent, or na before any resolution.   Namespace types: Coverage   Parameters:      this (Coverage) method covError(this)   Absolute calibration error in percentage points: |realized - target|. na before any resolution.   Namespace types: Coverage   Parameters:      this (Coverage) newConformal(targetPct, window, warmup)   Creates a conformal scaler. Feed it |realized error| / your band's unit width; ask it for k().   Parameters:      targetPct (float)      window (int)      warmup (int) method observe(this, normResid)   Records one realized normalized residual (e.g. |close - center| / sigma).   Namespace types: Conformal   Parameters:      this (Conformal)      normResid (float) method k(this, fallback)   The learned width multiplier: the target-quantile of observed residuals. Returns `fallback` until warm. Band = center ± k() * unitWidth delivers ~target coverage.   Namespace types: Conformal   Parameters:      this (Conformal)      fallback (float) newBarrier()   Creates a barrier tracker for first-touch setup outcomes. method arm(this, target, stop)   Arms a setup: which barrier must be touched first for a win (tgt) vs a loss (stp).   Namespace types: Barrier   Parameters:      this (Barrier)      target (float)      stop (float) method check(this, barHigh, barLow)   Checks the current bar. Returns +1 (target first), -1 (stop first), 0 (still open). If both are inside one bar, the stop wins: conservative by design.   Namespace types: Barrier   Parameters:      this (Barrier)      barHigh (float)      barLow (float) method winRate(this)   Lifetime win rate of resolved setups in percent, or na.   Namespace types: Barrier   Parameters:      this (Barrier) score(pq, cA, cB, minN)   The composite 0-100 audit score. Calibration earns up to 50 points (25 per coverage tracker; pass the same tracker twice if you only have one band). Skill earns up to 50 (Brier skill vs coin flip). Returns na until minN resolutions on the prequential tracker.   Parameters:      pq (Prequal)      cA (Coverage)      cB (Coverage)      minN (int) panel(pq, cA, cB, pos)   Renders the Receipt, the standard audit panel. Pass na for trackers you don't use.   Parameters:      pq (Prequal)      cA (Coverage)      cB (Coverage)      pos (string) Prequal   Fields:      pPend (series float)      accEma (series float)      brierEma (series float)      hits (series int)      n (series int)      emaA (series float) Coverage   Fields:      target (series float)      loPend (series float)      hiPend (series float)      covEma (series float)      hits (series int)      n (series int)      emaA (series float) Conformal   Fields:      resid (array)      target (series float)      win (series int)      warm (series int) Barrier   Fields:      tgt (series float)      stp (series float)      live (series bool)      wins (series int)      losses (series int)
Pine Script® library
by TheRealDrip2Rip
DivergenceLineLabelOutput_UtilitiesDivergenceLineLabelOutput_Utilities is a shared Pine v6 output library for scripts that already have their own oscillator, pivot, structure, or divergence logic but want a reusable divergence-rendering layer. It centralizes the parts of the workflow that tend to get rewritten across oscillator scripts: • HH / LH / HL / LL / EQ structure resolution • regular / hidden divergence state checks • same-structure context state checks • divergence and context color routing • standardized divergence/context label text • price-pane and oscillator-pane line helpers • price-pane and oscillator-pane label helpers • confirmed-object slot visibility helpers • live-preview line and label helpers • native-pane and price-pane pivot context box helpers On the example chart, the confirmed divergence lines, live preview lines, divergence labels, context labels, and pivot context boxes are all materially driven by this library. This library is intentionally focused on output and object management. It does not calculate RSI, MACD, VFI, volume flow, pressure, or any other oscillator. It does not confirm pivots or decide which pivots are valid. Calling scripts remain responsible for their own oscillator engine, pivot engine, comparison logic, colors, visibility modes, and signal interpretation. How to use Import the library near the top of your script in global scope, alongside any other imports, before you start calling its helpers. Typical placement: //@version=6 indicator(...) or strategy(...) import MYNAMEISBRANDON/DivergenceLineOutput_Utilities/1 as DivUtils Replace /1 with the latest published version if a newer version is available. This library expects the calling script to already know the price pivot, oscillator pivot, prior pivot reference, structure state, and output settings it wants to use. The library then handles the reusable line, label, live-preview, slot-budget, and box output layer. ➖Structure + Divergence State Helpers➖ These helpers convert pivot comparisons into structure tags and divergence/context states. divStructure(curr, prev, isHigh) Resolves HH, LH, HL, LL, or EQ from a current pivot and previous pivot. Parameters: curr (float): Current pivot value prev (float): Previous pivot value isHigh (bool): True for high-side comparison, false for low-side comparison Returns: Structure string divState(priceStruct, oscStruct) Resolves regular and hidden divergence states from price and oscillator structure tags. Returns: regularBear, regularBull, hiddenBear, hiddenBull, anyDivergence divContextState(priceStruct, oscStruct) Resolves same-structure context states from price and oscillator structure tags. Returns: highContinuation, highFade, lowContinuation, lowLift, anyContext divColor(priceStruct, oscStruct, regularBearColor, regularBullColor, hiddenBearColor, hiddenBullColor, highContinuationColor, lowContinuationColor, highFadeColor, lowLiftColor, fallbackColor) Routes a divergence or context pair to the matching caller-supplied color. Returns: Resolved color ➖Style + Label Helpers➖ These helpers keep divergence output styling consistent across scripts. divLineStyle(styleIn) Converts user-facing line-style text into Pine line-style enums. Parameters: styleIn (simple string): Solid, Dashed, or Dotted Returns: Pine line style divLabelSize(sizeIn) Converts user-facing label-size text into Pine label-size enums. Parameters: sizeIn (simple string): Tiny, Small, Normal, Large, or Huge Returns: Pine label size divContrastText(bg) Chooses black or white text based on background brightness. Parameters: bg (color): Background color Returns: Readable contrast text color divLabelText(divType, divSide, priceStruct, oscStruct, formatMode) Builds standardized divergence label text. Parameters: divType (simple string): Usually Reg or Hid divSide (simple string): Usually Bull or Bear priceStruct (string): Price structure tag oscStruct (string): Oscillator structure tag formatMode (simple string): Full, No Prefix, or Type Only Returns: Formatted label text ➖Confirmed Line Helpers➖ These helpers create and manage confirmed divergence or context lines. clearLines(lines, colors) Deletes all lines in an array and clears the matching color array. pushOscLine(lines, colors, show, active, x1, y1, x2, y2, lineColor, lineTransp, lineWidth, lineStyle, maxLines) Pushes a confirmed oscillator-pane line into line/color arrays. pushPriceLine(lines, colors, show, active, x1, y1, x2, y2, lineColor, lineTransp, lineWidth, lineStyle, maxLines) Pushes a confirmed price-pane line into line/color arrays using force_overlay=true. Note: Price helpers draw on the main chart from overlay=false oscillator scripts. Oscillator helpers draw in the script’s native pane. ➖Confirmed Label Helpers➖ These helpers create and manage confirmed divergence or context labels. clearLabels(labels, colors) Deletes all labels in an array and clears the matching color array. pushOscLabel(labels, colors, show, active, xIndex, y, labelText, styleText, lineColor, labelTextOnly, labelBgTransp, labelSize, maxLabels) Pushes a confirmed oscillator-pane label into label/color arrays. pushPriceLabel(labels, colors, show, active, xTime, labelText, ylocText, styleText, lineColor, labelTextOnly, labelBgTransp, labelSize, maxLabels) Pushes a confirmed price-pane label into label/color arrays using force_overlay=true. Note: For price-pane labels, xTime uses bar time and ylocText controls whether the label appears above or below the price bar. ➖Confirmed Slot Visibility Helpers➖ These helpers allow scripts to keep confirmed lines and labels stored while only showing the most recent visible slots. applyLineSlots(lines, colors, visibleSlots) Applies a visible slot budget to confirmed line arrays without deleting older objects. applyLabelSlots(labels, colors, visibleSlots, labelTextOnly, labelBgTransp) Applies a visible slot budget to confirmed label arrays without deleting older objects. Example: • Max Regular Lines = 1 - Live regular active = live regular only - No live regular = latest confirmed regular only • Max Regular Lines = 2 - Live regular active = live regular + latest confirmed regular - No live regular = latest two confirmed regular lines ➖Live Preview Line Helpers➖ These helpers create, update, or delete live divergence preview lines. syncLiveOscLine(ln, show, x1, y1, x2, y2, lineColor, lineWidth, lineStyle) Creates, updates, or deletes a live oscillator-pane line. syncLivePriceLine(ln, show, x1, y1, x2, y2, lineColor, lineWidth, lineStyle) Creates, updates, or deletes a live price-pane line using force_overlay=true. ➖Live Preview Label Helpers➖ These helpers create, update, or delete live divergence preview labels. syncLiveOscLabel(lbl, show, xIndex, y, labelText, styleText, lineColor, labelTextOnly, labelBgTransp, labelSize) Creates, updates, or deletes a live oscillator-pane label. syncLivePriceLabel(lbl, show, xTime, labelText, ylocText, styleText, lineColor, labelTextOnly, labelBgTransp, labelSize) Creates, updates, or deletes a live price-pane label using force_overlay=true. ➖Pivot Context Box Helpers➖ These helpers provide lightweight box utilities for scripts that want to frame confirmed pivot zones. divPivotBoxBounds(pivotValue, innerPct) Resolves a thin box around a pivot value using an inner percentage. Returns: top, bottom, ok syncNativeBox(bx, show, left, right, top, bottom, fillColor, borderColor, borderStyle, borderWidth) Creates, updates, or deletes a native-pane pivot context box. syncPriceBox(bx, show, left, right, top, bottom, fillColor, borderColor, borderStyle, borderWidth) Creates, updates, or deletes a price-pane pivot context box using force_overlay=true. ➖Divergence Model➖ Regular Bearish Divergence: Price makes HH while oscillator makes LH. Regular Bullish Divergence: Price makes LL while oscillator makes HL. Hidden Bearish Divergence: Price makes LH while oscillator makes HH. Hidden Bullish Divergence: Price makes HL while oscillator makes LL. ➖Structure Context Model➖ High-side continuation: Price makes HH while oscillator also makes HH. High-side fading: Price makes LH while oscillator also makes LH. Low-side continuation: Price makes LL while oscillator also makes LL. Low-side lifting: Price makes HL while oscillator also makes HL. Structure context is not divergence. It shows same-structure agreement between price and oscillator. ➖Important Notes➖ This library is an output utility layer only. It does not: • calculate an oscillator • confirm pivots • choose pivot anchors • decide whether a divergence is valid • decide trade direction • decide final signal logic Calling scripts remain responsible for: • oscillator calculation • pivot confirmation • price/oscillator comparison logic • visibility settings • color choices • max-line and max-label budgets • final visual interpretation For overlay=false oscillator scripts, Price + Oscillator / Price Only / Oscillator Only / Hide output modes work well. For overlay=true price-pane scripts, Price Only / Hide output modes usually make the most sense.
Pine Script® library
by MYNAMEISBRANDON
MarketPokerEnginev2 MarketPokerEnginev2 : Advanced Hand Evaluation Library Overview MarketPokerEngine is an institutional-grade, highly optimized library designed to evaluate poker hand combinatorics within Pine Script v6. It is specifically engineered to offload heavy logical processing and Abstract Syntax Tree (AST) node consumption from your main indicator script, ensuring rapid execution speeds even during live tick, multi-state simulations. Core Architecture The engine operates on a strict 5-card subset evaluation model. By feeding it exact 5-element arrays, the library mathematically guarantees zero false-positive evaluations (such as cross-suit straight flushes) without requiring excessive loop iterations. Key Features & Functions evaluate_hand(int ranks, int suits): The primary evaluation engine. It takes two 5-element arrays (ranks and suits) and returns a comprehensive tuple of 10 boolean/integer flags representing every possible hand hierarchy (from Royal Flush down to High Card), including Joker counts. get_card_vertical(int r, int s): A streamlined string formatting utility. It converts raw integer IDs into clean, vertical Unicode representations (e.g., "♠️ A") optimized for box.new() or label.new() UI rendering. Implementation Note This library assumes 0 is reserved for Jokers, 1-13 for standard ranks (A-K), and 1-4 for standard suits. It is highly recommended to pair this library with a master script that generates combinatoric 5-card subsets (e.g., 21 combinations for a 7-card Texas Hold'em board) to determine the absolute best hand score. 日本語公開文 MarketPokerEngine: 高度なポーカー役判定コアライブラリ 概要 MarketPokerEngine は、Pine Script v6においてポーカーの役（組み合わせ）評価を処理するための、高度に最適化された専用ライブラリです。メインのインジケータースクリプトから複雑な論理演算を切り離し、抽象構文木（AST）ノードの枯渇を回避することで、ライブティック更新時や多状態シミュレーションにおいても極めて軽量な実行速度を担保します。 コア・アーキテクチャ 本エンジンは、厳密な「5要素部分集合（Subset）」の評価モデルを採用しています。7枚などの複合状態から5要素の配列を抽出して本ライブラリに渡すことで、「スートが異なるストレートフラッシュ」などの誤判定を数学的かつ構造的に排除し、無駄な計算ループを必要としない洗練された判定を実現しています。 主要機能 evaluate_hand(int ranks, int suits): 判定エンジンの心臓部です。ランク（数字）とスート（マーク）の5要素配列を受け取り、ロイヤルフラッシュからワンペアまでの全役のフラグ、およびジョーカーの枚数を含む10要素のタプル（戻り値のまとまり）を高速で返します。 get_card_vertical(int r, int s): UI描画のための文字列フォーマット機能です。内部の整数IDを、box.new() や label.new() での表示に最適化されたクリーンな縦型のUnicodeテキスト（例: "♠️ A"）に即座に変換します。 実装上の注意事項 本ライブラリは、整数 0 をジョーカー、1-13 をランク（A-K）、1-4 をスートとして処理します。テキサスホールデムのような7枚のカードを扱うシステムに組み込む場合は、メインスクリプト側で7枚から5枚を選ぶ全21通りの組み合わせループを構築し、本ライブラリの評価を通過させることで、最もスコアの高い役を正確に抽出することが推奨されます。
Pine Script® library
by ALT_analyst
ExprLibExprLib is a library for parsing and evaluating string expressions. It allows scripts to expose configurable logic by letting users define custom conditions and calculations based on available data. █  KEY FEATURES • Rich expression support:     • Built-in constants (e.g., `10`, `2.5`, `5e-2`, `true`, `false`, `na`)     • Custom constants     • Variables     • Arithmetic operators: `+`, `-`, `*`, `/`, `%`     • Comparison operators: `>`, `<`, `>=`, `<=`, `==`, `!=`     • Logical operators: `AND`, `OR`, `NOT` (with aliases)     • Ternary operator: `condition ? if_true : if_false`     • Parentheses: `(`, `)`     • Built-in functions: `na()`, `nz()`, `max()`, `pow()`, `sqrt()`, `random()`, and more! • Graceful error handling during parsing and evaluation • Optimized for evaluation performance (RPN-based approach) █  NOTE Since the library description cannot be changed or removed after publication, some information here may be outdated. However, you can always get the latest version of the documentation at the bottom of the source code. █  QUICK START An example of an indicator that colors areas on a chart where the expression evaluates to `true`: //@version=6 indicator("Quick Start", overlay = true) import A1trdX/ExprLib/1 as ExprLib // --------------- // INPUTS // --------------- // Let the user customize the expression inputExpressionStr = input.text_area("trend_up AND (rsi < 50 OR close < open)", "Expression") // ------------------- // CALCULATION // ------------------- // Prepare some data to use in the expression. rsi = ta.rsi(close, 14) ema = ta.ema(close, 200) isTrendUp = close > ema isTrendDown = close < ema // Step 0: Prepare the parser and evaluator. var parser = ExprLib.createExpressionParser() var evaluator = ExprLib.createExpressionEvaluator() // Step 1: Parse the expression string. var expression = parser.parse(inputExpressionStr) // Step 2 (Recommended): Verify whether the expression was parsed without errors. if not parser.isParsed // You can define your own logic to handle errors runtime.error("Failed to parse expression: " + parser.error.message) // Step 3: Assign values to variables. Both numbers and booleans are supported. expression.setVariable("open", open) expression.setVariable("close", close) expression.setVariable("rsi", rsi) expression.setVariable("trend_up", isTrendUp) expression.setVariable("trend_down", isTrendDown) // Step 4: Evaluate the expression. bool result = evaluator.evaluateToBool(expression) // Step 4 (Alternative): If you expect a numeric result, use `evaluate()` instead. // float result = evaluator.evaluate(expression) // Step 5 (Recommended): Verify whether the expression was evaluated without errors. if not evaluator.isEvaluated // You can define your own logic to handle errors runtime.error("Failed to evaluate expression: " + evaluator.error.message) // ---------------- // GRAPHICS // ---------------- // Highlight bars where the expression returns `true` bgcolor(result ? color.new(color.green, 90) : na) █  EXPRESSION SYNTAX REFERENCE ❱❱  Components An expression can include: • Constants • Variables • Operators • Functions • Parentheses • Spaces, tabs, or newlines ❱❱  Data Types Constants and variables can have the following data types: • Numeric (`int`, `float`) • Boolean (`bool`) • Undefined (`na`) ❱❱  Identifiers Identifiers are names used to refer to named constants, variables, and functions. Identifier naming rules: • Must start with a letter (`a-z`, `A-Z`) or underscore (`_`). • May contain letters (`a-z`, `A-Z`), digits (`0-9`), and underscores (`_`). Identifiers cannot contain spaces or other characters. Identifiers are case-sensitive. ❱❱  Constants Numeric Constants Examples: +-----------+--------------+ | Constant | Plain Value | +-----------+--------------+ | 12 | 12.00 | | 0.05 | 0.05 | | .05 | 0.05 | | 5e-2 | 0.05 | | 5E-2 | 0.05 | | 1.2e4 | 12000.00 | +-----------+--------------+ Named Constants Available built-in named constants: +----------+-------------------------------------+-------------------------+ | Name | Description | Pine Script Equivalent | +----------+-------------------------------------+-------------------------+ | `true` | Boolean TRUE | `true` | | `false` | Boolean FALSE | `false` | | `na` | Undefined value | `na` | | `pi` | Pi (~3.14159) | `math.pi` | | `e` | Euler's number (~2.71828) | `math.e` | | `phi` | Golden ratio (~1.61803) | `math.phi` | | `rphi` | Golden ratio conjugate (~0.61803) | `math.rphi` | +----------+-------------------------------------+-------------------------+ It is possible to add custom constants. ❱❱  Variables It is possible to add variables, just like custom constants, except that variable values can be changed before each evaluation. ❱❱  Operators The following operators are supported: +--------------+-------------+-------------------------+-------------+------------------+-------------+ | Type | Operator | Name | Aliases | Example #1 | Example #2 | +--------------+-------------+-------------------------+-------------+------------------+-------------+ | Arithmetic | `+` | Add | | `a + b` | | | Arithmetic | `-` | Subtract | | `a - b` | | | Arithmetic | `*` | Multiply | | `a * b` | | | Arithmetic | `/` | Divide | | `a / b` | | | Arithmetic | `%` | Modulo | | `a % b` | | | Comparison | `>` | Greater than | | `a > b` | | | Comparison | `<` | Less than | | `a < b` | | | Comparison | `>=` | Greater than or equal | | `a >= b` | | | Comparison | `<=` | Less than or equal | | `a <= b` | | | Comparison | `==` | Equal | | `a == b` | | | Comparison | `!=` | Not equal | | `a != b` | | | Logical | `AND` | Logical AND | `&&`, `&` | `a AND b` | `a && b` | | Logical | `OR` | Logical OR | `||`, `|` | `a OR b` | `a || b` | | Logical | `NOT` | Logical NOT | `!` | `NOT x` | `!x` | | Conditional | `?:` | Ternary | | `cond ? x : y` | | | Unary | Unary `+` | Unary plus | | `+x` | | | Unary | Unary `-` | Unary minus | | `-x` | | +--------------+-------------+-------------------------+-------------+------------------+-------------+ Logical operator names are case-insensitive. Operator precedence: +------------+-----------------------------+ | Precedence | Operators | +------------+-----------------------------+ | 8 | Unary `-`, Unary `+`, `NOT` | | 7 | `*`, `/`, `%` | | 6 | `+`, `-` | | 5 | `>`, `<`, `>=`, `<=` | | 4 | `==`, `!=` | | 3 | `AND` | | 2 | `OR` | | 1 | `?:` | +------------+-----------------------------+ Operator associativity: • Unary `+`, Unary `-`, `NOT`, and ternary are right-associative • Other operators are left-associative ❱❱  Parentheses Parentheses are used to group sub-expressions and override the default operator precedence. Example: ((a + b) * c + 1) * d ❱❱  Functions Functions are called by an identifier followed immediately by parentheses: `func(arg1, arg2)`. Arguments are separated by commas. Each argument can be any valid expression, including another function call. Available built-in functions: +-------------------------------+----------+------------------------------------------------------------------------+ | Function | Args | Description | +-------------------------------+----------+------------------------------------------------------------------------+ | `na(x)` | 1 | Returns `true` when `x` is `na`, `false` otherwise. | | `nz(x, fallback)` | 2 | Returns `x` when it is not `na`, `fallback` otherwise. | | `max(x1, x2, ...)` | 2..999 | Returns the largest argument. | | `min(x1, x2, ...)` | 2..999 | Returns the smallest argument. | | `pow(base, exponent)` | 2 | Returns `base` raised to `exponent`. | | `sqrt(x)` | 1 | Returns the square root of `x`. | | `clamp(x, min, max)` | 3 | Restricts `x` to the ` ` range. | | `abs(x)` | 1 | Returns the absolute value of `x`. | | `ceil(x)` | 1 | Rounds `x` up to the nearest integer. | | `floor(x)` | 1 | Rounds `x` down to the nearest integer. | | `round(x)` | 1 | Rounds `x` to the nearest integer. | | `round_to_mintick(x)` | 1 | Rounds `x` to the symbol's minimum tick precision. | | `log(x)` | 1 | Returns the natural logarithm of `x`. | | `log10(x)` | 1 | Returns the base-10 logarithm of `x`. | | `sign(x)` | 1 | Returns the sign of `x`: `1`, `0`, or `-1`. | | `cos(x)` | 1 | Returns the cosine of `x` in radians. | | `sin(x)` | 1 | Returns the sine of `x` in radians. | | `tan(x)` | 1 | Returns the tangent of `x` in radians. | | `acos(x)` | 1 | Returns the arccosine of `x` in radians. | | `asin(x)` | 1 | Returns the arcsine of `x` in radians. | | `atan(x)` | 1 | Returns the arctangent of `x` in radians. | | `deg(x)` | 1 | Converts radians to degrees. | | `rad(x)` | 1 | Converts degrees to radians. | | `random(min, max, seed)` | 0..3 | Returns a random float. Bounds default to 0 and 1. Seed is optional. | | `random_int(min, max, seed)` | 2..3 | Returns a random integer. Seed is optional. | | `random_bool(seed)` | 0..1 | Returns a random boolean value. Seed is optional. | +-------------------------------+----------+------------------------------------------------------------------------+ The number of arguments can be either fixed or variable. For example, the `max(x1, x2, ...)` function supports 2 to 999 arguments, so the following calls to this function are valid: max(x1, x2) max(x1, x2, x3) max(x1, x2, x3, x4, x5) Other functions may have optional arguments. For example, the following calls to the `random(min, max, seed)` function are valid: random() // Random float from 0 to 1 random(0.5) // Random float from 0.5 to 1 random(0.5, 2) // Random float from 0.5 to 2 random(0.5, 2, 777) // Random float from 0.5 to 2 with a specific seed ❱❱  Whitespace Spaces, tabs, and line breaks are ignored between symbols. For example, an expression can be formatted across multiple lines: price > ema_slow AND ema_fast > ema_slow AND (bb_lo_up OR rsi_lo_up) █  PARSING ❱❱  Workflow Before evaluating an expression, it must be parsed. To do this: • Create a parser in advance using the `createExpressionParser()` function. • Call the `parse()` method, passing the expression string as an argument. Example: var parser = ExprLib.createExpressionParser() var expr1 = parser.parse("a + 2") var expr2 = parser.parse("a + b * c") ❱❱  Error Handling A user may enter an invalid expression. In this case, the parser will return `na` instead of a valid expression object. The parser stores the result of the last parse. You can use that result to retrieve the status and error information. Parser and error field structures: type ExpressionParser bool isParsed // `true` if the last parse completed successfully, `false` otherwise. ParseError error // Error from the last parse attempt. If the last parse was successful, then this field is `na`. type ParseError string message // Error message. int index // Character index where the parser detected the error. For example, suppose we want to display an error message on the chart if one of the expressions is invalid: //@version=6 indicator("Parser Error Handling") import A1trdX/ExprLib/1 as ExprLib inputExpr1 = input.text_area("a + 2", "Expression 1") inputExpr2 = input.text_area("a + b * c /", "Expression 2") displayErrorMessage(string errorMessage) => var table errorMessageTable = na if na(errorMessageTable) errorMessageTable := table.new(position.top_right, 1, 1) errorMessageTable.cell(0, 0, errorMessage, bgcolor = color.red, text_color = color.white, text_halign = text.align_left, text_formatting = text.format_bold) checkParsed(ExprLib.ExpressionParser parser, string prefix) => if not parser.isParsed displayErrorMessage(prefix + parser.error.message) var parser = ExprLib.createExpressionParser() var expr1 = parser.parse(inputExpr1) checkParsed(parser, "Failed to parse expression #1: ") var expr2 = parser.parse(inputExpr2) checkParsed(parser, "Failed to parse expression #2: ") A blank expression (e.g., "") is allowed and will evaluate to `na` (or `false` when returning a boolean value). ❱❱  Custom Constants You can add your own named constants during the parsing stage. To do this: • Create a constant pool in advance using the `createConstantPool()` function. • Set constants and their values using the `set()` method. • Pass the constant pool to the `parse()` method. Example: var constantPool = ExprLib.createConstantPool() if barstate.isfirst constantPool.set("one", 1) constantPool.set("two", 2) constantPool.set("three_p_one", 3.1) constantPool.set("yes", true) constantPool.set("no", false) var parser = ExprLib.createExpressionParser() var expr = parser.parse("one + two", constantPool) The `set()` method returns the same constant pool object, so you can chain calls together. This is more convenient and more elegant: var constantPool = ExprLib.createConstantPool() .set("one", 1) .set("two", 2) .set("three_p_one", 3.1) .set("yes", true) .set("no", false) // Note that the indentation is 7 spaces (not a multiple of 4) var parser = ExprLib.createExpressionParser() var expr = parser.parse("one + two", constantPool) You can also override built-in constants: var constantPool = ExprLib.createConstantPool() .set("true", false) .set("false", -1) .set("na", 0.0) █  EVALUATION ❱❱  Type Coercion An expression can consist of values of different data types. ExprLib does not have strict data type checking. Instead, all values are converted to `float` and then back if necessary. Converting `bool` to `float`: • `true` -> `1.0` • `false` -> `0.0` Converting `float` to `bool`: • `0.0` or `na` -> `false` • Any other value -> `true` Thus, expressions that incorrectly combine different data types are allowed. For example, `true + 2` will return `3.0`. Strict typing requires additional memory as well as additional computational resources during evaluation, which is a critical concern. Therefore, it was decided not to implement it. As in Pine Script, most operations with an `na` operand results in `na` or `false`, but logical operations first convert `na` to `false`, so their result follows boolean logic. For example: • `3 - na` returns `na` • `3 > na` returns `false` • `3 <= na` also returns `false` • `na AND true` returns `false` • `na OR true` returns `true` • `NOT na` returns `true` ❱❱  Workflow To evaluate an expression: • Create an evaluator in advance using the `createExpressionEvaluator()` function. • Set variables and their values in the expression using the `setVariable()` method. • Call the `evaluate()` or `evaluateToBool()` method, passing the expression as an argument. The `evaluate()` and `evaluateToBool()` methods differ in their return types. The former returns a `float` result, while the latter returns a `bool` result. The method to call depends on the expected result type. Example: // Parsed expressions: // - expr1 <= "(H - L) / 2 + L" // - expr2 <= "rsi_oversold AND close > open" // Initialize evaluator var evaluator = ExprLib.createExpressionEvaluator() // Set variables and evaluate the first expression expr1.setVariable("H", high) expr1.setVariable("L", low) float result1 = evaluator.evaluate(expr1) // Set variables and evaluate the second expression rsi = ta.rsi(close, 14) expr2.setVariable("open", open) expr2.setVariable("close", close) expr2.setVariable("rsi_oversold", rsi < 30) expr2.setVariable("rsi_overbought", rsi > 70) bool result2 = evaluator.evaluateToBool(expr2) ❱❱  Variables If an expression contains an identifier that is neither a function nor a constant, and this identifier has not been assigned a variable value, then this identifier is considered a constant with the value `na` (or `false` in boolean operations). The `setVariable()` method overrides existing constants (both built-in and custom). For example, by default, the identifier `e` is used as the constant Euler's number (~2.71828). However, you can make `e` your own variable: // Parsed expressions: // - expr <= "e + 1" expr.setVariable("e", 5) // Now `e` is equal to `5` instead of `2.7182818284590452` result = evaluator.evaluate(expr) // `6.0` The `setVariable()` method does not need to be called on each bar if the variable's value does not change. The expression always stores and uses the last value set. You can clear all previously set variables using the `clearVariables()` method. This can be useful if you have many variables and want to reset them all and set values for only a small subset. ❱❱  Error Handling In some cases (for example, when dividing by zero), evaluation results in an error. In this case, `evaluate()` will return `na`, and `evaluateToBool()` will return `false`. Like the parser, the evaluator stores the result of the last evaluation. Evaluator and error field structures: type ExpressionEvaluator bool isEvaluated // `true` if the last evaluation completed successfully, `false` otherwise. EvaluationError error // Error from the last evaluation attempt. If the last evaluation was successful, then this field is `na`. type EvaluationError EvaluationErrorReason reason // Error reason. string message // Error message. enum EvaluationErrorReason DIVISION_BY_ZERO Example: //@version=6 indicator("Evaluator Error Handling") import A1trdX/ExprLib/1 as ExprLib inputExpr1 = input.text_area("a + 2", "Expression 1") inputExpr2 = input.text_area("a + b / c", "Expression 2") displayErrorMessage(string errorMessage) => var table errorMessageTable = na if na(errorMessageTable) errorMessageTable := table.new(position.top_right, 1, 1) errorMessageTable.cell(0, 0, errorMessage, bgcolor = color.red, text_color = color.white, text_halign = text.align_left, text_formatting = text.format_bold) // Parse checkParsed(ExprLib.ExpressionParser parser, string prefix) => if not parser.isParsed displayErrorMessage(prefix + parser.error.message) var parser = ExprLib.createExpressionParser() var expr1 = parser.parse(inputExpr1) checkParsed(parser, "Failed to parse expression #1: ") var expr2 = parser.parse(inputExpr2) checkParsed(parser, "Failed to parse expression #2: ") // Evaluate checkEvaluated(ExprLib.ExpressionEvaluator evaluator, string prefix) => if not evaluator.isEvaluated displayErrorMessage(prefix + evaluator.error.message) var evaluator = ExprLib.createExpressionEvaluator() expr1.setVariable("a", open) expr1.setVariable("b", close) expr1.setVariable("c", 0) result1 = evaluator.evaluate(expr1) checkEvaluated(evaluator, "Failed to evaluate expression #1: ") expr2.setVariable("a", open) expr2.setVariable("b", close) expr2.setVariable("c", 0) result2 = evaluator.evaluate(expr2) checkEvaluated(evaluator, "Failed to evaluate expression #2: ") Currently, the only possible cause of this error is division by zero. You can disable this error and have the evaluator interpret the result of division by zero as `na`. To do this, disable the corresponding flag in the evaluator: evaluator.setFailOnDivisionByZero(false) Thus, an expression like `na(5 / 0) ? 1 : 2` will return `1` instead of an error. █  BEST PRACTICES • Reuse `ExpressionParser` and `ExpressionEvaluator` objects whenever possible. • Parse expressions only once, and evaluate them as needed. Parsing is slow. Evaluation is fast. • If certain variable values change rarely, call `setVariable()` only when necessary. • Try to avoid excessive numbers of variables whose values ​​change frequently. This can impact performance even if they're not used in the expression. █  API REFERENCE ❱❱  Expression Parser ExpressionParser   Expression parser.   Fields:      isParsed (series bool) : `true` if the last parse completed successfully, `false` otherwise.      error (ParseError) : Error from the last parse attempt. If the last parse was successful, then this field is `na`. createExpressionParser()   Creates an expression parser.   Returns: Expression parser. method parse(parser, exprStr, constantPool)   Parses an expression.   Namespace types: ExpressionParser   Parameters:      parser (ExpressionParser) : Expression parser.      exprStr (string) : Expression string. Can be empty, blank, or 'na'. That way expression is valid and will return `na` on evaluation.      constantPool (ExpressionConstantPool) : (Optional) Named constants.   Returns: Parsed expression. If an error occurs during parsing, then the returned expression will be `na`. You can check validity and error details accessing parser's `isParsed` and `error` fields. ❱❱  Expression Expression   Parsed expression. method setVariable(expr, identifier, value)   Assigns a numeric value to a variable.   Namespace types: Expression   Parameters:      expr (Expression) : Expression.      identifier (string) : Variable name.      value (float) : Value.   Returns: This expression. method setVariable(expr, identifier, value)   Assigns a boolean value to a variable.   Namespace types: Expression   Parameters:      expr (Expression) : Expression.      identifier (string) : Variable name.      value (bool) : Value.   Returns: This expression. method clearVariables(expr)   Clears all variable values.   Namespace types: Expression   Parameters:      expr (Expression) : Expression.   Returns: This expression. ❱❱  Constant Pool ExpressionConstantPool   Expression constant pool. createConstantPool()   Creates an expression constant pool.   Returns: Expression constant pool. method set(pool, identifier, value)   Assigns a numeric constant value.   Namespace types: ExpressionConstantPool   Parameters:      pool (ExpressionConstantPool) : Expression constant pool.      identifier (string) : Constant name.      value (float) : Value.   Returns: This expression constant pool. method set(pool, identifier, value)   Assigns a boolean constant value.   Namespace types: ExpressionConstantPool   Parameters:      pool (ExpressionConstantPool) : Expression constant pool.      identifier (string) : Constant name.      value (bool) : Value.   Returns: This expression constant pool. method clear(pool)   Clears all constants.   Namespace types: ExpressionConstantPool   Parameters:      pool (ExpressionConstantPool) : Expression constant pool.   Returns: This expression constant pool. ❱❱  Expression Evaluator ExpressionEvaluator   Expression evaluator.   Fields:      isEvaluated (series bool) : `true` if the last evaluation completed successfully, `false` otherwise.      error (EvaluationError) : Error from the last evaluation attempt. If the last evaluation was successful, then this field is `na`.      result (series float) : Numeric result of the last evaluation.      boolResult (series bool) : Boolean result of the last evaluation. createExpressionEvaluator()   Creates an expression evaluator.   Returns: Expression evaluator. method evaluate(evaluator, expr)   Evaluates an expression.   Namespace types: ExpressionEvaluator   Parameters:      evaluator (ExpressionEvaluator) : Expression evaluator.      expr (Expression) : Expression to evaluate.   Returns: Numeric evaluation result. For boolean-result expressions `1.0` means `true` and `0.0` means `false`. Returns `na` if expression is empty. method evaluateToBool(evaluator, expr)   Evaluates an expression.   Namespace types: ExpressionEvaluator   Parameters:      evaluator (ExpressionEvaluator) : Expression evaluator.      expr (Expression) : Expression to evaluate.   Returns: Boolean evaluation result. Returns `false` if expression is empty. method setFailOnDivisionByZero(evaluator, value)   Sets whether division or modulo by zero should fail evaluation.   Namespace types: ExpressionEvaluator   Parameters:      evaluator (ExpressionEvaluator) : Expression evaluator.      value (bool) : If `true`, division or modulo by zero fails evaluation. If `false`, it produces `na`.   Returns: This expression evaluator. ❱❱  Errors ParseError   Error that occurred during expression parsing.   Fields:      message (series string) : Error message.      index (series int) : Character index where the parser detected the error. EvaluationError   Error that occurred during expression evaluation.   Fields:      reason (series EvaluationErrorReason) : Error reason.      message (series string) : Error message.
Pine Script® library
by A1trdX
4
CyberMarketLib# CyberMarketLib v2 CyberMarketLib provides market structure analysis combining swing point detection, Break of Structure (BoS) / Change of Character (CHoCH) identification, session classification, and volatility regime tracking. ## What it does Delivers four core capabilities: swing point tracking (configurable left/right bar lookback), market structure events (BoS/CHoCH for trend continuation vs reversal), session classification (Asia/London/NY via UTC bucketing), and volatility regimes (LOW/NORMAL/HIGH/EXTREME via ATR percentiles). Build context-aware indicators that adapt to market conditions. Outputs FractalData structs, StructureEvent/Session/VolRegime enums. All pivots use confirmed swing points (requires right_len bars validation), preventing repainting. ## How it works Swing detection: `high < high > high `. Stores pivots in SwingHistory circular buffers with automatic capacity management. BoS/CHoCH follows Smart Money Concepts: - BOS_UP/DOWN: Price breaks recent swing (trend continuation) - CHOCH_UP/DOWN: Pivot break after opposite swing (reversal) Sessions via UTC hours: ASIA (00-08), LONDON (08-13), NY_OVERLAP (13-17), NY_AFTERNOON (17-21), OFF_HOURS (21-24). Volatility regimes via ATR percentiles (100-bar window): LOW (<25th), NORMAL (25-75th), HIGH (75-90th), EXTREME (>90th). ## Why this is original Only TradingView library combining BoS/CHoCH, sessions, and volatility regimes. Existing SMC indicators lack reusable libraries. Unique features: - Confirmed pivots only (no repainting) - CHoCH sequence analysis (pivot pattern detection) - UTC-based sessions (exchange-agnostic, DST-safe) - Percentile volatility (asset-adaptive) - Circular buffer (O(1) operations, memory-efficient) Designed for composability: sessions → conditional logic, regimes → stop multipliers, BoS/CHoCH → entry/exit signals. ## How to use it ```pine //@version=6 indicator("CyberMarketLib Demo", overlay=true) import cybermediaboy/CyberMarketLib/2 as ML // Swing points + BoS/CHoCH detection var swing_hist = ML.f_swing_history_new(max_n=20) var fractal = ML.f_detect_pivot(left_len=5, right_len=5) if not na(fractal) swing_hist.push(fractal) var event = ML.f_detect_structure_event(swing_hist, close) // event: BOS_UP, BOS_DOWN, CHOCH_UP, CHOCH_DOWN, NONE // Session + volatility regime session = ML.f_current_session() // ASIA, LONDON, NY_OVERLAP, etc. vol_regime = ML.f_volatility_regime(14, 100) // LOW, NORMAL, HIGH, EXTREME // Adaptive stops atr = ta.atr(14) stop_mult = vol_regime == ML.VolRegime.EXTREME ? 3.0 : 1.5 plot(close - atr * stop_mult, "Stop", color.red) ``` ## Key functions - `f_detect_pivot()` - Confirmed swing points (no repainting) - `f_detect_structure_event()` - BoS/CHoCH detection - `f_current_session()` - UTC-based session classification - `f_volatility_regime()` - ATR percentile regimes - `f_htf_for()` - Higher timeframe string generation - SwingHistory UDT - Circular buffer for pivot storage ## Limitations - Swing detection: `right_len` bars confirmation delay (lag vs repainting indicators) - BoS/CHoCH: Assumes trending markets (false signals in choppy ranges) - Sessions: UTC-only (no exchange-native or DST-aware sessions) - Volatility: ATR-based only (may lag on sudden spikes) - SwingHistory: Fixed capacity at initialization - CHoCH: Requires manual state tracking to avoid duplicate signals
Pine Script® library
by cybermediaboy
CyberSignalLib# CyberSignalLib v2 CyberSignalLib provides advanced signal processing tools for Pine Script traders, combining Kalman filtering, entropy-based changepoint detection, and market microstructure analysis in a single dependency. ## What it does SignalLib delivers three core capabilities: N-dimensional Kalman filters for multi-feature state estimation (price, velocity, z-scores), entropy-based changepoint detectors for regime shifts (NIS, CUSUM, BOCPD), and microstructure metrics for order flow analysis (delta, aggression, volume imbalance). Traders use these tools to build adaptive indicators that respond to market regime changes—for example, a Kalman filter tracking price and volatility simultaneously, with automatic parameter adjustment when a changepoint detector signals a structural break. The library outputs filtered state estimates (smoothed price, velocity, Mahalanobis distance), changepoint probabilities (0-1 scores indicating regime shift likelihood), and microstructure features (signed delta, aggression ratio, volume-weighted imbalance). All functions support real-time bar-by-bar updates with minimal memory overhead via circular buffers and packed covariance matrices. ## How it works The Kalman filter implementation uses an N-dimensional state vector with upper-triangular packed covariance storage, reducing memory from O(N²) to O(N(N+1)/2). The filter supports diagonal process noise (Q) and scalar measurement noise (R), both adaptive via innovation tracking. The update step follows the standard predict-correct cycle: predict state using transition matrix F, compute innovation (measurement - prediction), update state and covariance via Kalman gain. Normalized Innovation Squared (NIS) is computed as `innovation² / (H·P·H' + R)` to detect outliers and trigger adaptive R adjustments. Changepoint detection uses three methods: 1. **NIS-based**: Flags regime change when NIS exceeds a threshold (e.g., 9.0 for 99% confidence under chi-squared distribution) 2. **CUSUM**: Cumulative sum of log-likelihood ratios, resets when crossing upper/lower bounds 3. **BOCPD (Bayesian Online Changepoint Detection)**: Maintains run-length distribution, computes changepoint probability via hazard function Entropy calculations support four modes: binary (up/down), ternary (up/flat/down), combo (binary + ternary), and composite (weighted average). Shannon entropy is computed as `-Σ p_i log₂(p_i)` where p_i are empirical frequencies over a rolling window. High entropy (near maximum) indicates unpredictable price action; low entropy signals trending or mean-reverting regimes. Microstructure metrics derive from tick-level order flow: - **Delta**: Signed volume (buy volume - sell volume) - **Aggression**: Ratio of aggressive orders (market orders) to total volume - **Imbalance**: `(buy_vol - sell_vol) / (buy_vol + sell_vol)`, range These metrics are computed via request.security calls to lower timeframes (1-minute typical) and aggregated to the chart timeframe. ## Why this is original CyberSignalLib is the only TradingView library combining Kalman filtering, changepoint detection, and microstructure analysis in a unified interface. Existing Kalman filter libraries are limited to 1D or 2D state spaces and lack adaptive noise parameters. No public library offers BOCPD or CUSUM changepoint detection. Microstructure metrics typically require manual request.security calls with hardcoded timeframes—SignalLib abstracts this into reusable functions with configurable lookback windows. Unique features: - **Tri-packed covariance**: Memory-efficient N-dimensional Kalman filter (supports up to 16 features on TradingView's memory limits) - **Adaptive Q/R**: Automatic process/measurement noise tuning based on innovation statistics, eliminating manual parameter tweaking - **Trajectory store**: Circular buffer for Kalman state history, enabling lookback analysis (e.g., "was price above Kalman estimate 5 bars ago?") - **Mahalanobis distance**: 3D analytic formula with shrinkage regularization for outlier detection in multi-feature space - **Unified changepoint API**: Single enum-based interface for NIS/CUSUM/BOCPD, simplifying regime-switching indicator logic No other Pine library provides this combination of statistical rigor (Kalman optimality, Bayesian changepoint inference) and practical usability (adaptive parameters, memory-efficient storage, microstructure integration). ## How to use it ```pine //@version=6 indicator("CyberSignalLib Demo", overlay=true) import cybermediaboy/CyberSignalLib/2 as SL import cybermediaboy/NumLib/5 as N // Example 1: 2D Kalman filter (price + velocity) var kal = SL.f_kalman_init(nfeat=2, P0=1.0, Q0=0.01, R0=0.1, innov_window=20) if not na(close) kal.update_scalar(0, close, 1.0) // Measure price (feature 0) kal.predict(SL.f_transition_identity(2)) kal.adapt_Q(Q_min=0.001, Q_max=0.1, gain=1.5) kal.adapt_R(high_thresh=9.0, low_thresh=1.0, R_step=0.1) float price_est = array.get(kal.x, 0) float velocity_est = array.get(kal.x, 1) plot(price_est, "Kalman Price", color.blue, linewidth=2) plot(close + velocity_est * 10, "Velocity Offset", color.orange) // Example 2: NIS-based changepoint detection bool changepoint = kal.lastnis > 9.0 // 99% confidence threshold bgcolor(changepoint ? color.new(color.red, 80) : na, title="Regime Change") // Example 3: Entropy calculation (ternary mode) var ent_buf = array.new(50, 0) int direction = close > close ? 1 : (close < close ? -1 : 0) array.push(ent_buf, direction) if array.size(ent_buf) > 50 array.shift(ent_buf) float entropy = SL.f_entropy_ternary(ent_buf) plot(entropy, "Ternary Entropy", color.green) // Example 4: Mahalanobis distance (3D outlier detection) var z_vec = array.from(close, volume, ta.rsi(close, 14)) var mu_vec = array.from(ta.sma(close, 50), ta.sma(volume, 50), 50.0) var cov_tri = array.from(1.0, 0.0, 0.0, 1.0, 0.0, 1.0) // Identity covariance float maha = SL.f_mahalanobis_3d(z_vec, mu_vec, cov_tri, shrinkage=0.1) plot(maha, "Mahalanobis Distance", color.purple) ``` ## Inputs, outputs, expected behavior **Kalman filter** (`f_kalman_init`, `update_scalar`, `predict`): - **Inputs**: `nfeat` (int, 1-16 typical), `P0/Q0/R0` (float, initial noise estimates), `measurement` (float), `H` (float, observation matrix row) - **Outputs**: Updated state vector `x` (array), NIS value `lastnis` (float, unbounded), ready flag `ready` (bool) - **Edge cases**: Returns unmodified state if measurement is NA, requires ≥20 bars for adaptive Q/R to stabilize **Changepoint detection** (`f_changepoint_nis`, `f_changepoint_cusum`, `f_changepoint_bocpd`): - **Inputs**: `nis` (float, typically from Kalman filter), `threshold` (float, 9.0 for 99% confidence), `hazard` (float, 0.01-0.1 for BOCPD) - **Outputs**: Changepoint probability (float, ) or binary flag (bool) - **Edge cases**: CUSUM resets on boundary crossing, BOCPD requires ≥10 bars for stable run-length distribution **Entropy functions** (`f_entropy_binary`, `f_entropy_ternary`, `f_entropy_combo`): - **Inputs**: `data` (array, direction codes: -1/0/1), `window` (int, 20-100 typical) - **Outputs**: Shannon entropy (float, ), max entropy = 1.0 for binary, 1.585 for ternary - **Edge cases**: Returns 0.0 if all elements identical, handles empty arrays gracefully **Microstructure metrics** (`f_get_micro_state`, `f_get_scientific_delta`, `f_get_aggregated_volume`): - **Inputs**: `timeframe` (string, "1" for 1-minute), `lookback` (int, bars to aggregate) - **Outputs**: Delta (float, signed volume), aggression (float, ), imbalance (float, ) - **Edge cases**: Returns NA if lower timeframe data unavailable, requires Premium/Pro account for intraday request.security **Trajectory store** (`f_trajectory_new`, `push`, `read`): - **Inputs**: `snap_dim` (int, state vector length), `capacity` (int, max snapshots), `offset` (int, 0=latest) - **Outputs**: Snapshot array (array, length `snap_dim`) - **Edge cases**: Returns NA-filled array if offset exceeds filled count, circular overwrite after capacity reached ## Limitations 1. **Kalman filter assumes linear dynamics**: The transition matrix F is diagonal (no cross-feature coupling). For non-linear systems (e.g., price-volatility feedback loops), the filter may diverge. Extended Kalman Filter (EKF) or Unscented Kalman Filter (UKF) variants are not implemented. 2. **Changepoint detection requires tuning**: NIS threshold (default 9.0) assumes Gaussian measurement noise. In heavy-tailed distributions (crypto, low-liquidity assets), false positives increase. CUSUM and BOCPD require manual hazard/boundary tuning per asset and timeframe. 3. **Microstructure functions require lower timeframe data**: `f_get_micro_state` and related functions call request.security with `timeframe="1"` (1-minute). This fails on daily/weekly charts or for symbols without intraday data. Users must handle NA returns or pre-filter symbols. 4. **Memory overhead for high-dimensional Kalman**: An N=16 feature Kalman filter requires 136 floats for packed covariance (16×17/2) plus state vector. On TradingView's 50,000 float limit per script, this restricts other arrays. Reduce `nfeat` or use sparse feature selection. 5. **Entropy calculations assume discrete states**: Binary/ternary entropy requires pre-discretized input (direction codes -1/0/1). Continuous price data must be manually binned. The library does not auto-discretize or suggest bin counts. 6. **No multi-step prediction**: The Kalman filter supports one-step-ahead prediction only. For multi-bar forecasts (e.g., "predict price 5 bars ahead"), users must manually iterate the predict step, which compounds uncertainty without re-measurement. 7. **Adaptive Q/R convergence time**: Adaptive noise parameters require 20-50 bars to stabilize after initialization or regime change. During this period, filter estimates may be suboptimal. Consider using fixed Q/R for the first 50 bars, then enabling adaptation.
Pine Script® library
by cybermediaboy
CyberLearningLib# CyberLearningLib v4 CyberLearningLib provides online learning primitives for Pine Script traders building adaptive machine learning indicators, including circular training buffers, feature scaling, stochastic gradient descent (SGD), and distance metrics for k-nearest neighbors (kNN) algorithms. ## What it does LearningLib delivers four core components: circular training buffers for memory-efficient sample storage (O(1) push/read), feature scalers with exponentially weighted moving average (EWMA) normalization, SGD optimizers with gradient clipping and multiple loss functions (squared, hinge, logistic, Huber), and distance metrics for kNN classification (Euclidean, Manhattan, Cosine, Mahalanobis, Chebyshev). Traders use these tools to build indicators that learn from historical price patterns—for example, a kNN classifier predicting next-bar direction based on the 10 most similar historical setups, with features auto-scaled via EWMA to handle non-stationary markets. The library outputs trained model weights (SGD state vector), scaled feature vectors (normalized to or z-scores), distance matrices for kNN queries, and sample metadata (timestamp, sample type, trade direction). All data structures use circular buffers to maintain constant memory usage regardless of training duration, critical for long-running indicators on TradingView's 50,000 float limit. ## How it works The training buffer uses a circular array with write-head indexing: when capacity is reached, new samples overwrite the oldest. Each sample stores a feature vector (array), label (float, regression target or {-1,+1} for classification), weight (float, for importance sampling), timestamp (bar_index), sample type (enum: LIVE/SIMULATED/SHADOW/BACKFILL), trade direction (LONG/SHORT/FLAT), and two free metadata integers for custom categorization. The `read(offset)` method retrieves samples in reverse chronological order (0 = most recent), while `read_chrono(pos)` accesses samples in insertion order (0 = oldest). Feature scaling supports three methods: 1. **EWMA normalization**: Maintains running mean/variance via `μ_t = (1-α)μ_{t-1} + αx_t`, scales features to z-scores 2. **Min-max scaling**: Tracks rolling min/max over window, normalizes to 3. **Percentile-based**: Uses IQR (interquartile range) for outlier-resistant scaling SGD updates follow the standard formula `w_t = w_{t-1} - η∇L(w)` where η is learning rate and ∇L is loss gradient. Supported loss functions: - **Squared**: `0.5(y - ŷ)²`, gradient = `-(y - ŷ)` - **Hinge**: `max(0, 1 - y·ŷ)` for y ∈ {-1,+1}, gradient = `-y` if margin violated - **Logistic**: `log(1 + exp(-y·ŷ))`, gradient = `-y / (1 + exp(y·ŷ))` - **Huber**: Squared loss for small errors (|err| ≤ δ), linear for large errors (robust to outliers) Gradient clipping prevents exploding gradients: `g_clipped = g / max(1, ||g|| / threshold)`. The library also provides gated SGD updates that skip parameter changes when innovation (measurement error) is below a threshold, reducing overfitting to noise. Distance metrics compute similarity between feature vectors for kNN: - **Euclidean**: `√Σ(x_i - y_i)²` - **Manhattan**: `Σ|x_i - y_i|` - **Cosine**: `1 - (x·y) / (||x|| ||y||)` (angle-based, scale-invariant) - **Mahalanobis**: `√((x-y)'Σ⁻¹(x-y))` where Σ is covariance (accounts for feature correlations) - **Chebyshev**: `max_i |x_i - y_i|` (L∞ norm) ## Why this is original CyberLearningLib is the only TradingView library providing a complete online learning toolkit with memory-efficient circular buffers and production-ready SGD implementations. Existing ML libraries either use linear arrays (memory grows unbounded), lack feature scaling (assume stationary data), or implement only Euclidean distance (ignoring feature correlations). Unique features: - **Circular training buffers**: O(1) push/read with constant memory, critical for indicators running 24/7 on crypto markets. No other Pine library offers circular indexing with chronological/reverse-chronological access. - **Sample type tracking**: LIVE/SIMULATED/SHADOW/BACKFILL enum enables mixed training sets (e.g., "train on LIVE samples only, use SIMULATED for validation"). Essential for walk-forward optimization and out-of-sample testing. - **Gated SGD updates**: Skip weight updates when innovation < threshold, preventing overfitting during low-volatility regimes. Based on Kalman filter innovation gating, not found in standard ML libraries. - **Huber loss with configurable δ**: Robust regression loss that transitions from squared (δ-sensitive) to linear (outlier-resistant). Most Pine implementations use fixed δ=1.0; this library exposes δ as parameter. - **Mahalanobis distance with shrinkage**: Accounts for feature correlations via inverse covariance, with Ledoit-Wolf shrinkage to prevent singular matrix errors. No other Pine library implements this (most use Euclidean only). The library is designed for composition: training buffers feed into feature scalers, scaled features feed into SGD or kNN, distances feed into weighted voting. This modular design enables complex workflows (e.g., "scale features via EWMA, train linear SVM via hinge loss, classify new samples via kNN with Mahalanobis distance") without code duplication. ## How to use it ```pine //@version=6 indicator("CyberLearningLib Demo", overlay=false) import cybermediaboy/CyberLearningLib/4 as LL import cybermediaboy/NumLib/5 as N // Example 1: Circular training buffer var tb = LL.f_buffer_new(capacity=100, nfeat=3) if not na(close) var features = array.from(ta.rsi(close, 14), ta.atr(14), volume) float label = close < close ? 1.0 : -1.0 // Next-bar direction var sample = LL.f_sample_new(features, label, LL.SampleType.LIVE, LL.TradeDirection.LONG, meta_a=0, meta_b=0) tb.push(sample) // Read most recent sample var recent = tb.read(0) if not na(recent) plot(recent.label, "Last Label", color.blue) // Example 2: Feature scaling (EWMA) var scaler = LL.f_scaler_new(nfeat=3, alpha=0.1) if not na(close) var raw_features = array.from(close, volume, ta.rsi(close, 14)) var scaled = scaler.scale(raw_features) plot(array.get(scaled, 0), "Scaled Close", color.orange) // Example 3: SGD training (hinge loss for binary classification) var sgd = LL.f_sgd_new(nfeat=3, learning_rate=0.01, loss=LL.LossKind.HINGE) if tb.filled >= 10 var train_sample = tb.read(0) if not na(train_sample) sgd.update(train_sample.features, train_sample.label, clip_threshold=5.0) float prediction = sgd.predict(train_sample.features) plot(prediction, "SGD Prediction", color.green) // Example 4: kNN distance calculation if tb.filled >= 2 var s1 = tb.read(0) var s2 = tb.read(1) if not na(s1) and not na(s2) float dist_euclidean = LL.f_distance(s1.features, s2.features, LL.DistanceKind.EUCLIDEAN) float dist_cosine = LL.f_distance(s1.features, s2.features, LL.DistanceKind.COSINE) plot(dist_euclidean, "Euclidean Dist", color.red) plot(dist_cosine, "Cosine Dist", color.purple) ``` ## Inputs, outputs, expected behavior **Training buffer** (`f_buffer_new`, `push`, `read`, `read_chrono`): - **Inputs**: `capacity` (int, 50-1000 typical), `nfeat` (int, feature dimension), `offset/pos` (int, sample index) - **Outputs**: TBSample (struct with features, label, metadata) or na if index out of bounds - **Edge cases**: Returns na for invalid offsets, overwrites oldest sample at capacity, `filled` count saturates at capacity **Feature scaler** (`f_scaler_new`, `scale`, `update`): - **Inputs**: `nfeat` (int), `alpha` (float, EWMA decay 0.01-0.3 typical), `features` (array) - **Outputs**: Scaled feature vector (array, z-scores or normalized) - **Edge cases**: Returns unscaled features on first call (no history), handles NA elements via nz() **SGD optimizer** (`f_sgd_new`, `update`, `predict`): - **Inputs**: `nfeat` (int), `learning_rate` (float, 0.001-0.1 typical), `loss` (enum), `features/label` (float), `clip_threshold` (float, 1.0-10.0) - **Outputs**: Prediction (float, unbounded for regression, {-1,+1} for classification after sign()), updated weights (internal state) - **Edge cases**: Gradient clipping prevents exploding weights, returns 0.0 prediction before first update **Distance metrics** (`f_distance`, `f_distance_mahalanobis`): - **Inputs**: `x/y` (array, same length), `kind` (enum), `cov_inv` (array, tri-packed inverse covariance for Mahalanobis) - **Outputs**: Distance (float, ≥0 for Euclidean/Manhattan/Chebyshev, for Cosine, unbounded for Mahalanobis) - **Edge cases**: Returns NA if array lengths mismatch, Mahalanobis requires non-singular covariance (use shrinkage if needed) **Sample filtering** (`by_type`, `by_direction`): - **Inputs**: `tb` (TrainingBuffer), `st` (SampleType enum), `dir` (TradeDirection enum) - **Outputs**: Filtered array (subset of buffer matching criteria) - **Edge cases**: Returns empty array if no matches, preserves chronological order ## Limitations 1. **Fixed feature dimension**: Training buffers and scalers require `nfeat` declared at initialization. Changing feature count mid-stream requires creating a new buffer/scaler. Dynamic feature sets (e.g., "use 3 features on stocks, 5 on crypto") are not supported. 2. **No automatic hyperparameter tuning**: Learning rate, loss function, gradient clip threshold, and EWMA alpha must be manually specified. The library does not provide grid search, cross-validation, or adaptive learning rate schedules (e.g., Adam, RMSprop). Users must tune via backtesting. 3. **SGD assumes i.i.d. samples**: Stochastic gradient descent converges optimally when samples are independent and identically distributed. Financial time series violate this (autocorrelation, regime changes). For non-stationary data, consider using gated updates or periodically resetting weights. 4. **Mahalanobis distance requires covariance matrix**: Computing inverse covariance for N features requires O(N³) operations and N(N+1)/2 storage. For high-dimensional features (N > 10), this becomes computationally expensive. Use Euclidean or Cosine distance for N > 10, or apply PCA to reduce dimensionality first. 5. **No mini-batch SGD**: The library implements single-sample (online) SGD only. Mini-batch updates (averaging gradients over K samples) are not supported. For noisy gradients, increase EWMA alpha in feature scaling or use Huber loss instead of squared loss. 6. **Circular buffer overwrites without warning**: When capacity is reached, `push()` silently overwrites the oldest sample. If you need to preserve all historical data, implement external archiving (e.g., export to CSV via log.info) before buffer fills. 7. **Distance metrics do not handle missing features**: If a feature vector contains NA, distance functions return NA. The library does not impute missing values (mean, median, forward-fill). Users must handle NA via nz() or filtering before calling distance functions.
Pine Script® library
by cybermediaboy
CyberNumLib# CyberNumLib v5 CyberNumLib provides stateless numerical primitives for Pine Script traders who need advanced statistical calculations, robust normalization methods, and mathematical functions not available in TradingView's native library. ## What it does NumLib delivers 56 pure functions covering five categories: mathematical polyfills (hyperbolic functions, normal distribution CDF/inverse, error function), advanced smoothing filters (Ehlers Super Smoother, Butterworth, Savitzky-Golay), robust statistics (median-MAD, IQR-based scaling, Winsorized bounds), normalization methods (z-scores, percentile ranks, min-max scaling), and correlation analysis (Pearson, Spearman, Kendall, Hurst exponent). Traders use these functions to build custom indicators requiring statistical rigor beyond Pine's built-in ta.* namespace—for example, calculating confidence intervals from normal quantiles, applying outlier-resistant smoothing to noisy price data, or measuring non-linear correlation between assets. The library outputs standardized numerical values ready for downstream indicator logic: z-scores for mean-reversion signals, normalized coefficients for ML feature engineering, correlation matrices for multi-asset analysis, and smoothed series for trend detection. All functions are stateless (no internal state variables), making them composable and predictable across different timeframes and symbols. ## How it works NumLib implements well-documented statistical algorithms with explicit citations. The normal CDF uses the Abramowitz & Stegun 26.2.17 polynomial approximation (max error ~7e-8), while the inverse normal CDF employs the Beasley-Springer-Moro rational approximation for converting probabilities to z-scores with ~1e-10 precision—critical for quantile-based risk calculations. Hyperbolic tangent (tanh) is computed via the numerically stable identity `(e^(2x) - 1) / (e^(2x) + 1)` with argument clamping to ±20 to prevent math.exp overflow. Smoothing filters follow Ehlers' DSP methodology: the Super Smoother is a 2-pole IIR Butterworth-equivalent with coefficients derived from `exp(-1.414π/len)`, providing lag reduction vs simple moving averages while suppressing high-frequency noise. The Savitzky-Golay filter uses fixed polynomial coefficients (order 2, length 13) for edge-preserving smoothing without phase shift. Robust statistics leverage percentile-based methods resistant to outliers. The median-MAD estimator computes scale as `(Q75 - Q25) / 0.7413`, where 0.7413 is the IQR-to-standard-deviation conversion factor for normal distributions. Correlation functions implement textbook formulas: Pearson via covariance normalization, Spearman via rank transformation, Kendall via concordant-discordant pair counting. The Hurst exponent uses rescaled range (R/S) analysis to detect mean-reversion (H < 0.5) vs trending (H > 0.5) regimes. ## Why this is original NumLib fills critical gaps in Pine Script's native math library. TradingView provides no hyperbolic functions (tanh, sinh, cosh), no normal distribution quantile functions, no Savitzky-Golay smoothing, and no robust statistics beyond basic percentiles. Existing public libraries either bundle these functions with unrelated indicator logic (mixing calculation with rendering) or implement simplified versions without numerical stability guards. This library is the only TradingView publication offering: - **Numerically stable implementations**: tanh with overflow clamping, normal CDF with Abramowitz-Stegun precision, inverse CDF with Beasley-Springer-Moro accuracy - **Robust statistics suite**: median-MAD, IQR normalization, Winsorization—essential for outlier-resistant indicators in volatile markets - **Ehlers DSP filters**: Super Smoother and Butterworth implementations with exact coefficient formulas from Ehlers' published work - **Comprehensive correlation toolkit**: Pearson, Spearman, Kendall, plus Hurst exponent for regime detection—all in one dependency-free library No other Pine library combines these four categories with explicit algorithm citations and edge-case handling (NA guards, zero-division checks, warmup period validation). ## How to use it ```pine //@version=6 indicator("CyberNumLib Demo", overlay=false) import cybermediaboy/CyberNumLib/5 as N // Example 1: Z-score with robust median-MAD scaling = N.f_basis_median_mad(close, 50) plot(z_robust, "Robust Z-Score", color.blue) // Example 2: Smooth price with Ehlers Super Smoother smooth_close = N.f_supersmoother(close, 20) plot(smooth_close, "Super Smooth", color.orange) // Example 3: Calculate correlation between two assets // (Assumes you have arrays x_data and y_data populated) var x_arr = array.new(50) var y_arr = array.new(50) array.push(x_arr, close) array.push(y_arr, volume) if array.size(x_arr) > 50 array.shift(x_arr) array.shift(y_arr) corr_pearson = N.f_pearson(x_arr, y_arr, 50) plot(corr_pearson, "Pearson Correlation", color.green) // Example 4: Convert confidence level to z-score conf_95 = 0.95 z_95 = N.f_norm_inv((1.0 + conf_95) / 2.0) // Returns ~1.96 plot(z_95, "95% Confidence Z", color.red) ``` ## Inputs, outputs, expected behavior **Smoothing functions** (`f_supersmoother`, `f_buttersmooth`, `f_savgol_2_13`): - **Inputs**: `src` (float, typically close/high/low), `len` (int, window size 5-100 typical) - **Outputs**: Smoothed float value, range matches input series - **Edge cases**: Returns input value on first bar (no warmup), handles NA via nz() **Statistical functions** (`f_zscore`, `f_basis_median_mad`, `f_percentile_bands`): - **Inputs**: `src` (float series), `len` (int, minimum 10 for stability) - **Outputs**: Z-scores (unbounded float), percentiles (price units), scale factors (positive float) - **Edge cases**: Returns 0.0 for z-score if stdev = 0, returns NA for insufficient data (bar_index < len) **Correlation functions** (`f_pearson`, `f_spearman`, `f_kendall`, `f_hurst_rs`): - **Inputs**: `array` (length ≥ 10), `len` (int, sample size) - **Outputs**: Correlation coefficient for Pearson/Spearman/Kendall, Hurst - **Edge cases**: Returns 0.0 if array size < len, handles NA elements via filtering **Math polyfills** (`f_tanh`, `f_norm_cdf`, `f_norm_inv`, `f_erf`): - **Inputs**: Float values (unbounded for tanh/erf, for norm_inv, any for norm_cdf) - **Outputs**: Bounded floats (tanh: , sigmoid: , norm_cdf: , norm_inv: unbounded) - **Edge cases**: Clamps extreme inputs to prevent overflow (tanh at ±20, norm_inv at ) **Normalization functions** (`f_normalize`, `f_iqr_normalize`, `f_tanh_norm`): - **Inputs**: `value` (float), `minval/maxval` (float bounds) or `len` (int window) - **Outputs**: Normalized float in for f_normalize, for tanh-based methods - **Edge cases**: Returns 0.0 if range is zero, handles NA inputs gracefully ## Limitations 1. **No dynamic array sizing**: Correlation functions require pre-allocated arrays of fixed size. If your data stream length varies, you must manage array resizing externally (e.g., via array.push + array.shift pattern). The library does not auto-resize or buffer data. 2. **Warmup period required**: Statistical functions (z-score, percentile bands, correlation) return unreliable values during the first `len` bars. Indicators using NumLib should display a warmup warning (e.g., "Insufficient data: need 50 bars") or gate signals until `bar_index >= len`. 3. **Precision limits on extreme inputs**: Math polyfills use polynomial approximations with documented error bounds (e.g., normal CDF ~7e-8, erf ~1.5e-7). For applications requiring higher precision (e.g., options pricing), these approximations may be insufficient. Extreme inputs (|x| > 20 for tanh, p < 1e-10 for norm_inv) are clamped to prevent overflow, which can distort tail probabilities. 4. **Correlation functions assume stationarity**: Pearson, Spearman, and Kendall correlations are computed over rolling windows without detrending. In strongly trending markets, these measures may overstate correlation due to common trend components. For non-stationary data, consider differencing the series first or using Hurst exponent to detect regime changes. 5. **No built-in significance testing**: The library returns raw correlation coefficients without p-values or confidence intervals. Traders must implement their own significance tests (e.g., t-test for Pearson correlation) or use rule-of-thumb thresholds (|r| > 0.7 for strong correlation). 6. **Single-threaded execution**: All functions execute sequentially on each bar. For indicators calling multiple NumLib functions per bar (e.g., computing 10 correlations), execution time may exceed TradingView's script timeout on lower timeframes with large datasets. Optimize by caching results or reducing calculation frequency.
Pine Script® library
by cybermediaboy
CandlePressure_UtilitiesCandlePressure_Utilities is a lightweight Pine library for converting raw OHLC candle structure into a normalized candle-pressure score, buy/sell percentage estimates, oscillator output, and compact display helpers. The library is designed for scripts that want a reusable candle-pressure layer without rebuilding the same CLV/body/wick math every time. It centralizes the pieces that commonly repeat across pressure-based scripts: • close-location value / CLV calculation • candle body dominance • upper-vs-lower wick imbalance • deadzone-filtered wick pressure • normalized pressure output from -1 to +1 • buy/sell percentage conversion • pressure oscillator conversion from -100 to +100 • alternate body/wick buy-sell allocation • compact volume and relative-volume formatting • table/label size and table-position helpers • small percent and black/white text helpers On the example chart, the pressure candles, pressure oscillator, buy/sell split, CLV/body/wick breakdown, alternate body/wick comparison, and compact table values are all materially driven by this library. This library is intentionally focused on pure candle structure. It does not confirm trend, detect pivots, calculate RSI/DMI/ATR context, decide trade direction, or choose final signal logic for the calling script. Those layers remain script-level decisions. ➖Quick Start➖ Import the library near the top of your script in global scope, alongside any other imports, before calling its helpers. Typical placement: //@version=6 indicator(...) or strategy(...) import MYNAMEISBRANDON/CandlePressure_Utilities/1 as cp Replace /1 with the latest published version if a newer version is available. The main helper for most scripts is candlePressureMetrics(), which returns: • pressure • buyPct • sellPct Example: = cp.candlePressureMetrics( open, high, low, close, volume) string splitText = cp.fmtBuySellSplit( buyPct, sellPct, volume) float pressureOsc = cp.pressureOsc( pressure) The library uses standard OHLCV argument order: open, high, low, close, volume ➖What The Library Measures➖ The default candle-pressure model uses: • Wick Deadzone = 0.02 • CLV Weight = 0.55 • Body Weight = 0.30 • Wick Weight = 0.15 CLV measures where the close finished inside the candle range. Body contribution measures open-to-close directional dominance. Wick contribution measures lower-wick vs upper-wick imbalance. The final pressure score is a weighted blend of those components, normalized from -1 to +1. That pressure score can then be converted into buy/sell percentage estimates, a -100 to +100 pressure oscillator, candle-overlay colors, table values, labels, or dashboard outputs. ➖Function Reference➖ These helpers are grouped by purpose. Most scripts will only need: • candlePressureMetrics() • fmtBuySellSplit() • pressureOsc() More advanced scripts can use the full component helpers for tables, tooltips, debug output, or custom pressure models. ➖Model + Math Helpers➖ modelDefaults() Returns the default candle-pressure model values used by this library. Returns: Wick deadzone, CLV weight, body weight, wick weight clamp(v, lo, hi) Restricts a value between a lower and upper bound. Parameters: v (float): Input value lo (float): Lower bound hi (float): Upper bound Returns: Clamped value safeDiv(numerator, denominator, fallback) Safely divides two values and returns the fallback when division is not valid. Parameters: numerator (float): Numerator value denominator (float): Denominator value fallback (float): Value returned when division is unsafe Returns: numerator / denominator, or fallback when unsafe ➖Display + UI Helpers➖ fmtCompact(val, sigFigs, naText) Formats large values into compact display text such as 1.5k, 2.4m, or 1.2b. Parameters: val (float): Value to format sigFigs (simple int): Significant figures to keep naText (simple string): Text returned when val is na Returns: Compact formatted string fmtBuySellSplit(buyPct, sellPct, volumeValue) Formats buy/sell percentages into rounded split text such as 62/38. Parameters: buyPct (float): Buy percentage sellPct (float): Sell percentage volumeValue (float): Volume value used to handle missing or no-volume bars Returns: Formatted buy/sell split text contrastText(bg) Chooses black or white text based on background brightness. Parameters: bg (color): Background color Returns: Readable contrast text color stripLeadingZero(txt) Removes the leading zero from decimal text. Parameters: txt (string): Input text Returns: Adjusted text, such as 0.25 -> .25 or -0.25 -> -.25 fmtRelVol(val, naText) Formats relative volume with two decimals and strips the leading zero. Parameters: val (float): Relative volume value naText (string): Text returned when val is na Returns: Formatted relative-volume text pctChange(currentValue, baseValue) Returns the percent change from a base value. Parameters: currentValue (float): Current or projected value baseValue (float): Comparison baseline Returns: Percent change fmtPctWhole(val, naText) Formats a percent value as rounded whole-percent text. Parameters: val (float): Percent value naText (string): Text returned when val is na Returns: Rounded percent string pctInt(pct) Rounds and clamps a percentage into 0–100 integer form. Parameters: pct (float): Percent value Returns: Integer percent from 0 to 100 pctIntVol(pct, volumeValue) Rounds and clamps a percentage into 0–100 integer form, returning 0 on no-volume bars. Parameters: pct (float): Percent value volumeValue (float): Volume value Returns: Integer percent from 0 to 100 tableTextSize(sizeText) Converts user-facing table-size text into Pine table text-size enums. Parameters: sizeText (string): Size text. Expected values: "Tiny", "Small", "Normal", or "Large" Returns: Pine table text-size enum labelSize(sizeText) Converts user-facing label-size text into Pine label-size enums. Parameters: sizeText (string): Size text. Expected values: "Tiny", "Small", "Normal", "Large", or "Huge" Returns: Pine label-size enum tablePos(posText) Converts user-facing table-position text into Pine table position enums. Parameters: posText (string): Table position text Returns: Pine table position enum bw(useBlack) Returns black text when the condition is true, otherwise white. Parameters: useBlack (bool): Whether black text should be used Returns: Black or white text color ➖Candle Pressure Helpers➖ candlePressurePartsFull(openValue, highValue, lowValue, closeValue, wickDeadzone, weightClv, weightBody, weightWick) Converts OHLC candle structure into the full normalized pressure component set. Parameters: openValue (float): Candle open highValue (float): Candle high lowValue (float): Candle low closeValue (float): Candle close wickDeadzone (float): Wick imbalance threshold below which wick contribution is forced to 0 weightClv (float): Weight assigned to the CLV component weightBody (float): Weight assigned to the body component weightWick (float): Weight assigned to the wick component Returns: CLV, body % of range, signed body term, raw wick imbalance, deadzoned wick imbalance, final pressure Note: wickDeadzone, weightClv, weightBody, and weightWick are optional. If omitted, the library uses its default model: Wick Deadzone 0.02 / CLV 0.55 / Body 0.30 / Wick 0.15 candlePressureParts(openValue, highValue, lowValue, closeValue, wickDeadzone, weightClv, weightBody, weightWick) Converts OHLC candle structure into the compact pressure component set. Parameters: openValue (float): Candle open highValue (float): Candle high lowValue (float): Candle low closeValue (float): Candle close wickDeadzone (float): Wick imbalance threshold below which wick contribution is forced to 0 weightClv (float): Weight assigned to the CLV component weightBody (float): Weight assigned to the body component weightWick (float): Weight assigned to the wick component Returns: CLV, body % of range, raw wick imbalance, deadzoned wick imbalance, final pressure Note: wickDeadzone, weightClv, weightBody, and weightWick are optional. If omitted, the library uses its default model: Wick Deadzone 0.02 / CLV 0.55 / Body 0.30 / Wick 0.15 pressureToBuySell(pressure, volumeValue) Converts normalized pressure into buy/sell percentages. Parameters: pressure (float): Candle pressure in the -1..+1 range volumeValue (float): Volume value used to handle missing or no-volume bars Returns: Buy %, Sell % pressureOsc(pressure) Converts normalized pressure into a -100..+100 oscillator value. Parameters: pressure (float): Candle pressure in the -1..+1 range Returns: Pressure oscillator value candlePressureMetrics(openValue, highValue, lowValue, closeValue, volumeValue, wickDeadzone, weightClv, weightBody, weightWick) One-call convenience wrapper for scripts that need final pressure, buy %, and sell %. Parameters: openValue (float): Candle open highValue (float): Candle high lowValue (float): Candle low closeValue (float): Candle close volumeValue (float): Volume value used to handle missing or no-volume bars wickDeadzone (float): Wick imbalance threshold below which wick contribution is forced to 0 weightClv (float): Weight assigned to the CLV component weightBody (float): Weight assigned to the body component weightWick (float): Weight assigned to the wick component Returns: Pressure, Buy %, Sell % Note: wickDeadzone, weightClv, weightBody, and weightWick are optional. If omitted, the library uses its default model: Wick Deadzone 0.02 / CLV 0.55 / Body 0.30 / Wick 0.15 bodyWickRateBuyPct(openValue, highValue, lowValue, closeValue) Returns an alternate buy percentage using body/wick structure only. Parameters: openValue (float): Candle open highValue (float): Candle high lowValue (float): Candle low closeValue (float): Candle close Returns: Buy percentage bodyWickRateBuySell(openValue, highValue, lowValue, closeValue, volumeValue) Returns alternate body/wick buy and sell percentages. Parameters: openValue (float): Candle open highValue (float): Candle high lowValue (float): Candle low closeValue (float): Candle close volumeValue (float): Volume value used to handle missing or no-volume bars Returns: Buy %, Sell % ➖Important Notes➖ Candle Pressure is not order flow. The buy/sell split produced by this library is an estimate derived from candle structure. It is not true bid/ask volume, footprint data, or exchange-level order flow. The pressure model is intentionally pure OHLC structure: • CLV measures where the close finished inside the candle range. • Body contribution measures open-to-close directional dominance. • Wick contribution measures lower-wick vs upper-wick imbalance. • Final pressure is a weighted blend of those components. Momentum filters such as RSI, DMI, ATR, trend state, relative volume, or multi-timeframe context should be added by the calling script when needed. This library provides the reusable candle-pressure foundation only. ➖Release Notes➖ v1 Initial release of CandlePressure_Utilities. This release provides a focused candle-pressure utility layer for Pine scripts that need reusable OHLC pressure calculations, buy/sell percentage estimates, pressure oscillator output, compact display formatting, and small table/label helper functions. Included in this release: • default candle-pressure model values • safe math helpers • compact number formatting • buy/sell split formatting • relative-volume formatting • table/label size and table-position helpers • percent and bias display helpers • full candle-pressure component output • compact candle-pressure component output • pressure-to-buy/sell conversion • pressure oscillator conversion • alternate body/wick buy-sell allocation The library is designed to stay focused on reusable candle-pressure mechanics. It does not decide trend, trade direction, signal confirmation, pivot structure, RSI/DMI filters, ATR filters, or final color logic. Calling scripts remain responsible for their own signal model and visual interpretation.
Pine Script® library
by MYNAMEISBRANDON
taLibrary "ta" Collection of all custom and enhanced TA indicators ma(source, maType, length)   returns custom moving averages   Parameters:      source (float) : Moving Average Source      maType (simple string) : Moving Average Type : Can be sma, ema, hma, rma, wma, vwma, swma, highlow, linreg, median      length (simple int) : Moving Average Length   Returns: moving average for the given type and length atr(maType, length)   returns ATR with custom moving average   Parameters:      maType (simple string) : Moving Average Type : Can be sma, ema, hma, rma, wma, vwma, swma, highlow, linreg, median      length (simple int) : Moving Average Length   Returns: ATR for the given moving average type and length atrpercent(maType, length)   returns ATR as percentage of close price   Parameters:      maType (simple string) : Moving Average Type : Can be sma, ema, hma, rma, wma, vwma, swma, highlow, linreg, median      length (simple int) : Moving Average Length   Returns: ATR as percentage of close price for the given moving average type and length bb(source, maType, length, multiplier, sticky)   returns Bollinger band for custom moving average   Parameters:      source (float) : Moving Average Source      maType (simple string) : Moving Average Type : Can be sma, ema, hma, rma, wma, vwma, swma, highlow, linreg, median      length (simple int) : Moving Average Length      multiplier (float) : Standard Deviation multiplier      sticky (simple bool) : - sticky boundaries which will only change when value is outside boundary.   Returns: Bollinger band with custom moving average for given source, length and multiplier bbw(source, maType, length, multiplier, sticky)   returns Bollinger bandwidth for custom moving average   Parameters:      source (float) : Moving Average Source      maType (simple string) : Moving Average Type : Can be sma, ema, hma, rma, wma, vwma, swma, highlow, linreg, median      length (simple int) : Moving Average Length      multiplier (float) : Standard Deviation multiplier      sticky (simple bool) : - sticky boundaries which will only change when value is outside boundary.   Returns: Bollinger Bandwidth for custom moving average for given source, length and multiplier bpercentb(source, maType, length, multiplier, sticky)   returns Bollinger Percent B for custom moving average   Parameters:      source (float) : Moving Average Source      maType (simple string) : Moving Average Type : Can be sma, ema, hma, rma, wma, vwma, swma, highlow, linreg, median      length (simple int) : Moving Average Length      multiplier (float) : Standard Deviation multiplier      sticky (simple bool) : - sticky boundaries which will only change when value is outside boundary.   Returns: Bollinger Percent B for custom moving average for given source, length and multiplier kc(source, maType, length, multiplier, useTrueRange, sticky)   returns Keltner Channel for custom moving average   Parameters:      source (float) : Moving Average Source      maType (simple string) : Moving Average Type : Can be sma, ema, hma, rma, wma, vwma, swma, highlow, linreg, median      length (simple int) : Moving Average Length      multiplier (float) : Standard Deviation multiplier      useTrueRange (simple bool) : - if set to false, uses high-low.      sticky (simple bool) : - sticky boundaries which will only change when value is outside boundary.   Returns: Keltner Channel for custom moving average for given souce, length and multiplier kcw(source, maType, length, multiplier, useTrueRange, sticky)   returns Keltner Channel Width with custom moving average   Parameters:      source (float) : Moving Average Source      maType (simple string) : Moving Average Type : Can be sma, ema, hma, rma, wma, vwma, swma, highlow, linreg, median      length (simple int) : Moving Average Length      multiplier (float) : Standard Deviation multiplier      useTrueRange (simple bool) : - if set to false, uses high-low.      sticky (simple bool) : - sticky boundaries which will only change when value is outside boundary.   Returns: Keltner Channel Width for custom moving average kpercentk(source, maType, length, multiplier, useTrueRange, sticky)   returns Keltner Channel Percent K Width with custom moving average   Parameters:      source (float) : Moving Average Source      maType (simple string) : Moving Average Type : Can be sma, ema, hma, rma, wma, vwma, swma, highlow, linreg, median      length (simple int) : Moving Average Length      multiplier (float) : Standard Deviation multiplier      useTrueRange (simple bool) : - if set to false, uses high-low.      sticky (simple bool) : - sticky boundaries which will only change when value is outside boundary.   Returns: Keltner Percent K for given moving average, source, length and multiplier dc(length, useAlternateSource, alternateSource, sticky)   returns Custom Donchian Channel   Parameters:      length (simple int) : - donchian channel length      useAlternateSource (simple bool) : - Custom source is used only if useAlternateSource is set to true      alternateSource (float) : - Custom source      sticky (simple bool) : - sticky boundaries which will only change when value is outside boundary.   Returns: Donchian channel dcw(length, useAlternateSource, alternateSource, sticky)   returns Donchian Channel Width   Parameters:      length (simple int) : - donchian channel length      useAlternateSource (simple bool) : - Custom source is used only if useAlternateSource is set to true      alternateSource (float) : - Custom source      sticky (simple bool) : - sticky boundaries which will only change when value is outside boundary.   Returns: Donchian channel width dpercentd(length, useAlternateSource, alternateSource, sticky)   returns Donchian Channel Percent of price   Parameters:      length (simple int) : - donchian channel length      useAlternateSource (simple bool) : - Custom source is used only if useAlternateSource is set to true      alternateSource (float) : - Custom source      sticky (simple bool) : - sticky boundaries which will only change when value is outside boundary.   Returns: Donchian channel Percent D oscillatorRange(source, method, highlowLength, rangeLength, sticky)   oscillatorRange - returns Custom overbought/oversold areas for an oscillator input   Parameters:      source (float) : - Osillator source such as RSI, COG etc.      method (simple string) : - Valid values for method are : sma, ema, hma, rma, wma, vwma, swma, highlow, linreg, median      highlowLength (simple int) : - length on which highlow of the oscillator is calculated      rangeLength (simple int) : - length used for calculating oversold/overbought range - usually same as oscillator length      sticky (simple bool) : - overbought, oversold levels won't change unless crossed   Returns: Dynamic overbought and oversold range for oscillator input oscillator(type, length, shortLength, longLength, source, highSource, lowSource, method, highlowLength, sticky)   oscillator - returns Choice of oscillator with custom overbought/oversold range   Parameters:      type (simple string) : - oscillator type. Valid values : cci, cmo, cog, mfi, roc, rsi, stoch, tsi, wpr      length (simple int) : - Oscillator length - not used for TSI      shortLength (simple int) : - shortLength only used for TSI      longLength (simple int) : - longLength only used for TSI      source (float) : - custom source if required      highSource (float) : - custom high source for stochastic oscillator      lowSource (float) : - custom low source for stochastic oscillator      method (simple string) : - Valid values for method are : sma, ema, hma, rma, wma, vwma, swma, highlow, linreg, median      highlowLength (simple int) : - length on which highlow of the oscillator is calculated      sticky (simple bool) : - overbought, oversold levels won't change unless crossed   Returns: Oscillator value along with dynamic overbought and oversold range for oscillator input
Pine Script® library
by Seyyahix
SimTradeIndicatorsLibrary "SimTradeIndicators" SimTrade indicator library — exact parity with Python pipeline (TA-Lib + pandas_ta). Each function replicates the formula used in base.py / signals.py so that TradingView charts match the GPU hunt / validator / live engine outputs. Formula sources: TA-Lib → RSI, ATR, EMA, MACD, CCI, Stoch, WILLR, MFI, ADX, PSAR, OBV, BBANDS, AROON, PPO, AD pandas_ta → SuperTrend, Vortex, Ichimoku, Donchian, HMA, TSI, CMF, EFI, CHOP, Heikin-Ashi Manual → Keltner (EMA+ATR Wilder), TTM Squeeze, Chandelier Exit, VWAP reset, Pivot Points Known intentional deviations (documented): - Stoch trigger 11 uses Full %D (double-smoothed), not single %K - OBV filter 206 uses windowed 800-bar OBV (GPU-aligned, not cumulative) - Pivot Points use rolling window, not session-based (see pivot_pp notes) - EMA has longer warmup in TA-Lib (~50 bars unstable period) vs TW (from bar 1); steady-state identical smma(src, length)   SMMA / Wilder RMA. alpha = 1/length. Matches talib "RMA" used for ATR/RSI internally.   Parameters:      src (float) : Source series      length (simple int) : Period   Returns: RMA value hma(src, length)   HMA (Hull Moving Average). HMA = WMA(2·WMA(N/2) − WMA(N), √N). Matches pandas_ta.hma.   Parameters:      src (float) : Source series      length (simple int) : Period   Returns: HMA value dema(src, length)   DEMA (Double EMA) = 2·EMA − EMA(EMA). Matches talib.DEMA.   Parameters:      src (float) : Source series      length (simple int) : Period   Returns: DEMA value tema(src, length)   TEMA (Triple EMA) = 3·EMA − 3·EMA² + EMA³. Matches talib.TEMA.   Parameters:      src (float) : Source series      length (simple int) : Period   Returns: TEMA value atr_wilder(length)   ATR using Wilder RMA. Identical to talib.ATR and TW ta.atr.   Parameters:      length (simple int) : Period (default 14)   Returns: ATR value atr_percentile_pct(length, lookback)   ATR percentile rank over a rolling window. Matches Python vol_filter 201. Logic: for each bar count how many ATR values in are <= current ATR, return that fraction as 0..100. Warmup bars (< lookback + length) return 50.0.   Parameters:      length (simple int) : ATR period / Wilder RMA (default 14). Matches params .      lookback (simple int) : Rolling window for percentile rank (default 30). Matches params .   Returns: Percentile rank 0..100 (pass filter when >= pct_min / params ) bbands(src, length, mult)   Bollinger Bands. Returns . mid = SMA. Matches talib.BBANDS (matype=0 = SMA).   Parameters:      src (float) : Source series (typically close)      length (simple int) : Period (default 20)      mult (float) : Standard deviation multiplier (default 2.0)   Returns: bb_pctb(src, length, mult)   Bollinger Bands %B = (close − lower) / (upper − lower). Returns 0.5 during warmup (matches Python _nan50 fallback in base.bb_pctb).   Parameters:      src (float) : Source series      length (simple int) : Period (default 20)      mult (float) : Multiplier (default 2.0)   Returns: %B value bb_width_x1000(src, length, mult)   BB bandwidth × 1000 / mid. Used by vol filter 202 (bb_width).   Parameters:      src (float) : Source series      length (simple int) : Period (default 20)      mult (float) : Multiplier (default 2.0)   Returns: (upper − lower) / |mid| × 1000 keltner(ema_period, atr_period, mult)   Keltner Channel. mid = EMA(close, ema_period), band = ATR(atr_period) Wilder RMA. IMPORTANT: this is the TW-standard formula. NOT pandas_ta kc(mamode="ema") which uses EMA(TR). That version produces ~40% narrower bands than TW. This library uses the correct RMA(ATR) band.   Parameters:      ema_period (simple int) : EMA period for midline (default 20)      atr_period (simple int) : ATR period for band width (default 10)      mult (float) : ATR multiplier (default 1.5)   Returns: keltner_width_x1000(period, mult)   Keltner Channel bandwidth × 1000 / mid. Used by vol filter 204 (keltner_width).   Parameters:      period (simple int) : Period for both EMA and ATR (default 20)      mult (float) : ATR multiplier (default 1.5)   Returns: (upper − lower) / |mid| × 1000 choppiness(length)   Choppiness Index. CHOP = 100·log10(Σ ATR1 / (HH − LL)) / log10(N). Matches pandas_ta.chop and TW built-in CHOP. Returns 50.0 during warmup.   Parameters:      length (simple int) : Period (default 14)   Returns: CHOP value rsi_val(src, length)   RSI using Wilder RMA. Identical to talib.RSI and TW ta.rsi. Returns 50.0 during warmup (matches Python _nan50 fallback).   Parameters:      src (float) : Source series (typically close)      length (simple int) : Period (default 14)   Returns: RSI value cci_val(length)   CCI = (typical − SMA(typical)) / (0.015 · mean_deviation). Matches talib.CCI. Returns 0.0 during warmup (matches Python _nan0 fallback).   Parameters:      length (simple int) : Period (default 20)   Returns: CCI value stoch_raw_k(k_period)   Stochastic raw %K (no smoothing). Matches base.stoch_k (talib slowk_period=1). NOTE: TW ta.stoch default smooths %K with SMA(3). This is the unsmoothed fast %K. Used by filter 103 (stoch_k_below).   Parameters:      k_period (simple int) : Lookback period (default 14)   Returns: Raw %K (50.0 during warmup) stoch_full_d(k_period, d_period)   Full Stochastic %D = SMA(SMA(raw%K, d_period), d_period). Matches talib.STOCH output. Used by trigger 11 (stoch_cross). NOT single-smoothed %K — lag is +2-3 bars vs TW default.   Parameters:      k_period (simple int) : Raw %K lookback (default 14)      d_period (simple int) : Smoothing applied twice (default 3)   Returns: Full Stochastic %D (50.0 during warmup) williams_r(length)   Williams %R = −100 · (HH − close) / (HH − LL). Matches talib.WILLR. Range: −100 to 0. Returns −50.0 during warmup.   Parameters:      length (simple int) : Period (default 14)   Returns: Williams %R value mfi_val(length)   MFI (Money Flow Index). Matches talib.MFI. Returns 50.0 during warmup.   Parameters:      length (simple int) : Period (default 14)   Returns: MFI value macd_val(src, fast, slow, signal_period)   MACD. Returns . Identical to talib.MACD. All NaN values replaced with 0.0 (matches Python _nan0).   Parameters:      src (float) : Source series      fast (simple int) : Fast EMA period (default 12)      slow (simple int) : Slow EMA period (default 26)      signal_period (simple int) : Signal EMA period (default 9)   Returns: ppo_val(src, fast, slow)   PPO = (EMA(fast) − EMA(slow)) / EMA(slow) × 100. Matches talib.PPO. Returns 0.0 during warmup.   Parameters:      src (float) : Source series      fast (simple int) : Fast period (default 12)      slow (simple int) : Slow period (default 26)   Returns: PPO value tsi_val(src, long_period, short_period)   TSI (True Strength Index). Matches pandas_ta.tsi parameter order. TSI = 100 · EMA(EMA(Δclose, slow), fast) / EMA(EMA(|Δclose|, slow), fast) slow is the OUTER (first) smoothing, fast is the INNER (second). Same as TW.   Parameters:      src (float) : Source series      long_period (simple int) : Outer (slow) EMA period (default 25)      short_period (simple int) : Inner (fast) EMA period (default 13)   Returns: TSI value (0.0 during warmup) adx_di(length)   ADX + DI lines. Returns . Matches talib.ADX/PLUS_DI/MINUS_DI. Uses Wilder RMA (identical to TW ta.dmi / ta.adx).   Parameters:      length (simple int) : Period (default 14)   Returns: — 0.0 during warmup supertrend_val(length, mult)   SuperTrend direction and value. Matches pandas_ta.supertrend (RMA ATR). Returns : direction = 1 (bull) or −1 (bear).   Parameters:      length (simple int) : ATR period (default 10)      mult (float) : ATR multiplier (default 3.0)   Returns: psar_val(start, inc, max_af)   Parabolic SAR. Returns . Matches talib.SAR. direction = 1 if close > SAR (bull), −1 bear.   Parameters:      start (simple float) : Initial AF / step (default 0.02)      inc (simple float) : AF increment per bar (default 0.02)      max_af (simple float) : Maximum AF cap (default 0.2)   Returns: aroon_val(length)   Aroon Up and Down. Returns . Matches talib.AROON. ta.aroon does not exist in Pine v6 — computed manually: Aroon Up = (length − bars since highest high over length+1 bars) / length × 100 Aroon Down = (length − bars since lowest low over length+1 bars) / length × 100 This is identical to talib.AROON and TradingView's built-in Aroon indicator. Returns 50.0 during warmup (matches Python _nan50).   Parameters:      length (simple int) : Period (default 25)   Returns: vortex_diff(length)   Vortex Indicator difference (VI+ − VI−). Matches base.vortex. Positive = bullish regime, negative = bearish. Returns 0.0 during warmup.   Parameters:      length (simple int) : Period (default 14)   Returns: VI+ minus VI− linreg_slope(src, length)   Linear Regression Slope. Matches talib.LINEARREG_SLOPE exactly. Computes OLS slope for x = 0..N-1 (oldest=0, newest=N-1). Positive = uptrend, negative = downtrend. Returns 0.0 during warmup.   Parameters:      src (float) : Source series      length (simple int) : Period (default 20)   Returns: Slope value obv_val()   OBV (On-Balance Volume). Cumulative. Matches talib.OBV.   Returns: Cumulative OBV vwap_reset(reset_bars)   VWAP with periodic session reset. Matches base.vwap(reset_bars). reset_bars=24 on H1 ≈ daily VWAP (crypto 24/7). reset_bars=6 on H4 ≈ daily. reset_bars=0 uses TW built-in ta.vwap (session anchor).   Parameters:      reset_bars (simple int) : Bars per session (0 = TW session anchor, 24 = H1 daily, 6 = H4 daily)   Returns: VWAP value cmf_val(length)   CMF (Chaikin Money Flow) = Σ(CLV·vol) / Σvol. Matches pandas_ta.cmf. CLV = ((close − low) − (high − close)) / (high − low). Returns 0.0 during warmup.   Parameters:      length (simple int) : Period (default 20)   Returns: CMF value (−1 to 1) ad_val()   Accumulation/Distribution Line. Matches talib.AD.   Returns: Cumulative A/D value efi_val(length)   EFI (Elder Force Index). EFI = EMA((close − close ) · volume, length). Matches pandas_ta.efi. Returns 0.0 during warmup.   Parameters:      length (simple int) : EMA period (default 13)   Returns: EFI value ichimoku_val(tenkan_period, kijun_period, senkou_b_period)   Ichimoku lines. Returns . Matches pandas_ta.ichimoku with CORRECTED column mapping (ISA, ISB, ITS, IKS, ICS). senkou_a/b are plotted 26 bars AHEAD in TW — values here are for current bar alignment.   Parameters:      tenkan_period (simple int) : Tenkan-sen period (default 9)      kijun_period (simple int) : Kijun-sen period (default 26)      senkou_b_period (simple int) : Senkou B period (default 52)   Returns: donchian_val(length)   Donchian Channel. Returns . upper = highest(high, N), lower = lowest(low, N). Matches pandas_ta.donchian. NOTE: lookback may differ ±1 bar from TA-Lib; consistent across all pipeline stages. Trigger 37 (donchian_break) compares close > upper — use upper in Pine.   Parameters:      length (simple int) : Period (default 20)   Returns: ttm_squeeze_val(bb_period, bb_mult, kc_period, kc_mult)   TTM Squeeze. Returns . squeeze_on: BB inside KC (volatility compression). momentum: ta.linreg(close − (donchian_mid + SMA) / 2, bb_period) EXACT match with John Carter formula and base.ttm_squeeze after fix.   Parameters:      bb_period (simple int) : BB period (default 20)      bb_mult (float) : BB multiplier (default 2.0)      kc_period (simple int) : KC period — same for EMA midline and ATR band (default 20)      kc_mult (float) : KC ATR multiplier (default 1.5)   Returns: chandelier_val(period, mult)   Chandelier Exit. Returns . long_exit = highest(high, period) − mult · ATR(period) short_exit = lowest(low, period) + mult · ATR(period) Exact match with base.chandelier_exit. Both include current bar in rolling max/min. Trigger 45 fires when close crosses long_exit or short_exit (up = bull, down = bear).   Parameters:      period (simple int) : Lookback and ATR period (default 22)      mult (float) : ATR multiplier (default 3.0)   Returns: ha_close()   Heikin Ashi close. HA_close = (open + high + low + close) / 4. Matches pandas_ta.ha.   Returns: HA close value ha_open()   Heikin Ashi open. HA_open = (HA_open + HA_close ) / 2. Trigger 48 fires on HA candle color flip: HA_close vs HA_open.   Returns: HA open value pivot_pp(period)   Rolling Pivot Point (floor method). Matches base.pivot_points. pp = (max(high, period bars ago) + min(low, period bars ago) + close ) / 3 NOTE: Rolling window, NOT session-based. H1 default period=24 ≈ 1 day (crypto 24/7). For H4 set period=6 (6 × 4h = 1 day). TW Pivot Points use session H/L/C — differs.   Parameters:      period (simple int) : Rolling lookback (default 24)   Returns: Pivot point value pivot_r1_s1(period)   Rolling R1 and S1 levels. Matches base.pivot_points r1/s1. r1 = 2·pp − lowest_low, s1 = 2·pp − highest_high   Parameters:      period (simple int) : Rolling lookback (default 24)   Returns:
Pine Script® library
by sergeytapov
NeuraLib Expansion: Advanced Model LayersNeuraLib_Models is the companion model expansion for NeuraLib . NeuraLib provides the runtime: tensors, graph execution, datasets, scalers, losses, optimizers, training, inference, and validation tools. NeuraLib_Models builds on that foundation with higher-level neural architectures that are difficult and repetitive to write by hand. The purpose of this expansion is to keep the main NeuraLib runtime clean, compact, and general, while giving researchers ready-to-use model families for sequence learning, attention, temporal pattern extraction, and Reinforcement Learning workflows. ---------------------------------------------------------------------------------------------------------------- 🔷 HOW IT FITS INTO NEURALIB NeuraLib_Models is built entirely on top of the public NeuraLib API. It does not replace the main runtime and it does not introduce a separate training engine. After importing NeuraLib_Models, its fluent methods become available directly on NeuraLib `Sequential` models. The expansion alias can remain unused in the layer chain. //@version=6 indicator("NeuraLib Models Quick Start", overlay = false, calc_bars_count = 600) import Alien_Algorithms/NeuraLib/1 as nl import Alien_Algorithms/NeuraLib_Models/1 as models var nl.Sequential model = nl.sequential("advanced_model") var float qLong = na var float qFlat = na var float qShort = na if barstate.isfirst model := model .input(array.from(8), "sequence") .temporalConvStack(4, 2, 2, 2, 1, 1, nl.ActivationKind.relu, 0.0, "temporal") .globalAvgPool1d(3, 2, "pool") .duelingQHead(4, 3, nl.ActivationKind.relu, "dueling_head") .build(nl.rng(7)) float ret0 = na(close ) or close == 0.0 ? 0.0 : close / close - 1.0 float ret1 = na(close ) or close == 0.0 ? 0.0 : close / close - 1.0 float ret2 = na(close ) or close == 0.0 ? 0.0 : close / close - 1.0 float ret3 = na(close ) or close == 0.0 ? 0.0 : close / close - 1.0 float atrValue = ta.atr(14) float atr0 = close == 0.0 ? 0.0 : atrValue / close float atr1 = close == 0.0 ? 0.0 : atrValue / close float atr2 = close == 0.0 ? 0.0 : atrValue / close float atr3 = close == 0.0 ? 0.0 : atrValue / close bool ready = not na(ret3) and not na(atr3) if ready nl.Tensor state = nl.vector(array.from(ret3, atr3, ret2, atr2, ret1, atr1, ret0, atr0), "state_window") nl.Tensor qValues = model.predict(state) qLong := qValues.get1d(0) qFlat := qValues.get1d(1) qShort := qValues.get1d(2) plot(qLong, "Q long", color = color.lime, linewidth = 2) plot(qFlat, "Q flat", color = color.gray) plot(qShort, "Q short", color = color.red, linewidth = 2) hline(0.0, "Zero", color = color.new(color.gray, 70)) The model is still a normal NeuraLib model. You still call `.compile()`, `.trainOnBatch()`, `.predict()`, `.evaluate()`, `.getWeightsArray()`, and `.softUpdateFrom()` from the main library. ---------------------------------------------------------------------------------------------------------------- 🔷 WHY THIS EXPANSION EXISTS The main NeuraLib library is the foundation. It exposes a graph engine powerful enough to create custom architectures, but repeatedly building LSTM gates, attention projections, residual blocks, Conv1D stacks, or Transformer paths from raw graph operations would be too verbose for everyday research. NeuraLib_Models packages those patterns into readable blocks: Temporal models : Conv1D blocks, temporal convolution stacks, global average pooling, and global max pooling for flattened sequence inputs. Recurrent models : LSTM and GRU blocks for compact sequence memory. Attention models : Self-attention, multi-head self-attention, cross-attention, Transformer encoder blocks, Transformer encoder stacks, and Transformer decoder blocks. Residual models : Residual dense blocks for deeper feedforward paths. Reinforcement Learning heads : Q-head blocks and dueling Q-heads for action-value style outputs. Replay utilities : Deterministic Prioritized Experience Replay for reproducible Pine research. Sequence helpers : Positional encoding for token, sequence, and attention workflows. ---------------------------------------------------------------------------------------------------------------- 🔷 PRACTICAL EXAMPLES 🔸 Temporal Conv Model With Dueling Q-Head This pattern is useful when a flattened sequence contains recent market states and the output represents action values. //@version=6 indicator("NeuraLib Models Temporal Q Example", overlay = false, calc_bars_count = 600) import Alien_Algorithms/NeuraLib/1 as nl import Alien_Algorithms/NeuraLib_Models/1 as models var nl.Sequential qModel = nl.sequential("temporal_q_model") var nl.WindowDataset qDataset = nl.windowDataset(8, 3, 400, "q_rows") var float qDown = na var float qNeutral = na var float qUp = na var float qLoss = na if barstate.isfirst nl.CompileConfig cfg = nl.compileConfig() cfg := cfg .presetQValues() .optimizer(nl.adamW(0.001)) .withTrainingGate(true) qModel := qModel .input(array.from(8), "state_window") .temporalConvStack(4, 2, 2, 2, 1, 1, nl.ActivationKind.relu, 0.0, "temporal") .globalAvgPool1d(3, 2, "pool") .duelingQHead(4, 3, nl.ActivationKind.relu, "dueling_head") .compile(cfg) qDataset := qDataset .setInputScaler(nl.ScalerKind.zScore) .setTargetScaler(nl.ScalerKind.none) float ret0 = na(close ) or close == 0.0 ? 0.0 : close / close - 1.0 float ret1 = na(close ) or close == 0.0 ? 0.0 : close / close - 1.0 float ret2 = na(close ) or close == 0.0 ? 0.0 : close / close - 1.0 float ret3 = na(close ) or close == 0.0 ? 0.0 : close / close - 1.0 float ret4 = na(close ) or close == 0.0 ? 0.0 : close / close - 1.0 float atrValue = ta.atr(14) float atr0 = close == 0.0 ? 0.0 : atrValue / close float atr1 = close == 0.0 ? 0.0 : atrValue / close float atr2 = close == 0.0 ? 0.0 : atrValue / close float atr3 = close == 0.0 ? 0.0 : atrValue / close float atr4 = close == 0.0 ? 0.0 : atrValue / close bool rowReady = not na(ret4) and not na(atr4) if rowReady array features = array.from(ret4, atr4, ret3, atr3, ret2, atr2, ret1, atr1) float downTarget = math.max(-ret0, 0.0) float neutralTarget = math.max(0.002 - math.abs(ret0), 0.0) float upTarget = math.max(ret0, 0.0) qDataset := qDataset.pushRow(features, array.from(downTarget, neutralTarget, upTarget)) if qDataset.ready(48) if barstate.islastconfirmedhistory nl.Batch train = qDataset.trainBatch(12) qModel := qModel.trainOnBatch(train.inputTensor, train.targetTensor) qLoss := qModel.trainStats.lastLoss nl.Tensor liveState = nl.vector(array.from(ret3, atr3, ret2, atr2, ret1, atr1, ret0, atr0), "live_state") nl.Tensor scaledState = qDataset.scaleInput(liveState) nl.Tensor qValues = qModel.predict(scaledState) qDown := qValues.get1d(0) qNeutral := qValues.get1d(1) qUp := qValues.get1d(2) plot(qDown, "Q down", color = color.red, linewidth = 2) plot(qNeutral, "Q neutral", color = color.gray) plot(qUp, "Q up", color = color.lime, linewidth = 2) plot(qLoss, "Training loss", color = color.orange) hline(0.0, "Zero", color = color.new(color.gray, 70)) Input shape `array.from(8)` represents a flattened 4 step by 2 feature sequence. The temporal stack extracts short sequence structure, pooling compresses the sequence, and the dueling head separates value and advantage paths before producing action scores. The example trains only on the last confirmed historical bar so it remains safe to paste onto long charts. 🔸 Transformer Encoder For Token Rows Attention models are useful when each row is a token or time step, and each column is a feature dimension. //@version=6 indicator("NeuraLib Models Transformer Encoder Example", overlay = false, calc_bars_count = 600) import Alien_Algorithms/NeuraLib/1 as nl import Alien_Algorithms/NeuraLib_Models/1 as models var nl.Sequential encoder = nl.sequential("encoder_model") var float tokenSignal = na var float tokenContext = na var float tokenVolatility = na if barstate.isfirst encoder := encoder .input(array.from(4), "tokens") .multiHeadSelfAttention(4, 2, true, "mha") .transformerEncoder(4, true, 2, nl.ActivationKind.geluApprox, "encoder", 0.05, 2) .build(nl.rng(11)) float emaValue = ta.ema(close, 21) float atrValue = ta.atr(14) float ret0 = na(close ) or close == 0.0 ? 0.0 : close / close - 1.0 float ret1 = na(close ) or close == 0.0 ? 0.0 : close / close - 1.0 float ret2 = na(close ) or close == 0.0 ? 0.0 : close / close - 1.0 float ret3 = na(close ) or close == 0.0 ? 0.0 : close / close - 1.0 float emaGap0 = emaValue == 0.0 ? 0.0 : close / emaValue - 1.0 float emaGap1 = emaValue == 0.0 ? 0.0 : close / emaValue - 1.0 float emaGap2 = emaValue == 0.0 ? 0.0 : close / emaValue - 1.0 float emaGap3 = emaValue == 0.0 ? 0.0 : close / emaValue - 1.0 float atr0 = close == 0.0 ? 0.0 : atrValue / close float atr1 = close == 0.0 ? 0.0 : atrValue / close float atr2 = close == 0.0 ? 0.0 : atrValue / close float atr3 = close == 0.0 ? 0.0 : atrValue / close bool ready = not na(ret3) and not na(emaGap3) and not na(atr3) if ready nl.Tensor tokens = nl.vector(array.from( ret3, emaGap3, atr3, -1.0, ret2, emaGap2, atr2, -0.33, ret1, emaGap1, atr1, 0.33, ret0, emaGap0, atr0, 1.0), "tokens").reshape(array.from(4, 4)) nl.Tensor encoded = encoder.predict(tokens) tokenSignal := encoded.get1d(12) tokenContext := encoded.get1d(13) tokenVolatility := encoded.get1d(14) plot(tokenSignal, "Latest token signal", color = color.aqua, linewidth = 2) plot(tokenContext, "Latest token context", color = color.purple) plot(tokenVolatility, "Latest token volatility", color = color.orange) hline(0.0, "Zero", color = color.new(color.gray, 70)) In this example, each input row has 4 features. `headCount` is 2, so the model dimension is split into two attention heads. Attention rule: `modelDim` must be divisible by `headCount`, and the current implementation supports up to 8 heads. 🔸 Prioritized Experience Replay Prioritized Experience Replay stores examples with priorities, then returns reproducible weighted samples. This is especially useful for Reinforcement Learning experiments where high-error transitions should be revisited more often. //@version=6 indicator("NeuraLib Models PER Example", overlay = false, calc_bars_count = 1200) import Alien_Algorithms/NeuraLib/1 as nl import Alien_Algorithms/NeuraLib_Models/1 as models var models.PrioritizedReplayBuffer replay = models.prioritizedReplayBuffer(4, 2, 300, "replay") var nl.Sequential replayModel = nl.sequential("replay_q_model") var float replayLoss = na var float firstImportanceWeight = na var float replayRows = na if barstate.isfirst nl.CompileConfig cfg = nl.compileConfig() cfg := cfg .presetQValues() .optimizer(nl.adamW(0.001)) .trainEveryCall() replayModel := replayModel .input(array.from(4), "state") .dense(8, nl.ActivationKind.relu, "hidden") .qHead(2, nl.ActivationKind.linear, "q_values") .compile(cfg) float rsiValue = ta.rsi(close, 14) float emaValue = ta.ema(close, 21) float atrValue = ta.atr(14) float atrPct = close == 0.0 ? 0.0 : atrValue / close float momentum = na(close ) or close == 0.0 ? 0.0 : close / close - 1.0 float nextReturn = na(close ) ? 0.0 : nl.nextReturnValue(close , close) bool rowReady = not na(rsiValue ) and not na(emaValue ) and not na(atrPct ) and not na(momentum ) if rowReady float prevEma = emaValue float priceVsEma = prevEma == 0.0 ? 0.0 : close / prevEma - 1.0 array stateFeatures = array.from(rsiValue / 100.0, priceVsEma, atrPct , momentum ) array targetValues = array.from(math.max(-nextReturn, 0.0), math.max(nextReturn, 0.0)) float priority = math.abs(nextReturn) + 0.0001 replay := replay.pushExperience(stateFeatures, targetValues, priority) replayRows := float(replay.size()) if replay.ready(32) models.PrioritizedReplaySample sample = replay.sampleBatch(32, 0.6, 0.4, 17) replayModel := replayModel.trainOnBatch(sample.batch.inputTensor, sample.batch.targetTensor) replayLoss := replayModel.trainStats.lastLoss firstImportanceWeight := sample.weightArray.size() > 0 ? sample.weightArray.get(0) : na if sample.indexArray.size() > 0 replay := replay.updatePriority(sample.indexArray.get(0), replayLoss + 0.0001) plot(replayLoss, "Replay training loss", color = color.orange, linewidth = 2) plot(firstImportanceWeight, "First sample weight", color = color.aqua) The returned sample includes: batch : A normal NeuraLib `Batch` containing sampled inputs and targets. indexArray : Logical replay indices that can be passed back to `updatePriority()`. weightArray : Normalized importance weights for custom loss weighting or diagnostics. sampleRows : Number of sampled rows. PER sampling is deterministic for a given buffer, `batchSize`, and `seed`. That makes Pine tests and live research easier to reproduce. ---------------------------------------------------------------------------------------------------------------- 🔷 MODEL FAMILIES 🔸 Residual Dense Blocks `residualDense()` adds a feedforward residual block. Residual paths help preserve information through deeper models and reduce the chance that a dense stack destroys useful features too early. 🔸 Conv1D And Temporal Convolution Stacks `conv1d()` and `temporalConvStack()` operate on flattened sequence inputs. A sequence with `timeSteps = 4` and `featureCount = 2` is represented as 8 input features. These blocks are useful for local temporal structure, short rolling windows, feature rhythm, and compact pattern extraction. 🔸 Global Pooling `globalAvgPool1d()` and `globalMaxPool1d()` compress flattened sequence outputs into feature-level summaries. Average pooling captures broad sequence behavior, while max pooling emphasizes the strongest activation per feature. 🔸 LSTM And GRU Blocks `lstm()` and `gru()` provide recurrent sequence memory over flattened time-series inputs. They are useful when the order of recent states matters more than a single snapshot. 🔸 Attention And Transformers `selfAttention()`, `multiHeadSelfAttention()`, `crossAttention()`, `transformerEncoder()`, `transformerEncoderStack()`, and `transformerDecoder()` bring attention-style modeling into Pine. They are designed for compact token matrices, packed target-memory layouts, and small Transformer-style research models that fit TradingView limits. 🔸 Q-Heads And Dueling Q-Heads `qHeadBlock()` creates action-value style outputs. `duelingQHead()` splits the model into value and advantage branches, then recombines them into Q-values. This is useful when you want the model to estimate both the overall state value and the relative value of each action. 🔸 Positional Encoding `pushPositionalEncoding()` adds sinusoidal position features to a NeuraLib `FeatureBuilder`. This helps attention-style models distinguish where a token or time step sits in a sequence. ---------------------------------------------------------------------------------------------------------------- 🔷 FEATURE QUICK REFERENCE Built on NeuraLib : Uses the main NeuraLib graph, tensor, training, optimizer, dataset, and inference runtime. Fluent API : Adds methods directly to NeuraLib `Sequential` models after import. Block factories : Provides standalone `GraphBlock` factories for users who want lower-level composition. Temporal modeling : Conv1D, temporal convolution stacks, and 1D pooling. Recurrent modeling : LSTM and GRU sequence blocks. Attention modeling : Self-attention, multi-head self-attention, cross-attention, encoders, encoder stacks, and decoders. Reinforcement Learning support : Q-heads, dueling Q-heads, target-model soft updates through NeuraLib, and Prioritized Experience Replay. Reproducible replay : PER sampling is deterministic for a given seed. Shape guardrails : Advanced builders validate expected model feature counts and attention head compatibility. ---------------------------------------------------------------------------------------------------------------- 🔷 IMPORTANT USAGE NOTES Import order matters : Import `NeuraLib` first, then `NeuraLib_Models`. The alias can be unused : The imported expansion registers methods on NeuraLib types, so `.lstm()`, `.gru()`, `.transformerEncoder()`, and similar methods can be called in the model chain. Keep models compact : Pine Script has execution limits. Start with small hidden sizes, short sequences, and low head counts. Control chart history : Use `calc_bars_count = 600` in `indicator()` when needed to balance available training history against model size and execution time. Respect sequence shapes : Conv1D, temporal stacks, LSTM, and GRU methods expect flattened sequence sizes of `timeSteps * featureCount`. Respect attention shapes : Attention methods expect each input row to have `modelDim` columns. Cross-attention and decoder blocks use packed rows. Use NeuraLib guardrails : Train/validation splits, scalers, EarlyStopper, training gates, and gradient clipping remain part of the main NeuraLib workflow. ---------------------------------------------------------------------------------------------------------------- 🔷 API REFERENCE 🔸 Sequential Methods residualDense(hiddenUnits, activationKind, dropoutRate, name) : Adds a residual dense block. duelingQHead(hiddenUnits, actionCount, activationKind, name) : Adds a dueling value/advantage Q-head. conv1d(timeSteps, featureCount, filters, kernelSize, stride, activationKind, name) : Adds a Conv1D block for flattened sequences. temporalConvStack(timeSteps, featureCount, filters, kernelSize, layers, stride, activationKind, dropoutRate, name) : Adds stacked temporal Conv1D layers. globalAvgPool1d(timeSteps, featureCount, name) : Adds global average pooling over a flattened 1D sequence. globalMaxPool1d(timeSteps, featureCount, name) : Adds global max pooling over a flattened 1D sequence. lstm(timeSteps, featureCount, units, activationKind, name) : Adds an LSTM scan block. gru(timeSteps, featureCount, units, activationKind, name) : Adds a GRU scan block. selfAttention(modelDim, causal, name) : Adds row-wise self-attention. multiHeadSelfAttention(modelDim, headCount, causal, name) : Adds multi-head self-attention. crossAttention(queryRows, memoryRows, modelDim, headCount, name) : Adds packed query-memory cross-attention. transformerEncoder(modelDim, causal, ffMultiplier, activationKind, name, dropoutRate, headCount) : Adds one Transformer encoder block. transformerEncoderStack(modelDim, layers, causal, ffMultiplier, activationKind, dropoutRate, headCount, name) : Adds repeated Transformer encoder blocks. transformerDecoder(targetRows, memoryRows, modelDim, headCount, ffMultiplier, activationKind, dropoutRate, name) : Adds a packed target-memory Transformer decoder. 🔸 GraphBlock Factories qHeadBlock(inputFeatures, actionCount, activationKind, name) : Creates a Q-head block. duelingQHeadBlock(inputFeatures, hiddenUnits, actionCount, activationKind, name) : Creates a dueling Q-head block. residualDenseBlock(inputFeatures, hiddenUnits, activationKind, dropoutRate, name) : Creates a residual dense block. conv1dBlock(timeSteps, featureCount, filters, kernelSize, stride, activationKind, name) : Creates a Conv1D block. temporalConvStackBlock(timeSteps, featureCount, filters, kernelSize, layers, stride, activationKind, dropoutRate, name) : Creates a temporal convolution stack. globalAvgPool1dBlock(timeSteps, featureCount, name) and globalMaxPool1dBlock(timeSteps, featureCount, name) : Create pooling blocks. lstmBlock(timeSteps, featureCount, units, activationKind, name) and gruBlock(timeSteps, featureCount, units, activationKind, name) : Create recurrent blocks. selfAttentionBlock(modelDim, causal, name) , multiHeadSelfAttentionBlock(modelDim, headCount, causal, name) , and crossAttentionBlock(queryRows, memoryRows, modelDim, headCount, name) : Create attention blocks. transformerEncoderBlock(modelDim, causal, ffMultiplier, activationKind, name, dropoutRate, headCount) and transformerDecoderBlock(targetRows, memoryRows, modelDim, headCount, ffMultiplier, activationKind, dropoutRate, name) : Create Transformer blocks. 🔸 Prioritized Experience Replay prioritizedReplayBuffer(featureCount, targetCount, maxRows, name) : Creates a replay buffer. pushExperience(featureRowArray, targetRowArray, priority) : Adds or overwrites one replay row. sampleBatch(batchSize, alpha, beta, seed) : Returns a deterministic weighted sample. updatePriority(index, priority) : Updates a sampled row priority. toBatch() : Returns all replay rows in chronological order. ready(minRows) , size() , and clear() : Replay buffer utilities. 🔸 Feature Helpers pushPositionalEncoding(position, dimensions, maxPeriod, featurePrefix) : Appends sinusoidal positional encoding values to a NeuraLib `FeatureBuilder`. NeuraLib_Models is for Pine Script developers who want higher-level neural architecture blocks without leaving the NeuraLib runtime. It is built for compact research models inside TradingView's execution limits, not for oversized GPU-style networks. All the diagrams in this publication are rendered natively on TradingView using Pine3D ---------------------------------------------------------------------------------------------------------------- This work is licensed under (CC BY-NC-SA 4.0) , meaning usage is free for non-commercial purposes given that Alien_Algorithms is credited in the description for the underlying software. For commercial use licensing, contact Alien_Algorithms
Pine Script® library
by Alien_Algorithms
1
NeuraLib: A Native AI and Deep Learning RuntimeNeuraLib is a tensor-based, auto-differentiating Machine Learning runtime built natively for Pine Script™. It brings real Deep Learning mechanisms that power modern Artificial Intelligence systems into TradingView. Instead of relying on fixed formulas, static regressions, or rigid structures, NeuraLib gives Pine developers a different tool: a compact neural runtime that can learn from the features you feed it, using the architecture you define. This means users are no longer limited to classical methods like Linear Regression, Logistic Regression, KNN, Naive Bayes, Kalman Filters, or Markov Chains. One can build adaptive architectures perfectly suited for custom indicators, strategies, regime detection, directional prediction, price transforms, and AI-assisted signal generation. Using NeuraLib, one can build a model, collect market data, normalize it, run predictions, train through backpropagation, track validation behavior, and update weights directly inside TradingView. Furthermore, it is not necessary to directly display trained variables. The process can be a part of a larger script functionality, where AI-powered decision making changes how an indicator behaves. The goal is to make real neural network workflows usable in Pine Script without hiding the important controls, being scalable with evolving market dynamics, and abstracting away the complexity that comes with such software. The provided API is highly modular and intuitive, using chained object-oriented programming for easy readability and use. The backend is engineered with fault-tolerance in mind, providing users with sanity checks and preventing common pitfalls by default. Think of NeuraLib as a comprehensive machine learning ecosystem, containing: A Model Builder : Define neural networks with readable chained calls like `.input()`, `.dense()`, and `.dropout()`. An In-Pine Training Engine : Models calculate losses, backpropagate gradients, update weights, and produce predictions directly on chart data. Automated Data Pipelines : Built-in datasets handle feature collection, robust scaling (Z-Score, Min-Max), validation holdout splits, and time-series rolling windows. Finance-Native Loss Functions : Beyond standard error metrics, the engine includes Directional, Quantile, Multi-Horizon Weighted, and Sharpe-style losses tailored for trading. Practical Training Controls : Layer Normalization, AdamW weight decay, gradient clipping, gradient accumulation, and early stopping are built in to prevent overfitting. Advanced Optimizers : Train networks using RMSProp, Adam, or AdamW, paired with learning rate schedules like Warmup Cosine and Step Decay. For newer users, this means you can start with a simple dense model. For advanced users, the same runtime exposes graph operations, custom blocks, tensors, matrix operations, optimizers, schedules, losses, and extension hooks. In plain terms, a model receives a row of numbers called features, compares its output against a target, measures the error with a loss function, and then adjusts its internal weights to reduce that error next time. ---------------------------------------------------------------------------------------------------------------- 🔷 WHAT MAKES IT DIFFERENT 🔸 Parity-tested neural math NeuraLib’s core operations have been tested against established Machine Learning Runtimes outside of TradingView (Such as Keras / TensorFlow / PyTorch). The goal was not to imitate the appearance of Machine Learning, but to reproduce the math that is proven to work. Standard forward passes, gradients, losses, and optimizer behavior were checked for 1:1 algorithmic parity, with negligible differences coming from normal floating-point behavior. That means the matrix math, backpropagation, and gradient updates running on your chart follow the same underlying logic expected from professional Machine Learning environments. 🔸 Matrix-first computation NeuraLib uses tensor and matrix abstractions as the foundation of the runtime. Under the hood, it supports the operations needed for neural computation, including matrix multiplication, broadcasting, activation functions, softmax, slicing, concatenation, reductions, normalization, attention scoring, convolution-style operations, and recurrent scan blocks. 🔸 Auto-differentiating graph engine NeuraLib makes the computational graph a first-class object. You can use high-level Sequential models, or build custom GraphBlocks from lower-level operations. Once a custom block is connected to a model, the same runtime handles the backward pass. That means your custom architecture can be trained with the same `.trainOnBatch()` workflow as standard layers. ---------------------------------------------------------------------------------------------------------------- 🔷 CUSTOM GRAPHS The Sequential API is the easiest way to start, but NeuraLib is not just a list of built-in layers. You can create a `GraphBlock`, add operations, set an output node, and plug that block into a model. Once connected, the runtime handles the backward pass and parameter updates. Useful graph operations include: Matrix multiplication, transpose, add, subtract, multiply, divide, and scale. Activation functions and softmax. Layer Normalization and Dropout. Causal masking, slicing, concatenation, row reduction, and column reduction. Global average pooling and global max pooling for 1D sequences. Attention score and attention apply operations. Conv1D, LSTM scan, and GRU scan primitives. This is the foundation that allows companion model libraries to add advanced AI and Machine Learning architectures without changing the main NeuraLib runtime. ---------------------------------------------------------------------------------------------------------------- 🔷 BUILT-IN DATA GUARDRAILS NeuraLib is not only a training mechanism. It also includes guardrails for cleaner research: Invalid rows are rejected : Dataset rows must match the configured feature and target counts, and rows containing `na` values are not inserted. Shape checks protect model calls : Forward, training, backward, and evaluation paths validate input and target shapes before running expensive graph code. Train and validation splits are separated : `trainBatch()` and `validationBatch()` use holdout rows instead of blending all rows into one batch. Scaler leakage is controlled : Validation batches are scaled from the training-side profile where the dataset split requires it, so validation normalization does not learn from the holdout slice. Rolling windows respect time order : `RollingDataset` supports target offsets and wrapped ring buffers while preserving chronological reads. These checks help reduce common data poisoning and data leakage mistakes: wrong row widths, missing values, validation contamination, target-offset leakage, and accidental overtraining across every historical bar. ---------------------------------------------------------------------------------------------------------------- 🔷 A FIRST MODEL The basic API is intentionally readable. This creates a small model with dropout, one hidden layer, Huber loss, AdamW optimization, and MAE tracking. //@version=6 indicator("NeuraLib Basic Model", overlay = false, calc_bars_count = 600) import Alien_Algorithms/NeuraLib/1 as nl var nl.Sequential model = nl.sequential("basic_model") var float modelOutput = na if barstate.isfirst nl.CompileConfig cfg = nl.compileConfig() cfg := cfg .optimizer(nl.adamW(0.001)) .loss(nl.LossKind.huber) .metric(nl.MetricKind.mae) .withTrainingGate(true) model := model .input(array.from(4), "features") .dropout(0.15) .dense(8, nl.ActivationKind.relu, "hidden") .dense(1, nl.ActivationKind.linear, "output") .compile(cfg) float rsiValue = ta.rsi(close, 14) float emaValue = ta.ema(close, 21) float atrValue = ta.atr(14) float atrPct = close == 0.0 ? 0.0 : atrValue / close float momentum = na(close ) or close == 0.0 ? 0.0 : close / close - 1.0 bool ready = not na(rsiValue) and not na(emaValue) and not na(atrPct) and not na(momentum) if ready float priceVsEma = emaValue == 0.0 ? 0.0 : close / emaValue - 1.0 nl.Tensor inputTensor = nl.vector(array.from(rsiValue, priceVsEma, atrPct, momentum), "features") nl.Tensor outputTensor = model.predict(inputTensor) modelOutput := outputTensor.get1d(0) plot(modelOutput, "Untrained model output", color = color.aqua, linewidth = 2) hline(0.0, "Zero", color = color.new(color.gray, 70)) The same model can then receive scaled batches from a dataset and train with `.trainOnBatch()`. The plot in this first example is the untrained forward output, included so the block can be pasted directly into an indicator. ---------------------------------------------------------------------------------------------------------------- 🔷 A PRACTICAL DATA FLOW Machine Learning models usually fail when the data pipeline is careless. Price, volume, volatility, and oscillators often live on very different scales. NeuraLib includes dataset and scaling helpers so the common workflow stays explicit: Build a feature row. Build a target row. Push the row into a dataset. Request a training batch. Request a validation batch when needed. Train, evaluate, predict, and inverse-scale targets when appropriate. //@version=6 indicator("NeuraLib Return Validation Example", overlay = false, calc_bars_count = 600) import Alien_Algorithms/NeuraLib/1 as nl var nl.Sequential model = nl.sequential("returns_model") var nl.WindowDataset dataset = nl.windowDataset(4, 1, 500, "returns_dataset") var float predictedReturn = na var float validationLossValue = na var float trainingLossValue = na if barstate.isfirst nl.CompileConfig cfg = nl.compileConfig() cfg := cfg .optimizer(nl.adamW(0.003)) .loss(nl.LossKind.huber) .metric(nl.MetricKind.mae) .trainEveryCall() model := model .input(array.from(4), "features") .dense(8, nl.ActivationKind.relu, "hidden") .dropout(0.10, "dropout") .dense(1, nl.ActivationKind.linear, "next_return") .compile(cfg) dataset := dataset .setInputScaler(nl.ScalerKind.zScore) .setTargetScaler(nl.ScalerKind.zScore) float rsiValue = ta.rsi(close, 14) float emaValue = ta.ema(close, 21) float atrValue = ta.atr(14) float atrPct = close == 0.0 ? 0.0 : atrValue / close float momentum = na(close ) or close == 0.0 ? 0.0 : close / close - 1.0 float realizedReturn = na(close ) ? na : nl.nextReturnValue(close , close) bool rowReady = not na(rsiValue ) and not na(emaValue ) and not na(atrPct ) and not na(momentum ) and not na(close ) if rowReady float prevEma = emaValue float priceVsEma = prevEma == 0.0 ? 0.0 : close / prevEma - 1.0 array features = array.from( rsiValue , priceVsEma, atrPct , momentum ) array target = array.from(nl.nextReturnValue(close , close)) dataset := dataset.pushRow(features, target) if dataset.ready(64) nl.Batch train = dataset.trainBatch(16) nl.Batch validation = dataset.validationBatch(16) model := model.trainOnBatch(train.inputTensor, train.targetTensor) trainingLossValue := model.trainStats.lastLoss nl.LossResult validationLoss = model.evaluate(validation.inputTensor, validation.targetTensor) validationLossValue := validationLoss.value bool liveReady = not na(rsiValue) and not na(emaValue) and not na(atrPct) and not na(momentum) if liveReady float livePriceVsEma = emaValue == 0.0 ? 0.0 : close / emaValue - 1.0 array liveFeatures = array.from(rsiValue, livePriceVsEma, atrPct, momentum) nl.Tensor liveInput = nl.vector(liveFeatures, "live_features") nl.Tensor scaledInput = dataset.scaleInput(liveInput) nl.Tensor scaledPrediction = model.predict(scaledInput) nl.Tensor rawPrediction = dataset.inverseScaleTarget(scaledPrediction) predictedReturn := rawPrediction.get1d(0) plot(realizedReturn, "Last realized return", color = color.gray) plot(predictedReturn, "Predicted next return", color = color.aqua, linewidth = 2) plot(validationLossValue, "Validation loss", color = color.orange) plot(trainingLossValue, "Training loss", color = color.new(color.blue, 35)) hline(0.0, "Zero", color = color.new(color.gray, 70)) This example trains from completed historical pairs. The feature row comes from the previous bar, and the target is the return from that previous bar to the current bar. That keeps the example easy to inspect and avoids using future information in the feature row. When pasted into an indicator, it plots the last realized return, the model's predicted next return, training loss, and validation loss. ---------------------------------------------------------------------------------------------------------------- 🔷 TWO PRACTICAL EXECUTION MODES Deep Learning in Pine requires careful execution control. NeuraLib supports two main workflows. 🔸 1. Live-edge training Use this when you want safer execution for larger models. The dataset can collect rows across the chart, while the expensive training step only runs on the last confirmed historical bar. This helps avoid timeouts while still allowing the model to learn from recent prepared data. cfg := cfg.withTrainingGate(true) Use this for: Larger models More features Rolling sequence inputs Heavier architectures Safer live-edge updates 🔸 2. Full-history training and inference Use this when the model is intentionally small. The model can train and infer across historical bars, which makes it possible to create lightweight adaptive indicators, such as an AI Moving Average that learns from recent local structure instead of using a fixed smoothing formula. cfg := cfg.trainEveryCall() Use this for: Tiny dense models Small batches Fast adaptive filters AI-assisted moving averages Lightweight feature transforms For full-history workflows, start small. A shallow model with 4 to 8 hidden units and a batch size of 8 or 16 is usually a better starting point than a deep architecture. ---------------------------------------------------------------------------------------------------------------- 🔷 ADVANCED MODEL EXPANSION NeuraLib is designed to act as the foundation for larger model libraries and community-built extensions. To demonstrate this, NeuraLib Expansion: Advanced Model Layers is built entirely on top of the public NeuraLib API and is launched in parallel on day one. The expansion library is published as NeuraLib_Models . It extends the runtime with higher-level builders for LSTMs, GRUs, temporal convolution stacks, residual dense blocks, dueling Q-heads for Reinforcement Learning, Transformer-style attention blocks, and Prioritized Experience Replay utilities. The important part is architectural: advanced models plug into the same runtime. NeuraLib remains the foundation for tensors, graph execution, optimization, training, inference, datasets, and scaling. After importing `NeuraLib_Models`, its fluent methods become available on NeuraLib `Sequential` models, so the expansion alias does not need to be referenced directly in the layer chain. //@version=6 indicator("NeuraLib Models Extension Demo", overlay = false, calc_bars_count = 600) import Alien_Algorithms/NeuraLib/1 as nl import Alien_Algorithms/NeuraLib_Models/1 as models var nl.Sequential model = nl.sequential("advanced_demo") if barstate.isfirst model := model .input(array.from(8), "sequence") .temporalConvStack(4, 2, 3, 2, 2, 1, nl.ActivationKind.relu, 0.0, "temporal") .globalAvgPool1d(2, 3, "pool") .duelingQHead(4, 2, nl.ActivationKind.relu, "q_head") .build(nl.rng(7)) ---------------------------------------------------------------------------------------------------------------- 🔷 FEATURE QUICK REFERENCE Runtime : Matrix-first auto-differentiating neural graph runtime for Pine Script. Model API : Chainable `Sequential` builder with `input`, `dense`, `dropout`, `layerNorm`, `activation`, `flatten`, `reshape`, and custom `block` support. Training : Forward pass, loss calculation, backpropagation, gradient accumulation, optimizer steps, train stats, and history buffers. Inference : `.predict()` for deterministic inference and `.predictMC()` for dropout-based uncertainty sampling. Datasets : `WindowDataset` for flat rows and `RollingDataset` for time-series windows. Scaling : None, Z-Score, Min-Max, Running Z-Score scalers, dataset input scaling, target scaling, and inverse target scaling. Optimizers : SGD, Momentum, RMSProp, Adam, and AdamW. Schedulers : Constant, Step Decay, Cosine Decay, and Warmup Cosine. Activations : Linear, ReLU, Leaky ReLU, ELU, GELU Approx, Sigmoid, Tanh, Softplus, Swish, and Softmax. Losses : MSE, MAE, Huber, LogCosh, Binary Cross Entropy, Binary Cross Entropy From Logits, Categorical Cross Entropy, Softmax Cross Entropy From Logits, Directional, Quantile, Multi-Horizon Weighted, and Sharpe. Metrics : MAE, RMSE, Directional Accuracy, Binary Accuracy, Binary Accuracy From Logits, Categorical Accuracy, and Cosine Similarity. Guardrails : Shape validation, invalid-row rejection, train/validation split helpers, leakage-aware scaler profiles, training gates, gradient clipping, and EarlyStopper. Advanced expansion : Conv1D, temporal stacks, recurrent blocks, attention, Transformers, dueling Q-heads, positional encodings, and Prioritized Experience Replay. ---------------------------------------------------------------------------------------------------------------- 🔷 IMPORTANT CONSIDERATIONS Start small : Pine Script is not a GPU training environment. Compact models are the right starting point. Control chart history : Use `calc_bars_count = 600` in `indicator()` when needed to balance available training history against model size and execution time. Use the training gate : For heavier models, use `.withTrainingGate(true)` so backpropagation runs only at the confirmed historical edge. Scale your inputs : Raw market features often differ by orders of magnitude. Use dataset scalers unless you have a deliberate reason not to. Validate separately : Use `trainBatch()` and `validationBatch()` to monitor generalization instead of only watching training loss. Avoid lookahead : Build feature rows only from information available at the time of the row. Use completed target rows for training. Treat outputs as research signals : NeuraLib provides model mechanics. Strategy design, risk management, and market assumptions remain the user's responsibility. ---------------------------------------------------------------------------------------------------------------- 🔷 API REFERENCE 🔸 Model Setup sequential(name) : Creates an empty `Sequential` model. compileConfig() : Creates a model configuration object. build(rng) : Builds model parameters with a deterministic random stream. compile(config) : Builds the model when needed and applies the training configuration. rng(seed, streamId) : Creates a deterministic random stream. 🔸 Sequential Methods input(dimsArray, name) : Defines the input shape. dense(units, activation, name) : Adds a fully connected layer. qHead(actionCount, activation, name) : Adds a Q-value output head. activation(activationKind, alpha, name) : Adds an activation block. dropout(rate, name) : Adds dropout regularization. layerNorm(name) : Adds layer normalization. flatten(name) and reshape(outputDimsArray, name) : Adjust model shape metadata. block(graphBlock) : Adds a custom `GraphBlock`. trainOnBatch(inputTensor, targetTensor) : Runs training when the active gate allows it. backward(targetTensor) : Accumulates gradients from the last forward pass without stepping. step() : Applies the optimizer step to accumulated gradients. predict(inputTensor) : Runs inference. predictMC(inputTensor, samples) : Runs dropout-enabled Monte Carlo prediction and returns mean and variance. evaluate(inputTensor, targetTensor) : Calculates loss without updating weights. fitDataset(dataset) and fitRollingDataset(dataset, targetOffset) : Train through dataset adapters. getWeightsArray() and setWeightsArray(weightsArray) : Export and import flat model weights. softUpdateFrom(sourceModel, tau) : Soft-update parameters from another model. 🔸 CompileConfig Methods optimizer(optimizerState) : Sets the optimizer. schedule(scheduleState) : Sets the learning-rate schedule. loss(lossKind) : Sets the training loss. reduction(reductionKind) : Sets loss reduction behavior. metric(metricKind) : Adds a metric. batchSize(size) , epochsPerBar(count) , evalStride(stride) , and historyLength(length) : Store batch and cadence preferences, and set the metric history length. clipNorm(value) and clipValue(value) : Apply gradient clipping. gradAccumSteps(steps) : Accumulates gradients before stepping. withTrainingGate(enabled) : Restricts training to the last confirmed historical bar when enabled. trainEveryCall() : Allows training whenever `.trainOnBatch()` is called. presetPriceRegression() , presetReturnRegression() , presetBinaryDirection() , presetBinaryDirectionLogits() , presetQValues() , and presetSharpe() : Apply common loss and metric presets. 🔸 Datasets windowDataset(featureCount, targetCount, maxRows, name) : Stores flat feature and target rows. rollingDataset(timeSteps, featureCount, targetCount, maxRows, name) : Stores time-series windows. pushRow(featureArray, targetArray) : Adds one validated row. pushBuilderRow(featureBuilder, targetArray) : Adds a row from a `FeatureBuilder`. pushNextReturnRow(featureBuilder, currentValue, futureValue) : Adds a next-return target. pushNextDirectionRow(featureBuilder, currentValue, futureValue, threshold, zeroOne) : Adds a direction target. ready(minRows or minWindows, targetOffset) and size() : Check dataset readiness. lastBatch(batchSize) : Returns the most recent scaled rows from a `WindowDataset`. toBatch() : Returns all rows from a `WindowDataset`. unrollBatch(targetOffset) : Returns all rolling windows from a `RollingDataset`. trainBatch(validationRows or validationWindows, targetOffset) : Returns the training side of the split. validationBatch(validationRows or validationWindows, targetOffset) : Returns the validation side of the split. setInputScaler(kind) , setTargetScaler(kind) , scaleInput(tensor) , scaleTarget(tensor) , and inverseScaleTarget(tensor) : Configure and apply scaling. clear() : Clears stored rows. 🔸 Tensor, Matrix, and Feature Helpers scalar(value) , vector(valuesArray) , matrix2d(rows, cols, fillValue) , zeros(shape) , ones(shape) , and full(shape, fillValue) : Create tensors. shapeFromDims(dimsArray) : Creates a shape. matrixTensor(tensor) , matrixTensor2d(rows, cols, fillValue) , and matrixTensorFromMatrix(sourceMatrix) : Create matrix tensors. reshape(dimsArray) , flatten() , row(rowIndex) , get1d(index) , sum() , mean() , variance() , normL2() , argmax() , and dot(other) : Tensor methods. matmul() , transpose() , add() , subtract() , multiply() , divide() , scale() , activate() , softmax() , sliceRows() , sliceCols() , concatRows() , concatCols() , globalAvgPool1d() , and globalMaxPool1d() : MatrixTensor methods. featureBuilder(name) , push(value, featureName) , addFeature(value, featureName) , toTensor(tensorName) , toArray() , size() , and clear() : Feature row helpers. 🔸 Scalers, Optimizers, and Schedules zScoreScaler() , minMaxScaler() , runningZScoreScaler() , and noneScaler() : Standalone scaler states. fit(tensor) , partialFit(tensor) , transform(tensor) , and inverseTransform(tensor) : Scaler methods. sgd(learningRate) , momentum(learningRate, momentum) , rmsprop(learningRate, rho, epsilon) , adam(learningRate, beta1, beta2, epsilon) , and adamW(learningRate, beta1, beta2, epsilon, weightDecay) : Optimizers. constantSchedule(learningRate) , stepDecay(baseLearningRate, decaySteps, gamma) , cosineDecay(baseLearningRate, minLearningRate, decaySteps) , and warmupCosine(baseLearningRate, minLearningRate, warmupSteps, decaySteps) : Schedules. currentRate(stepCount) : Reads a schedule's learning rate at a step. paramBank() , append() , zeroGrad() , globalGradNorm() , step(optimizerState) , and softUpdateFrom(sourceBank, tau) : Low-level parameter bank utilities. 🔸 Losses and Metrics mse() , mae() , huber() , logCosh() , binaryCrossEntropy() , binaryCrossEntropyFromLogits() , categoricalCrossEntropy() , softmaxCrossEntropyFromLogits() , directionalLoss() , quantileLoss() , multiHorizonWeighted() , and sharpeLoss() : Direct loss helpers. metricValue(metricKind, predictionTensor, targetTensor) : Direct metric helper. earlyStopper(patience, minDelta) , update(validationLoss) , and reset() : Validation stopping helper. nextReturnValue(currentValue, futureValue) and nextDirectionValue(currentValue, futureValue, threshold, zeroOne) : Common target helpers. 🔸 GraphBlock Operations graphBlock(name) : Creates a custom trainable graph block. input() , param() , constScalar() , constMatrix() , and output() : Define graph inputs, parameters, constants, and output metadata. matmul() , add() , subtract() , multiply() , divide() , scale() , activate() , softmax() , transpose() , layerNorm() , and dropout() : NeuraLib graph math. causalMask() , sliceRows() , concatRows() , sliceCols() , concatCols() , reduceRows() , and reduceCols() : Structural graph operations. globalAvgPool1d() , globalMaxPool1d() , attentionScore() , attentionApply() , conv1d() , scanLstm() , and scanGru() : Sequence and architecture primitives. 🔸 NeuraLib_Models API prioritizedReplayBuffer(featureCount, targetCount, maxRows, name) : Creates a replay buffer. pushExperience(featureRowArray, targetRowArray, priority) , sampleBatch(batchSize, alpha, beta, seed) , updatePriority(index, priority) , toBatch() , ready(minRows) , size() , and clear() : Prioritized Experience Replay helpers. pushPositionalEncoding(position, dimensions, maxPeriod, featurePrefix) : Adds positional encoding values to a `FeatureBuilder`. residualDense() , duelingQHead() , conv1d() , temporalConvStack() , globalAvgPool1d() , globalMaxPool1d() , lstm() , gru() , selfAttention() , multiHeadSelfAttention() , crossAttention() , transformerEncoder() , transformerEncoderStack() , and transformerDecoder() : NeuraLib_Models `Sequential` methods. NeuraLib is for Pine Script developers who want to move beyond fixed formulas and experiment with real neural network workflows directly inside TradingView. It is a research framework, not a guarantee of market performance. Use validation, avoid lookahead, control risk, and keep models small enough for Pine's execution limits. All the diagrams in this publication are rendered natively on TradingView using Pine3D ---------------------------------------------------------------------------------------------------------------- This work is licensed under (CC BY-NC-SA 4.0) , meaning usage is free for non-commercial purposes given that Alien_Algorithms is credited in the description for the underlying software. For commercial use licensing, contact Alien_Algorithms
Pine Script® library
by Alien_Algorithms
7
TP_Ephem_LibLibrary "TP_Ephem_Lib" Cowan-tailored heliocentric ephemeris (VSOP87D) for TradingView. @description Returns heliocentric ecliptic longitudes for Mercury through Neptune @description (tropical or sidereal/Lahiri), synodic phases between any two planets, @description and Cowan-canon helpers: 3-Step Astro cumulative advance (V4:L5079), @description pentagram vertex dates (V4:L449), and cube-face boundary dates @description (V1:L2106-2114, V1:L2962-2997). All math validated to <0.01 deg vs @description Swiss Ephemeris (DE441) across 1899-2026. Frame: ecliptic of date. jd_to_t_millennia(jd)   Parameters:      jd (float) jd_from_timestamp(unix_ms)   Parameters:      unix_ms (int) timestamp_from_jd(jd)   Parameters:      jd (float) normalize_longitude(deg)   Parameters:      deg (float) get_ayanamsa(jd)   Parameters:      jd (float) get_helio_longitude(planet, jd, useSidereal)   Parameters:      planet (simple Planet)      jd (float)      useSidereal (simple bool) get_sun_geo_longitude(jd, useSidereal)   Parameters:      jd (float)      useSidereal (simple bool) get_synodic_phase(p1, p2, jd)   Parameters:      p1 (simple Planet)      p2 (simple Planet)      jd (float) get_aspect_angle(p1, p2, jd)   Parameters:      p1 (simple Planet)      p2 (simple Planet)      jd (float) average_speed_deg_per_day(planet)   Parameters:      planet (simple Planet) speed_deg_per_day(planet, jd)   Parameters:      planet (simple Planet)      jd (float) is_retrograde(planet, jd)   Parameters:      planet (simple Planet)      jd (float) cumulative_advance_deg(planet, origin_jd, target_jd, useSidereal)   Parameters:      planet (simple Planet)      origin_jd (float)      target_jd (float)      useSidereal (simple bool) cumulative_synodic_advance_deg(p1, p2, origin_jd, target_jd)   Parameters:      p1 (simple Planet)      p2 (simple Planet)      origin_jd (float)      target_jd (float) find_advance_jd(planet, origin_jd, target_advance_deg, useSidereal)   Parameters:      planet (simple Planet)      origin_jd (float)      target_advance_deg (float)      useSidereal (simple bool) find_synodic_advance_jd(p1, p2, origin_jd, target_synodic_advance_deg)   Parameters:      p1 (simple Planet)      p2 (simple Planet)      origin_jd (float)      target_synodic_advance_deg (float) pentagram_vertex_jd(planet, origin_jd, n, useSidereal)   Parameters:      planet (simple Planet)      origin_jd (float)      n (simple int)      useSidereal (simple bool) cube_face_boundary_jd(origin_jd, face_n)   Parameters:      origin_jd (float)      face_n (simple int)
Pine Script® library
by Anant_Acharya
RandomForestLibraryRandomForestLibrary is a self-contained Random Forest library for Pine Script v6 that other Pine developers can import and use to build their own machine learning indicators and strategies. What Makes This Different Random Forest is one of the most widely used ensemble methods in applied machine learning. Until now, Pine Script developers wanting to use it had only two choices: call out to an external Python / ONNX pipeline, or hand-roll a single decision tree inline. This library closes that gap by providing a complete Random Forest implementation — CART trees, bootstrap aggregation, Gini / MSE splitting, out-of-bag scoring, weighted feature importance — reachable with a few lines of import code. The API intentionally mirrors scikit-learn's RandomForestClassifier and RandomForestRegressor (init → fit → predict → evaluate), so practitioners already familiar with scikit-learn can translate existing logic directly. What This Library Provides Binary classification: fit(X, y) , predict , predict_proba , predict_batch , oob_score Multi-output regression: fit_regressor(X, Y) , predict_multi , predict_multi_per_tree , oob_r2 , oob_residual_std Weighted Gini / MSE feature importance: feature_importance() Deterministic Park-Miller RNG for reproducible forests Exported Types Forest — the ensemble model. Holds all trees, hyperparameters, training data references, OOB accumulators, and feature importances. Tree — a single decision tree with its node array, max depth, leaf count, and split-failure count. Node — a single node storing feature index, threshold, children indices, leaf label / probability, Gini impurity (or MSE in regressor mode), sample count, and a per-horizon output array for regression. RNG — a Park-Miller linear congruential generator with a=48271, m=2^31-1. Deterministic given the same seed. Exported Methods Initialization and training init(n_estimators, max_depth, max_features, min_samples_leaf, n_threshold_candidates, seed) — configure hyperparameters. max_features=0 auto-selects ceil(sqrt(n_features)) for classification and ceil(n_features/3) for regression. fit(X, y) — train classifier on a feature matrix X (rows = samples, columns = features) and integer label array y (values 0 or 1). fit_regressor(X, Y) — train multi-output regressor. Y is a matrix whose columns are separate regression horizons / targets. Inference predict(sample) — classify a single sample via soft voting (threshold 0.5). predict_proba(sample) — average class-1 probability across all trees. predict_batch(X) — classify every row of a matrix. predict_multi(sample) — regressor output: averaged per-horizon predictions. predict_multi_per_tree(sample) — per-tree, per-horizon predictions for custom uncertainty analysis. tree_predict , tree_predict_proba , tree_predict_multi — single-tree inference for advanced use. Evaluation oob_score() — classification out-of-bag accuracy (0.0 to 1.0), computed by soft voting on samples not selected in each tree's bootstrap. oob_r2() — regression out-of-bag R^2, averaged across horizons. oob_residual_std() — per-horizon standard deviation of OOB residuals. Useful for prediction interval construction (Wager, Hastie, and Efron 2014). feature_importance() — normalized weighted Gini (or MSE) decrease per feature, averaged across trees. Sums to approximately 1.0. How It Works Tree construction (CART, iterative, level-by-level) Each tree is built top-down, one depth level at a time, using complete binary tree indexing ( left = 2i+1 , right = 2i+2 ). At every internal node: A random subset of features of size max_features is drawn without replacement. For each feature, n_threshold_candidates thresholds are sampled uniformly between the feature's min and max on the samples at that node. For classification, the split minimizing weighted Gini impurity is chosen. For regression, the split minimizing weighted MSE (summed over all horizons) is chosen. A node becomes a leaf when it is pure (classification), too small ( n < 2 * min_samples_leaf ), at max depth, or when no valid split exists. Bootstrap aggregation and OOB Each tree is trained on a bootstrap sample (same size as the training set, sampled with replacement). Samples that were not drawn for a given tree become its out-of-bag set and are used to compute unbiased performance estimates ( oob_score / oob_r2 ) and residual variance ( oob_residual_std ), avoiding the need for a separate holdout. Feature importance Each split records its weighted impurity decrease ( n_node * impurity_node - n_left * impurity_left - n_right * impurity_right ). Per-tree importances are normalized to sum to 1, then averaged across trees — matching scikit-learn's definition. Quick Start //@version=6 indicator("My RF Indicator") import ShigemiQuant/RandomForestLibrary/2 as RF // 1. Build feature matrix X and label array y over recent bars // (not shown: accumulate features into a matrix) // 2. Initialize and train var RF.Forest model = RF.Forest.new().init( n_estimators = 10, max_depth = 4, seed = 42) if barstate.islast model.fit(X, y) // 3. Predict on current bar array sample = array.from(rsi_val, atr_pct, cci_val, adx_val) float prob = model.predict_proba(sample) // 4. Evaluate float oob = model.oob_score() label.new(bar_index, close, "prob=" + str.tostring(prob, "#.##") + " oob=" + str.tostring(oob, "#.##")) Compatibility Notes scikit-learn parity : same init → fit → predict / predict_proba workflow, same default for max_features , OOB uses soft voting, importances use weighted Gini decrease. Determinism : given identical seed , training set, and hyperparameters, the resulting forest and all predictions are bit-identical across reruns. Binary classification only in fit() : labels must be 0 or 1. Multi-class is not yet supported. Numeric features only : all columns of X must be float . Limitations This is a machine-learning library , not a trading signal. Indicators built with it make no guarantee of profit, do not predict the future, and depend entirely on the quality of the features, labels, and hyperparameters that the caller supplies. Binary classification only in fit() (labels must be 0 or 1); multi-class is not supported. Regression via fit_regressor() supports multi-output targets but assumes they are numeric float values. TradingView runtime budget limits tree size. A reasonable starting point is n_estimators between 5 and 20 with max_depth between 3 and 6. Total node budget per tree is 2^(max_depth+1) - 1 — depth 6 allows up to 127 nodes per tree, and 15 trees means up to roughly 1,905 nodes total. Large training sets combined with deep trees (thousands of bars × depth 6) can hit Pine Script's loop iteration caps. Start small and scale up while watching compile / runtime warnings. OOB metrics ( oob_score , oob_r2 , oob_residual_std ) are valid only when each sample is out-of-bag in at least one tree. For very small training sets or very few estimators, some samples may never be OOB and those metrics will be biased or undefined. Overfitting is the caller's responsibility. The library exposes standard controls ( max_depth , min_samples_leaf , max_features , n_estimators ) but applies no automatic regularization. Trees that are too deep on a noisy training window will memorize noise. Features must be stationary enough to generalize. Raw price levels or unnormalized indicators that drift with the market will cause training-test distribution shift. Prefer bounded or ratio-based features (RSI, ATR%, percentile ranks). Training happens on the chart's own bar history. There is no external data upload; the library cannot import pre-trained models, and the forest must be rebuilt whenever the script recomputes. Designs that rely on very large historical context may conflict with Pine Script's bar-history window. References Breiman, L. (2001). Random Forests. Machine Learning, 45(1), 5–32. Wager, S., Hastie, T., and Efron, B. (2014). Confidence Intervals for Random Forests: The Jackknife and the Infinitesimal Jackknife. Journal of Machine Learning Research, 15, 1625–1651. Disclaimer This library is an educational and research tool. It does not constitute financial advice. All trading decisions based on code built with this library are the sole responsibility of the user. Past model performance does not guarantee future results.
Pine Script® library
by ShigemiQuant
Pine3D: A Native 3D Graphical Rendering EnginePine3D is a full 3D rendering engine for TradingView, powered by Pine Script™ v6. Pine3D pushes forward the frontier of TradingView 3D rendering capabilities, providing a fully fledged graphical engine under an intuitive, chainable, object oriented API. Build meshes, transform them in world space, light them, cast shadows, project them through a perspective camera, and render the result directly on your chart, all without ever bothering about trigonometry synchronization or optimization. The library brings forth a streamlined process for anyone that wishes to visualize data in 3D, without needing to know anything about the complex math that has previously gatekept such indicators. Pine3D does all the heavy lifting, including extreme optimization techniques designed for production ready indicators. The entire API is chainable and tag addressable, so spawning a mesh, registering it, pointing the camera at it, and rendering the frame is a four line affair: Mesh mybox = cube(40.0, color.orange).setTag("hero").rotateBy(0.0, 45.0, 0.0) scene.add(mybox) scene.lookAt("hero") render(scene) 🔷 SURFACES: CONTOUR BAND RENDERING Pine Script imposes a hard ceiling of 100 polylines and 500 lines per indicator . On the surface this looks fatal for dense 3D meshes: every triangle drawn naively burns one of those 100 slots, or two of the 500, and the budget evaporates within a few hundred faces. The conventional escape hatch is strip stitching , tracing a polyline forward along one row of a grid and back along the next, packing a ribbon of quads into a single drawing slot. It buys a meaningful multiplier, but it pays for that multiplier with two structural constraints baked into the geometry itself: One color per strip. A polyline carries a single stroke and fill color, so every cell along the ribbon must share the same shade. The moment you want per cell lighting, contour banding, or value driven gradients, every color change forces a new polyline and the budget collapses. One contiguous ribbon per slot. Strips can only describe topologically connected runs of cells. Disjoint regions, holes, islands, and value clustered fragments scattered across the surface each demand their own polyline. Pine3D breaks both constraints at once. At the core of the engine sits an innovation that redefines the limits for visual fidelity: contour band rendering using degenerate bridge stitching . The technique quantizes a surface's elevation into colored bands, then collapses every cell that falls inside the same band, no matter where it sits on the screen , into one continuous, hole aware polyline path per band, threading invisible zero width bridges between disjoint islands so that a single polyline can carry thousands of polygon equivalent fragments scattered across the geometry. The result: A single polyline can render up to 2,000 disconnected triangle equivalents , spread across arbitrarily separated regions of the surface. Theoretical ceiling of around 200,000 disconnected faces inside the 100 polyline budget, a regime that strip based stitching cannot enter at any color count above one. A 40 x 40 heightmap (around 3,000 triangles) renders inside the budget with full per band contour coloring and room to spare. Stress harnesses have run 40 x 80 grids . Each band's path is depth sorted and near plane culled, and cached between bars , so once geometry is built only the screen space projection runs per frame. This algorithm enables scenes with extreme detail relative to the 100 polyline limit, and shifts the optimization focus from "drawing limits" to "CPU limits", which Pine3D natively handles with aggressive caching at every layer of the pipeline. The contour technique is currently integrated into the surface() function, with the same compression strategy generalizable to any mesh class and ultimately full scene rendering in future versions. Non-uniform grids out of the box. surface() accepts optional axisX and axisZ arrays that override the default uniform spacing with custom column and row positions. This means logarithmic strike spacing on an option volatility surface, irregular timestamp spacing on a market depth heatmap, or any other non-evenly-sampled grid renders correctly without resampling the data first. The contour band engine, axis ticks, and gridBox cage all snap to the custom positions automatically. A full contour surface is just a handful of lines; the damped ripple below builds once and never needs updating: //@version=6 indicator("Pine3D - Contour Surface", overlay = false, max_polylines_count = 100, max_lines_count = 500, max_labels_count = 500) import Alien_Algorithms/Pine3D/1 as p3d var p3d.Scene scene = p3d.newScene() var p3d.Mesh heatmap = na if barstate.isfirst // Damped cosine ripple int N = 20 matrix data = matrix.new(N, N, 0.0) for r = 0 to N - 1 for c = 0 to N - 1 float dx = c - (N - 1) / 2.0 float dz = r - (N - 1) / 2.0 float d = math.sqrt(dx * dx + dz * dz) * 0.7 data.set(r, c, math.cos(d) * math.exp(-d * 0.12) * 50.0) heatmap := p3d.surface(data, 200.0, color.blue, color.red, 24) .gridBox() .gridLabels(color.white, "X", "Amplitude", "Z") scene.add(heatmap) scene.camera.orbit(35.0, 25.0, 380.0) if barstate.islast p3d.render(scene, lighting = true) 🔷 TRAIL3D: STREAMED OSCILLATOR PATHS Trail3D is a first class streaming primitive built for visualizing two correlated time series as a 3D ribbon evolving through time. You give it a rolling buffer capacity and push (u, v) samples bar by bar; the primitive maintains the buffer, builds the ribbon geometry, and renders it inside a normalized bounding cube so the path always fits cleanly in view regardless of the underlying data range. Under the hood, Trail3D is a coordinated bundle of polylines: one for the main ribbon, two for optional shadow projections onto the back wall and floor, and one for the wireframe cage. All four are depth sorted and occlusion clipped against the rest of the scene, and the primitive auto normalizes incoming samples against the rolling window's min/max so streaming data always fills the cube without manual scaling. This enables a class of visualizations that would otherwise require dozens of polylines and manual buffer management: phase space portraits, Lissajous figures, oscillator pair correlations, attractor trajectories, and any "two indicators evolving together over time" study. The demo above shows a sine and cosine pair pushing samples each bar to trace a clean spiral inside the cage, the same pattern you would use to plot RSI vs MFI, momentum vs volatility, or any custom (u, v) signal pair. A full streamed scene is a handful of lines: //@version=6 indicator("Pine3D - Trail3D", overlay = false, max_polylines_count = 100, max_lines_count = 500, max_labels_count = 500) import Alien_Algorithms/Pine3D/1 as p3d var p3d.Scene scene = p3d.newScene() var p3d.Trail3D trail = na if barstate.isfirst trail := p3d.trail3D(220.0, 200, color.yellow) .cage(true) .axisLabels("sin", "cos", color.white) trail._uProj.col := #00ffff69 trail._vProj.col := #ff00ff71 scene.add(trail) scene.camera.orbit(215.0, 20.0, 360.0) float phase = bar_index * 0.15 float sinX = math.sin(phase) * 100.0 float cosY = math.cos(phase) * 100.0 if barstate.isconfirmed trail.pushSample(sinX, cosY) p3d.render(scene) 🔷 BARS3D: CATEGORICAL 3D BAR CHARTS bars3D() turns any series of values into a fully lit, depth sorted 3D bar chart in a single call. Each bar is height mapped to its value, color graded between a low and high color, and packed into one combined mesh with per bar depth grouping so individual bars sort correctly even inside the merged geometry. The companion updateBars() mutator refreshes heights, colors, and labels in place every bar without rebuilding geometry, making it suitable for live rankings, rolling windows, and animated comparisons. The chainable barLabels(catNames, valNames) helper attaches category labels at the base of each bar and value labels at the top, both depth sorted with the rest of the scene. Category labels are set once at build time, while value labels can be passed to updateBars(values, valLabels = ...) each frame to reflect live data. Combined with wireGrid() for the floor and a contour surface() in the background, bars3D() becomes the centerpiece of dashboards comparing assets, sectors, timeframes, or any categorical metric. Negative values are handled automatically: bars below zero extrude downward from the base plane with reversed face winding, so signed series like PnL, delta, or momentum histograms render correctly without any extra setup. A complete labeled bar chart is just a few lines: //@version=6 indicator("Pine3D - Bars3D", overlay = false, max_polylines_count = 100, max_lines_count = 500, max_labels_count = 500) import Alien_Algorithms/Pine3D/1 as p3d var p3d.Scene scene = p3d.newScene() var p3d.Mesh bars = na array values = array.from(volume - volume , volume - volume , volume - volume , volume - volume , volume - volume , volume - volume ) array names = array.from("ΔV0", "ΔV-1", "ΔV-2", "ΔV-3", "ΔV-4", "ΔV-5") if barstate.isfirst bars := p3d.bars3D(values, 30.0, 30.0, 10.0, color.blue, color.red, 200.0) .barLabels(names) scene.add(bars) p3d.wireGrid(scene, 300.0, 300.0, 6, 6, color.new(color.gray, 80)) scene.camera.orbit(215.0, 25.0, 360.0) if barstate.islast bars.updateBars(values) p3d.render(scene, lighting = true) Omitting valLabels in updateBars() tells the engine to auto format each numeric value via str.tostring() . Pass valLabels only when you need custom strings. 🔷 SCATTER CLOUDS: POINTS IN 3D SPACE Pine3D treats scatter clouds as a first class use case without needing a dedicated scatter API. Because Label3D is the primitive and scene.add(array) is a single batch operation, you can scatter up to 500 points anywhere in 3D space, each with independent color, symbol, size, and tooltip , and have them depth sorted and occlusion clipped against the rest of the scene automatically. Each point is a fully addressable Label3D with mutable fields. You can change position , textColor , bgColor , labelStyle (any label.style_* glyph including circles, squares, diamonds, triangles, crosses, arrows, flags), labelSize (any size.* preset), and text per point per bar. The renderer reads these mutations every frame, so animation is just direct field assignment. This unlocks a wide class of visualizations: clustered data scatter, K means visualizations, particle systems, parametric surfaces sampled as point clouds, gradient colored attractors, multi class classification overlays, and structured curves like the demo above. The double helix demo plots two intertwined parametric strands as ~500 points with alternating colors and per point sizing, all inside the standard scene.add(array) pipeline. The pattern is straightforward: build the array once in barstate.isfirst , add it to the scene, then mutate point fields per bar to animate. //@version=6 indicator("Pine3D - Scatter Cloud", overlay = false, max_polylines_count = 100, max_lines_count = 500, max_labels_count = 500) import Alien_Algorithms/Pine3D/1 as p3d var p3d.Scene scene = p3d.newScene() var array points = array.new() if barstate.isfirst for i = 0 to 499 p3d.Vec3 pos = p3d.vec3(0.0, 0.0, 0.0) points.push(p3d.Label3D.new(position = pos, txt = "•")) scene.add(points) scene.camera.orbit(35.0, 20.0, 400.0) if barstate.islast for i = 0 to points.size() - 1 float t = i * 0.05 + bar_index * 0.01 p3d.Label3D pt = points.get(i) pt.position := p3d.vec3(80.0 * math.cos(t), i * 0.4 - 100.0, 80.0 * math.sin(t)) pt.textColor := i % 2 == 0 ? color.aqua : color.fuchsia p3d.render(scene) ---------------------------------------------------------------------------------------------------------------- 🔷 TWO LAYER ARCHITECTURE Pine3D ships as a clean, two layer library: 🔸 Layer 1 - DIY API. First principle building blocks ( Vec3 , Mesh , Camera , Light , Scene , plus world space overlay primitives) for total creative control. Author your own geometry, camera behavior, lighting setup, and scene graph from scratch. 🔸 Layer 2 - High Level Helpers. Production ready wrappers like surface() , bars3D() , trail3D() , updateBars() , updateSurface() , sphere() , torus() , cylinder() , and wireGrid() , plus chainable contour helpers gridBox() and gridLabels() that wrap the primitives into a few lines of code. Scatter clouds use the standard Label3D primitive directly. The object model is chainable and scene oriented, so complex setups still read cleanly. 🔷 FEATURE LIST Contour Surface Rendering - The most powerful 3D surface engine ever released for Pine Script. Render tens of thousands of polygon equivalent faces using a single polyline per contour band, delivering smooth, continuous terrain with natural ridges and valleys. Adaptive Rail Sharing - Solid meshes drawn with the default linefill backend reuse one edge line between adjacent coplanar faces, averaging roughly 1.6 lines per face instead of the naive two, pushing practical mesh capacity up to ~360 faces depending on topology. Interior Face Culling on Merge - mergeMeshes(meshes, removeInterior = true) detects coincident faces with opposing normals and strips them, so voxel style scenes (stacked cubes, block walls, lattice geometry) ship only their exterior shell and spend no budget on hidden interior faces. True Perspective Camera System - Full 3D camera with position, target, fov, and orbit() controls. Supports cinematic camera movement, lookAt by mesh tag, and realistic depth. Real Time Lighting and Shadows - Directional and point lights with configurable ambient, shadow strength, self shadowing, and a spatial grid acceleration structure for fast shadow queries. High Performance Update System - updateSurface() and updateBars() let you animate massive datasets bar by bar without rebuilding geometry, keeping CPU usage minimal. Rich Primitive Library - Cubes, cuboids, spheres, cylinders, tori, pyramids, planes, discs, circles, custom meshes, and the groundbreaking bars3D() with automatic labels. Streamed Trail Primitive - trail3D() maintains a rolling buffer of (u, v) samples and renders them as a 3D ribbon inside a bounding cube, with optional projections onto the back wall and floor and a wireframe cage. Depth Sorted Overlays - 3D labels, lines, polylines, wire grids, and trails, all correctly occluded and painter sorted against the rest of the scene. Professional Contour Helpers - gridBox() and gridLabels() automatically add clean bounding boxes and axis titles, ticks, and series names that refresh on every updateSurface() call. Tag Based Scene Graph - Every Mesh , Label3D , Line3D , and Polyline3D can carry a string tag. Scene exposes getMesh() , getLabel() , getLine() , getPolyline() , lookAt() , and remove() by tag, turning your scene into a lookup by name graph instead of an index juggling exercise. Chainable, Intuitive API - Everything is designed for maximum readability and speed of development. Build complex scenes in just a few lines. Production Ready Optimizations - World vertex caching, view projection caching, face preprocessing cache, shadow grid cache, and contour geometry cache, all managed automatically. ---------------------------------------------------------------------------------------------------------------- 🔷 THE RENDERER Every frame is produced by a single call to render(scene, ...) . The renderer runs the full pipeline: world transform, camera transform, back face culling, occlusion culling, depth sort, directional or point lighting with shadows, and perspective projection. ⚠ render() clears the entire chart drawing pool at the start of every call - every polyline , line , label , and linefill on the chart is deleted before Pine3D redraws, not just the ones it created. If you mix Pine3D with manual label.new() , line.new() , or similar calls, those drawings must be emitted after render() or they will be wiped every frame. 🔸 Setup Requirements. Pine3D consumes polylines, lines, and labels simultaneously, so your indicator() declaration must raise all three budgets, and the library must be imported under an alias: indicator("My 3D Scene", overlay = false, max_polylines_count = 100, max_lines_count = 500, max_labels_count = 500) import Alien_Algorithms/Pine3D/1 as p3d 🔸 render() parameters. maxFaces (int, default 100). Hard cap on solid faces drawn per frame. Contour bands, wireframe edges, labels, lines, and overlay polylines are not counted against this cap, and are bounded only by TradingView's global 100 polyline / 500 line / 500 label budgets. culling (bool, default true). Enable back face culling. lighting (bool, default false). Enable diffuse shading. Reads scene.light if set; otherwise falls back to the render() args. lightDir (Vec3). Overrides scene.light.direction when provided. Points toward the light. ambient (float, default 0.3). Minimum brightness for shadowed faces (0.0-1.0). wireframe (bool, default false). Force outline only output for the entire scene. occlusion (bool, default true). Sparse raster pass that drops hidden faces before drawing. Major perf win on dense scenes. occlusionRaster (int, default 768). Raster resolution of the occlusion buffer. Lower = faster but coarser; higher = stricter hidden face rejection. Explicit render() args always win over scene.light , which makes render() the right place for ad hoc, per frame lighting tweaks. ---------------------------------------------------------------------------------------------------------------- 🔷 MESH DRAWING MODES Two independent axes control how a mesh appears on the chart: 🔸 Style (via mesh.setStyle(...) ) - what gets drawn: "solid" . Filled faces. Default. "wireframe" . All edges, no fill. Shows interior geometry. "wireframe_front" . Only front facing edges. Cleaner silhouette for convex meshes. 🔸 Draw Mode (via mesh.drawMode ) - which TradingView primitive carries the solid faces: "linefill" (default). Uses the line and linefill budgets. An adaptive rail sharing optimization reuses one edge line between adjacent coplanar faces, pushing practical capacity up to ~360 faces per mesh depending on topology. Supports in place updates via updateSurface() and updateBars() . Rails are drawn transparent, so solid faces in this mode have no visible outline - use a wireframe style or "poly" drawMode if you need stroked edges. Recommended for all new code. "poly" . Legacy polyline backend. Capacity ~100 faces, no in place updates, but renders the face outline using mesh.lineStyle and mesh.lineWidth . Use only when you need styled solid face outlines. Wireframe styles always render with line primitives regardless of drawMode. Stroke width and style on edges (and on poly mode face outlines) come from mesh.lineWidth and mesh.lineStyle , which you mutate by direct field assignment. ---------------------------------------------------------------------------------------------------------------- 🔷 QUICK START The best practice lifecycle is simple: Create one persistent Scene with newScene() . Build meshes and helper overlays once in barstate.isfirst . On later bars, mutate objects in place with transforms or helper mutators like updateBars() and updateSurface() . Call render(scene, ...) once per frame. It automatically clears the previous chart drawings. A complete, lit, animated 3D scene is still a handful of lines: //@version=6 indicator("My First 3D Scene", overlay = false, max_polylines_count = 100, max_lines_count = 500, max_labels_count = 500) import Alien_Algorithms/Pine3D/1 as p3d var p3d.Scene scene = p3d.newScene() var p3d.Mesh sun = na if barstate.isfirst scene.setLightDir(1.0, -1.0, 0.5).setAmbient(0.3) sun := p3d.sphere(50.0, 16, 12, color.orange).setTag("sun") scene.add(sun) p3d.wireGrid(scene, 300.0, 300.0, 6, 6, color.new(color.gray, 80)) scene.camera.orbit(35.0, 25.0, 220.0) if barstate.islast sun.rotateBy(0.0, 1.5, 0.0) p3d.render(scene, lighting = true) ---------------------------------------------------------------------------------------------------------------- 🔷 RECOMMENDED USAGE PATTERN Use your Scene and major meshes in var . Build geometry once in barstate.isfirst . Use updateSurface() and updateBars() on later bars instead of rebuilding meshes. Use scene level helpers like wireGrid() when you want overlays added immediately. Use trail3D() when you want a streamed oscillator style path with built in wall projections and cage geometry. For scatter clouds, build an array once, hand it to scene.add(pts) , then mutate pt.position , pt.textColor , etc. each bar to animate. Use mesh level gridBox() and gridLabels() (contour) and barLabels() (bars) to attach overlays to the mesh setup chain. They are drained into the scene by scene.add(mesh) . 🔷 CONSIDERATIONS scene.clear() vs render(). scene.clear() removes objects from the scene graph (meshes, labels, lines, polylines). render() only clears the previous frame's TradingView drawings and redraws from the current scene graph. You almost never need scene.clear() in the build once and update pattern. Global scope series for updateSurface() / updateBars(). If your data uses Pine's history operator ( ) or calls functions like ta.rsi() , ta.atr() , request.security() , those must be declared at global scope so Pine tracks their bar by bar history. Calling them inside barstate.islast produces inconsistent results or compiler errors. gridLabels() tick values auto refresh. When you call updateSurface() , any tick value labels created by gridLabels() are automatically updated to reflect the new data range. Axis titles and positions stay constant. You don't need to rebuild them. barLabels() value labels via updateBars(). Create category labels once with mesh.barLabels(catNames) at build time, then pass valLabels to updateBars() on each frame. Value labels are refreshed automatically. Don't call barLabels() again. Lighting convenience methods are chainable. scene.setLightDir() , setLightPos() , setLightMode() , setAmbient() , setShadowStrength() , and showLightSource() all return Scene and can be chained: scene.setLightMode("point").setLightPos(0, 200, 150).setAmbient(0.25) . Mesh transforms return Mesh. moveTo() , moveBy() , rotateTo() , rotateBy() , scaleTo() , scaleUniform() , setTag() , setStyle() , setColor() , show() , hide() all return Mesh for chaining: mesh.moveTo(0, -20, 0).rotateTo(0, 45, 0).setStyle("solid") . Degrees vs radians. rotateTo() and rotateBy() on Mesh expect degrees. The low level Vec3.rotateX/Y/Z() methods expect radians. scene.lookAt() is tag only. scene.lookAt(t) accepts a string tag and points the camera at that mesh. To aim the camera at an arbitrary Vec3 , call scene.camera.lookAt(vec) directly. remove(tag) removes one object. The search order is meshes, then labels, then lines, then polylines, and the first hit wins. Avoid reusing tags across primitive types if you intend to delete by tag. Shadow grid acceleration is directional light only. The spatial shadow grid is only built when lightMode == "directional" . Point lights fall back to a linear O(M) scan, so heavy shadow scenes are fastest in directional mode. guiShift and yOffset. scene.guiShift and scene.yOffset position the 3D viewport on the chart without consuming historical bar slots. Increase guiShift to push the scene rightward into future bar space; adjust yOffset to slide it vertically in price units. bar_time projection. All chart drawings are emitted with xloc.bar_time , so the scene can sit arbitrarily far left or right of bar_index without forcing Pine to extend its history buffer. This is what keeps the engine stable on long charts and future projected scenes. barLabels() without values. When you call mesh.barLabels(catNames) and omit value labels, every later updateBars(values) auto formats the numeric values via str.tostring() . Pass valLabels only when you need custom strings. Direct mesh.vertices mutation requires invalidateCache(). Transform mutators ( moveTo , rotateBy , scaleTo , etc.) invalidate the world vertex cache on their own. Only raw index writes like mesh.vertices.set(i, newVec) need a manual mesh.invalidateCache() call to force re-projection. Skipping it will make the renderer draw stale geometry. Drawing budgets fail silently. If a scene emits more than 100 polylines, 500 lines, or 500 labels in a single frame, TradingView silently drops the overflow without raising a runtime error. Missing geometry almost always means a budget overrun - lower maxFaces , drop a contour level, or simplify overlay primitives to bring the frame back inside the caps. render() deletes non Pine3D drawings too. Every render() call clears polyline.all , line.all , label.all , and linefill.all before redrawing. Any manual label.new() , line.new() , etc. issued before render() in the same frame will be wiped. Issue custom drawings after the render call if you need them to persist. mergeMeshes() preserves depth grouping. When every source mesh passed into mergeMeshes() has the same vertex and face count (e.g. identical primitives in a voxel grid), the merged mesh auto derives depth group boundaries so the combined geometry still sorts correctly per original instance. Mixing primitives with different topologies disables the grouping. CPU timeouts: knobs to turn. Pine Script enforces a per bar execution budget, and dense scenes can trip it before the drawing budget ever does. If a scene compiles but times out at runtime, reach for these levers in order: lower occlusionRaster (e.g. 768 -> 384) for the biggest single perf win, reduce maxFaces to cap the solid face pool, drop levels on contour surfaces, simplify sphere/torus segment counts, and gate heavy work behind barstate.islast so history bars only build geometry rather than render it. ---------------------------------------------------------------------------------------------------------------- 🔷 MORE EXAMPLES The following scenes were all built entirely in Pine Script™ v6 using Pine3D as the rendering layer. They exist to demonstrate that the library is a real engine capable of complex, production grade visualizations. 🔸 4D Hypercube (Tesseract). A rotating tesseract, projected from 4D to 3D to 2D in real time using a custom 4D rotation matrix layered on top of Pine3D's standard projection pipeline. 🔸 Solar System. Following the publication of my 3D Solar System back in 2024, which introduced new graphical rendering concepts into Pine Script, we have seen a wave of various interpretations of the underlying vector classes, ranging from tutorials to niche specific integrations using hardcoded math. It became clear that a unified architecture was needed, one that would lower the barrier to entry while simultaneously handling the optimization process, which is both complex and error prone to do manually. That architecture is what Pine3D delivers. Below is a re-creation of the classic 3D Solar System rebuilt entirely on top of the library. It uses a fraction of the original code , renders roughly 5x faster , and adds real lighting cast directly from the Sun , all while consuming only a third of the available drawing budget thanks to the occlusion and culling mechanisms Pine3D handles out of the box. ---------------------------------------------------------------------------------------------------------------- 🔷 API REFERENCE 🔸 Top Level Entry Points. newScene() creates a ready to use Scene with a default camera and light. render(scene, ...) draws the current frame and auto clears the previous frame's chart drawings; see the Renderer section above for the full parameter list. vec3(x, y, z) creates a Vec3. colorBrightness() is an exported color utility helper. 🔸 Mesh Factories. Primitives - cube() , cuboid() , pyramid() , plane() , sphere() , cylinder() , torus() , grid() , disc() , circle() for ready made geometry. customMesh(verts, faces) - Low level escape hatch for authoring your own topology. mergeMeshes(meshes, tag, removeInterior) - Bakes transforms and combines many meshes into one. With removeInterior = true , coincident faces with opposing normals (e.g. shared walls between adjacent cubes in a grid) are culled so only the exterior shell survives, a major optimization for dense voxel style scenes. surface(heights, size, lowCol, highCol, levels, axisX, axisZ) - Creates a contour surface mesh. bars3D(values, barWidth, barDepth, spacing, lowCol, highCol, maxHeight) - Creates a combined 3D bar chart mesh; add labels with the chainable barLabels(names, values) method. 🔸 UDT Constructors. Overlay primitives and face descriptors are plain UDTs. Because these types have many fields, always instantiate them with named arguments rather than positional, e.g. Label3D.new(position = pos, txt = "•") : Face - fields: vi (array of vertex indices into the parent mesh), col . Used when authoring customMesh() topology; every face must have at least 3 indices and should be planar. Label3D - fields: position , txt , textColor , bgColor , labelStyle , labelSize , fontFamily , tooltip , visible , tag . Only position is required. Line3D - fields: start , end , col , width , visible , tag , lineStyle . Polyline3D - fields: points , col , fillColor , width , closed , visible , tag , lineStyle . Vec3.new(x, y, z) or the vec3(x, y, z) shorthand. 🔸 Trail Primitive. trail3D(size, capacity, trailCol, minSamples) creates a streamed Trail3D primitive with a main trail, two projection polylines, and a cage polyline. capacity is internally clamped to 300 samples to keep the rolling buffer inside Pine's execution budget; passing a larger value silently resolves to 300. minSamples (default 60) is the sample count at which the cage reaches its full cube width: below that the cage stays cube shaped and samples stretch across it; above that the cage grows rightward at a fixed step until capacity is hit. scene.add(trail) registers the sub primitives into the scene. Trail3D methods: pushSample() , axisLabels() , cage() , moveTo() , show() , hide() . 🔸 Mesh Methods. Transform - moveTo() , moveBy() , rotateTo() , rotateBy() , scaleTo() , scaleUniform() . Appearance - setColor() , setFaceColor() , setStyle() , show() , hide() , setTag() . Stroke styling (direct) - mesh.lineWidth := 3 and mesh.lineStyle := line.style_dashed control width and style of every visible mesh edge in wireframe modes and the outline of solid faces in drawMode = "poly" . Shadow opt out (direct) - mesh.castShadow := false excludes the mesh from shadow casting while still receiving light. Useful for ghost overlays, debug geometry, or semi transparent meshes you do not want occluding the scene. Lifecycle - clone() , faceCount() , invalidateCache() . Data mutation - updateSurface() and updateBars() refresh persistent meshes in place. updateBars() refreshes any bar label positions automatically; pass catLabels / valLabels to also update the text. Contour helpers - gridBox() and gridLabels() queue overlays on the mesh and hand them to the scene when you call scene.add(mesh) . Bar helpers - barLabels() is chainable on a bars3D() mesh and queues its category and value labels for the next scene.add(mesh) . Note: rotateTo() and rotateBy() expect degrees. The low level Vec3.rotateX/Y/Z() methods work in radians. 🔸 Scene Methods. Lighting - setLightDir() , setLightPos() , setLightMode() , setAmbient() , setShadowStrength() , showLightSource() . Scene graph - add(mesh) , add(label) , add(array) , add(line) , add(polyline) , add(trail) , remove(index) , remove(tag) , clear() . Lookup and navigation - getMesh() , getLabel() , getLine() , getPolyline() , lookAt() , totalFaces() . Cache control - invalidateLightCache() after mutating light direction or scene bounds externally; invalidateAllCaches() to also invalidate every mesh's world vertex cache (use after directly mutating mesh.vertices ). Note: scene.clear() clears the scene graph itself. render() only clears the previous frame's TradingView drawings. 🔸 Camera Methods. setPosition(x, y, z) moves the camera. lookAt(x, y, z) / lookAt(vec3) points at a world space target. orbit(angleX, angleY, distance) does a spherical orbit around the current target. setFov(val) sets the perspective scale factor. Camera fields ( position , target , fov ) are also directly mutable via assignment when you need to tune them outside the provided setters, e.g. scene.camera.fov := 1200.0 . 🔸 Light Field Mutation. In addition to the scene level convenience setters, every field on scene.light is directly mutable for fine grained tuning: scene.light.selfShadow := true enables self shadowing, scene.light.shadowBias := 0.2 adjusts the shadow acne offset, scene.light.shadowStrength and scene.light.ambient are also exposed. Mutate them after newScene() or between frames; the renderer reads them every call. 🔸 Vec3 Methods. Core math: add() , sub() , scale() , negate() , dot() , cross() , length() , normalize() , distanceTo() , lerp() . Rotation and helpers: rotateX() , rotateY() , rotateZ() , copy() , toString() . 🔸 Overlay Primitive Methods. Label3D - moveTo() , moveBy() , setText() , setTextColor() , setTooltip() , show() , hide() , setTag() . Line3D - setStart() , setEnd() , setPoints() , setColor() , show() , hide() , setTag() . Polyline3D - setColor() , show() , hide() , setTag() . Every UDT field is mutable via direct assignment for properties without a chainable setter: Label3D - bgColor , labelStyle (label.style_*), labelSize (size.*), fontFamily (font.family_*), visible . Line3D - width , lineStyle (line.style_solid / _dashed / _dotted / _arrow_left / _arrow_right / _arrow_both), visible . Polyline3D - width , lineStyle (line.style_solid / _dashed / _dotted only; arrow styles are not supported by TradingView's polyline primitive), fillColor , closed , visible . Mutations are read per frame by the renderer, so they animate freely. 🔸 High Level Scene Helpers. wireGrid(scene, w, d, divX, divZ, col) adds a depth sorted ground grid. scene.add(array) adds a batch of labels in one call - the idiomatic way to push a scatter cloud into the scene. 🔸 Mesh Level Chainable Overlays. mesh.barLabels(names, values, ...) adds category and value labels on a bars3D() mesh. mesh.gridBox(col, divs) adds a wireframe bounding box cage on a surface() mesh. mesh.gridLabels(col, xName, yName, zName, ticks, fmt) adds axis titles and tick value labels on a surface() mesh; tick values auto refresh on updateSurface() . All three are queued on the mesh and drained into the scene by scene.add(mesh) . ---------------------------------------------------------------------------------------------------------------- This work is licensed under (CC BY-NC-SA 4.0) , meaning usage is free for non-commercial purposes given that Alien_Algorithms is credited in the description for the underlying software. For commercial use licensing, contact Alien_Algorithms
Pine Script® library
by Alien_Algorithms
9
KalmanEngineLibKalmanEngineLib A Pine Script v6 library that provides a reusable engine for multi-state Kalman filtering, symmetric covariance packing, sequential scalar measurement updates, Mahalanobis gating, adaptive noise estimation, online coupling estimation, multi-scale trajectory storage, covariance-derived confidence bands, and k-step covariance propagation. What it does Implements a generic N-state Kalman filter where the posterior covariance P is stored as a packed upper triangle (n*(n+1)/2 elements), saving ~47% memory vs a full matrix.new(n,n) at n=14. Supports block-diagonal transition matrices via separate sub-blocks (3×3 kinematics, 6×6 z-score dynamics, 5×5 Mahalanobis, 3×5 cross-coupling Γ_lag) instead of a single n×n F matrix. Provides a sequential scalar measurement update in Joseph form for numerical stability; calling it once per observation is equivalent to a batch update but avoids allocating an m×n H matrix. Core components UDTs: KalmanState_N, TransitionConfig, TrajectoryStore, ConceptConfig — callers own all persistent state; library functions are stateless transforms. Triangle primitives: f_tri_idx, f_tri_get, f_tri_set, f_tri_new, f_tri_diag, f_tri_add_outer_product for packed symmetric matrix arithmetic. Prediction: f_predict_block, f_predict_identity, f_P_predict_diag, f_P_predict_cross. Update: f_sequential_update returning for external diagnostics. Gating: f_mahalanobis_3d (analytic 3×3 inverse with Ledoit-Wolf shrinkage and diagonal fallback near singularity), f_nis_test, f_gating_gain_mod. Adaptive noise: f_adaptive_Q_scalar (windowed MLE), f_adaptive_R_scalar (innovation z-score ratchet). Coupling: f_gamma_lag_update (scalar 1-D Kalman β-tracker for Γ_lag elements). Trajectory: f_traj_init, f_traj_update, f_traj_xcorr — circular buffers at Δ={3,5,7} bar skips with Pearson cross-correlation for lag calibration. Bands and projection: f_covariance_band_width, f_confidence_envelope, f_k_step_cov_propagation, f_z_spread. Derived outputs: KMEMA (adaptive EMA modulated by innovation shock, TE confidence, velocity), online OLS beta update, execution-score helpers. Architecture notes All functions are stateless transforms operating on UDTs passed by the caller; no var declarations inside library functions. Element budget: ~3,600 for the core engine; ~1,800 for TrajectoryStore at depth=100, n_feat=6. Total ~22K elements under Pine's 100K limit. Self-healing: f_state_sanitize resets na or overflow entries in x and P diagonals to caller-supplied defaults. Usage pattern Declare a var KalmanState_N state = f_init_regression(n, P0, Q0, R0) in the indicator. Each bar: call f_predict_block → f_P_predict_diag/f_P_predict_cross → one or more f_sequential_update per scalar observation → optional f_mahalanobis_3d/f_adaptive_Q_scalar/f_adaptive_R_scalar → read outputs via f_z_spread, f_confidence_envelope, f_k_step_cov_propagation. Scope General-purpose Kalman infrastructure; no market-specific logic, no signals, no thresholds embedded. Intended as a dependency for indicators and strategies that need rigorous multi-state filtering with adaptive noise and regime-aware gating. License Mozilla Public License 2.0.
Pine Script® library
by cybermediaboy
HeikinAshiTrendUtilities Library HeikinAshiTrendUtilities This library contains reusable Heikin Ashi helpers for building Pine scripts that use Heikin Ashi as more than a candle style. It centralizes the Heikin Ashi foundation, HA-based oscillator engines, streak and confirmed-trend logic, Pressure Meter helpers, max-move scanning, Fib Backbone structure helpers, and Primary Trend helpers so those parts do not need to be rewritten across multiple scripts. Everything on the example chart is materially driven by the library, whether through the Heikin Ashi calculations themselves, the HA-based oscillator and pressure engine, the predictive close logic, the smoothed HA overlay, the Fib Backbone context window, or the structure geometry used to project key analytical visuals. How to use Import the library near the top of your script in global scope, alongside any other imports, before you start calling its helpers. Typical placement: • //@version=6 • indicator(...) or strategy(...) • import MYNAMEISBRANDON/HeikinAshiTrendUtilities/1 as haUtils For more information on libraries and incorporating them into your scripts, see the Libraries section of the Pine Script User Manual: www.tradingview.com ➖Heikin Ashi Core Helpers➖ These helpers handle the basic building blocks of Heikin Ashi. They let a script create standard HA candles, estimate the price needed to flip the current HA candle, and generate a smoothed HA version for a cleaner trend view. In other words, this region provides the core HA math used to build the rest of the library’s trend, engine, and structure tools. heikinAshi(openValue, closeValue, highValue, lowValue, haOpenPrev, haClosePrev) Builds one Heikin Ashi candle from real OHLC and prior HA state Parameters: openValue (float): Real open closeValue (float): Real close highValue (float): Real high lowValue (float): Real low haOpenPrev (float): Prior Heikin Ashi open haClosePrev (float): Prior Heikin Ashi close Returns: HA open, HA close, HA high, HA low, is HA up, is HA down haPredictClose(haOpen, openValue, highValue, lowValue) Estimates the real close price needed to flip the current HA candle Parameters: haOpen (float): Current Heikin Ashi open openValue (float): Real open highValue (float): Real high lowValue (float): Real low Returns: Predicted real close needed to flip the HA candle smoothedHeikinAshi(openValue, highValue, lowValue, closeValue, len1, len2) Builds double-smoothed Heikin Ashi values from real OHLC inputs Parameters: openValue (float): Real open highValue (float): Real high lowValue (float): Real low closeValue (float): Real close len1 (simple int): First EMA smoothing length applied to real OHLC len2 (simple int): Second EMA smoothing length applied to HA OHLC Returns: Smoothed HA open, smoothed HA high, smoothed HA low, smoothed HA close, is smoothed HA up, is smoothed HA down ➖HA Oscillator Foundation Helpers➖ These helpers turn raw Heikin Ashi candle movement into a usable oscillator foundation. They measure the HA candle’s bullish or bearish range, normalize that movement so it can be compared more consistently across bars, and build upper/lower guide levels that help a script judge when that oscillator is stretching into stronger trend pressure. In other words, this region creates the base signal that the HA Blend, HA Range Base, color engine, and Pressure Meter can build from. haSignedRangePct(haHigh, haLow, haClose, haIsBull, haIsBear) Returns the signed HA range-percent foundation used by the oscillator engine Parameters: haHigh (float): Heikin Ashi high haLow (float): Heikin Ashi low haClose (float): Heikin Ashi close haIsBull (bool): True when the current HA candle is bullish haIsBear (bool): True when the current HA candle is bearish Returns: Signed HA range-percent foundation haPreparedOscSource(signedSrc, normLen, useClamp, clampRange) Returns the normalized / optionally clamped HA oscillator source Parameters: signedSrc (float): Signed HA foundation normLen (simple int): Normalization lookback length useClamp (simple bool): Whether the normalized result should be clamped clampRange (float): Absolute clamp boundary when useClamp is true Returns: Prepared HA oscillator source haOscGuides(src, lookback, guideFactor) Returns upper and lower threshold guides from an oscillator series Parameters: src (float): Oscillator series lookback (simple int): Guide lookback window guideFactor (float): Scaling factor applied to the highest/lowest values Returns: Upper guide, lower guide ➖HA Blend Engine Helpers➖ These helpers take the prepared HA oscillator source and turn it into a smoother trend engine by blending multiple EMA pairs together. They let the script choose a faster, more balanced, or slower blend profile, then optionally smooth that final output one more time. In other words, this region builds the more layered, trend-following version of the HA oscillator engine. haBlendPairStackText(pairSet) Returns the active EMA pair-stack text for the selected HA Blend pair set Parameters: pairSet (simple string): Pair-set label. Expected values: "Fast", "Balanced", or "Slow" Returns: Pair-stack text haBlendEngineCore(src, pairSet) Returns the raw HA Blend engine core before final smoothing Parameters: src (float): Prepared HA signed source used by the blend engine pairSet (simple string): Pair-set label. Expected values: "Fast", "Balanced", or "Slow" Returns: Raw HA Blend engine core haBlendEngine(src, pairSet, useFinalSmooth, finalSmoothLen, finalSmoothType) Returns the final HA Blend engine with optional final smoothing Parameters: src (float): Prepared HA signed source used by the blend engine pairSet (simple string): Pair-set label. Expected values: "Fast", "Balanced", or "Slow" useFinalSmooth (simple bool): Whether final smoothing should be applied finalSmoothLen (simple int): Final smoothing length finalSmoothType (simple string): Final smoothing type. Expected values: "EMA" or "SMA" Returns: Final HA Blend engine ➖HA Range Base Engine Helpers➖ These helpers take the prepared HA oscillator source and smooth it in a more direct way than the Blend engine. Instead of combining multiple EMA pairs, they use one selected smoothing length and MA type to create a cleaner base trend signal, with the option to smooth that result one more time. In other words, this region builds the simpler, more straightforward version of the HA oscillator engine. haRangeEngineCore(src, rangeLen, rangeMaType) Returns the raw HA Range Base engine core before final smoothing Parameters: src (float): Prepared HA signed source used by the Range Base engine rangeLen (simple int): Core smoothing length used by the Range Base engine rangeMaType (simple string): Core smoothing type. Expected values: "EMA" or "SMA" Returns: Raw HA Range Base engine core haRangeEngine(src, rangeLen, rangeMaType, useFinalSmooth, finalSmoothLen, finalSmoothType) Returns the final HA Range Base engine with optional final smoothing Parameters: src (float): Prepared HA signed source used by the Range Base engine rangeLen (simple int): Core smoothing length used by the Range Base engine rangeMaType (simple string): Core smoothing type. Expected values: "EMA" or "SMA" useFinalSmooth (simple bool): Whether final smoothing should be applied finalSmoothLen (simple int): Final smoothing length finalSmoothType (simple string): Final smoothing type. Expected values: "EMA" or "SMA" Returns: Final HA Range Base engine ➖HA Threshold Color Helpers➖ This helper takes centered oscillator behavior and turns it into a usable visual color state. It helps a script decide when the HA-based oscillator is rising or falling above or below its guide levels so candles, rows, or other visuals can reflect stronger or weaker trend pressure. haThresholdStateColor(src, upperGuide, lowerGuide, aboveUpperRiseColor, aboveZeroRiseColor, aboveZeroFallColor, belowZeroFallColor, belowLowerFallColor, belowZeroRiseColor) Resolves a visual color from centered-oscillator threshold state Parameters: src (float): Source series upperGuide (float): Upper threshold guide lowerGuide (float): Lower threshold guide aboveUpperRiseColor (color): Color used when src is above the upper guide and rising aboveZeroRiseColor (color): Color used when src is above zero and rising aboveZeroFallColor (color): Color used when src is above zero and falling belowZeroFallColor (color): Color used when src is below zero and falling belowLowerFallColor (color): Color used when src is below the lower guide and falling belowZeroRiseColor (color): Color used when src is below zero and rising Returns: Resolved visual color ➖HA Structure Scan Helpers➖ This helper scans a chosen lookback window and finds the strongest completed move inside it. It compares bullish and bearish candidates in the same scan, then returns whichever move was stronger along with the start and end anchors. In other words, this region gives a script a reusable way to locate the dominant move that can later be used for Fib Backbone structure, Primary Max Move logic, or other trend-structure work. :contentReference {index=0} :contentReference {index=1} haScanMaxMove(lookback, includeCurrentBar, highSeries, lowSeries) Scans a lookback window for the strongest upward or downward percentage move Parameters: lookback (simple int): Number of bars to scan includeCurrentBar (simple bool): Whether bar 0 should be included in the scan highSeries (float): High series used for upward and downward move detection lowSeries (float): Low series used for upward and downward move detection Returns: Winning direction, winning percent move, winning start bars-ago, winning end bars-ago, winning span bars ➖HA Streak Helpers➖ These helpers let a script keep track of active Heikin Ashi streaks. They determine whether the current HA sequence is bullish or bearish, count how long that streak has been running, assign a tier color based on streak length, and measure how far price has moved from the streak’s starting point. In other words, this region helps turn raw HA trend runs into usable streak state, color, and percent-move data for candles, rows, labels, and trend readouts. :contentReference {index=0} haStreakState(haOpen, haClose, bullCountPrev, bearCountPrev) Resolves raw HA bull/bear state, streak counts, and streak start offset Parameters: haOpen (float): Current Heikin Ashi open haClose (float): Current Heikin Ashi close bullCountPrev (int): Prior bullish streak count bearCountPrev (int): Prior bearish streak count Returns: is HA bullish, is HA bearish, bullish streak count, bearish streak count, current streak length, streak start bars-ago haStreakTierColor(isHaBull, isHaBear, bullCount, bearCount, streakTierBars, bullTier1, bullTier2, bullTier3, bullTier4, bearTier1, bearTier2, bearTier3, bearTier4, neutralColor) Returns the active streak-tier color from bull/bear streak counts Parameters: isHaBull (bool): True when the current HA streak is bullish isHaBear (bool): True when the current HA streak is bearish bullCount (int): Current bullish streak count bearCount (int): Current bearish streak count streakTierBars (simple int): Number of bars required before advancing to the next tier bullTier1 (color): Bullish tier 1 color bullTier2 (color): Bullish tier 2 color bullTier3 (color): Bullish tier 3 color bullTier4 (color): Bullish tier 4 color bearTier1 (color): Bearish tier 1 color bearTier2 (color): Bearish tier 2 color bearTier3 (color): Bearish tier 3 color bearTier4 (color): Bearish tier 4 color neutralColor (color): Fallback color when no active streak is available Returns: Active streak-tier color haStreakPct(isHaBull, isHaBear, streakBars, highSeries, lowSeries) Returns the wick-based percent move from the streak start to the current bar Parameters: isHaBull (bool): True when the current HA streak is bullish isHaBear (bool): True when the current HA streak is bearish streakBars (int): Current active streak length highSeries (float): High series used for streak measurement lowSeries (float): Low series used for streak measurement Returns: Wick-based streak percent move ➖Confirmed HA Trend Helpers➖ These helpers let a script work with a slower, confirmation-based HA trend instead of flipping immediately on the first opposite HA candle. They track the currently confirmed direction, count how many opposite candles are building toward the next possible flip, project the confirmed trend using regular-price body or wick anchors, and measure how far that confirmed trend has moved from its confirmed start. In other words, this region helps scripts build a more stable HA trend model that filters out some of the noise of raw HA flips. :contentReference {index=0} :contentReference {index=1} haConfirmedTrendState(enabled, rawDir, confirmBars, dirPrev, oppCountPrev, startBarPrev, firstOppBarPrev) Resolves confirmed trend direction, build count, and confirmed start bar Parameters: enabled (simple bool): Whether the confirmed-trend engine is active rawDir (int): Current raw HA direction: +1 bull, -1 bear, 0 neutral confirmBars (simple int): Consecutive opposite raw HA bars required to confirm a flip dirPrev (int): Prior confirmed direction oppCountPrev (int): Prior opposite-side build count startBarPrev (int): Prior confirmed trend start bar index firstOppBarPrev (int): Prior first opposite raw HA bar index Returns: Confirmed direction, opposite-side build count, confirmed start bar index, first opposite raw HA bar index, confirmed leg bars, confirmed start bars-ago haConfirmedTrendProjection(confirmedDir, startOffset, openValue, highValue, lowValue, closeValue, anchorMode, pathMode, forwardBars) Returns confirmed trend projection geometry from body/wick anchor rules Parameters: confirmedDir (int): Confirmed direction: +1 bull, -1 bear, 0 neutral startOffset (int): Confirmed start bars-ago offset openValue (float): Regular-price open highValue (float): Regular-price high lowValue (float): Regular-price low closeValue (float): Regular-price close anchorMode (simple string): Projection anchor mode: "Body" or "Wick" pathMode (simple string): Projection path mode: "Same Side" or "Opposite Side" forwardBars (simple int): Number of bars forward for projection Returns: Has valid projection, start Y, current Y, future Y, slope haConfirmedTrendPct(confirmedDir, startOffset, highSeries, lowSeries) Returns confirmed streak percent movement from the confirmed start bar Parameters: confirmedDir (int): Confirmed direction: +1 bull, -1 bear, 0 neutral startOffset (int): Confirmed start bars-ago offset highSeries (float): HA high series used for confirmed move measurement lowSeries (float): HA low series used for confirmed move measurement Returns: Confirmed streak percent move ➖HA Pressure Meter Helpers➖ These helpers take the HA-based oscillator engine and convert it into an easier 0–100 pressure reading. They help a script decide when bullish or bearish pressure is becoming active, assign matching tier colors for rows or other visuals, and return the color state for a pressure strip or similar chart-edge signal. In other words, this region turns the HA oscillator into a simpler pressure model that is easier to read at a glance. haPressureMeter(rawOsc, bullAnchor, bearAnchor) Normalizes a raw oscillator value into a 0-100 Pressure Meter Parameters: rawOsc (float): Raw oscillator value bullAnchor (float): Raw oscillator value that should map to 100 bearAnchor (float): Raw oscillator value that should map to 0 Returns: Pressure Meter value in the 0-100 range haPressureState(pressureMeter, bullThreshold, bearThreshold) Resolves bullish, bearish, and neutral threshold state from the Pressure Meter Parameters: pressureMeter (float): Normalized Pressure Meter value bullThreshold (float): Meter level where bullish pressure becomes active bearThreshold (float): Meter level where bearish pressure becomes active Returns: Bull-active, bear-active, neutral-between haPressureTierColors(pressureMeter, bullTier1, bullTier2, bullTier3, bullTier4, bearTier1, bearTier2, bearTier3, bearTier4, fallbackBg) Returns tier-based pressure-row background and readable text color Parameters: pressureMeter (float): Normalized Pressure Meter value bullTier1 (color): Bull tier 1 color bullTier2 (color): Bull tier 2 color bullTier3 (color): Bull tier 3 color bullTier4 (color): Bull tier 4 color bearTier1 (color): Bear tier 1 color bearTier2 (color): Bear tier 2 color bearTier3 (color): Bear tier 3 color bearTier4 (color): Bear tier 4 color fallbackBg (color): Fallback background when the meter is na Returns: Row background color, row text color haPressureStripColor(pressureMeter, bullThreshold, bearThreshold, bullTier1, bullTier2, bullTier3, bullTier4, bearTier1, bearTier2, bearTier3, bearTier4, neutralColor, activeTransp, neutralTransp) Returns active or neutral strip color from the Pressure Meter state Parameters: pressureMeter (float): Normalized Pressure Meter value bullThreshold (float): Meter level where bullish pressure becomes active bearThreshold (float): Meter level where bearish pressure becomes active bullTier1 (color): Bull tier 1 color bullTier2 (color): Bull tier 2 color bullTier3 (color): Bull tier 3 color bullTier4 (color): Bull tier 4 color bearTier1 (color): Bear tier 1 color bearTier2 (color): Bear tier 2 color bearTier3 (color): Bear tier 3 color bearTier4 (color): Bear tier 4 color neutralColor (color): Neutral-zone base color activeTransp (int): Transparency used when bull or bear pressure is active neutralTransp (int): Transparency used inside the neutral zone Returns: Strip color ➖Fib Backbone Structure Helpers➖ These helpers take a winning max-move scan and turn it into the structure a script can use for Fib Backbone analysis. They define the backbone’s start and end anchors, determine the related support/resistance anchor geometry, calculate Fib level prices between those anchors, and measure how far current price is from those levels. In other words, this region helps convert a dominant move into a reusable backbone structure that can support diagonals, S/R anchors, boxes, and Fib-based readouts. haFibBackboneStructure(dir, startBA, endBA, openValue, highValue, lowValue, closeValue) Returns backbone coordinates, S/R anchors, and anchor-box geometry Parameters: dir (int): Winning move direction: +1 bull, -1 bear, 0 none startBA (int): Winning move start bars-ago endBA (int): Winning move end bars-ago openValue (float): Regular-price open highValue (float): Regular-price high lowValue (float): Regular-price low closeValue (float): Regular-price close Returns: ok, xStart, xEnd, yStart, yEnd, startIsRes, endIsRes, anchorTopS, anchorBotS, anchorTopE, anchorBotE, isTopS, isTopE haFibLevelPrice(yStart, yEnd, fibLevel) Returns the price of one fib level between the backbone anchors Parameters: yStart (float): Backbone start anchor price yEnd (float): Backbone end anchor price fibLevel (float): Fib level such as 0.236, 0.382, 0.50, 0.618, 0.786 Returns: Fib level price haFibPctFromClose(closeValue, fibPrice) Returns percent distance from close to a fib level Parameters: closeValue (float): Current close fibPrice (float): Fib level price Returns: Percent from close to fib level ➖Fib Backbone Context Window Helpers➖ These helpers build the larger context window around the active Fib Backbone lookback. They let a script define the left/right range of that window, calculate its current high and low bounds, and find the midpoint of the same structure. In other words, this region helps frame the broader area that the active backbone move is being selected from, so the move can be viewed in context rather than in isolation. haFibContextWindow(lookback, includeCurrentBar, sourceMode, highValue, lowValue, closeValue) Returns the active Fib Backbone context window geometry Parameters: lookback (simple int): Context-window lookback length includeCurrentBar (simple bool): Whether the current bar participates in the active window sourceMode (simple string): Source selection. Expected values: "Wicks" or "Closes" highValue (float): Regular-price high lowValue (float): Regular-price low closeValue (float): Regular-price close Returns: ok, leftX, rightX, windowBars, windowHigh, windowLow, leftHigh, leftLow haFibContextMidpoint(ok, windowHigh, windowLow) Returns the midpoint of the active Fib Backbone context window Parameters: ok (bool): Whether the context window is valid windowHigh (float): Active context-window high windowLow (float): Active context-window low Returns: Context-window midpoint ➖Primary Trend Window Helpers➖ These helpers scan a lookback window to find the strongest completed HA streak and turn that winner into usable trend information. They identify the winning streak, assign it the correct tier color, and return the anchor coordinates needed to project that streak as a chart-side diagonal. In other words, this region helps a script reduce a larger HA trend window down to its most important completed streak structure. haPrimaryTrendWinner(lookback, haBull, haBear, bullCount, bearCount, haHigh, haLow) Returns the strongest completed HA streak inside the lookback window Parameters: lookback (simple int): Number of bars to scan haBull (bool): Bullish HA state series haBear (bool): Bearish HA state series bullCount (int): Bullish HA streak-count series bearCount (int): Bearish HA streak-count series haHigh (float): HA high series used for wick-based streak measurement haLow (float): HA low series used for wick-based streak measurement Returns: Winning streak length, winning direction, winning percent move, winning start bars-ago, winning end bars-ago, winning validity state haPrimaryTrendTierColor(dir, streakLen, streakTierBars, bullTier1, bullTier2, bullTier3, bullTier4, bearTier1, bearTier2, bearTier3, bearTier4, fallbackBg) Returns the winning Primary Trend tier color Parameters: dir (int): Winning streak direction: +1 bull, -1 bear, 0 none streakLen (int): Winning streak length streakTierBars (simple int): Number of bars required before advancing to the next tier bullTier1 (color): Bullish tier 1 color bullTier2 (color): Bullish tier 2 color bullTier3 (color): Bullish tier 3 color bullTier4 (color): Bullish tier 4 color bearTier1 (color): Bearish tier 1 color bearTier2 (color): Bearish tier 2 color bearTier3 (color): Bearish tier 3 color bearTier4 (color): Bearish tier 4 color fallbackBg (color): Fallback background when no valid winner exists Returns: Winning tier color haPrimaryTrendCoords(dir, startBA, endBA, highSeries, lowSeries) Returns diagonal coordinates from the winning streak anchors Parameters: dir (int): Winning streak direction: +1 bull, -1 bear, 0 none startBA (int): Winning start bars-ago endBA (int): Winning end bars-ago highSeries (float): High series used for line anchors lowSeries (float): Low series used for line anchors Returns: ok, x1, x2, y1, y2 NOTES This is a Heikin-Ashi-specific utility library. It is meant to provide the reusable HA math, state, and structure layer. Final rendering choices such as plot style, line objects, boxes, labels, tables, and overall UI layout are expected to remain script-level decisions. Thanks to SimpleCryptoLife for the open-source HA core functions heikinAshi() & haPredictClose() and thus the inspiration that they've given me to create HA-based indicators for the HA trader enthusiast.
Pine Script® library
by MYNAMEISBRANDON
2
Vantage_PairedSizingVantage_PairedSizing — Position sizing for strategies that pair a primary trade with a recovery trade under a daily loss budget. ───────────────────────────────────────── WHAT IT DOES Answers the question "how many contracts can I take on the primary trade so that, if it stops out, a correctly-sized recovery trade still fits within my daily loss limit?" The library scans candidate quantities top-down and returns the largest one whose worst case (primary stop + recovery stop) stays inside the budget, subject to one of four risk-reward modes. ───────────────────────────────────────── WHAT IT PROVIDES A single entry-point auto-sizer that takes the primary leg's entry/stop/target, the recovery leg's entry/stop/target, a daily loss budget, and a sizing mode — and returns a result record with primary quantity, recovery quantity, per-leg dollar risk, worst-case dollar exposure, and net-if-recovery-wins. The scan falls through a mode ladder (MatchPrimaryProfit → MatchPct → NetGreen) and a no-recovery fallback before giving up, so callers get a usable answer in marginal cases instead of a flat rejection. Four named sizing modes covering the common risk-reward shapes: largest size under a drawdown cap, largest size where the recovery win leaves the session net-green, largest size where the recovery win matches the primary's target profit, and a percentage variant of the match mode. Two utility functions for the dollar math — risk and profit for a given quantity between two prices — so strategies don't have to redo the tick-size / point-value arithmetic themselves. ───────────────────────────────────────── HOW TO USE A complete example call is in the comment block at the top of the source file — import the library, copy the pattern, plug in your primary and recovery price levels. Hover any exported type, enum, or function in the Pine Editor for per-parameter documentation.
Pine Script® library
by Vantage-Stack
KernelLens🟦 KernelLens is a professional kernel regression library for Pine Script v6, providing eight mathematically rigorous Nadaraya–Watson estimators, a three-mode filter layer, a unified string dispatcher, and a suite of trading utilities — all built from the ground up on correct non-parametric statistics. Unlike existing Pine smoothing libraries — which inherit a decade-old loop-bound bug that silently reduces every kernel window to a handful of bars, regardless of the bandwidth parameter — KernelLens is built with auditable math, NA-safe iteration, input validation at every entry point, and academic references cited inline next to the formulas they describe. The library integrates eight independent kernel families — Rational Quadratic, Gaussian, Periodic, Locally Periodic, Epanechnikov, Tricube, Triangular, and Cosine — behind a consistent API, with every raw estimator wrapped in a filter layer (None / Smooth / Zero Lag), a unified dispatcher for dropdown-driven kernel selection, and five utility exports covering slope detection, trend state, crossover signaling, residual confidence bands, and Silverman's rule-of-thumb bandwidth recommendation. Every public function validates its inputs, raises descriptive runtime errors on misuse, and returns `na` only when there is genuinely no data — never as a silent fallback. 🟦 MATHEMATICAL FOUNDATION **The Nadaraya–Watson Estimator** Given a source series `y_t` and a symmetric kernel `K` with scale parameter `ℓ` (the "bandwidth"), the Nadaraya–Watson estimator of the regression function `m(x) = E ` evaluated at the current bar is: ``` Σᵢ K(dᵢ / ℓ) · y_{t−i} ŷ(t) = ─────────────────────── Σᵢ K(dᵢ / ℓ) ``` where `dᵢ` is the bar-distance from the kernel center and the sum runs over a finite window determined by the effective support of `K`. The estimator is a locally weighted average: bars close to the kernel center contribute heavily, distant bars contribute proportionally less, and bars outside the support contribute nothing. It is asymptotically unbiased up to `O(ℓ²)` for twice-differentiable `m`, with variance of order `(n·ℓ)⁻¹` — the classical bias–variance trade-off that defines all non-parametric smoothers. **Why Kernel Regression Beats Rolling Means** A simple moving average gives every bar in the window the same weight. Kernel regression gives each bar a weight that decays smoothly with distance, producing: - **Smoother output** — no step artifacts when bars enter / leave the window - **Better bias control** — the peak of the kernel sits exactly on the point being estimated - **Kernel-specific behavior** — compact-support kernels eliminate tail contamination entirely; Rational Quadratic's `α` parameter exposes multi-scale mixing; Periodic kernels resonate with known cycle lengths The math has been the academic standard for non-parametric regression since Nadaraya (1964) and Watson (1964). KernelLens brings it to Pine Script v6 in its correct, bug-free form. 🟦 THE EIGHT KERNELS All eight kernels implement the Nadaraya–Watson weighting scheme. They differ in support (compact versus infinite), smoothness (how many times differentiable), and how weight decays with distance. | # | Kernel | Formula | Support | Smoothness | Character | |---|---|---|---|---|---| | 1 | **Rational Quadratic** | `(1 + d² / (2·α·ℓ²))^(−α)` | ℝ | C∞ | Multi-scale mixer — `α` controls stretch versus wiggle | | 2 | **Gaussian (RBF)** | `exp(−d² / (2·ℓ²))` | ℝ | C∞ | The canonical smoother — smoothest possible with L² optimality | | 3 | **Periodic** | `exp(−2·sin²(π·d/p) / ℓ²)` | ℝ | C∞ | Resonates with repetition distance `p` — ideal for cycles | | 4 | **Locally Periodic** | Periodic · Gaussian | ℝ | C∞ | Seasonal patterns that slowly drift with trend | | 5 | **Epanechnikov** | `(3/4)(1 − u²) · 𝟙{|u|≤1}` | | C⁰ | Asymptotically MSE-optimal (Watson 1964) — no tail contamination | | 6 | **Tricube** | `(70/81)(1 − \|u\|³)³ · 𝟙{|u|≤1}` | | C² | The LOWESS standard — near-Gaussian with compact support | | 7 | **Triangular** | `(1 − \|u\|) · 𝟙{|u|≤1}` | | C⁰ | Simplest non-uniform kernel — fastest to compute | | 8 | **Cosine** | `(π/4)·cos(π·u/2) · 𝟙{|u|≤1}` | | C¹ | Raised-cosine taper — smoother boundary than Epanechnikov | where `u = d/ℓ` and `𝟙` is the indicator function. **Infinite-Support vs Compact-Support — Why Both Matter** | | Infinite Support (RQ, Gauss, Periodic, LocPeriodic) | Compact Support (Epa, Tricube, Triangular, Cosine) | |---|---|---| | **Tail weight** | Never exactly zero | Exactly zero beyond ±ℓ | | **Loop depth** | `3·ℓ` (3-σ cutoff, ≈99.7% mass) | Exactly `ℓ` | | **Bar contamination** | Distant bars still pull the estimate a tiny amount | Distant bars cannot affect the estimate at all | | **Best for** | Smooth trends, Gaussian-process intuition | Robust regression, outlier resistance | KernelLens picks the correct loop depth automatically based on kernel family: `_depthInfinite` for Gaussian-family kernels, `_depthCompact` for bounded kernels, `_depthPeriodic` for Periodic (which must span enough cycles to reach stable weights). **Why Eight, Not Four** Most Pine kernel libraries ship only the four kernels from MacKay's Gaussian process tutorial. KernelLens adds the four compact-support classical kernels because: - **Epanechnikov** minimises asymptotic mean squared error among all non-negative kernels of bounded support (Watson 1964) — it is the MSE-optimal baseline against which all other kernels are measured - **Tricube** is the kernel used by LOWESS (Cleveland 1979), the de-facto standard for robust locally weighted scatterplot smoothing - **Triangular** is the cheapest non-uniform compact kernel — useful when loop-budget matters on intraday charts with huge dataset size - **Cosine** is C¹-continuous at the support boundary, unlike Epanechnikov's C⁰ discontinuity, producing visibly smoother transitions at kernel edges Adding them makes the library an academically complete toolkit, not just a Pine port of one tutorial. 🟦 FILTER LAYER — NONE / SMOOTH / ZERO LAG Every kernel export accepts a `_filter` parameter with three valid values. The filter layer is implemented identically across all eight kernels, so switching kernel families does not change filter behavior. **"No Filter" — Single-Pass Raw Estimate** ``` ŷ = K(y) ``` One Nadaraya–Watson pass over the source. Cheapest mode, most reactive, fully represents the underlying kernel. Use this when you want the kernel's raw behavior with no additional smoothing or lag correction. **"Smooth" — Double-Pass Estimate** ``` ŷ = K(K(y)) ``` The kernel is applied once to the source, then applied again to its own output using the same bandwidth and the same parameters. The result is a more strongly smoothed curve at the cost of one extra loop pass per bar. This is mathematically equivalent to convolving the kernel with itself — the effective kernel is wider and flatter, pulling longer-range context into each estimate without requiring the user to double the bandwidth. **"Zero Lag" — Ehlers De-Lagged Estimate** ``` ŷ = 2·K(y) − K(K(y)) ``` The ZLEMA identity from Ehlers (*Rocket Science for Traders*, 2000): subtract the smoothing lag from the raw estimate, effectively shifting the output back in time to match the source more closely. The intuition: `K(y)` lags `y` by some amount; `K(K(y))` lags `K(y)` by the same amount; so `K(y) − K(K(y))` is an estimate of the lag itself, and adding it back to `K(y)` cancels out. The result tracks the source more tightly than either pass alone, at the cost of slightly noisier turning points. **Lazy Evaluation — No Wasted Cycles** In `"No Filter"` mode, the second pass is skipped entirely — it never runs. The filter branch uses an `if` block (not a ternary), so Pine's short-circuit semantics prevent the unused computation. A single kernel call costs one pass; `"Smooth"` or `"Zero Lag"` costs two. You only pay for what you use. 🟦 KERNEL CENTER OFFSET — THE `_phase` PARAMETER Every KernelLens kernel takes a `_phase` parameter that shifts the kernel center into the past by `_phase` bars. It is the library's non-repainting knob. **_phase = 0 — Live Estimate** The kernel is centered on the current bar. The most recent price has maximum weight, and the estimate is as fresh as possible. Suitable for live signal generation, but the most recent bar can re-evaluate as it develops within its interval — standard Pine real-time behavior. **_phase > 0 — Non-Repainting Historical Estimate** The kernel center is moved `_phase` bars into the past. The estimate becomes the smoothed value *at that historical bar*, not the current bar. Once the bar at `bar_index − _phase` is fully confirmed (`barstate.isconfirmed`), its estimate cannot change again. This is the standard trick for publishing kernel indicators that do not repaint: you get a stable, historically accurate curve at the cost of shifting the entire output `_phase` bars to the right on the chart. A `_phase = 25` call gives a curve that lags live price by 25 bars but is guaranteed stable for every past bar. **Why It Belongs in the Library, Not the Caller** Pushing `_phase` into the kernel's own loop is not the same as evaluating the kernel at a shifted source (`K(src )`). Shifting the source just uses a stale input with a current-bar-centered kernel, which still produces a fresh estimate of a stale series. KernelLens's `_phase` genuinely moves the kernel center, producing a historical-bar estimate that computes over the correct surrounding window. 🟦 NON-REPAINTING BEHAVIOR Repainting is the single most-asked question about any Pine indicator, and the single most common source of silent failure when a retail trader moves from backtest to live. A strategy that looks flawless on historical bars and then bleeds money the moment it is deployed is almost always suffering from some form of repainting. KernelLens is engineered from first principles to eliminate every class of repainting by construction — not by patching symptoms, but by removing the dependencies that cause repainting in the first place. **The Two Forms of Repainting** | Form | Symptom | Typical Cause | |---|---|---| | **Historical repainting** | A bar that was closed days or weeks ago silently changes its plotted value when the chart is refreshed or scrolled | `request.security()` with `lookahead = barmerge.lookahead_on`, un-gated higher-timeframe data, or incorrect array rotation that reads into future bars | | **Real-time repainting** | The plotted value on the live (current developing) bar flickers tick-by-tick as new price ticks arrive, then freezes at a final value when the bar closes | The indicator reads `close ` (or any current-bar value) inside a weighted sum — the current-bar weight changes every tick | KernelLens avoids the first kind **entirely and unconditionally**: the library contains no `request.security` calls, no higher-timeframe lookups, no `lookahead_on` usage, and no array rotation that could leak future bars into the window. Every historical bar plotted by any KernelLens kernel is computed exclusively from bars that existed at the time that bar was closed. The plotted history is immutable. Real-time repainting is controlled explicitly by the `_phase` parameter — it is the user's choice whether to accept tick-by-tick flicker on the live bar in exchange for zero lag (`_phase = 0`) or to eliminate the flicker entirely at the cost of a small fixed lag (`_phase ≥ 1`). **Why Kernel Regression Normally Repaints (And How KernelLens Stops It)** A traditional Nadaraya–Watson call centered on the current bar evaluates: ``` ŷ(t) = Σᵢ K(dᵢ/ℓ) · y_{t−i} for i = 0 … depth ``` On the live bar, the term `y_{t−0} = close ` is the current real-time price — which changes on every tick. Every tick moves the weighted sum, every tick moves the estimate, and the trader watching the chart sees the kernel plot flicker as the bar develops. The historical bars (where `close ` for that past bar is now fixed) are stable, but the live plot is unstable. KernelLens's `_phase` parameter shifts the loop so the kernel runs over `i = _phase … _phase + depth`. With `_phase = 2`: ``` ŷ(t) = Σᵢ K((i−2)/ℓ) · y_{t−i} for i = 2 … 2 + depth ``` The sum no longer touches `close ` or `close ` — every bar it reads is already confirmed and cannot change. The live-bar kernel output is therefore identical from the first tick of the bar to the last tick of the bar, and identical again when the bar finally closes. There is no flicker and nothing to repaint. **The Lag / Stability Trade-Off** | `_phase` | Lag on Live Bar | Live-Bar Flicker | Historical Repainting | Best For | |---|---|---|---|---| | **0** | 0 bars | Yes (real-time only; history is stable) | None | Scalping, academic research, calibration | | **1** | 1 bar | None | None | Fast day-trading; minimum acceptable lag for a live trading desk | | **2** | 2 bars | None | None | Default for most users — the sweet spot between freshness and stability | | **3** | 3 bars | None | None | Swing trading — extra margin against false flickers from erratic ticks | | **5+** | 5+ bars | None | None | Position trading, long-term chart analysis, published signal marks | Even at `_phase = 0`, **historical repainting never occurs** — only the live bar flickers during its own development. Once a bar closes, its plotted value is final; scrolling away and back, refreshing the chart, or re-opening TradingView will never change that historical plot. The flicker is exclusively a live-bar tick-by-tick phenomenon. **KernelLens as a Non-Repainting Primitive** KernelLens exposes real-time flicker as an explicit, user-controlled trade-off rather than a hidden behavior. The caller picks any point on the spectrum from "fully live" (`_phase = 0`, maximum reactivity with tick-by-tick flicker) to "fully confirmed" (`_phase ≥ 1`, one or more bars of lag in exchange for a curve that never redraws) with a single integer parameter. Historical repainting — the dangerous form that silently rewrites past plots — is eliminated unconditionally regardless of `_phase`. **How to Verify Non-Repainting Yourself** Do not trust the word "non-repainting" from any library — always verify. KernelLens can be verified in about thirty seconds: 1. Load a chart with KernelLens on it using `_phase = 2` (or any value > 0). 2. Take a screenshot at any specific historical bar. 3. Scroll far to the left, refresh the chart, or reload the indicator. 4. Return to the same bar. The plotted value at that bar must be pixel-identical to the screenshot — because the computation on that bar used only the bars before it, which have not changed. 5. Repeat with `_phase = 0`. The historical bars must still be pixel-identical — only the live bar's plot can differ between observations, and only because the live bar's `close` is now a different number than it was when you took the screenshot. For a stricter test, use TradingView's **Bar Replay** mode. Enable Bar Replay, step forward one bar at a time, and watch the kernel plot on each newly-closed bar. With `_phase ≥ 1`, the value plotted on each newly-closed bar will exactly match what the indicator shows after you exit replay mode and view the same bar normally. This is the gold-standard test — Bar Replay reproduces live-bar tick arrival in a controlled way. **Common Misconceptions** > *"Any Pine indicator that uses `close` repaints."* False. Using `close` on a confirmed bar does not repaint — the confirmed bar's close is locked. What can repaint is using `close` on the live bar, and only within that live bar's interval. KernelLens with `_phase > 0` never reads the live-bar close at all. > *"`lookahead = barmerge.lookahead_on` is always wrong."* Context-dependent. `lookahead_on` is used correctly in some multi-timeframe indicators to request a higher-TF value that is already settled on the lower TF. KernelLens does not use `request.security` at all, so this question does not apply — but for libraries that do, `lookahead_on` is only problematic when it leaks values from bars that were not yet closed at the lower-TF time of evaluation. > *"Non-repainting means zero lag."* False. Zero lag and non-repainting are orthogonal properties. KernelLens `_phase = 0` is zero lag with real-time flicker; `_phase = 2` is two-bar lag with no flicker. You can have any combination of the two, and the right choice depends on the trading style. > *"The `FILTER_ZEROLAG` mode makes the indicator non-repainting."* False. `FILTER_ZEROLAG` is an Ehlers-style de-lagging filter applied to the kernel output; it reduces the perceived lag of the estimate, but it does not affect whether the live bar flickers. Non-repainting is controlled exclusively by `_phase`. Choose `_phase` for repainting behavior, and `_filter` for smoothness / lag shape — they are independent knobs. **When to Accept Real-Time Flicker (`_phase = 0`)** Despite everything above, there are legitimate reasons to deliberately use `_phase = 0`: - **Academic research and backtesting** — you want the kernel mathematics in its classical form, centered on the point being estimated, with no phase adjustment - **Scalping on very short timeframes** — a 2-bar lag on a 1-minute chart is a 2-minute delay, which can matter when you are exiting within a 4-minute window - **Visual calibration** — when you are choosing a bandwidth by eye, the live-bar flicker actually helps: you see how sensitive the curve is to each incoming tick, which is diagnostic information - **Indicators that read the kernel output only on `barstate.isconfirmed`** — if your signal logic is gated by `if barstate.isconfirmed`, then live-bar flicker is invisible to your signal (it sees only the frozen close-of-bar value), and you can safely use `_phase = 0` with no practical consequence For every other case — and especially for any live alert or automated trading system — use `_phase ≥ 1`. Two bars of lag on a clean, stable curve is almost always worth more than zero lag on a curve that redraws itself several times per bar. 🟦 UNIFIED DISPATCHER — `estimate()` For indicators where the user picks a kernel from a dropdown, writing eight separate ternary branches is tedious and error-prone. KernelLens ships with a unified dispatcher that routes to the correct kernel based on a string argument: ```pine import a_jabbaroff/KernelLens/1 as kl line = kl.estimate( kernelType = kl.KERNEL_GAUSS, src = close, bandwidth = 32, shapeAlpha = 1.0, period = 1, phase = 2, filter = kl.FILTER_SMOOTH) ``` The dispatcher forwards to the matching typed export, so there is no performance penalty versus calling the kernel directly — it is a compile-time routing pass. Unknown kernel names raise a descriptive `runtime.error` naming every valid alternative, so typos fail loudly instead of silently returning `na`. **Public Constants** KernelLens exposes its string constants so callers never type the magic values by hand: | Constant | Value | |---|---| | `FILTER_NONE` | `"No Filter"` | | `FILTER_SMOOTH` | `"Smooth"` | | `FILTER_ZEROLAG` | `"Zero Lag"` | | `KERNEL_RQ` | `"Rational Quadratic"` | | `KERNEL_GAUSS` | `"Gaussian"` | | `KERNEL_PERIODIC` | `"Periodic"` | | `KERNEL_LOCPER` | `"Locally Periodic"` | | `KERNEL_EPA` | `"Epanechnikov"` | | `KERNEL_TRICUBE` | `"Tricube"` | | `KERNEL_TRIANG` | `"Triangular"` | | `KERNEL_COSINE` | `"Cosine"` | Using the constants in your caller code means the Pine compiler — not a runtime string compare — catches typos at edit time. 🟦 UTILITY LAYER — FIVE PROFESSIONAL HELPERS KernelLens ships with five utility exports that complement the core estimators. They are the functions you almost always write immediately after getting a smoothed line, factored out so you don't rewrite them in every indicator. **`slope(estimate, step)` — Discrete First Derivative** Returns `(y_t − y_{t−step}) / step`, the normalized rate of change over `step` bars. Use it to detect whether a kernel output is trending up, flat, or down — the foundation for any trend-following signal built on top of KernelLens. ```pine rising = kl.slope(line, 3) > 0.0 ``` **`trendState(estimate, step)` — Ternary Trend Indicator** Returns `+1` if the estimate is rising, `−1` if falling, `0` if exactly flat over the window. A single-call replacement for hand-rolled `line > line ? 1 : line < line ? -1 : 0` ladders. **`crossSignal(fast, slow)` — Bi-directional Crossover** Returns `+1` on the bar where `fast` crosses above `slow` (bullish), `−1` on a bearish cross, and `0` otherwise. Built on `ta.crossover` / `ta.crossunder`, so the signal is non-repainting once the bar is confirmed. **`confidenceBand(src, estimate, window)` — Residual Standard Deviation** Computes the rolling standard deviation of `(src − estimate)` over a user-defined window. Use the return value as the half-width of a confidence band around the estimate: ```pine est = kl.gaussian(close, 32, 2, kl.FILTER_SMOOTH) sigma = kl.confidenceBand(close, est, 50) upper = est + 1.96 * sigma lower = est - 1.96 * sigma ``` This is a computationally cheap proxy for the full kernel-weighted local variance — ideal when you need visual bands without paying for a second weighted pass. **`silvermanBandwidth(src, window)` — Optimal ℓ Suggestion** Returns the Silverman rule-of-thumb bandwidth: ``` h ≈ 1.06 · σ · n^(−1/5) ``` where `σ` is the rolling standard deviation of the source and `n` is the window size. This is the classical starting point for Gaussian-family bandwidths in academic texts (Silverman 1986). Because Pine requires `simple int` for kernel bandwidth, the returned value is intended for diagnostic display — plot it, read it off the chart, then hard-code the rounded integer into the kernel call. 🟦 INPUT VALIDATION — FAIL LOUDLY, FAIL EARLY Every public function in KernelLens validates its inputs through a set of internal `_assert*` helpers. Invalid arguments never produce silent `na` fallbacks or buried zero-divisions — they raise `runtime.error` with a descriptive message identifying the function, the parameter, and the expected range. | Helper | Checks | Raises On | |---|---|---| | `_assertFilter` | Filter string is `FILTER_NONE`, `FILTER_SMOOTH`, or `FILTER_ZEROLAG` | Typos like `"No FIlter"` (capital I) — a bug that exists in at least one published kernel indicator | | `_assertBandwidth` | Bandwidth is a strictly positive integer | Negative or zero bandwidth, which would cause division by zero or infinite loops | | `_assertPeriod` | Period is a strictly positive integer | Zero period, which would cause `sin(π·d/0)` in Periodic kernels | | `_assertAlpha` | Rational Quadratic shape parameter is strictly positive | Zero or negative `α`, which would invert the RQ formula | Error messages are prefixed `KernelLens:` (or `KernelLens.:`) so they are easy to spot in the TradingView runtime log. Every message names the parameter that failed, the value that was passed, and the set of valid alternatives — so a misconfigured chart tells you exactly what to fix. 🟦 LOOP DEPTH — THE BUG FIX THAT MOTIVATED KERNELLENS The two most popular Pine kernel libraries on TradingView share the same fatal bug: both compute their loop depth as ```pine _size = array.size(array.from(_src)) ``` where `array.from(_src)` creates a **one-element array containing the current value of `_src`**, so `_size` is always `1`. The loop then runs `for i = 0 to 1 + startAtBar`, effectively using only `startAtBar + 2` bars — completely ignoring the user's bandwidth. Every published kernel indicator built on those libraries inherits this silent miscalculation. KernelLens replaces the broken helper with three explicit depth selectors: | Helper | Depth | Used By | |---|---|---| | `_depthInfinite(bw)` | `max(bw · 3, 4)` | Gaussian, Rational Quadratic, Locally Periodic | | `_depthCompact(bw)` | `max(bw, 4)` | Epanechnikov, Tricube, Triangular, Cosine | | `_depthPeriodic(bw, p)` | `max(bw · 3, p · 10, 4)` | Periodic | For Gaussian-family kernels, the `3·ℓ` cutoff captures approximately 99.7% of the kernel mass (the three-sigma rule). For compact-support kernels, the depth equals the bandwidth exactly — the loop terminates at the kernel's natural zero point. For Periodic kernels, the depth is the larger of the scale-based and cycle-based minima, so the loop always spans enough periods to produce a stable weighted average. The loop counter `i` runs over bar offsets starting at `_phase`, every bar lookup is NA-checked before being incorporated into the sum, and the final `num / den` division is guarded against zero denominators. On a fresh chart, the kernel gracefully returns `na` for bars where the window extends past available history, rather than producing poisoned sums from implicit NA arithmetic. 🟦 API REFERENCE **Core Kernel Estimators — Eight Exports** | Export | Signature | |---|---| | `rationalQuadratic` | `(src, bandwidth, shapeAlpha, phase, filter) → float` | | `gaussian` | `(src, bandwidth, phase, filter) → float` | | `periodic` | `(src, bandwidth, period, phase, filter) → float` | | `locallyPeriodic` | `(src, bandwidth, period, phase, filter) → float` | | `epanechnikov` | `(src, bandwidth, phase, filter) → float` | | `tricube` | `(src, bandwidth, phase, filter) → float` | | `triangular` | `(src, bandwidth, phase, filter) → float` | | `cosineKernel` | `(src, bandwidth, phase, filter) → float` | **Unified Dispatcher** | Export | Signature | |---|---| | `estimate` | `(kernelType, src, bandwidth, shapeAlpha, period, phase, filter) → float` | **Utility Layer — Five Exports** | Export | Signature | |---|---| | `slope` | `(estimate, step) → float` | | `trendState` | `(estimate, step) → int` | | `crossSignal` | `(fast, slow) → int` | | `confidenceBand` | `(src, estimate, window) → float` | | `silvermanBandwidth` | `(src, window) → float` | **Parameter Types** | Name | Pine Type | Description | |---|---|---| | `src` | `series float` | Source series (close, hl2, ohlc4, or any other price-derived series) | | `bandwidth` | `simple int` | Kernel scale `ℓ`, must be `> 0` | | `shapeAlpha` | `simple float` | Rational Quadratic shape parameter, must be `> 0` | | `period` | `simple int` | Periodic repetition distance, must be `> 0` | | `phase` | `simple int` | Kernel center offset in bars, must be `≥ 0` | | `filter` | `simple string` | One of `FILTER_NONE`, `FILTER_SMOOTH`, `FILTER_ZEROLAG` | | `kernelType` | `simple string` | One of the eight `KERNEL_*` constants | | `step` | `simple int` | Finite-difference step for `slope` / `trendState`, must be `≥ 1` | | `window` | `simple int` | Rolling window for `confidenceBand` / `silvermanBandwidth`, must be `≥ 2` | 🟦 USAGE EXAMPLES **Minimal — One Gaussian Curve** ```pine //@version=6 indicator("KernelLens — Gaussian Demo", overlay = true) import a_jabbaroff/KernelLens/1 as kl line = kl.gaussian(close, 32, 2, kl.FILTER_SMOOTH) plot(line, "Gaussian", color = color.orange, linewidth = 2) ``` **Fast / Slow Crossover System** ```pine //@version=6 indicator("KernelLens — RQ Crossover", overlay = true) import a_jabbaroff/KernelLens/1 as kl fast = kl.rationalQuadratic(close, 8, 1.0, 2, kl.FILTER_NONE) slow = kl.rationalQuadratic(close, 32, 1.0, 2, kl.FILTER_SMOOTH) cross = kl.crossSignal(fast, slow) plot(fast, "Fast", color = color.aqua, linewidth = 2) plot(slow, "Slow", color = color.orange, linewidth = 2) plotshape(cross == 1, "Bull", location = location.belowbar, color = color.lime, style = shape.triangleup, size = size.tiny) plotshape(cross == -1, "Bear", location = location.abovebar, color = color.red, style = shape.triangledown, size = size.tiny) ``` **Confidence Band Envelope** ```pine //@version=6 indicator("KernelLens — Confidence Band", overlay = true) import a_jabbaroff/KernelLens/1 as kl est = kl.tricube(close, 48, 2, kl.FILTER_SMOOTH) sigma = kl.confidenceBand(close, est, 50) k = 1.96 upper = est + k * sigma lower = est - k * sigma plot(est, "Estimate", color = color.orange, linewidth = 2) p1 = plot(upper, "+1.96σ", color = color.new(color.aqua, 70)) p2 = plot(lower, "−1.96σ", color = color.new(color.aqua, 70)) fill(p1, p2, color = color.new(color.aqua, 92)) ``` **Dropdown-Driven Kernel Selection** ```pine //@version=6 indicator("KernelLens — Dropdown", overlay = true) import a_jabbaroff/KernelLens/1 as kl kernelType = input.string(kl.KERNEL_GAUSS, "Kernel", options = ) bandwidth = input.int(32, "Bandwidth", minval = 2) alphaRQ = input.float(1.0,"RQ Alpha", minval = 0.01, step = 0.25) period = input.int(20, "Period", minval = 1) phase = input.int(2, "Phase", minval = 0) filter = input.string(kl.FILTER_SMOOTH, "Filter", options = ) line = kl.estimate(kernelType, close, bandwidth, alphaRQ, period, phase, filter) plot(line, "KernelLens", color = color.orange, linewidth = 2) ``` 🟦 TIMEFRAME PRESETS — BANDWIDTH BY STYLE Kernel bandwidth is the single most important parameter. It controls the trade-off between reactivity (small `ℓ`, tight fit, noisier) and stability (large `ℓ`, smooth curve, slower to react). The presets below are tested starting points — adjust by ±25 % to taste. --- **SCALPER — 1m / 3m / 5m** | Parameter | Value | |---|---| | Bandwidth (ℓ) | 8 | | Phase | 1 | | Filter | `FILTER_NONE` | | Best Kernel | Rational Quadratic or Gaussian | | RQ shapeAlpha | 1.0 | **Why:** Short bandwidth means the kernel reacts within a handful of bars. `FILTER_NONE` removes the double-pass lag, so the estimate tracks price as tightly as possible. Phase 1 keeps the estimate nearly live while still avoiding the current-bar tick noise. --- **DAY TRADER — 15m / 30m / 1H** | Parameter | Value | |---|---| | Bandwidth (ℓ) | 16 | | Phase | 2 | | Filter | `FILTER_SMOOTH` | | Best Kernel | Gaussian or Tricube | | RQ shapeAlpha | 1.0 | **Why:** Balanced reactivity — the 16-bar Gaussian is the default Silverman range for intraday price data, and `FILTER_SMOOTH` removes most of the bar-to-bar chop without significantly increasing lag. Tricube provides near-identical behaviour with strict compact support and is preferred on noisy assets where outlier bars should not influence the curve. --- **SWING TRADER — 4H / 1D** | Parameter | Value | |---|---| | Bandwidth (ℓ) | 32 | | Phase | 3 | | Filter | `FILTER_SMOOTH` | | Best Kernel | Rational Quadratic | | RQ shapeAlpha | 2.0 | **Why:** Swing trades need structural signals, not intraday noise. Rational Quadratic with `α = 2.0` mixes medium and long length scales, producing a curve that ignores transient spikes but catches genuine regime shifts. Phase 3 shifts the estimate three bars back so each swing decision is made against a fully confirmed kernel output. --- **POSITION / LONG-TERM — 1D / 1W / 1M** | Parameter | Value | |---|---| | Bandwidth (ℓ) | 64 | | Phase | 5 | | Filter | `FILTER_SMOOTH` or `FILTER_ZEROLAG` | | Best Kernel | Gaussian or Locally Periodic | | Period (if LP) | 52 (weekly cycle) | **Why:** Position traders care about the macro trajectory. A Gaussian with ℓ = 64 produces a curve that only turns on genuine multi-month inflections. Locally Periodic with `period = 52` is the ideal choice when a clear seasonal cycle is present — it uses both the long-range Gaussian envelope and the 52-bar periodicity to highlight cycle turns that align with trend. --- **RESEARCH — Academic / Backtest** | Parameter | Value | |---|---| | Bandwidth (ℓ) | Compute via `silvermanBandwidth(src, 200)` | | Phase | 0 | | Filter | `FILTER_NONE` | | Best Kernel | Epanechnikov | **Why:** Epanechnikov is the MSE-optimal kernel; `FILTER_NONE` keeps the estimator in its classical single-pass form; `phase = 0` centers the kernel on the bar being evaluated. This is the configuration that matches the statistical literature exactly — use it when publishing research, running Monte-Carlo studies, or calibrating against reference implementations. 🟦 BANDWIDTH SELECTION Bandwidth `ℓ` is the single most consequential choice in kernel regression. Too small and the estimate overfits local noise; too large and it flattens real structure. KernelLens exposes two helpers to support both manual and semi-automated bandwidth selection. **Manual — Start with ℓ ≈ √n** A practical starting point for financial time series: set `ℓ ≈ √window_of_interest`. If you care about 100-bar structure, try `ℓ = 10`. If you care about 400-bar structure, try `ℓ = 20`. Adjust by ±25 % based on how noisy the result looks. **Silverman's Rule of Thumb** The closed-form optimal bandwidth for Gaussian-family kernels under Gaussian source assumptions: ``` h ≈ 1.06 · σ · n^(−1/5) ``` Call `silvermanBandwidth(src, window)` to compute this value live. Because Pine requires `simple int` bandwidth at compile time, the returned value is for diagnostic use — plot it, read the stable value off the chart, then hard-code the rounded integer into your kernel calls. **Leave-One-Out Cross-Validation (Manual)** For academic rigor, compute the leave-one-out mean squared error for a range of bandwidths and pick the minimum. KernelLens does not automate this (it would require `series int` bandwidth, which Pine does not support inside kernel loops), but the formula is straightforward: ``` LOOCV(ℓ) = (1/n) · Σᵢ (yᵢ − ŷᵢ⁻ⁱ(ℓ))² ``` where `ŷᵢ⁻ⁱ` is the kernel estimate at bar `i` computed without including bar `i` in the sum. Evaluate offline, pick the minimum, hard-code the result. 🟦 FILTER SELECTION — WHEN TO USE EACH | Filter | Best For | Avoid When | |---|---|---| | `FILTER_NONE` | Live signal generation, research / calibration, compact-support kernels on noisy data | Choppy markets where you need extra smoothing | | `FILTER_SMOOTH` | Swing and position trades, confidence band midlines, most day-trading setups | Scalping — the double pass adds measurable lag | | `FILTER_ZEROLAG` | Regime detection, crossover systems that need the curve to track price tightly | Low-volume assets — Zero Lag amplifies high-frequency noise | The three filters use the same underlying kernel with the same bandwidth, so switching between them does not require re-tuning. Default to `FILTER_SMOOTH` when in doubt — it is the best-behaved option across the widest range of assets and timeframes. 🟦 COMPATIBILITY KernelLens targets Pine Script v6 and runs on every TradingView chart — no exchange, asset class, or timeframe restriction. - **Crypto** — Spot, futures, perpetual contracts - **Forex** — All majors, minors, and exotics - **Equities** — Stocks, ETFs, indices - **Commodities** — Metals, energy, agriculture - **Timeframes** — 1 minute through Monthly The library is deterministic — given the same source and parameters, every bar of every symbol produces the same estimate. No calibration is needed across assets; the bandwidth parameter alone controls smoothness, and the kernel formulas are scale-free in the source dimension. Silverman's bandwidth helper automatically adapts to each asset's volatility. 🟦 TECHNICAL NOTES - **Pine Script v6** — uses the modern type system, strict type checking, and the `switch` expression in the unified dispatcher - **Non-repainting** — kernel outputs for any confirmed bar depend only on that bar's history; there is no look-ahead, no `request.security` with lookahead, and no dependency on the unconfirmed current bar unless `_phase = 0` is deliberately chosen - **NA-safe iteration** — every bar lookup inside a kernel loop is guarded by `if not na(y)`, so chart history gaps and warm-up bars cannot poison the weighted sum - **Division-by-zero protection** — every kernel's final division checks `den > 0.0` and returns `na` if the denominator collapses (which can only happen on truly empty windows) - **Input validation** — every public function asserts its preconditions up front via `_assertFilter`, `_assertBandwidth`, `_assertPeriod`, `_assertAlpha`, and raises `runtime.error` with a descriptive message on misuse — no silent `na` fallbacks - **Lazy filter evaluation** — the `"No Filter"` path never executes the second kernel pass; the `if`-branch check short-circuits, so single-pass mode is as cheap as a raw kernel call - **Correct loop bounds** — `_depthInfinite`, `_depthCompact`, and `_depthPeriodic` compute the correct window size per kernel family, fixing the silent `_size = 1` bug that plagues every other published Pine kernel library - **No persistent state** — the library is purely functional: no `var`, no arrays, no history buffers that grow over time; every export is a pure expression of `(inputs) → output`, so Pine's `max_*_count` limits cannot be exceeded and the library cannot leak memory - **O(bandwidth) per bar per kernel call** — the loop depth is bounded by the constants in Section 0; there is no hidden quadratic behavior and the cost scales linearly with the user-chosen bandwidth - **Unicode-safe comments** — the source uses academic notation (`σ`, `ℓ`, `α`, `ŷ`, `ℝ`) where it improves readability; all strings are plain ASCII for runtime compatibility 🟦 ACADEMIC REFERENCES Every kernel and every formula in KernelLens is cited inline in the source. The combined bibliography: - **Nadaraya, E. A. (1964).** On estimating regression. *Theory of Probability & Its Applications*, 9(1), 141–142. - **Watson, G. S. (1964).** Smooth regression analysis. *Sankhyā: The Indian Journal of Statistics, Series A*, 26(4), 359–372. - **Cleveland, W. S. (1979).** Robust locally weighted regression and smoothing scatterplots. *Journal of the American Statistical Association*, 74(368), 829–836. *(Tricube kernel, LOWESS.)* - **Silverman, B. W. (1986).** *Density Estimation for Statistics and Data Analysis*. Chapman & Hall, London. *(Bandwidth rule of thumb.)* - **Wand, M. P. & Jones, M. C. (1995).** *Kernel Smoothing*. Chapman & Hall. *(Unified treatment of all eight kernels.)* - **MacKay, D. J. C. (1998).** Introduction to Gaussian Processes. *NIPS Tutorial*. *(Periodic and Rational Quadratic kernels.)* - **Ehlers, J. F. (2000).** *Rocket Science for Traders*. John Wiley & Sons. *(Zero-lag smoothing trick.)* - **Rasmussen, C. E. & Williams, C. K. I. (2006).** *Gaussian Processes for Machine Learning*. MIT Press. *(Locally Periodic and Rational Quadratic kernels.)* 🟦 VERSIONING & LICENSE - **Version** — 1.0.0 - **Pine Script** — v6 - **License** — Mozilla Public License 2.0 - **Status** — Production-ready KernelLens follows semantic versioning. Minor versions add new exports without breaking existing ones; patch versions fix bugs; major versions may change function signatures and will be announced in the changelog. 🟦 DISCLAIMER KernelLens is a mathematical library for non-parametric regression on financial time series using the Nadaraya–Watson method. The library is provided solely for educational and research purposes and does not constitute financial, investment, or trading advice. Kernel regression is a local smoothing technique. It estimates the mean of a source series in the neighborhood of the current bar based on historical data, but it does not predict future prices, does not generate trading signals on its own, and does not guarantee the profitability of any strategy built on top of its output. Past performance of any model does not guarantee future results. Markets contain systemic risks that cannot be eliminated by any amount of mathematical rigor in the kernel itself. Responsibility for any trading decisions made using this library rests entirely with the user. Always apply sound capital management, conduct your own independent analysis, and never risk capital you are not prepared to lose. The author assumes no liability for direct or indirect losses incurred through the use of KernelLens or any indicator built on top of it.
Pine Script® library
by a_jabbaroff
1