OptiPine: High-Performance Caching and Data PipelinesOptiPine is a high performance architecture library for Pine Script™, built for algorithms that push beyond ordinary indicator workloads. It turns caching, sparse updates, reusable storage and workload-aware data structures into practical APIs that stay small at the call site.
In a small indicator, optimization is often optional. In a rendering engine, machine learning library, simulation, dashboard or object system, it can determine whether a feature runs at all. The problem is rarely one slow formula. It is the thousands of unnecessary operations around it: recalculating unchanged results, shifting rolling arrays, scanning large collections for a few changes, and moving stored objects when one disappears.
OptiPine attacks that layer with techniques used in projects such as Pine3D and NeuraLib . The idea is simple: do less work, move less data, and let the representation follow the workload.
Compared with conventional Pine implementations of the same task, OptiPine's optimized paths commonly ran 15% to 40% faster . Sparse updates and indexed lookups exceeded 90% when the alternative scanned or searched the full collection.
Most users can stay entirely within the high-level API. A Memo cache with several dependencies looks like this:
// Pseudocode: trendRegime and volatilityRegime are floats;
// rebuildModel() is a pure calculation.
var op.FloatMemo model = op.floatMemo()
if model.staleOn(trendRegime, volatilityRegime)
model.store(rebuildModel(trendRegime, volatilityRegime))
float result = model.get()
// Output: rebuildModel() runs once, then only when either regime changes.
Memo owns the previous dependencies, first-run state, validity and cached result. The caller only declares what the result depends on.
----------------------------------------------------------------------------------------------------------------
🔷 DO NOT CALCULATE THE SAME THING TWICE
The fastest expensive calculation is the one that never needed to run. Models, simulations and generated geometry often remain valid across many script executions.
Memo is the direct choice when the cached result is an int, float, bool, string or color. staleOn() checks up to four floats, two integers, one Boolean and one string; store() saves a rebuilt value, and get() returns it.
Many models respond to regimes rather than every tiny change in raw data. Round the inputs into meaningful regimes, pass them to staleOn() , and the model runs only when a regime changes.
In practice: Memo is useful for scenario models, parameter sweeps, numerical solvers and other expensive pure calculations that reduce to one primitive result. If its dependencies repeat on nine out of ten executions, it avoids roughly 90% of those model runs.
For collections or a variable dependency list, use Memo's explicit begin() , dependencies.watch*() and miss() lifecycle.
Keep guarded work pure: Stateful ta.* and similar history-dependent calls must remain outside Memo and Watch guards. Compute them every bar, then pass their results into the guarded calculation.
🔸 WATCH: CHANGE DETECTION WITHOUT RESULT STORAGE
Watch is the lighter choice when the caller already owns the result. Several consumers can observe the same producer independently by giving each its own Watch. changed() returns true on the first observation and whenever one scalar, primitive array or OptiPine row ring changes. Row rings expose an internal revision, so checking them is O(1).
For a single source, the dependency check should take less attention than the calculation it protects. Here another component supplies one caller-owned feature array:
// Pseudocode: getFeatureSnapshot() supplies an array.
array features = getFeatureSnapshot()
var op.Watch featureWatch = op.watch()
var float modelScore = na
if featureWatch.changed(features)
modelScore := evaluateModel(features)
// Output: modelScore is rebuilt only when the features array changes.
Because OptiPine does not own features , it compares the array with a retained snapshot and rewrites that snapshot only after a change. Supported row rings use their internal revision instead. The call stays the same, and this compare-first array pattern measured roughly 35% to 60% faster than rewriting the snapshot every time.
The array comparison is still O(N), so use it when the avoided calculation costs more than the comparison. If the producer already provides one reliable change flag, use the flag directly.
For several dependencies, use an explicit pass. begin() starts the comparison, the typed watch*() methods add dependencies, and finish() returns true if the completed set changed. A Watch remembers dependencies; it does not store the result.
// Pseudocode dependencies: int length, float multiplier,
// and array features.
var op.Watch settingsWatch = op.watch()
var float result = na
settingsWatch.begin()
settingsWatch.watchInt(length)
settingsWatch.watchFloat(multiplier)
settingsWatch.watchFloats(features)
bool dependenciesChanged = settingsWatch.finish()
if dependenciesChanged
result := rebuild(length, multiplier, features)
// Output: result is rebuilt when any observed dependency changes.
Construct the Watch once with var , then run begin() and finish() on every comparison pass. For one dependency, changed(source) is the shorter path.
In practice: Watch fits module boundaries: a model can observe a feature array, a renderer can observe a managed ring, or a cache can observe several mixed settings without duplicating the producer's change logic.
CadenceGate limits how often work may run. due() is periodic; dueWhenChanged() also requires a producer revision and remembers changes until the cadence opens. Use it for intentionally delayed work such as periodic model fitting, not results that must update immediately.
----------------------------------------------------------------------------------------------------------------
🔷 ROLLING HISTORY WITHOUT SHIFTING IT
Rolling histories often perform work that adds nothing to the result. If an array keeps the latest 200 events, removing the oldest one and shifting the other 199 entries is unnecessary.
FloatRowRing and IntRowRing keep fixed-width rows in reusable storage. Once full, the next row overwrites the oldest physical slot while reads remain chronological.
var op.FloatRowRing history = op.floatRowRing(200, 3)
float atr14 = ta.atr(14)
if barstate.isconfirmed
history.push(array.from(close, volume, atr14))
float oldestPrice = history.at(0, 0)
float latestPrice = history.newestAt(0, 0)
// Output: after a confirmed push, these are the oldest and newest retained closes.
A push costs O(width), or O(1) through pushValue() for a width-one ring. Rings also provide chronological windows and gathered rows. When several producers can mutate a ring, a separate consumer can detect its revision with Watch.changed(ring) in O(1).
In practice: Row rings fit pivots, completed trades, sampled features and other fixed event histories.
Performance: A full ring overwrites one row instead of shifting every retained row. Its chronological output uses at most two native contiguous copies, which measured 90% faster than rebuilding a 512-cell, width-four output row by row.
Use RingCursor when several caller-owned arrays need the same circular layout. Ordinary series history such as close should remain native Pine.
----------------------------------------------------------------------------------------------------------------
🔷 KEEP DYNAMIC OBJECTS STABLE
Dynamic objects become surprisingly expensive when identity is tied to array position. If one object is removed from several parallel arrays, every later entry shifts, every synchronized payload array needs the same removal, and every external reference to those positions becomes fragile.
StablePool is not the zone storage itself. It keeps one association: an object ID supplied by the script points to a reusable array slot. The ID answers "which zone is this?" while the slot answers "where is this zone's data stored?"
The example has three different logical zones named A, B and C. Their IDs, 1001, 1002 and 1003, are arbitrary unique values chosen for readability. Real IDs may come from a pivot bar, timestamp, order number or incrementing counter.
const int ZONE_A_ID = 1001
const int ZONE_B_ID = 1002
const int ZONE_C_ID = 1003
var op.StablePool zonePool = op.stablePool()
// This example never has more than two active zones.
var array prices = array.new(2, na)
if barstate.isfirst
// A receives slot 0. B receives slot 1.
= zonePool.acquire(ZONE_A_ID)
= zonePool.acquire(ZONE_B_ID)
prices.set(slotA, 100.0)
prices.set(slotB, 200.0)
// Zone A no longer exists. Its slot becomes available.
zonePool.release(ZONE_A_ID)
// C is a new zone with a new identity, but it can reuse A's old slot.
= zonePool.acquire(ZONE_C_ID)
prices.set(slotC, 300.0)
// Output: B keeps slot 1. C has ID 1003 but reuses A's released slot 0.
// prices is .
Why C needs a new ID: C is a different zone, even though it occupies the same array position A once used. Reusing 1001 would describe A returning, not a new zone C. IDs preserve object identity; slots are only reusable storage addresses.
Several fields, one slot: In production, the same slot usually addresses every field belonging to the object. Continuing the A, B and C lifecycle with four parallel arrays:
const int ZONE_A_ID = 1001
const int ZONE_B_ID = 1002
const int ZONE_C_ID = 1003
var op.StablePool zonePool = op.stablePool()
var array zonePrices = array.new()
var array zoneTimes = array.new()
var array zoneStrengths = array.new()
var array zoneColors = array.new()
if barstate.isfirst
= zonePool.acquire(ZONE_A_ID)
= zonePool.acquire(ZONE_B_ID)
// Grow every payload array to cover the allocated slots.
int required = zonePool.slotCount()
op.ensureSizeFloat(zonePrices, required, na)
op.ensureSizeInt(zoneTimes, required, na)
op.ensureSizeFloat(zoneStrengths, required, na)
op.ensureSizeColor(zoneColors, required, na)
zonePrices.set(slotA, 100.0)
zoneTimes.set(slotA, 10)
zoneStrengths.set(slotA, 0.40)
zoneColors.set(slotA, color.blue)
zonePrices.set(slotB, 200.0)
zoneTimes.set(slotB, 20)
zoneStrengths.set(slotB, 0.80)
zoneColors.set(slotB, color.red)
zonePool.release(ZONE_A_ID)
= zonePool.acquire(ZONE_C_ID)
// C reuses A's slot, so every field at that slot must be overwritten.
zonePrices.set(slotC, 300.0)
zoneTimes.set(slotC, 30)
zoneStrengths.set(slotC, 0.60)
zoneColors.set(slotC, color.lime)
// Output: B keeps slot 1 in every array. C owns slot 0 in every array.
// Nothing is removed or shifted.
acquire(id) returns the slot and whether the ID was newly added. Calling it again for an active ID returns the same slot. release(id) frees the slot, but does not erase its array data, so every field must be overwritten when that slot is reused.
The example preallocates two values because it has at most two active zones. A dynamic script can grow its payload arrays with ensureSize*() whenever acquire() reports a new ID. zonePool.slots() returns the currently active slots as a read-only view.
In practice: One zone slot can index its price, time, color, strength and line across several arrays. In the complete example later, the pivot bar and event type form each zone ID. Releasing one zone frees its slot without shifting other zones or breaking saved positions.
Performance: StablePool is independent of payload layout: its slots can index parallel arrays or one array of UDTs. acquire() , release() and find() are O(1), and releasing an object never shifts caller-owned payloads.
For a few fixed objects, manual indices are simpler. StablePool becomes useful when IDs appear and disappear over time, several payload arrays share the same slots, or other parts of the script retain those positions.
SlotCache is the frame-based alternative. Call begin() , acquire every active key, then call finish() ; previously active keys that were not touched are retired automatically.
----------------------------------------------------------------------------------------------------------------
🔷 UPDATE ONLY WHAT CHANGED
Large state does not imply large change. A dashboard may contain 10,000 cells while only a few change on one bar, or a large object system may need to refresh only a handful of entries.
A conventional dirty-flag array must be cleared and scanned in full. DirtySet stores only the changed indices, removes duplicate marks and begins a new cycle without clearing the entire universe. It is a work list, not payload storage or an ID-to-slot map.
Here StablePool resolves zoneId , the arrays store zone data, and DirtySet schedules the slots that need rebuilding. The event values are pseudocode:
int MAX_ZONES = 50000
var op.StablePool zones = op.stablePool()
var op.DirtySet dirtySlots = op.dirtySet(MAX_ZONES)
var array tops = array.new()
var array bottoms = array.new()
var array midpoints = array.new()
// Start this bar's sparse-work cycle.
dirtySlots.begin()
if zoneGeometryChanged
// StablePool converts the logical ID into a reusable physical slot.
= zones.acquire(zoneId)
if created
op.ensureSizeFloat(tops, zoneSlot + 1, na)
op.ensureSizeFloat(bottoms, zoneSlot + 1, na)
op.ensureSizeFloat(midpoints, zoneSlot + 1, na)
tops.set(zoneSlot, newTop)
bottoms.set(zoneSlot, newBottom)
dirtySlots.mark(zoneSlot)
if zoneStyleChanged
int styleSlot = zones.find(zoneId)
if styleSlot >= 0
dirtySlots.mark(styleSlot) // A second mark of the same slot is ignored.
// Process only the distinct physical slots marked during this bar.
for dirtySlot in dirtySlots.values()
float midpoint = (tops.get(dirtySlot) + bottoms.get(dirtySlot)) * 0.5
midpoints.set(dirtySlot, midpoint)
redrawZone(zones.keyAt(dirtySlot), midpoint)
// Output: one zone is rebuilt once even if geometry and style both mark it.
Repeated marks are deduplicated, and unmarked zones are never visited. Work scales with the number of changed slots, not the size of the collection. If the natural address is already a dense index, mark it directly without StablePool.
In practice: Several producers can mark work, then one consumer updates each affected cell, drawing or record once. With 1% of entries changed, this measured 93% faster than clearing and scanning the full universe.
----------------------------------------------------------------------------------------------------------------
🔷 KEYED LOOKUP WITHOUT GUESSWORK
Keyed lookup appears throughout object systems, caches and grouped data, but no structure fits every key set. Distribution, rebuild frequency and query volume change the best choice. OptiPine sees the completed keys at build() , then selects the lookup shape that fits them.
🔸 TYPED STORES: ONE VALUE PER KEY
A typed store maps each integer key to one primitive value. build() pairs entries at matching positions in the key and value arrays. Consecutive IDs allow direct addressing:
var op.IntFloatStore scores = op.intFloatStore()
if barstate.isfirst
// Four entries are shown for readability; both arrays may be much larger.
scores.build(
array.from(410, 411, 412, 413),
array.from(0.80, 0.30, 0.95, 0.50))
float selected = scores.get(412)
// Output: integer key 412 resolves to float value 0.95.
Lookup is one-way: get(412) returns 0.95 , but values may repeat, so get(0.95) has no general meaning.
What automatic mode chooses:
Consecutive ascending keys: Direct arithmetic indexing.
Compact key ranges: A dense lookup table.
Other unordered keys: A native map when within Pine's map limit.
Ascending sparse keys: Binary search, or a map within that limit when expectedQueries justifies its build cost.
Linear lookup remains available for unusual workloads that rebuild far more often than they query. Automatic mode only selects it for non-empty stores when linearMaxEntries is deliberately configured.
The same API avoids hashing when direct addressing fits, uses a map when it pays, and remains usable beyond Pine's map capacity. Automatic mode is the normal default. Use op.indexConfigDynamic() when future query volume is unknown and the store may need to promote itself later.
build(keys, values, expectedQueries) accepts two same-length arrays. The optional hint tells OptiPine how many lookups to expect before the next build. Stores support int, float, bool, string and color values. Use one IntIndex for several payload fields, or IntBuckets when a key owns several integers.
In practice: Batch-build IDs to scores, states or metadata, then query them without committing to a representation. Direct integer addressing measured 21% faster than a map, while a map measured 91% faster than repeated linear lookup with 32 entries.
🔸 INTBUCKETS: ONE KEY TO MANY INTEGER VALUES
A Store returns one value for each key. IntBuckets returns a group of integers, usually object IDs or physical slots. Repeating a key adds another member instead of replacing the previous one.
var op.IntBuckets cellMembers = op.intBuckets()
var array matches = array.new()
if barstate.isfirst
// Six (cell, object slot) pairs. Cell 7 appears three times.
array cellKeys = array.from(7, 2, 7, 5, 2, 7)
array objectSlots = array.from(101, 205, 412, 990, 777, 888)
cellMembers.buildFromPairs(cellKeys, objectSlots)
// Read cell 7's group from flat storage. matches is only demo output.
= cellMembers.rangeByKey(7)
if count > 0
for position = start to start + count - 1
matches.push(cellMembers.valueAt(position))
// Output: matches contains , the object slots assigned to cell 7.
What happens: Each key is paired with the slot at the same array position. Cell 7 appears three times, so its group contains 101, 412 and 888. rangeByKey() returns where that group starts and how many values it contains. A missing key returns a count of 0.
Lifecycle: buildFromPairs() replaces all previous groups. Use buildBegin() , add() and buildFinish() only when pairs arrive one at a time.
In practice: A price cell can own several zone slots, a graph node can own several neighbors, or a category can own several record IDs. One query visits only that group.
Why use it: A native map stores one value per key, and Pine does not allow an array directly as that value. Giving one key several values therefore requires a small wrapper UDT containing an array. IntBuckets provides that relationship directly, packing every group into shared contiguous storage. It suits batch rebuilds followed by repeated traversal, while the wrapper approach is more convenient when individual groups change constantly. In the tested 64-key traversal workload, IntBuckets averaged 19% faster across four runs.
----------------------------------------------------------------------------------------------------------------
🔷 REUSE STATE INSTEAD OF REBUILDING IT
IntDoubleBuffer and FloatDoubleBuffer retain current and previous arrays. swap() exchanges their references in O(1), preserves the old result and clears the new current buffer for reuse. That clear still costs O(N).
This is useful when one pass must remain readable while the next is built. In this small search, node n has children 2n and 2n + 1 . Each pass reads the active level and writes the next one:
var op.IntDoubleBuffer searchFrontier = op.intDoubleBuffer()
if barstate.isfirst
searchFrontier.current.push(1)
for depth = 1 to 3
= searchFrontier.swap()
for nodeId in activeFrontier
nextFrontier.push(nodeId * 2)
nextFrontier.push(nodeId * 2 + 1)
// Output: current contains .
// previous contains .
What happens: swap() makes the completed level available as activeFrontier and returns the other retained array, already empty, as nextFrontier . No level is copied and no replacement array is created. The same pattern supports graph searches, flood fills, iterative clustering and simulations. Use swapSized() when every pass needs a fixed-size output.
A var array can also be reused. The ensureSize*() , resize*() and refill*() families modify existing storage, while sameExact*() compares primitive arrays without Pine's float-comparison rounding.
Revision handles caller-owned state that OptiPine cannot observe. The producer calls bump() after a change; each consumer compares its own saved token with changedSince() instead of keeping a snapshot.
----------------------------------------------------------------------------------------------------------------
🔷 WEIGHTED SELECTION FOR STATIC AND DYNAMIC SYSTEMS
Weighted selection chooses entries in proportion to their weights. It is useful in simulations, randomized search and priority sampling.
WeightedSampler is the high-level interface. Set weights, then supply a fraction to select a slot. The sampler does not generate randomness; use math.random() or a repeatable fraction sequence:
var op.WeightedSampler sampler = op.weightedSampler(512)
if barstate.isfirst
sampler.setWeight(10, 0.25)
sampler.setWeight(11, 0.80)
sampler.setWeight(12, 0.10)
float fraction = 0.50
int selected = sampler.sample(fraction)
// Output: selected is 11 for the supplied fraction of 0.50.
The default cumulative prefix suits stable weights. Pass op.weightConfigSparseUpdates() and the sampler can move to an update-friendly Fenwick tree as the workload changes. sample() stays the same. Use WeightedIndex for circular ranges or explicit policy control.
In practice: Each slot can represent a candidate model, simulation outcome or work item. Update its weight when its score changes, then sample repeatedly through the same interface.
----------------------------------------------------------------------------------------------------------------
🔷 THREE LEVELS OF CONTROL
OptiPine is layered so high-level code describes the problem rather than the mechanism. Start with Tier 1 and move deeper only when the workload requires more control:
Tier 1, Quick: Ready-to-use APIs with automatic defaults, including Watch, Memo, CadenceGate, typed stores, StablePool, DirtySet, row rings, double buffers and WeightedSampler.
Tier 2, Composable: Explicit lifecycles, configuration and representation policies through IntIndex, IntBuckets, SlotCache, RingCursor and Revision.
Tier 3, Expert: Physical addressing, unchecked operations and scoped raw mutation for measured hot paths. Ordinary read-only views are not Tier 3.
Editor warnings: Methods such as get() , set() , push() and clear() intentionally match Pine's collection vocabulary. Any shadowing-method warning is cosmetic; the receiver's type determines which method runs.
----------------------------------------------------------------------------------------------------------------
🔷 COMPLETE, COPY-PASTE EXAMPLES
The fragments above isolate one idea at a time. These two copy-paste indicators combine them in practical workflows, using native Pine where it is simpler and OptiPine where it removes real work.
🔸 Complete example 1: high-level cached stress model
What it does: The indicator plots a probability-weighted downside estimate for the current trend and volatility regime, while exposing both regime values in the Data Window.
The EMA and ATR calculations run normally on every bar. Their rounded regimes change less often, so Memo recalculates the 401-scenario model only when one of those regimes changes and serves the cached result between changes.
//@version=6
indicator("OptiPine - Cached Regime Stress", overlay = false)
import Alien_Algorithms/OptiPine/1 as op
// Test 401 possible moves, giving more weight to common moves.
// This function is pure: its result depends only on its inputs.
estimateDownside(float trendInAtr, float atrPercent) =>
float result = na
if not na(trendInAtr) and not na(atrPercent) and atrPercent > 0
float weightedDownside = 0.0
float totalWeight = 0.0
for scenario = -200 to 200
float standardShock = scenario / 40.0
float weight = math.exp(-0.5 * standardShock * standardShock)
float projectedMove = (trendInAtr + standardShock) * atrPercent
float downside = math.max(-projectedMove, 0.0)
weightedDownside += downside * weight
totalWeight += weight
result := totalWeight > 0 ? weightedDownside / totalWeight : na
result
// Stateful Pine calculations stay outside the Memo guard.
float ema20 = ta.ema(close, 20)
float ema50 = ta.ema(close, 50)
float atr14 = ta.atr(14)
float trendInAtr = atr14 > 0 ? (ema20 - ema50) / atr14 : na
float atrPercent = close > 0 ? atr14 / close * 100.0 : na
// Quantization makes the dependencies describe a regime, not every tick.
float trendRegime = math.round(
math.max(-3.0, math.min(3.0, trendInAtr)) * 10.0) / 10.0
float volatilityRegime = math.round(atrPercent * 4.0) / 4.0
var op.FloatMemo downsideStress = op.floatMemo()
if downsideStress.staleOn(trendRegime, volatilityRegime)
downsideStress.store(
estimateDownside(trendRegime, volatilityRegime))
float stress = downsideStress.get()
plot(stress, "Expected downside (%)", color.orange, linewidth = 2)
plot(trendRegime, "Trend regime (ATR units)", display = display.data_window)
plot(volatilityRegime, "Volatility regime (%)", display = display.data_window)
🔸 Complete example 2: advanced zone-cluster engine
What it does: The indicator draws recent pivot levels, thickens those near the current price, plots the strongest price cluster and reports its key statistics in the Data Window.
StablePool preserves drawing slots, the ring tracks retirement order, DirtySet queues redraws, IntBuckets forms price clusters and IntFloatStore looks up their strength.
Relevant benchmarks: These are component results, not a total for this 32-zone indicator. In larger matching workloads, DirtySet saved 93% at 1% dirty and IntBuckets averaged 19% with 64 keys. For typed lookup, direct addressing saved 21% over a map on compact keys, while a map saved 91% over linear search at 32 entries. Automatic mode selects the representation.
StablePool and the ring manage recycling. The script still scans live zones for proximity changes, then DirtySet avoids unnecessary drawing updates.
//@version=6
indicator("OptiPine - Zone Cluster Engine", overlay = true, max_lines_count = 100)
import Alien_Algorithms/OptiPine/1 as op
int pivotLength = input.int(5, "Pivot length", minval = 1)
int maxZones = input.int(32, "Maximum zones", minval = 4, maxval = 100)
int bucketTicks = input.int(25, "Cluster size in ticks", minval = 1)
float bucketSize = syminfo.mintick * bucketTicks
// Stateful Pine calculations remain outside every conditional rebuild.
float pivotHigh = ta.pivothigh(high, pivotLength, pivotLength)
float pivotLow = ta.pivotlow(low, pivotLength, pivotLength)
float pivotStrength = math.max(nz(volume , 1.0), 1.0)
float highlightDistance = ta.atr(14)
var op.StablePool zones = op.stablePool()
var op.IntRowRing zoneOrder = op.intRowRing(maxZones, 1)
var op.DirtySet dirtyZones = op.dirtySet(maxZones)
var array zonePrices = array.new(maxZones, na)
var array zoneStrengths = array.new(maxZones, 0.0)
var array zoneTimes = array.new(maxZones, na)
var array resistance = array.new(maxZones, false)
var array highlighted = array.new(maxZones, false)
var array zoneLines = array.new(maxZones)
var op.IntBuckets zonesByBucket = op.intBuckets()
var op.IntFloatStore strengthByBucket = op.intFloatStore()
// Retained build storage is resized and overwritten, never cleared and repopulated.
var array bucketKeyByPosition = array.new()
var array aggregateKeys = array.new()
var array aggregateStrengths = array.new()
var int strongestBucketKey = na
var float strongestBucketStrength = na
var int strongestZoneCount = 0
dirtyZones.begin()
bool topologyChanged = barstate.isfirst
// Logical pivot IDs receive stable, reusable physical drawing slots.
for event = 0 to 1
float level = event == 0 ? pivotHigh : pivotLow
if barstate.isconfirmed and not na(level)
int pivotBar = bar_index - pivotLength
int pivotTime = time
int zoneId = pivotBar * 2 + event
int slot = zones.find(zoneId)
// Only a new logical pivot enters the retirement queue.
if slot < 0
if zoneOrder.rowCount() == maxZones
int oldestId = zoneOrder.at(0, 0)
zones.release(oldestId)
= zones.acquire(zoneId)
slot := newSlot
zoneOrder.pushValue(zoneId)
zonePrices.set(slot, level)
zoneStrengths.set(slot, pivotStrength)
zoneTimes.set(slot, pivotTime)
resistance.set(slot, event == 0)
highlighted.set(slot, false)
dirtyZones.mark(slot)
topologyChanged := true
// Proximity can mark a newly created slot again; DirtySet still stores it once.
for slot in zones.slots()
bool isHighlighted = math.abs(close - zonePrices.get(slot)) <= highlightDistance
if isHighlighted != highlighted.get(slot)
highlighted.set(slot, isHighlighted)
dirtyZones.mark(slot)
// Only changed drawings cross the line API boundary.
for slot in dirtyZones.values()
float level = zonePrices.get(slot)
color baseColor = resistance.get(slot) ? color.red : color.lime
line zoneLine = zoneLines.get(slot)
if na(zoneLine)
zoneLine := line.new(zoneTimes.get(slot), level, time, level,
xloc = xloc.bar_time)
zoneLines.set(slot, zoneLine)
line.set_xy1(zoneLine, zoneTimes.get(slot), level)
line.set_xy2(zoneLine, time, level)
line.set_extend(zoneLine, extend.right)
line.set_width(zoneLine, highlighted.get(slot) ? 3 : 1)
line.set_color(zoneLine,
color.new(baseColor, highlighted.get(slot) ? 0 : 55))
// Rebuild grouped lookup only after the explicit creation event.
if topologyChanged
array liveSlots = zones.slots()
int liveCount = liveSlots.size()
op.resizeInt(bucketKeyByPosition, liveCount, 0)
if liveCount > 0
for position = 0 to liveCount - 1
int slot = liveSlots.get(position)
int bucketKey = int(math.round(zonePrices.get(slot) / bucketSize))
bucketKeyByPosition.set(position, bucketKey)
// Repeated bucket keys accumulate several physical zone slots.
zonesByBucket.buildFromPairs(bucketKeyByPosition, liveSlots)
int bucketCount = zonesByBucket.bucketCount()
op.resizeInt(aggregateKeys, bucketCount, 0)
op.resizeFloat(aggregateStrengths, bucketCount, 0.0)
strongestBucketKey := na
strongestBucketStrength := na
strongestZoneCount := 0
if bucketCount > 0
for bucketSlot = 0 to bucketCount - 1
int bucketKey = zonesByBucket.keyAt(bucketSlot)
= zonesByBucket.rangeBySlot(bucketSlot)
float totalStrength = 0.0
if count > 0
for position = start to start + count - 1
int zoneSlot = zonesByBucket.valueAt(position)
totalStrength += zoneStrengths.get(zoneSlot)
aggregateKeys.set(bucketSlot, bucketKey)
aggregateStrengths.set(bucketSlot, totalStrength)
if na(strongestBucketStrength) or totalStrength > strongestBucketStrength
strongestBucketKey := bucketKey
strongestBucketStrength := totalStrength
strongestZoneCount := count
strengthByBucket.build(aggregateKeys, aggregateStrengths)
// Query the current price cluster directly and display the strongest cluster.
int currentBucketKey = int(math.round(close / bucketSize))
float nearbyStrength = strengthByBucket.get(currentBucketKey, 0.0)
float strongestClusterPrice = na(strongestBucketKey) ?
na : strongestBucketKey * bucketSize
plot(strongestClusterPrice, "Strongest zone cluster", color.orange,
linewidth = 2, style = plot.style_stepline)
plot(nearbyStrength, "Strength near current price", display = display.data_window)
plot(strongestBucketStrength, "Strongest cluster strength",
display = display.data_window)
plot(strongestZoneCount, "Zones in strongest cluster",
display = display.data_window)
plot(dirtyZones.size(), "Drawings updated", display = display.data_window)
----------------------------------------------------------------------------------------------------------------
🔷 API REFERENCE
This is a compact index of the main public entry points.
🔸 Watch and Memo: changed(source) handles one scalar, primitive array or row ring. For several dependencies, use begin() , watch*() and finish() . Typed Memos add staleOn() , store() , get() and invalidate() .
🔸 Revision and Cadence: revision() exposes bump() , current() and changedSince() for manual change tracking. cadenceGate() provides due() and change-aware dueWhenChanged() scheduling.
🔸 Row Rings: floatRowRing() and intRowRing() provide push() , width-one pushValue() , at() , setAt() , newestAt() , chronological() and gather() .
🔸 RingCursor: Circular addressing for caller-owned arrays. Use reserve() to advance, physical() and logical() to translate positions, and newest() or oldest() to locate retained rows.
🔸 StablePool: acquire() and release() manage stable key-to-slot assignments. Lookup and traversal use find() , contains() , keyAt() , slots() and size() . Recycled slots retain their caller-owned payload until overwritten.
🔸 SlotCache: Frame-based stable allocation follows begin() , acquire() , finish() . active() , retired() and size() expose its state.
🔸 DirtySet: begin() starts a cycle; mark() , markMany() and markRange() add entries. Read the distinct work list with values() and size() .
🔸 Typed Stores: intIntStore() , intFloatStore() , intBoolStore() , intStringStore() and intColorStore() map integer keys to primitive values. Build with build() , then use get() , set() , contains() or getMany() .
🔸 IntIndex: A shared integer key-to-slot directory for custom payloads and explicit lookup policy. Build with buildBegin() , add() or addMany() and buildFinish() ; query with find() , keyAt() and findMany() . IndexConfig controls representation and duplicate policy.
🔸 IntBuckets: A one-key-to-many-integers index. Build directly with buildFromPairs() , or incrementally with buildBegin() , add() or addMany() and buildFinish() . Read groups with rangeByKey() and valueAt() .
🔸 Double Buffers: intDoubleBuffer() and floatDoubleBuffer() retain current and previous arrays. swap() exchanges them; swapSized() also sizes and refills the new current buffer.
🔸 Weighted Sampling: weightedSampler() provides weight updates, sample() , sampleMany() , probability() and total() . It maps caller-supplied fractions; it does not generate randomness. weightedIndex() adds circular ranges and explicit policy control.
🔸 Storage Utilities: ensureSize*() , resize*() , refill*() and sameExact*() handle primitive arrays. Other helpers cover flat/matrix conversion, transposition and bulk ring reads.
----------------------------------------------------------------------------------------------------------------
🔷 WHY OPTIPINE EXISTS
Pine's limits are real, but standard architecture often reaches them long before the idea itself has to. Repeating unchanged calculations, shifting rolling storage, scanning mostly untouched collections and rebuilding state all consume the same execution budget the feature needs to exist.
OptiPine reclaims that budget. Expensive models can run only when their inputs change. Large dashboards can refresh only what moved. Dynamic object systems can grow and recycle storage without reorganizing everything around them. The APIs stay approachable, while the architecture underneath is built for workloads that would normally force a Pine project to scale back.
At large scale, optimization is no longer simply about feature speed. It is the factor that dictates whether an ambitious idea can ship at all.
----------------------------------------------------------------------------------------------------------------
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
The publication diagram has been rendered natively by Pine3D .
Library
Universal Signal Backtester [LuxAlgo]The Universal Signal Backtester indicator is a tool designed to simulate and analyze the performance of virtually any trading signal, ranging from moving average crossovers to external indicator triggers. By providing a professional-grade backtesting environment directly on the chart, it allows users to optimize entry logic, exit strategies, and cost management in real-time.
🔶 USAGE
The script operates by selecting a Source Mode to define how trades are initiated. Users can choose between built-in MA crosses, external source crossovers, or discrete signal triggers from other indicators. Once a signal is detected, the script simulates a trade using up to three Take Profit (TP) and three Stop Loss (SL) levels.
🔹 Trade Visualization
* Sign Posts: Upon entry, the script plots a "Sign Post" label below or above the bar. This label dynamically suggests which TP level is currently the most effective based on the selected metric (e.g., Hit Rate or Expected Profit).
* Active Exit Lines: Horizontal dashed lines extend from the entry point to visualize the selected TP and SL targets. These lines update in real-time and mark hits with a checkmark (✓) or an "X" (✗).
* MA Ribbon: When using predefined crosses, a gradient ribbon is displayed to visualize the trend strength and crossover points.
🔹 Signal Modes
* Predefined Crosses: Quickly test standard strategies like the 9/21 EMA, 12/26 EMA, or the Golden/Death Cross (50/200 SMA).
* External Sources (Crossovers): Select two external plots (e.g., RSI and a level, or two custom MAs) to test their crossover performance.
* External Signals (Triggers): Connect the script to discrete signals such as Plotshapes or Boolean conditions. This is ideal for testing "Buy" and "Sell" signals from specialized indicators.
🔶 DETAILS
🔹 Advanced Analytics Dashboard
The indicator features a robust dashboard providing institutional-level metrics:
* Core Metrics: Total trades, Win Rate, Profit Factor, Sharpe Ratio, and Recovery Factor.
* Equity Curve: A sparkline representation of the account growth over time.
* Hourly Histogram: A performance breakdown by the hour of the day, helping identify the most profitable trading sessions.
* Heatmaps: A "Days of the Week" or "Monthly" heatmap that colors cells based on profitability, allowing for the identification of seasonal or periodic performance patterns.
🔹 Cost Simulation
To ensure realistic results, the script includes a cost engine. Users can select from profiles like Forex, Crypto, or Stocks to automatically apply industry-standard spreads and commissions, or input manual values to match a specific broker's fee structure.
🔶 SETTINGS
🔹 Source Settings
Source Mode: Determines the logic for trade entries (Predefined, External Crossover, or External Trigger). Signal Logic: Defines how external triggers are interpreted (e.g., Value Changes, Crosses 0, or Not NA). Trade Direction: Filters signals to allow only Longs, only Shorts, or Both.
🔹 Filters
Use ATR Choppiness Filter: When enabled, the script ignores signals that occur during low-volatility "choppy" periods.
🔹 Target Settings
Distance Type: Sets the measurement unit for TP/SL levels (ATR, Ticks, or Points). Take Profit (1-3): Toggles and sets the distance for up to three partial take-profit levels. Stop Loss (1-3): Toggles and sets the distance for up to three stop-loss levels.
🔹 Costs
Simulate Spread & Commission: Enables the cost engine for more realistic PnL calculations. Cost Profile: Presets for Forex, Crypto, and Stocks, or "Manual" for custom inputs.
🔹 Dashboard & Visuals
Heatmap Period: Switches the dashboard heatmap between "Days of Week" and "Months". Suggested TP Metric: Chooses the criteria the "Sign Post" uses to suggest the best TP level. Gradient Candle Coloring: Colors candles based on the distance between the fast and slow sources. Indicator
Indicator
Indicator
Pinescript Custom Performance BoostThis small script is a custom function that works similarly to the built-in calc_bars_count and max_bars_back functions, but can be used far more flexibly and significantly reduces the required computation time of Pine Script scripts.
The advantages over calc_bars_count are substantial.
The standard function works with a fixed value, e.g. calc_bars_count = 20000. The custom function, on the other hand, works on a percentage basis, e.g. with 20% of the total available chart bars.
In addition, calc_bars_count always affects the entire code, while the custom function can be applied selectively to specific parts of the script.
These two differences enable a much more flexible and efficient usage.
Fixed number of bars vs. percentage-based limitation:
The number of available bars varies greatly, not only depending on the ticker and timeframe used, but also on the PulseWire subscription (approx. 5,000–40,000 historical bars).
For example, when using calc_bars_count = 20000, only charts that have more than 20,000 candles benefit. If the available number of bars is lower, there is no performance benefit at all until the value is changed after the first slow calculation.
When using the custom function with, for example, 50%, only 50% of the available bars are always calculated, regardless of how many bars are available. This results in a performance gain with shorter calculation times regardless of the chart.
Entire code vs. partial code sections:
calc_bars_count = 20000 affects the entire code globally, meaning the script processes data from only those 20,000 bars.
The custom function, however, can be used selectively for specific sections of the code. This makes it possible to continue accessing certain values across all available bars, while limiting only the truly computation-intensive parts of the script to a percentage-based range.
In this way, computation time can be drastically reduced without restricting the overall size of the data sets.
It is also possible to imitate max_bars_back and selectively limit specific values instead of limiting all of them.
I hope this is useful to some of you. Have fun with it! Indicator
Monthly Seasonality AnalyzerThis indicator analyzes historical performance/seasonality of a chosen month, from date of inception to present. Users can choose any calendar month via dropdown menu.
For each historical month selected, it will calculate the monthly percentage gain/loss, range(volatility), and average gain/loss percentage, average range percentage across all recorded years. Positive returns are colored green and negative returns are red. Also, calculates if the selected month was bullish(open>close) or bearish.
When current chart month matches the selected month, it shows the in-progress range as well.
Data is collected from 1930 to present. Results are shown in vertical and horizontal tables. If the vertical table exceeds a 36 years, the script automatically switches to horizontal table to display all the data, with option to change table position.
Overall this tool is valuable for seasonality research, such as Santa Rally, May Go Away and swing trading/ position trading to capture the monthly PO3 range.
Most seasonality indicators show all 12 months at once or use daily bars. This one zooms in deeply on one month only, providing detailed per-year breakdowns, accurate completed-month stats, and a practical live range display.
The script uses arrays to store years, gains, and ranges. Uses table.new(), table.cell(), table.merge_cells() for easily readable result display. Code handles the current in-progress month separately (shows live range without including it in historical averages).
**Script will not run on any timeframe other than monthly and displays error otherwise. Script is best used on spot and not futures. Indicator
Indicator
Smart Money Alpha Signals (Performance Dashboard) Smart Money Alpha Signals: Identifying Market Leaders & Generating Alpha
GMP Alpha Signals (Global Market Performance Alpha) is a specialized analysis tool designed not merely to find stocks that are rising, but to identify "Alpha" assets—Market Leaders that defend their price or rise even under adverse conditions where the market index falls or consolidates.
This indicator visualizes the concept of Comparative Relative Strength (RS) and Smart Money accumulation patterns, helping traders capture profit opportunities even during bearish market phases.
Key Objectives (Purpose)
Alpha Capture: Identifying assets generating 'excess returns' that outperform the market Beta.
Smart Money Tracking: Detecting traces of 'institutional buying' and 'accumulation' that defend prices during index plunges.
Decoupling Identification: Spotting assets moving on independent catalysts or momentum, regardless of the broader market direction.
Stop Hunt Filtering: Distinguishing 'fake drops' where price dips temporarily, but Relative Strength remains intact.
Dashboard Guide
Interpretation of the information panel (Table) displayed on the chart.
Rel. Performance: Shows the excess return compared to the index over the set period. (Positive/Green = Stronger than the market).
Decoupling Strength: The correlation coefficient with the index. Lower values (0 or negative) indicate movement independent of market risk.
Bullish: The count/rate of rising or limiting losses when the index drops sharply (e.g., < -0.5%). (Gold = Market Crash Leader).
Defended: The count/rate of holding support levels when the index shows mild weakness (e.g., < -0.05%). (Gold = Strong Accumulation).
Bench. Defense: The defense rate of the comparison benchmark (e.g., TSLA, ETH). Your target asset must be higher to be considered the sector leader.
Input Options & Settings Guide
You can optimize settings according to your trading style and asset class (Stocks/Crypto).
(1) Main Settings
Major Index: The baseline market index for comparison.
(US Stocks: NASDAQ:NDX or TVC:SPX / Crypto: BINANCE:BTCUSDT)
Benchmark Symbol: A competitor within the sector.
(e.g., Set NVDA when analyzing Semiconductor stocks).
Correlation Lookback: The lookback period for judging decoupling. (Default: 30)
Performance Lookback: The number of bars to calculate cumulative returns and defense rates. (Default: 60)
(2) Dashboard Thresholds
These settings define the criteria for what qualifies as "Defended" or "Bullish".
Performance (Max %): Used to find assets that haven't pumped yet. Signals trigger only when Alpha is below this value.
Defended Logic:
Index Drop Condition: The index must drop by at least this amount to start checking. (e.g., -0.05%)
Asset Buffer: How much the asset must outperform the index drop.
(Example: If Index drops -1.0% and Buffer is 0.2%, the asset must be at least -0.8% to count as 'Defended').
Bullish Logic: Measures resilience during steeper market dumps (e.g., -0.5% drop) compared to the Defended Logic.
Volume Settings: Decides whether to count Defended/Bullish instances only when accompanied by volume above the SMA.
(3) Signal Logic Settings (Crucial)
Customize conditions to trigger alerts. The choice between AND / OR is crucial.
AND: Condition must be met SIMULTANEOUSLY with other active conditions (Conservative/High Certainty).
OR: Condition triggers the signal INDEPENDENTLY (Aggressive/Opportunity Capture).
Performance: Is the relative performance within the threshold? (Basic Filter).
Decoupling: Has the correlation dropped? (Start of independent move).
Bullish Rate: Is the Bullish rate high during market dumps?
Defended Rate (High): (Recommended) Is there continuous price defense occurring? (Accumulation detection).
Defended Rate (Low): (Warning) Has the defense rate broken down? (For Stop Loss).
Defended > Benchmark: Is it stronger than the Benchmark (2nd tier)?
Volume Spike: Has volume surged compared to the average? (Institutional involvement).
RSI Oversold: Is it in oversold territory? (Counter-trend trading).
Decoupling Move: Does the current bar show the "Index Down / Asset Up" pattern?
Min USD Volume: Transaction value filter (To exclude low liquidity assets).
Indicator
Indicator
Multi-Ticker Anchored CandlesMulti-Ticker Anchored Candles (MTAC) is a simple tool for overlaying up to 3 tickers onto the same chart. This is achieved by interpreting each symbol's OHLC data as percentages, then plotting their candle points relative to the main chart's open. This allows for a simple comparison of tickers to track performance or locate relationships between them.
> Background
The concept of multi-ticker analysis is not new, this type of analysis can be extremely helpful to get a gauge of the over all market, and it's sentiment. By analyzing more than one ticker at a time, relationships can often be observed between tickers as time progresses.
While seeing multiple charts on top of each other sounds like a good idea...each ticker has its own price scale, with some being only cents while others are thousands of dollars.
Directly overlaying these charts is not possible without modification to their sources.
By using a fixed point in time (Period Open) and percentage performance relative to that point for each ticker, we are able to directly overlay symbols regardless of their price scale differences.
The entire process used to make this indicator can be summed up into 2 keywords, "Scaling & Anchoring".
> Scaling
First, we start by determining a frame of reference for our analysis. The indicator uses timeframe inputs to determine sessions which are used, by default this is set to 1 day.
With this in place, we then determine our point of reference for scaling. While this could be any point in time, the most sensible for our application is the daily (or session) open.
Each symbol shares time, therefore, we can take a price point from a specified time (Opening Price) and use it to sync our analysis over each period.
Over the day, we track the percentage performance of each ticker's OHLC values relative to its daily open (% change from open).
Since each ticker's data is now tracked based on its opening price, all data is now using the same scale.
The scale is simply "% change from open".
> Anchoring
Now that we have our scaled data, we need to put it onto the chart.
Since each point of data is relative to it's daily open (anchor point), relatively speaking, all daily opens are now equal to each other.
By adding the scaled ticker data to the main chart's daily open, each of our resulting series will be properly scaled to the main chart's data based on percentages.
Congratulations, We have now accurately scaled multiple tickers onto one chart.
> Display
The indicator shows each requested ticker as different colored candlesticks plotted on top of the main chart.
Each ticker has an associated label in front of the current bar, each component of this label can be toggled on or off to allow only the desired information to be displayed.
To retain relevance, at the start of each session, a "Session Break" line is drawn, as well as the opening price for the session. These can also be toggled.
Note: The opening price is the opening price for ALL tickers, when a ticker crosses the open on the main chart, it is crossing its own opening price as well.
> Examples
In the chart below, we can see NYSE:MCD NASDAQ:WEN and NASDAQ:JACK overlaid on a NASDAQ:SBUX chart.
From this, we can see NASDAQ:JACK was the top gainer on the day. While this was the case, it also fell roughly 4% from its peak near lunchtime. Unlike the top gainer, we can see the other 3 tickers ended their day near their daily high.
In the explanations above, the daily timeframe is used since it is the default; however, the analysis is not constrained to only days. The anchoring period can be set to any timeframe period.
In the chart below, you can observe the Daily, Weekly, and Monthly anchored charts side-by-side.
This can be used on all tickers, timeframes, and markets. While a typical application may be comparing relevant assets... the script is not limited.
Below we have a chart tracking COMEX:GCV2026 , FX:EURUSD , and COINBASE:DOGEUSD on the AMEX:SPY chart.
While these tickers are not typically compared side-by-side, here it is simply a display of the capabilities of the script.
Enjoy! Indicator
Relative Performance Analyzer [AstrideUnicorn]Relative Performance Analyzer (RPA) is a performance analysis tool inspired by the data comparison features found in professional trading terminals. The RPA replicates the analytical approach used by portfolio managers and institutional analysts who routinely compare multiple securities or other types of data to identify relative strength opportunities, make allocation decisions, choose the most optimal investment from several alternatives, and much more.
Key Features:
Multi-Symbol Comparison: Track up to 5 different symbols simultaneously across any asset class or dataset
Two Performance Calculation Methods: Choose between percentage returns or risk-adjusted returns
Interactive Analysis: Drag the start date line on the chart or manually choose the start date in the settings
Professional Visualization: High-contrast color scheme designed for both dark and light chart themes
Live Performance Table: Real-time display of current return values sorted from the top to the worst performers
Practical Use Cases:
ETF Selection: Compare similar ETFs (e.g., SPY vs IVV vs VOO) to identify the most efficient investment
Sector Rotation: Analyze which sectors are showing relative strength for strategic allocation
Competitive Analysis: Compare companies within the same industry to identify leaders (e.g., APPLE vs SAMSUNG vs XIAOMI)
Cross-Asset Allocation: Evaluate performance across stocks, bonds, commodities, and currencies to guide portfolio rebalancing
Risk-Adjusted Decisions: Use risk-adjusted performance to find investments with the best returns per unit of risk
Example Scenarios:
Analyze whether tech stocks are outperforming the broader market by comparing XLK to SPY
Evaluate which emerging market ETF (EEM vs VWO) has provided better risk-adjusted returns over the past year
HOW DOES IT WORK
The indicator calculates and visualizes performance from a user-defined starting point using two methodologies:
Percentage Returns: Standard total return calculation showing percentage change from the start date
Risk-Adjusted Returns: Cumulative returns divided by the volatility (standard deviation), providing insight into the efficiency of performance. An expanding window is used to calculate the volatility, ensuring accurate risk-adjusted comparisons throughout the analysis period.
HOW TO USE
Setup Your Comparison: Enable up to 5 assets and input their symbols in the settings
Set Analysis Period: When you first launch the indicator, select the start date by clicking on the price chart. The vertical start date line will appear. Drag it on the chart or manually input a specific date to change the start date.
Choose Return Type: Select between percentage or risk-adjusted returns based on your analysis needs
Interpret Results
Use the real-time table for precise current values
SETTINGS
Assets 1-5: Toggle on/off and input symbols for comparison (stocks, ETFs, indices, forex, crypto, fundamental data, etc.)
Start Date: Set the initial point for return calculations (drag on chart or input manually)
Return Type: Choose between "Percentage" or "Risk-Adjusted" performance. Indicator
Relative Performance Areas [LuxAlgo]The Relative Performance Areas tool enables traders to analyze the relative performance of any asset against a user-selected benchmark directly on the chart, session by session.
The tool features three display modes for rescaled benchmark prices, as well as a statistics panel providing relevant information about overperforming and underperforming streaks.
🔶 USAGE
Usage is straightforward. Each session is highlighted with an area displaying the asset price range. By default, a green background is displayed when the asset outperforms the benchmark for the session. A red background is displayed if the asset underperforms the benchmark.
The benchmark is displayed as a green or red line. An extended price area is displayed when the benchmark exceeds the asset price and is set to SPX by default, but traders can choose any ticker from the settings panel.
Using benchmarks to compare performance is a common practice in trading and investing. Using indexes such as the S&P 500 (SPX) or the NASDAQ 100 (NDX) to measure our portfolio's performance provides a clear indication of whether our returns are above or below the broad market.
As the previous chart shows, if we have a long position in the NASDAQ 100 and buy an ETF like QQQ, we can clearly see how this position performs against BTSUSD and GOLD in each session.
Over the last 15 sessions, the NASDAQ 100 outperformed the BTSUSD in eight sessions and the GOLD in six sessions. Conversely, it underperformed the BTCUSD in seven sessions and the GOLD in nine sessions.
🔹 Display Mode
The display mode options in the Settings panel determine how benchmark performance is calculated. There are three display modes for the benchmark:
Net Returns: Uses the raw net returns of the benchmark from the start of the session.
Rescaled Returns: Uses the benchmark net returns multiplied by the ratio of the benchmark net returns standard deviation to the asset net returns standard deviation.
Standardized Returns: Uses the z-score of the benchmark returns multiplied by the standard deviation of the asset returns.
Comparing net returns between an asset and a benchmark provides traders with a broad view of relative performance and is straightforward.
When traders want a better comparison, they can use rescaled returns. This option scales the benchmark performance using the asset's volatility, providing a fairer comparison.
Standardized returns are the most sophisticated approach. They calculate the z-score of the benchmark returns to determine how many standard deviations they are from the mean. Then, they scale that number using the asset volatility, which is measured by the asset returns standard deviation.
As the chart above shows, different display modes produce different results. All of these methods are useful for making comparisons and accounting for different factors.
🔹 Dashboard
The statistics dashboard is a great addition that allows traders to gain a deep understanding of the relationship between assets and benchmarks.
First, we have raw data on overperforming and underperforming sessions. This shows how many sessions the asset performance at the end of the session was above or below the benchmark.
Next, we have the streaks statistics. We define a streak as two or more consecutive sessions where the asset overperformed or underperformed the benchmark.
Here, we have the number of winning and losing streaks (winning means overperforming and losing means underperforming), the median duration of each streak in sessions, the mode (the number of sessions that occurs most frequently), and the percentages of streaks with durations equal to or greater than three, four, five, and six sessions.
As the image shows, these statistics are useful for traders to better understand the relative behavior of different assets.
🔶 SETTINGS
Benchmark: Benchmark for comparison
Display Mode: Choose how to display the benchmark; Net Returns: Uses the raw net returns of the benchmark. Rescaled Returns: Uses the benchmark net returns multiplied by the ratio of the benchmark and asset standard deviations. Standardized Returns: Uses the benchmark z-score multiplied by the asset standard deviation.
🔹 Dashboard
Dashboard: Enable or disable the dashboard.
Position: Select the location of the dashboard.
Size: Select the dashboard size.
🔹 Style
Overperforming: Enable or disable displaying overperforming sessions and choose a color.
Underperforming: Enable or disable displaying underperforming sessions and choose a color.
Benchmark: Enable or disable displaying the benchmark and choose colors.
Indicator
Indicator
Apex Edge - London Open Session# Apex Edge - London Open Session Trading System
## Overview
The London Open Session indicator captures institutional price action during the first hour of the London forex session (8:00-9:00 AM GMT) and identifies high-probability breakout and retest opportunities. This system tracks the session's high/low range and generates precise entry signals when price breaks or retests these key institutional levels.
## Core Strategy
**Session Tracking**: Automatically identifies and marks the London Open session boundaries, creating a trading zone from the first hour's price range.
**Dual Entry Logic**:
- **Breakout Entries**: Triggers when price closes beyond the session high/low and continues in that direction
- **Retest Entries**: Activates when price returns to test the broken level as new support/resistance
**Performance Analytics**: Built-in win rate tracking displays real-time performance statistics over user-defined lookback periods, enabling data-driven optimization for each currency pair.
## Key Features
### Automated Zone Detection
- Precise London session timing with timezone offset controls
- Visual session boundaries with customizable colours
- Automatic high/low range calculation and display
### Smart Entry System
- Breakout confirmation requiring candle close beyond zone
- Retest detection with configurable pip distance tolerance
- Separate risk/reward ratios for breakout vs retest entries
- Visual entry arrows with clear trade direction labels
### Performance HUD
- Real-time win rate calculation over customizable periods (7-365 days)
- Total trades tracking with win/loss breakdown
- Average risk-reward ratio display
- Color-coded performance metrics (green >70%, yellow >50%, red <50%)
### PineConnector Integration
- Direct MT4/MT5 execution via PineConnector alerts
- Proper forex pip calculations for all currency pairs
- Customizable risk percentage per trade
- Symbol override capability for broker compatibility
- Automatic SL/TP level calculation in pips
## Critical Usage Requirements
### Pair-Specific Optimization
Each currency pair requires individual optimization due to varying volatility characteristics, institutional participation levels, and typical price ranges during London hours. The performance HUD is essential for identifying optimal settings before live trading.
**Recommended Testing Process**:
1. Apply indicator to desired currency pair and timeframe
2. Experiment with session timing - while 8:00-9:00 AM GMT is standard, some pairs may show improved performance with alternative hourly windows (e.g., 7:00-8:00 AM or 9:00-10:00 AM)
3. Adjust Stop Loss distances, Risk/Reward ratios, and Retest distances
4. Monitor win rate over 30+ day periods using the performance HUD
5. Only proceed with live alerts once consistent 60%+ win rates are achieved
6. Create separate optimized chart setups for each profitable pair/timeframe combination
### Timeframe Specifications
This indicator is specifically designed and tested for:
- **1-minute charts**: Optimal for capturing immediate institutional reactions
- **5-minute charts**: Balanced approach between noise reduction and opportunity frequency
Higher timeframes generally produce inferior results due to increased noise and reduced institutional edge during the London session window.
## Settings Configuration
### Session Timing
- **London Open/Close Hours**: Adjust for your chart's timezone
- **Rectangle End Time**: Set to 4:30 PM to stop signals before NY session close
- **Timezone Offset**: Ensure accurate London session capture
### Entry Parameters
- **Retest Distance**: 3-8 pips depending on pair volatility
- **Stop Loss Pips**: Separate settings for breakouts (10-15 pips) and retests (8-12 pips)
- **Risk/Reward Ratios**: Independent ratios for different entry types
### PineConnector Setup
- **License ID**: Your PineConnector license key
- **Symbol Override**: MT4/MT5 symbol names if different from PulseWire
- **Risk Percentage**: Position size as percentage of account balance
- **Prefix/Comment**: Organize trades in terminal
## Manual Trading Limitations
Without PineConnector automation, traders face significant practical challenges:
**Settings Management**: Each currency pair requires different optimized parameters. Switching between charts means manually adjusting multiple settings each time, creating potential for errors and missed opportunities.
**Timing Sensitivity**: London Open signals can occur rapidly during high-volatility periods. Manual execution may result in slippage or missed entries.
**Multi-Pair Monitoring**: Tracking 4-11 currency pairs simultaneously while manually adjusting settings for each switch becomes impractical for most traders.
**Parameter Consistency**: Risk of using suboptimal settings when quickly switching between pairs, potentially compromising the careful optimization work.
## Recommended Workflow
1. **Historical Testing**: Use win rate HUD to identify profitable pairs and optimal parameters
2. **Demo Automation**: Test PineConnector alerts on demo accounts with optimized settings
3. **Live Implementation**: Deploy alerts only on proven profitable pair/timeframe combinations
4. **Ongoing Monitoring**: Regular review of performance metrics to maintain edge
## Risk Disclaimer
This indicator provides analysis tools and automation capabilities but does not guarantee profitable trading outcomes. Past performance does not predict future results. Users should thoroughly backtest and demo trade before risking live capital. The London session strategy works best during specific market conditions and may underperform during low volatility or unusual market environments.
## Support Requirements
Successful implementation requires:
- Basic understanding of London session market dynamics
- PineConnector subscription for automation features
- Patience for proper optimization process
- Realistic expectations about win rates and drawdown periods
This system is designed for serious traders willing to invest time in proper optimization and risk management rather than plug-and-play solutions. Indicator
Trading Report Generator from CSVMany people use the Trading Panel. Unfortunately, it doesn't have a Performance Report. However, PulseWire has strategies, and they have a Performance Report :-D
What if we combine the first and second? It's easy!
This script is a special strategy that parses transactions in csv format from Paper Trading (and it will also work for other brokers) and “plays” them. As a result, we get a Performance Report for a specific instrument based on our real trades in Paper or another broker.
How to use it :
First, we need to get a CSV file with transactions. To do this, go to the Trading Panel and connect the desired broker. Select the History tab, then the Filled sub-tab, and configure the columns there, leaving only: Side, Qty, Fill Price, Closing Time. After that, open the Export data dialog, select History, and click Export. Open the downloaded CSV file in a regular text editor (Notepad or similar). It will contain a text like this:
Symbol,Side,Qty,Fill Price,Closing Time
FX:EURUSD,Buy,1000,1.0938700000000001,2023-04-05 14:29:23
COINBASE:ETHUSD,Sell,1,1332.05,2023-01-11 17:41:33
CME_MINI:ESH2023,Sell,1,3961.75,2023-01-11 17:30:40
CME_MINI:ESH2023,Buy,1,3956.75,2023-01-11 17:08:53
Next select all the text (Ctrl+A) and copy it to the clipboard.
Now apply the "Trading Report Generator from CSV" strategy to the chart with the desired symbol and TF, open the settings/input dialog, paste the contents of the clipboard into the single text input field of the strategy, and click Ok.
That's it.
In the Strategy Tester, we see a detailed Performance Report based on our real transactions.
P.S. The CSV file may contain transactions for different instruments, for example, you may have transactions for CRYPTO:BTCUSD and NASDAQ:AAPL. To view the report is based on CRYPTO:BTCUSD trades, simply change the symbol on the chart to CRYPTO:BTCUSD. To view the report is based on NASDAQ:AAPL trades, simply change the symbol on the chart to NASDAQ:AAPL. No changes to the strategy are required.
How it works :
At the beginning of the calculation, we parse the csv once, create trade objects (Trade) and sort them in chronological order. Next, on each bar, we check whether we have trades for the time period of the next bar. If there are, we place a limit order for each trade, with limit price == Fill Price of the trade. Here, we assume that if the trade is real, its execution price will be within the bar range, and the Pine strategy engine will execute this order at the specified limit price.
Strategy
DCA Investment Tracker Pro [tradeviZion]DCA Investment Tracker Pro: Educational DCA Analysis Tool
An educational indicator that helps analyze Dollar-Cost Averaging strategies by comparing actual performance with historical data calculations.
---
💡 Why I Created This Indicator
As someone who practices Dollar-Cost Averaging, I was frustrated with constantly switching between spreadsheets, calculators, and charts just to understand how my investments were really performing. I wanted to see everything in one place - my actual performance, what I should expect based on historical data, and most importantly, visualize where my strategy could take me over the long term .
What really motivated me was watching friends and family underestimate the incredible power of consistent investing. When Napoleon Bonaparte first learned about compound interest, he reportedly exclaimed "I wonder it has not swallowed the world" - and he was right! Yet most people can't visualize how their $500 monthly contributions today could become substantial wealth decades later.
Traditional DCA tracking tools exist, but they share similar limitations:
Require manual data entry and complex spreadsheets
Use fixed assumptions that don't reflect real market behavior
Can't show future projections overlaid on actual price charts
Lose the visual context of what's happening in the market
Make compound growth feel abstract rather than tangible
I wanted to create something different - a tool that automatically analyzes real market history, detects volatility periods, and shows you both current performance AND educational projections based on historical patterns right on your PulseWire charts. As Warren Buffett said: "Someone's sitting in the shade today because someone planted a tree a long time ago." This tool helps you visualize your financial tree growing over time.
This isn't just another calculator - it's a visualization tool that makes the magic of compound growth impossible to ignore.
---
🎯 What This Indicator Does
This educational indicator provides DCA analysis tools. Users can input investment scenarios to study:
Theoretical Performance: Educational calculations based on historical return data
Comparative Analysis: Study differences between actual and theoretical scenarios
Historical Projections: Theoretical projections for educational analysis (not predictions)
Performance Metrics: CAGR, ROI, and other analytical metrics for study
Historical Analysis: Calculates historical return data for reference purposes
---
🚀 Key Features
Volatility-Adjusted Historical Return Calculation
Analyzes 3-20 years of actual price data for any symbol
Automatically detects high-volatility stocks (meme stocks, growth stocks)
Uses median returns for volatile stocks, standard CAGR for stable stocks
Provides conservative estimates when extreme outlier years are detected
Smart fallback to manual percentages when data insufficient
Customizable Performance Dashboard
Educational DCA performance analysis with compound growth calculations
Customizable table sizing (Tiny to Huge text options)
9 positioning options (Top/Middle/Bottom + Left/Center/Right)
Theme-adaptive colors (automatically adjusts to dark/light mode)
Multiple display layout options
Future Projection System
Visual future growth projections
Timeframe-aware calculations (Daily/Weekly/Monthly charts)
1-30 year projection options
Shows projected portfolio value and total investment amounts
Investment Insights
Performance vs benchmark comparison
ROI from initial investment tracking
Monthly average return analysis
Investment milestone alerts (25%, 50%, 100% gains)
Contribution tracking and next milestone indicators
---
📊 Step-by-Step Setup Guide
1. Investment Settings 💰
Initial Investment: Enter your starting lump sum (e.g., $60,000)
Monthly Contribution: Set your regular DCA amount (e.g., $500/month)
Return Calculation: Choose "Auto (Stock History)" for real data or "Manual" for fixed %
Historical Period: Select 3-20 years for auto calculations (default: 10 years)
Start Year: When you began investing (e.g., 2020)
Current Portfolio Value: Your actual portfolio worth today (e.g., $150,000)
2. Display Settings 📊
Table Sizes: Choose from Tiny, Small, Normal, Large, or Huge
Table Positions: 9 options - Top/Middle/Bottom + Left/Center/Right
Visibility Toggles: Show/hide Main Table and Stats Table independently
3. Future Projection 🔮
Enable Projections: Toggle on to see future growth visualization
Projection Years: Set 1-30 years ahead for analysis
Live Example - NASDAQ:META Analysis:
Settings shown: $60K initial + $500/month + Auto calculation + 10-year history + 2020 start + $150K current value
---
🔬 Pine Script Code Examples
Core DCA Calculations:
// Calculate total invested over time
months_elapsed = (year - start_year) * 12 + month - 1
total_invested = initial_investment + (monthly_contribution * months_elapsed)
// Compound growth formula for initial investment
theoretical_initial_growth = initial_investment * math.pow(1 + annual_return, years_elapsed)
// Future Value of Annuity for monthly contributions
monthly_rate = annual_return / 12
fv_contributions = monthly_contribution * ((math.pow(1 + monthly_rate, months_elapsed) - 1) / monthly_rate)
// Total expected value
theoretical_total = theoretical_initial_growth + fv_contributions
Volatility Detection Logic:
// Detect extreme years for volatility adjustment
extreme_years = 0
for i = 1 to historical_years
yearly_return = ((price_current / price_i_years_ago) - 1) * 100
if yearly_return > 100 or yearly_return < -50
extreme_years += 1
// Use median approach for high volatility stocks
high_volatility = (extreme_years / historical_years) > 0.2
calculated_return = high_volatility ? median_of_returns : standard_cagr
Performance Metrics:
// Calculate key performance indicators
absolute_gain = actual_value - total_invested
total_return_pct = (absolute_gain / total_invested) * 100
roi_initial = ((actual_value - initial_investment) / initial_investment) * 100
cagr = (math.pow(actual_value / initial_investment, 1 / years_elapsed) - 1) * 100
---
📊 Real-World Examples
See the indicator in action across different investment types:
Stable Index Investments:
AMEX:SPY (SPDR S&P 500) - Shows steady compound growth with standard CAGR calculations
Classic DCA success story: $60K initial + $500/month starting 2020. The indicator shows SPY's historical 10%+ returns, demonstrating how consistent broad market investing builds wealth over time. Notice the smooth theoretical growth line vs actual performance tracking.
MIL:VUAA (Vanguard S&P 500 UCITS) - Shows both data limitation and solution approaches
Data limitation example: VUAA shows "Manual (Auto Failed)" and "No Data" when default 10-year historical setting exceeds available data. The indicator gracefully falls back to manual percentage input while maintaining all DCA calculations and projections.
MIL:VUAA (Vanguard S&P 500 UCITS) - European ETF with successful 5-year auto calculation
Solution demonstration: By adjusting historical period to 5 years (matching available data), VUAA auto calculation works perfectly. Shows how users can optimize settings for newer assets. European market exposure with EUR denomination, demonstrating DCA effectiveness across different markets and currencies.
NYSE:BRK.B (Berkshire Hathaway) - Quality value investment with Warren Buffett's proven track record
Value investing approach: Berkshire Hathaway's legendary performance through DCA lens. The indicator demonstrates how quality companies compound wealth over decades. Lower volatility than tech stocks = standard CAGR calculations used.
High-Volatility Growth Stocks:
NASDAQ:NVDA (NVIDIA Corporation) - Demonstrates volatility-adjusted calculations for extreme price swings
High-volatility example: NVIDIA's explosive AI boom creates extreme years that trigger volatility detection. The indicator automatically switches to "Median (High Vol): 50%" calculations for conservative projections, protecting against unrealistic future estimates based on outlier performance periods.
NASDAQ:TSLA (Tesla) - Shows how 10-year analysis can stabilize volatile tech stocks
Stable long-term growth: Despite Tesla's reputation for volatility, the 10-year historical analysis (34.8% CAGR) shows consistent enough performance that volatility detection doesn't trigger. Demonstrates how longer timeframes can smooth out extreme periods for more reliable projections.
NASDAQ:META (Meta Platforms) - Shows stable tech stock analysis using standard CAGR calculations
Tech stock with stable growth: Despite being a tech stock and experiencing the 2022 crash, META's 10-year history shows consistent enough performance (23.98% CAGR) that volatility detection doesn't trigger. The indicator uses standard CAGR calculations, demonstrating how not all tech stocks require conservative median adjustments.
Notice how the indicator automatically detects high-volatility periods and switches to median-based calculations for more conservative projections, while stable investments use standard CAGR methods.
---
📈 Performance Metrics Explained
Current Portfolio Value: Your actual investment worth today
Expected Value: What you should have based on historical returns (Auto) or your target return (Manual)
Total Invested: Your actual money invested (initial + all monthly contributions)
Total Gains/Loss: Absolute dollar difference between current value and total invested
Total Return %: Percentage gain/loss on your total invested amount
ROI from Initial Investment: How your starting lump sum has performed
CAGR: Compound Annual Growth Rate of your initial investment (Note: This shows initial investment performance, not full DCA strategy)
vs Benchmark: How you're performing compared to the expected returns
---
⚠️ Important Notes & Limitations
Data Requirements: Auto mode requires sufficient historical data (minimum 3 years recommended)
CAGR Limitation: CAGR calculation is based on initial investment growth only, not the complete DCA strategy
Projection Accuracy: Future projections are theoretical and based on historical returns - actual results may vary
Timeframe Support: Works ONLY on Daily (1D), Weekly (1W), and Monthly (1M) charts - no other timeframes supported
Update Frequency: Update "Current Portfolio Value" regularly for accurate tracking
---
📚 Educational Use & Disclaimer
This analysis tool can be applied to various stock and ETF charts for educational study of DCA mathematical concepts and historical performance patterns.
Study Examples: Can be used with symbols like AMEX:SPY , NASDAQ:QQQ , AMEX:VTI , NASDAQ:AAPL , NASDAQ:MSFT , NASDAQ:GOOGL , NASDAQ:AMZN , NASDAQ:TSLA , NASDAQ:NVDA for learning purposes.
EDUCATIONAL DISCLAIMER: This indicator is a study tool for analyzing Dollar-Cost Averaging strategies. It does not provide investment advice, trading signals, or guarantees. All calculations are theoretical examples for educational purposes only. Past performance does not predict future results. Users should conduct their own research and consult qualified financial professionals before making any investment decisions.
---
© 2025 TradeVizion. All rights reserved.
Indicator
Indicator
Sector Relative StrengthDescription
This script compares sector performance relative to the S&P 500. Sector price levels or charts alone can mislead, because they tend to move with the broader market. An increase in a sector’s price does not necessarily indicate strength, as it may simply be following the index.
For more a more reliable picture, the script calculates a ratio between each sector ETF and SPY. If the ratio has increased, the sector has outperformed the index. In case it has declined, the sector has underperformed. If the value is near zero, the sector has moved in line with the index. The sectors are presented in a table and sorted on relative performance.
Calculation Method
The performance is expressed as a percentage change in the ratio over a user-defined lookback period. The default lookback is set to 21 bars, which corresponds to one month on a daily chart. This value can be adopted in the settings to match preferred time period.
Z-Score
In addition to the percentage change, the script calculates a Z-score of the ratio, which measures how far the current value deviates from its recent mean. A high positive Z-score indicates that the ratio is significantly above its average, while a negative value indicates it is below. This normalization allows for comparison between sectors with different price levels or volatility profiles.
Table Columns
- Relative %: The sector's performance relative to SPY over the selected lookback period
- Z-Score: Standardized measure of current performance ratio is relative to its average
- Trend Arrow: Indicates the direction of relative performance up down or flat
Example Interpretation
For example, if XLK shows a 3.7% change, it has outperformed SPY over the selected period. Another sector might show a -2.1% change, which indicates underperformance. While both values shows relative strength or weakness, the Z-score is optional and can provide additional context based on how unusual that performance is compared to the sector's own recent behavior.
Use Case
This approach helps evaluate overall market conditions and supports a top-down method. By starting with sector performance, it becomes easier to identify where the market is showing leadership or weakness. This allows the stock selection process to be more deliberate and can help refine or customize screeners based on certain sectors. Indicator
Custom Performance TableThis script generates a table designed to provide a concise yet highly customizable overview of the performance of multiple financial instruments, displayed directly on the chart. The table can include up to 40 tickers, each individually configurable, with values updated in real time based on either the current chart timeframe or a specific user-selected timeframe.
NOTE : The update frequency of the table values depends on the refresh rate of the chart's main ticker to which the indicator is applied. To ensure a consistent and reliable data feed, especially when monitoring heterogeneous instruments, it is recommended to apply the indicator to a highly liquid and continuously traded asset, such as BTCUSD.
PERFORMANCE CALCULATION MODES
You can choose from three different performance calculation modes:
1) Change % (Percentage Change)
Displays the percentage change of the current price compared to the previous candle within the selected timeframe.
(Current Price - Previous Price) / Previous Price * 100
This mode provides an immediate and straightforward measure of each instrument's percentage movement, useful for quick visual comparisons of relative strength among assets.
2) Z-Score
The Z-Score measures how much the current price variation deviates from the historical average variation, relative to the standard deviation of those variations.
(Current Variation - Average Variation) / Standard Deviation of Variations
The result indicates how statistically unusual a movement is:
- Values near 0 suggest normal variations.
- Values above ±2 indicate statistically significant deviations.
This is a valuable tool for identifying overbought/oversold conditions or market stress events and is often used in mean reversion strategies.
NOTE : Due to technical constraints, Z-Score can only be calculated when the selected timeframe matches the chart's timeframe exactly.
3) RAROC (Risk-Adjusted Return on Capital)
RAROC expresses an asset's performance in relation to the risk taken, measured through its volatility (standard deviation of price).
Percentage Change / Standard Deviation of Price
It allows for an assessment of return efficiency in relation to volatility.
A high RAROC value indicates a high return relative to the risk, making it a useful tool for comparing assets with different risk profiles. It is especially suitable for portfolio selection and allocation purposes.
TABLE CONFIGURATION
Each ticker can be customized with its own label, colors, and position in the table.
Each row can display the ticker name or a custom label, which, at the user's discretion, can either replace the name or be shown as an informational tooltip.
The table can be placed anywhere on the chart using horizontal and vertical offset parameters. Thanks to offset support, you can, for example, create financial market overview layouts. This can be done by completely “cleaning” the chart from price and indicators using PulseWire settings, and then displaying multiple tables simultaneously (see the example chart published here).
Advanced customization options are also available for the table's appearance, including font settings, colors, borders, and more.
CALCULATION TIMEFRAME
The indicator allows the user to force a specific timeframe (Daily, Weekly, Monthly, Yearly) when applied to intraday charts.
However, for Z-Score mode, the selected timeframe must match the chart's timeframe exactly to ensure correct computation. Otherwise, the script will halt until settings are properly adjusted.
USAGE NOTES
Custom Performance Table is a flexible and adaptable tool, suitable for both intraday operations and medium- to long-term analysis. It is designed for traders and analysts who need to compare assets based on quantitative metrics, whether simple (like percentage change) or more advanced and risk-adjusted (such as Z-Score and RAROC). Indicator
ValueAtTime█ OVERVIEW
This library is a Pine Script® programming tool for accessing historical values in a time series using UNIX timestamps . Its data structure and functions index values by time, allowing scripts to retrieve past values based on absolute timestamps or relative time offsets instead of relying on bar index offsets.
█ CONCEPTS
UNIX timestamps
In Pine Script®, a UNIX timestamp is an integer representing the number of milliseconds elapsed since January 1, 1970, at 00:00:00 UTC (the UNIX Epoch ). The timestamp is a unique, absolute representation of a specific point in time. Unlike a calendar date and time, a UNIX timestamp's meaning does not change relative to any time zone .
This library's functions process series values and corresponding UNIX timestamps in pairs , offering a simplified way to identify values that occur at or near distinct points in time instead of on specific bars.
Storing and retrieving time-value pairs
This library's `Data` type defines the structure for collecting time and value information in pairs. Objects of the `Data` type contain the following two fields:
• `times` – An array of "int" UNIX timestamps for each recorded value.
• `values` – An array of "float" values for each saved timestamp.
Each index in both arrays refers to a specific time-value pair. For instance, the `times` and `values` elements at index 0 represent the first saved timestamp and corresponding value. The library functions that maintain `Data` objects queue up to one time-value pair per bar into the object's arrays, where the saved timestamp represents the bar's opening time .
Because the `times` array contains a distinct UNIX timestamp for each item in the `values` array, it serves as a custom mapping for retrieving saved values. All the library functions that return information from a `Data` object use this simple two-step process to identify a value based on time:
1. Perform a binary search on the `times` array to find the earliest saved timestamp closest to the specified time or offset and get the element's index.
2. Access the element from the `values` array at the retrieved index, returning the stored value corresponding to the found timestamp.
Value search methods
There are several techniques programmers can use to identify historical values from corresponding timestamps. This library's functions include three different search methods to locate and retrieve values based on absolute times or relative time offsets:
Timestamp search
Find the value with the earliest saved timestamp closest to a specified timestamp.
Millisecond offset search
Find the value with the earliest saved timestamp closest to a specified number of milliseconds behind the current bar's opening time. This search method provides a time-based alternative to retrieving historical values at specific bar offsets.
Period offset search
Locate the value with the earliest saved timestamp closest to a defined period offset behind the current bar's opening time. The function calculates the span of the offset based on a period string . The "string" must contain one of the following unit tokens:
• "D" for days
• "W" for weeks
• "M" for months
• "Y" for years
• "YTD" for year-to-date, meaning the time elapsed since the beginning of the bar's opening year in the exchange time zone.
The period string can include a multiplier prefix for all supported units except "YTD" (e.g., "2W" for two weeks).
Note that the precise span covered by the "M", "Y", and "YTD" units varies across time. The "1M" period can cover 28, 29, 30, or 31 days, depending on the bar's opening month and year in the exchange time zone. The "1Y" period covers 365 or 366 days, depending on leap years. The "YTD" period's span changes with each new bar, because it always measures the time from the start of the current bar's opening year.
█ CALCULATIONS AND USE
This library's functions offer a flexible, structured approach to retrieving historical values at or near specific timestamps, millisecond offsets, or period offsets for different analytical needs.
See below for explanations of the exported functions and how to use them.
Retrieving single values
The library includes three functions that retrieve a single stored value using timestamp, millisecond offset, or period offset search methods:
• `valueAtTime()` – Locates the saved value with the earliest timestamp closest to a specified timestamp.
• `valueAtTimeOffset()` – Finds the saved value with the earliest timestamp closest to the specified number of milliseconds behind the current bar's opening time.
• `valueAtPeriodOffset()` – Finds the saved value with the earliest timestamp closest to the period-based offset behind the current bar's opening time.
Each function has two overloads for advanced and simple use cases. The first overload searches for a value in a user-specified `Data` object created by the `collectData()` function (see below). It returns a tuple containing the found value and the corresponding timestamp.
The second overload maintains a `Data` object internally to store and retrieve values for a specified `source` series. This overload returns a tuple containing the historical `source` value, the corresponding timestamp, and the current bar's `source` value, making it helpful for comparing past and present values from requested contexts.
Retrieving multiple values
The library includes the following functions to retrieve values from multiple historical points in time, facilitating calculations and comparisons with values retrieved across several intervals:
• `getDataAtTimes()` – Locates a past `source` value for each item in a `timestamps` array. Each retrieved value's timestamp represents the earliest time closest to one of the specified timestamps.
• `getDataAtTimeOffsets()` – Finds a past `source` value for each item in a `timeOffsets` array. Each retrieved value's timestamp represents the earliest time closest to one of the specified millisecond offsets behind the current bar's opening time.
• `getDataAtPeriodOffsets()` – Finds a past value for each item in a `periods` array. Each retrieved value's timestamp represents the earliest time closest to one of the specified period offsets behind the current bar's opening time.
Each function returns a tuple with arrays containing the found `source` values and their corresponding timestamps. In addition, the tuple includes the current `source` value and the symbol's description, which also makes these functions helpful for multi-interval comparisons using data from requested contexts.
Processing period inputs
When writing scripts that retrieve historical values based on several user-specified period offsets, the most concise approach is to create a single text input that allows users to list each period, then process the "string" list into an array for use in the `getDataAtPeriodOffsets()` function.
This library includes a `getArrayFromString()` function to provide a simple way to process strings containing comma-separated lists of periods. The function splits the specified `str` by its commas and returns an array containing every non-empty item in the list with surrounding whitespaces removed. View the example code to see how we use this function to process the value of a text area input .
Calculating period offset times
Because the exact amount of time covered by a specified period offset can vary, it is often helpful to verify the resulting times when using the `valueAtPeriodOffset()` or `getDataAtPeriodOffsets()` functions to ensure the calculations work as intended for your use case.
The library's `periodToTimestamp()` function calculates an offset timestamp from a given period and reference time. With this function, programmers can verify the time offsets in a period-based data search and use the calculated offset times in additional operations.
For periods with "D" or "W" units, the function calculates the time offset based on the absolute number of milliseconds the period covers (e.g., `86400000` for "1D"). For periods with "M", "Y", or "YTD" units, the function calculates an offset time based on the reference time's calendar date in the exchange time zone.
Collecting data
All the `getDataAt*()` functions, and the second overloads of the `valueAt*()` functions, collect and maintain data internally, meaning scripts do not require a separate `Data` object when using them. However, the first overloads of the `valueAt*()` functions do not collect data, because they retrieve values from a user-specified `Data` object.
For cases where a script requires a separate `Data` object for use with these overloads or other custom routines, this library exports the `collectData()` function. This function queues each bar's `source` value and opening timestamp into a `Data` object and returns the object's ID.
This function is particularly useful when searching for values from a specific series more than once. For instance, instead of using multiple calls to the second overloads of `valueAt*()` functions with the same `source` argument, programmers can call `collectData()` to store each bar's `source` and opening timestamp, then use the returned `Data` object's ID in calls to the first `valueAt*()` overloads to reduce memory usage.
The `collectData()` function and all the functions that collect data internally include two optional parameters for limiting the saved time-value pairs to a sliding window: `timeOffsetLimit` and `timeframeLimit`. When either has a non-na argument, the function restricts the collected data to the maximum number of recent bars covered by the specified millisecond- and timeframe-based intervals.
NOTE : All calls to the functions that collect data for a `source` series can execute up to once per bar or realtime tick, because each stored value requires a unique corresponding timestamp. Therefore, scripts cannot call these functions iteratively within a loop . If a call to these functions executes more than once inside a loop's scope, it causes a runtime error.
█ EXAMPLE CODE
The example code at the end of the script demonstrates one possible use case for this library's functions. The code retrieves historical price data at user-specified period offsets, calculates price returns for each period from the retrieved data, and then populates a table with the results.
The example code's process is as follows:
1. Input a list of periods – The user specifies a comma-separated list of period strings in the script's "Period list" input (e.g., "1W, 1M, 3M, 1Y, YTD"). Each item in the input list represents a period offset from the latest bar's opening time.
2. Process the period list – The example calls `getArrayFromString()` on the first bar to split the input list by its commas and construct an array of period strings.
3. Request historical data – The code uses a call to `getDataAtPeriodOffsets()` as the `expression` argument in a request.security() call to retrieve the closing prices of "1D" bars for each period included in the processed `periods` array.
4. Display information in a table – On the latest bar, the code uses the retrieved data to calculate price returns over each specified period, then populates a two-row table with the results. The cells for each return percentage are color-coded based on the magnitude and direction of the price change. The cells also include tooltips showing the compared daily bar's opening date in the exchange time zone.
█ NOTES
• This library's architecture relies on a user-defined type (UDT) for its data storage format. UDTs are blueprints from which scripts create objects , i.e., composite structures with fields containing independent values or references of any supported type.
• The library functions search through a `Data` object's `times` array using the array.binary_search_leftmost() function, which is more efficient than looping through collected data to identify matching timestamps. Note that this built-in works only for arrays with elements sorted in ascending order .
• Each function that collects data from a `source` series updates the values and times stored in a local `Data` object's arrays. If a single call to these functions were to execute in a loop , it would store multiple values with an identical timestamp, which can cause erroneous search behavior. To prevent looped calls to these functions, the library uses the `checkCall()` helper function in their scopes. This function maintains a counter that increases by one each time it executes on a confirmed bar. If the count exceeds the total number of bars, indicating the call executes more than once in a loop, it raises a runtime error .
• Typically, when requesting higher-timeframe data with request.security() while using barmerge.lookahead_on as the `lookahead` argument, the `expression` argument should be offset with the history-referencing operator to prevent lookahead bias on historical bars. However, the call in this script's example code enables lookahead without offsetting the `expression` because the script displays results only on the last historical bar and all realtime bars, where there is no future data to leak into the past. This call ensures the displayed results use the latest data available from the context on realtime bars.
Look first. Then leap.
█ EXPORTED TYPES
Data
A structure for storing successive timestamps and corresponding values from a dataset.
Fields:
times (array) : An "int" array containing a UNIX timestamp for each value in the `values` array.
values (array) : A "float" array containing values corresponding to the timestamps in the `times` array.
█ EXPORTED FUNCTIONS
getArrayFromString(str)
Splits a "string" into an array of substrings using the comma (`,`) as the delimiter. The function trims surrounding whitespace characters from each substring, and it excludes empty substrings from the result.
Parameters:
str (series string) : The "string" to split into an array based on its commas.
Returns: (array) An array of trimmed substrings from the specified `str`.
periodToTimestamp(period, referenceTime)
Calculates a UNIX timestamp representing the point offset behind a reference time by the amount of time within the specified `period`.
Parameters:
period (series string) : The period string, which determines the time offset of the returned timestamp. The specified argument must contain a unit and an optional multiplier (e.g., "1Y", "3M", "2W", "YTD"). Supported units are:
- "Y" for years.
- "M" for months.
- "W" for weeks.
- "D" for days.
- "YTD" (Year-to-date) for the span from the start of the `referenceTime` value's year in the exchange time zone. An argument with this unit cannot contain a multiplier.
referenceTime (series int) : The millisecond UNIX timestamp from which to calculate the offset time.
Returns: (int) A millisecond UNIX timestamp representing the offset time point behind the `referenceTime`.
collectData(source, timeOffsetLimit, timeframeLimit)
Collects `source` and `time` data successively across bars. The function stores the information within a `Data` object for use in other exported functions/methods, such as `valueAtTimeOffset()` and `valueAtPeriodOffset()`. Any call to this function cannot execute more than once per bar or realtime tick.
Parameters:
source (series float) : The source series to collect. The function stores each value in the series with an associated timestamp representing its corresponding bar's opening time.
timeOffsetLimit (simple int) : Optional. A time offset (range) in milliseconds. If specified, the function limits the collected data to the maximum number of bars covered by the range, with a minimum of one bar. If the call includes a non-empty `timeframeLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
timeframeLimit (simple string) : Optional. A valid timeframe string. If specified and not empty, the function limits the collected data to the maximum number of bars covered by the timeframe, with a minimum of one bar. If the call includes a non-na `timeOffsetLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
Returns: (Data) A `Data` object containing collected `source` values and corresponding timestamps over the allowed time range.
method valueAtTime(data, timestamp)
(Overload 1 of 2) Retrieves value and time data from a `Data` object's fields at the index of the earliest timestamp closest to the specified `timestamp`. Callable as a method or a function.
Parameters:
data (series Data) : The `Data` object containing the collected time and value data.
timestamp (series int) : The millisecond UNIX timestamp to search. The function returns data for the earliest saved timestamp that is closest to the value.
Returns: ( ) A tuple containing the following data from the `Data` object:
- The stored value corresponding to the identified timestamp ("float").
- The earliest saved timestamp that is closest to the specified `timestamp` ("int").
valueAtTime(source, timestamp, timeOffsetLimit, timeframeLimit)
(Overload 2 of 2) Retrieves `source` and time information for the earliest bar whose opening timestamp is closest to the specified `timestamp`. Any call to this function cannot execute more than once per bar or realtime tick.
Parameters:
source (series float) : The source series to analyze. The function stores each value in the series with an associated timestamp representing its corresponding bar's opening time.
timestamp (series int) : The millisecond UNIX timestamp to search. The function returns data for the earliest bar whose timestamp is closest to the value.
timeOffsetLimit (simple int) : Optional. A time offset (range) in milliseconds. If specified, the function limits the collected data to the maximum number of bars covered by the range, with a minimum of one bar. If the call includes a non-empty `timeframeLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
timeframeLimit (simple string) : (simple string) Optional. A valid timeframe string. If specified and not empty, the function limits the collected data to the maximum number of bars covered by the timeframe, with a minimum of one bar. If the call includes a non-na `timeOffsetLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
Returns: ( ) A tuple containing the following data:
- The `source` value corresponding to the identified timestamp ("float").
- The earliest bar's timestamp that is closest to the specified `timestamp` ("int").
- The current bar's `source` value ("float").
method valueAtTimeOffset(data, timeOffset)
(Overload 1 of 2) Retrieves value and time data from a `Data` object's fields at the index of the earliest saved timestamp closest to `timeOffset` milliseconds behind the current bar's opening time. Callable as a method or a function.
Parameters:
data (series Data) : The `Data` object containing the collected time and value data.
timeOffset (series int) : The millisecond offset behind the bar's opening time. The function returns data for the earliest saved timestamp that is closest to the calculated offset time.
Returns: ( ) A tuple containing the following data from the `Data` object:
- The stored value corresponding to the identified timestamp ("float").
- The earliest saved timestamp that is closest to `timeOffset` milliseconds before the current bar's opening time ("int").
valueAtTimeOffset(source, timeOffset, timeOffsetLimit, timeframeLimit)
(Overload 2 of 2) Retrieves `source` and time information for the earliest bar whose opening timestamp is closest to `timeOffset` milliseconds behind the current bar's opening time. Any call to this function cannot execute more than once per bar or realtime tick.
Parameters:
source (series float) : The source series to analyze. The function stores each value in the series with an associated timestamp representing its corresponding bar's opening time.
timeOffset (series int) : The millisecond offset behind the bar's opening time. The function returns data for the earliest bar's timestamp that is closest to the calculated offset time.
timeOffsetLimit (simple int) : Optional. A time offset (range) in milliseconds. If specified, the function limits the collected data to the maximum number of bars covered by the range, with a minimum of one bar. If the call includes a non-empty `timeframeLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
timeframeLimit (simple string) : Optional. A valid timeframe string. If specified and not empty, the function limits the collected data to the maximum number of bars covered by the timeframe, with a minimum of one bar. If the call includes a non-na `timeOffsetLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
Returns: ( ) A tuple containing the following data:
- The `source` value corresponding to the identified timestamp ("float").
- The earliest bar's timestamp that is closest to `timeOffset` milliseconds before the current bar's opening time ("int").
- The current bar's `source` value ("float").
method valueAtPeriodOffset(data, period)
(Overload 1 of 2) Retrieves value and time data from a `Data` object's fields at the index of the earliest timestamp closest to a calculated offset behind the current bar's opening time. The calculated offset represents the amount of time covered by the specified `period`. Callable as a method or a function.
Parameters:
data (series Data) : The `Data` object containing the collected time and value data.
period (series string) : The period string, which determines the calculated time offset. The specified argument must contain a unit and an optional multiplier (e.g., "1Y", "3M", "2W", "YTD"). Supported units are:
- "Y" for years.
- "M" for months.
- "W" for weeks.
- "D" for days.
- "YTD" (Year-to-date) for the span from the start of the current bar's year in the exchange time zone. An argument with this unit cannot contain a multiplier.
Returns: ( ) A tuple containing the following data from the `Data` object:
- The stored value corresponding to the identified timestamp ("float").
- The earliest saved timestamp that is closest to the calculated offset behind the bar's opening time ("int").
valueAtPeriodOffset(source, period, timeOffsetLimit, timeframeLimit)
(Overload 2 of 2) Retrieves `source` and time information for the earliest bar whose opening timestamp is closest to a calculated offset behind the current bar's opening time. The calculated offset represents the amount of time covered by the specified `period`. Any call to this function cannot execute more than once per bar or realtime tick.
Parameters:
source (series float) : The source series to analyze. The function stores each value in the series with an associated timestamp representing its corresponding bar's opening time.
period (series string) : The period string, which determines the calculated time offset. The specified argument must contain a unit and an optional multiplier (e.g., "1Y", "3M", "2W", "YTD"). Supported units are:
- "Y" for years.
- "M" for months.
- "W" for weeks.
- "D" for days.
- "YTD" (Year-to-date) for the span from the start of the current bar's year in the exchange time zone. An argument with this unit cannot contain a multiplier.
timeOffsetLimit (simple int) : Optional. A time offset (range) in milliseconds. If specified, the function limits the collected data to the maximum number of bars covered by the range, with a minimum of one bar. If the call includes a non-empty `timeframeLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
timeframeLimit (simple string) : Optional. A valid timeframe string. If specified and not empty, the function limits the collected data to the maximum number of bars covered by the timeframe, with a minimum of one bar. If the call includes a non-na `timeOffsetLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
Returns: ( ) A tuple containing the following data:
- The `source` value corresponding to the identified timestamp ("float").
- The earliest bar's timestamp that is closest to the calculated offset behind the current bar's opening time ("int").
- The current bar's `source` value ("float").
getDataAtTimes(timestamps, source, timeOffsetLimit, timeframeLimit)
Retrieves `source` and time information for each bar whose opening timestamp is the earliest one closest to one of the UNIX timestamps specified in the `timestamps` array. Any call to this function cannot execute more than once per bar or realtime tick.
Parameters:
timestamps (array) : An array of "int" values representing UNIX timestamps. The function retrieves `source` and time data for each element in this array.
source (series float) : The source series to analyze. The function stores each value in the series with an associated timestamp representing its corresponding bar's opening time.
timeOffsetLimit (simple int) : Optional. A time offset (range) in milliseconds. If specified, the function limits the collected data to the maximum number of bars covered by the range, with a minimum of one bar. If the call includes a non-empty `timeframeLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
timeframeLimit (simple string) : Optional. A valid timeframe string. If specified and not empty, the function limits the collected data to the maximum number of bars covered by the timeframe, with a minimum of one bar. If the call includes a non-na `timeOffsetLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
Returns: ( ) A tuple of the following data:
- An array containing a `source` value for each identified timestamp (array).
- An array containing an identified timestamp for each item in the `timestamps` array (array).
- The current bar's `source` value ("float").
- The symbol's description from `syminfo.description` ("string").
getDataAtTimeOffsets(timeOffsets, source, timeOffsetLimit, timeframeLimit)
Retrieves `source` and time information for each bar whose opening timestamp is the earliest one closest to one of the time offsets specified in the `timeOffsets` array. Each offset in the array represents the absolute number of milliseconds behind the current bar's opening time. Any call to this function cannot execute more than once per bar or realtime tick.
Parameters:
timeOffsets (array) : An array of "int" values representing the millisecond time offsets used in the search. The function retrieves `source` and time data for each element in this array. For example, the array ` ` specifies that the function returns data for the timestamps closest to one day and one week behind the current bar's opening time.
source (float) : (series float) The source series to analyze. The function stores each value in the series with an associated timestamp representing its corresponding bar's opening time.
timeOffsetLimit (simple int) : Optional. A time offset (range) in milliseconds. If specified, the function limits the collected data to the maximum number of bars covered by the range, with a minimum of one bar. If the call includes a non-empty `timeframeLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
timeframeLimit (simple string) : Optional. A valid timeframe string. If specified and not empty, the function limits the collected data to the maximum number of bars covered by the timeframe, with a minimum of one bar. If the call includes a non-na `timeOffsetLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
Returns: ( ) A tuple of the following data:
- An array containing a `source` value for each identified timestamp (array).
- An array containing an identified timestamp for each offset specified in the `timeOffsets` array (array).
- The current bar's `source` value ("float").
- The symbol's description from `syminfo.description` ("string").
getDataAtPeriodOffsets(periods, source, timeOffsetLimit, timeframeLimit)
Retrieves `source` and time information for each bar whose opening timestamp is the earliest one closest to a calculated offset behind the current bar's opening time. Each calculated offset represents the amount of time covered by a period specified in the `periods` array. Any call to this function cannot execute more than once per bar or realtime tick.
Parameters:
periods (array) : An array of period strings, which determines the time offsets used in the search. The function retrieves `source` and time data for each element in this array. For example, the array ` ` specifies that the function returns data for the timestamps closest to one day, week, and month behind the current bar's opening time. Each "string" in the array must contain a unit and an optional multiplier. Supported units are:
- "Y" for years.
- "M" for months.
- "W" for weeks.
- "D" for days.
- "YTD" (Year-to-date) for the span from the start of the current bar's year in the exchange time zone. An argument with this unit cannot contain a multiplier.
source (float) : (series float) The source series to analyze. The function stores each value in the series with an associated timestamp representing its corresponding bar's opening time.
timeOffsetLimit (simple int) : Optional. A time offset (range) in milliseconds. If specified, the function limits the collected data to the maximum number of bars covered by the range, with a minimum of one bar. If the call includes a non-empty `timeframeLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
timeframeLimit (simple string) : Optional. A valid timeframe string. If specified and not empty, the function limits the collected data to the maximum number of bars covered by the timeframe, with a minimum of one bar. If the call includes a non-na `timeOffsetLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
Returns: ( ) A tuple of the following data:
- An array containing a `source` value for each identified timestamp (array).
- An array containing an identified timestamp for each period specified in the `periods` array (array).
- The current bar's `source` value ("float").
- The symbol's description from `syminfo.description` ("string").
Library
Indicator
Indicator
Indicator
