Catalog: D07-F05-A01 · Family: D07-F05 Volume Indicators · Status: publication-ready
Start with the decision, not the line
The engineering question is precise: How much reported volume occurred on higher closes versus lower closes, under one declared seed and history start? The learner outcome is equally concrete: Turn close direction into a seed-invariant signed-volume path and reconcile two OBV lines without mistaking their absolute levels for comparable measurements.
That boundary matters because a chart line is only the last stage of a data contract. OBV sees the sign of the close-to-close change and the full current-bar volume. It does not see return magnitude, the close's location inside the high-low range, trade initiator identity, and where inside the interval volume occurred. A plausible interpretation that depends on an ignored field is not an insight from this indicator; it is a new rule that must be specified and tested separately.
The market-data identity comes first
“Volume” is not one universal unit. U.S. listed-equity consolidated reporting can combine transactions from multiple market centers; a venue-only feed is a different population. Futures volume counts contracts for a specific contract, which raises a separate continuous-series and roll question. Other datasets may expose base-asset units, quote-asset notional, trade counts, or tick volume. None can be exchanged silently.
The close also needs a clock. A regular-session official close, a last consolidated trade, and an after-hours last trade can differ. When the formula compares closes, classifies typical-price direction, or locates the close inside a bar, that upstream choice can change the result even when the numeric kernel is flawless.
Production output should therefore travel with instrument identifier, venue or consolidated scope, volume unit, bar interval, session and close policy, time zone, correction state, corporate-action basis, parameters, history start, seed, and code version. The synthetic fixture deliberately claims none of those market identities.
The question this indicator actually answers
Technical indicators become dangerous when a familiar label replaces a precise question. OBV is useful because it compresses a defined recent path, but its output only means what its inputs, windows, and initialization allow it to mean.
Add current volume after an up close, subtract it after a down close, and add zero after an equal close. OBV records signed volume direction. Its changes are meaningful under a fixed history and seed; the absolute level is not comparable across arbitrary starts. That sentence is the center of the tutorial: measurement first, interpretation second, trading rules elsewhere.
Freeze the data before the formula
The selected input is finalized close and nonnegative volume. Bars must be strictly ordered and finalized, use one interval and session policy, and share one documented price/volume adjustment basis. If a split is handled in close but not high and low, a range indicator can become mathematically correct over economically inconsistent fields. If a missing bar is silently filled, the lookback describes a different time path. The reference function therefore validates numeric structure and leaves timestamps, calendars, adjustments, and finality to the caller.
The canonical fixture contains 120 author-generated UTC daily bars. It is intentionally synthetic. It can prove arithmetic, warm-up, parity, and causal behavior; it cannot prove a market edge.
The selected calculation
| Symbol | Meaning | Unit / scale |
|---|---|---|
| Cₜ | Finalized close | price units |
| Vₜ | Current reported volume | instrument volume units |
| sign(ΔCₜ) | Up +1, down -1, equal 0 | direction |
| OBVₜ | Seed plus cumulative signed volume | volume units |
Parameters are initial=0. Add current volume after an up close, subtract it after a down close, and add zero after an equal close. The first ready point is index 0; the seed is ready and the first directional update occurs at index 1. Every earlier row remains visibly unavailable rather than being replaced by zero. Zero is a valid indicator value for some indicators, so using it as a warm-up sentinel would corrupt both charts and downstream rules.
Read the scale carefully
OBV records signed volume direction. Its changes are meaningful under a fixed history and seed; the absolute level is not comparable across arbitrary starts. Equal closes contribute zero; zero-volume bars leave the line unchanged. A threshold can be a convenient classification boundary, but it is not a probability calibration. A reading in a commonly named zone does not specify an entry time, order type, holding period, stop, cost model, or expected return.
The variant trap
Providers differ on the first seed and history start. This package uses zero at index 0 and an equal-close contribution of zero. When two platforms disagree, compare instrument and venue scope, volume unit, session close, source fields, parameters, scale, seed or EMA initialization, warm-up, equality policy, and zero behavior before assuming either is broken. Matching the indicator name is not enough.
Reproduce one complete row
The independently audited canonical row is zero-based index 1 (2025-01-02T00:00:00Z, synthetic). No value below is a provider observation.
| Component | Author-derived value |
|---|---|
| Close direction | 1.00000000 |
| Volume | 1066468.03600000 |
| Signed volume | 1066468.03600000 |
| OBV | 1066468.03600000 |
Independent substitution: 0.00000000 + 1066468.03600000 = 1066468.03600000.
Published checkpoints round to 10 decimal places; teaching prose shows 8 decimals.
Compare six complete paths
| Scenario | Ready rows | Undefined rows | Final output | Teaching purpose |
|---|---|---|---|---|
| Canonical · four regimes | 120 | 0 | 15276116.3580 | Four deterministic price regimes with changing participation and three controlled volume shocks. |
| Comparison · rise with expanding volume | 120 | 0 | 157745789.0630 | A persistent rise with expanding activity separates full-volume signs from return- and range-weighted contributions. |
| Comparison · range cycle | 120 | 0 | 2877318.0210 | A bounded price cycle with varying activity exposes repeated positive and negative volume contributions. |
| Boundary · flat, zero volume, then shock | 120 | 0 | 48105000.0000 | A flat zero-range and zero-volume prefix exposes neutral, unchanged, warm-up, and undefined states before a controlled shock. |
| Diagnostic · gap versus close location | 120 | 0 | 22466847.6260 | Alternating gaps deliberately close near the opposite edge of each bar, separating close-to-close indicators from Chaikin close-location indicators. |
| Diagnostic · activity shock without price movement | 120 | 0 | -1635992.7390 | Extreme-volume equal-close and zero-range bars expose which formulas contribute zero, dilute a denominator, return neutral, or retain recursive state. |
These scenarios are not cherry-picked trades. They isolate mechanics: multi-regime behavior, persistent direction, repeated range movement, and a zero-movement boundary followed by a controlled shock. Python and TypeScript consume the same canonical JSON checkpoints, while the playground exposes the enriched component trace for all scenario/preset combinations.
Why this indicator disagrees with Volume Price Trend
OBV assigns the entire current volume by direction; VPT assigns only current volume multiplied by the decimal close return. This is not a minor display difference. It changes which observations receive weight and therefore which path can move the output.
The shared gap versus close location scenario makes the distinction observable. Alternating gaps deliberately close near the opposite edge of each bar. The shared activity shock without price movement scenario inserts extreme volume on equal-close, zero-range rows. For this topic, the expected takeaway is: The gap scenario matters only through close-to-close direction; the activity-shock scenario stays unchanged when the close is equal even if volume is extreme.
Open the comparison at full size
Reconcile another implementation in this order
- Confirm the exact formula name; “A/D,” “money flow,” and “Force Index” can refer to nearby but different methods.
- Compare ordered raw inputs—not screenshots—including instrument, venue scope, volume unit, interval, session, correction version, and price/volume adjustment basis.
- Freeze parameters, scale, tie policy, zero-range or zero-denominator policy, seed, EMA initialization, first-ready index, and rounding.
- Compare intermediate components at the first disagreement. A final-line mismatch is only a symptom.
- Test one equality row, one zero-volume row, one large gap, and one revision. These cases identify conventions faster than a long ordinary history.
Some libraries initialize OBV with the first bar's volume; this package initializes index 0 at the supplied seed. If two implementations use identical increments but seeds differ by k, their complete lines differ by the same constant k.
Revisions and causal recomputation
A revised close can change the signs at the revised row and the following row; a revised volume changes that row's increment. Because OBV is cumulative, every later level shifts by the net changed increments.
This is a causal statement, not merely a performance optimization. Recompute too little and stale values survive; recompute the entire history unnecessarily and an operational pipeline becomes expensive without gaining correctness. Store the earliest affected observation and the algorithm's dependency horizon beside revision jobs.
See the component pipeline
What to notice: each box names a state that is visible in the playground audit table. If the final output is unavailable, the status panel identifies whether the missing stage is causal warm-up or an undefined denominator.
Open the component pipeline at full size.
Implementation and operational behavior
The reference code favors transparency and aligned nulls. The enriched fixture adds author-derived component traces without changing the reference function's public calculation. The executable examples print audited ready rows. The reference implementation is O(n): cumulative and recursive stages update once per row, while CMF and MFI use causal running sums. A streaming version must preserve the same clock, components, seed or window state, aligned nulls, and invalid-state semantics.
Revision policy matters. Rolling indicators require recalculation until the revised row leaves the largest window. Recursive indicators can alter the entire suffix. Store the code version and parameters with the published series.
What can go wrong
Do not compare absolute levels from different seeds, treat reported volume across instruments as one unit, or call divergence predictive without a separately frozen rule. Also avoid hindsight-defined divergence, thresholds optimized on the evaluation sample, and provisional-bar signals evaluated against finalized-bar outcomes. These are research-design failures, not formula failures.
Combining several volume indicators does not automatically create independent evidence. OBV, VPT, A/D, CMF, MFI, and Force Index reuse overlapping price-volume information. Correlated transforms may create a false impression of confirmation.
Appropriate real-world use
Use OBV as a reproducible chart layer, a monitored feature, or one input to a separately governed research pipeline. Define any event rule after the measurement: crossing direction, tolerance, bar finality, action time, costs, and risk controls all belong outside the indicator.
Why the historical example is deferred
A named security would require authoritative or licensed timestamped observations, stable identifier, time zone and session semantics, adjusted-or-unadjusted basis, corporate-action and correction lineage, access date, and redistribution rights. It would also require a clean separation between provider observations and author-derived values. Until that evidence bundle exists, a named example would add realism at the cost of provenance. The synthetic case is the stronger verification artifact today.
Takeaway
OBV is best understood as a contract: declared data, declared transformation, declared warm-up, and declared limits. Preserve that contract and the output is reproducible. Add trading meaning without a separate rule and evidence process, and precision turns into false confidence.
Sources
See ../REFERENCES.md for the claim-level source ledger and limits.
Rendered from the canonical Mermaid sources linked by this article.
Calculation flow
Purpose: expose the exact dependency that is warming up or undefined before OBV is emitted.
Interpretation: a null result is not enough information by itself. The enriched fixture and lab preserve the component trace plus a reason that distinguishes causal warm-up from an undefined scale.
Takeaway: availability gates are part of the algorithm, not presentation cleanup.
Data-basis reconciliation — On-Balance Volume (OBV)
Use this decision flow before comparing two implementations or provider displays.
Takeaway: Some libraries initialize OBV with the first bar's volume; this package initializes index 0 at the supplied seed. If two implementations use identical increments but seeds differ by k, their complete lines differ by the same constant k. Final values come last; the first mismatched input or component explains the disagreement.
ReferencesPrimary sources and evidence notesExpand the source trail, evidence role, and limitations behind the engineering choices.
Expand the source trail, evidence role, and limitations behind the engineering choices.
On Balance Volume (OBV)
- Organization or authors: TradingView
- Source type: Official product or maintained technical documentation
- Publication or effective date: Current documentation at access
- Version: Web documentation accessed 2026-07-26
- URL: On Balance Volume (OBV)
- Accessed: 2026-07-26
- Jurisdiction: Platform convention; not jurisdiction-specific
- Applicability: Used only within the scope recorded for On Balance Volume (OBV); it does not override this package's explicit implementation and market-data conventions.
- Supports: The add/subtract/unchanged recurrence for up, down, and equal closes and attribution to Joe Granville.
- Limitations: The package selects a zero seed; absolute OBV level depends on the selected seed and history start.
Volume
- Organization or authors: TradingView
- Source type: Official product or maintained technical documentation
- Publication or effective date: Current documentation at access
- Version: Web documentation accessed 2026-07-26
- URL: Volume
- Accessed: 2026-07-26
- Jurisdiction: Platform convention; not jurisdiction-specific
- Applicability: Used only within the scope recorded for Volume; it does not override this package's explicit implementation and market-data conventions.
- Supports: Volume is instrument-specific: shares for stocks and contracts for futures or options.
- Limitations: The page explains charting semantics, not exchange reporting, correction, or licensing rules.
TA-Lib function API and volume indicators
- Organization or authors: TA-Lib
- Source type: Maintained official technical documentation
- Publication or effective date: Current documentation at access
- Version: Web documentation accessed 2026-07-26
- URL: TA-Lib function API and volume indicators
- Accessed: 2026-07-26
- Jurisdiction: Platform convention; not jurisdiction-specific
- Applicability: Used only within the scope recorded for TA-Lib function API and volume indicators; it does not override this package's explicit implementation and market-data conventions.
- Supports: Maintained function identities for Chaikin A/D, OBV, and the related TA-Lib volume-indicator group.
- Limitations: The function list does not establish this package's seed, null, tie, precision, or error conventions; byte-for-byte TA-Lib parity is not claimed.
Consolidated Tape
- Organization or authors: U.S. Securities and Exchange Commission, Investor.gov
- Source type: Regulator investor-education glossary
- Publication or effective date: Current documentation at access
- Version: Web documentation accessed 2026-07-26
- URL: Consolidated Tape
- Accessed: 2026-07-26
- Jurisdiction: United States listed equities
- Applicability: Used only within the scope recorded for Consolidated Tape; it does not override this package's explicit implementation and market-data conventions.
- Supports: For U.S. exchange-listed stocks, consolidated price and volume reports combine transactions from multiple market centers, including exchanges and off-exchange venues.
- Limitations: This glossary definition does not prescribe a universal bar-building, correction, licensing, or international-market policy.
Closing Price
- Organization or authors: U.S. Securities and Exchange Commission, Investor.gov
- Source type: Regulator investor-education glossary
- Publication or effective date: Current documentation at access
- Version: Web documentation accessed 2026-07-26
- URL: Closing Price
- Accessed: 2026-07-26
- Jurisdiction: United States equities
- Applicability: Used only within the scope recorded for Closing Price; it does not override this package's explicit implementation and market-data conventions.
- Supports: Regular-session and after-hours closing-price conventions can differ across published sources, so the close field and session boundary must be declared.
- Limitations: The page describes U.S. equity conventions; other jurisdictions, instruments, and providers can use different sessions and official closes.
What is Volume?
- Organization or authors: CME Group
- Source type: Official exchange education
- Publication or effective date: Current documentation at access
- Version: Web documentation accessed 2026-07-26
- URL: What is Volume?
- Accessed: 2026-07-26
- Jurisdiction: Exchange-traded futures
- Applicability: Used only within the scope recorded for What is Volume?; it does not override this package's explicit implementation and market-data conventions.
- Supports: Futures volume counts contracts traded over the selected interval and is reported by contract.
- Limitations: This is futures-specific education and does not define equity shares, options multipliers, spot-FX tick volume, crypto venue scope, or continuous-contract roll construction.
Claim-role ledger
| Role | Material content in this package | Treatment |
|---|---|---|
| Sourced fact | Indicator attribution, original-book identity, and maintained function/reference implementation identity | Supported only to the limits recorded above |
| Implementation choice | Parameters, seed, warm-up suppression, null behavior, tie handling, and displayed scale | Frozen in the canonical README and contract; never attributed universally |
| Synthetic teaching input | Four deterministic 120-row OHLCV scenarios | Labeled synthetic in datasets, examples, visuals, and playground |
| Author-derived calculation | Component traces, checkpoints, classifications, diagrams, and worked substitutions | Reproducible from the published formula and fixture; not provider data |
| Empirical result | None | No association, prediction, profitability, or strategy-performance claim is published |
Evidence boundary
The scenarios are author-generated synthetic teaching data. Formulas, outputs, component traces, checkpoints, diagrams, and interpretations derived from them are author calculations. No fixture row is a provider observation, no threshold is presented as a probability, and no trading-performance claim is made.
A historical example is deferred. Publication would require a traceable instrument identifier, licensed or authoritative timestamped OHLCV data, session/time-zone rules, adjusted-or-unadjusted basis, corporate-action lineage, exact parameters and seeds, access date, and reproducible provider-versus-author calculation separation.
Enhanced claim-to-source map
| Claim | Role | Evidence treatment |
|---|---|---|
| Canonical formula identity | Sourced fact plus package convention | Indicator-specific maintained documentation supports the named components; this package freezes seed, null, tie, scale, and warm-up behavior |
| U.S. consolidated equity scope | Sourced fact | Investor.gov supports multi-market-center consolidated reporting; no universal or international scope is inferred |
| Regular-session versus after-hours close | Sourced fact | Investor.gov supports the existence of differing published close conventions; the caller must select one |
| Futures volume counts contracts | Sourced fact | CME Group supports the futures-specific unit; it is not generalized to shares, ticks, or notional |
| OBV checkpoints and scenarios | Author-derived calculation | Reproduced from labeled synthetic OHLCV, formula components, and declared rounding |
| A tiny positive close change and a very large positive close change receive the same full-volume sign. OBV measures signed participation, not move size. | Formula analysis / implementation boundary | Follows from the variables absent from the selected formula; it is not an empirical performance result |
Public evidence boundary
No provider payload or named market observation is republished. Platform pages support formula identity and documented conventions, not profitability, causal order flow, or universal predictive value. Historical publication remains deferred until identity, market-data scope, session, corrections, adjustment lineage, parameters, access time, and rights are reproducible.
Full dependency-light reference implementations in both supported languages.
function period(value:number,name:string){if(!Number.isInteger(value)||value<=0)throw new Error(`${name} must be a positive integer`)}
function series(values:number[],name:string,nonnegative=false,positive=false){if(!Array.isArray(values)||values.length===0)throw new Error(`${name} must be non-empty`);return values.map(value=>{if(!Number.isFinite(value))throw new Error(`${name} must be finite`);if(nonnegative&&value<0)throw new Error(`${name} must be nonnegative`);if(positive&&value<=0)throw new Error(`${name} must be strictly positive`);return Number(value)})}
function aligned(...items:number[][]){if(new Set(items.map(x=>x.length)).size!==1)throw new Error("input series must align")}
function ohlcv(high:number[],low:number[],close:number[],volume:number[]){high=series(high,"high");low=series(low,"low");close=series(close,"close");volume=series(volume,"volume",true);aligned(high,low,close,volume);for(let i=0;i<close.length;i++)if(low[i]>high[i]||close[i]<low[i]||close[i]>high[i])throw new Error("require low <= close <= high");return{high,low,close,volume}}
function moneyFlow(high:number[],low:number[],close:number[],volume:number[]){const x=ohlcv(high,low,close,volume),multiplier:number[]=[],mfv:number[]=[];for(let i=0;i<x.close.length;i++){const span=x.high[i]-x.low[i],m=span===0?0:((x.close[i]-x.low[i])-(x.high[i]-x.close[i]))/span;multiplier.push(m);mfv.push(m*x.volume[i])}return{...x,multiplier,mfv}}
export function obv(close:number[],volume:number[],initial=0){close=series(close,"close");volume=series(volume,"volume",true);aligned(close,volume);if(!Number.isFinite(initial))throw new Error("initial must be finite");const direction=Array(close.length).fill(0),signed_volume=Array(close.length).fill(0),values=Array(close.length).fill(initial);for(let i=1;i<close.length;i++){direction[i]=close[i]>close[i-1]?1:close[i]<close[i-1]?-1:0;signed_volume[i]=direction[i]*volume[i];values[i]=values[i-1]+signed_volume[i]}return{direction,volume,signed_volume,obv:values}}
export function accumulation_distribution_line(high:number[],low:number[],close:number[],volume:number[],initial=0){const x=moneyFlow(high,low,close,volume);if(!Number.isFinite(initial))throw new Error("initial must be finite");let running=initial;const adl=x.mfv.map(value=>(running+=value));return{range:x.high.map((h,i)=>h-x.low[i]),money_flow_multiplier:x.multiplier,volume:x.volume,money_flow_volume:x.mfv,adl}}
export function chaikin_money_flow(high:number[],low:number[],close:number[],volume:number[],p=20){period(p,"period");const x=moneyFlow(high,low,close,volume),rolling_mfv:(number|null)[]=Array(x.close.length).fill(null),rolling_volume:(number|null)[]=Array(x.close.length).fill(null),cmf:(number|null)[]=Array(x.close.length).fill(null);let numerator=0,denominator=0;for(let i=0;i<x.close.length;i++){numerator+=x.mfv[i];denominator+=x.volume[i];if(i>=p){numerator-=x.mfv[i-p];denominator-=x.volume[i-p]}if(i>=p-1){rolling_mfv[i]=numerator;rolling_volume[i]=denominator;if(denominator!==0)cmf[i]=numerator/denominator}}return{money_flow_multiplier:x.multiplier,money_flow_volume:x.mfv,rolling_mfv,rolling_volume,cmf}}
export function money_flow_index(high:number[],low:number[],close:number[],volume:number[],p=14){period(p,"period");const x=ohlcv(high,low,close,volume),typical_price=x.close.map((c,i)=>(x.high[i]+x.low[i]+c)/3),raw_money_flow=typical_price.map((v,i)=>v*x.volume[i]),positive=Array(x.close.length).fill(0),negative=Array(x.close.length).fill(0);for(let i=1;i<x.close.length;i++){if(typical_price[i]>typical_price[i-1])positive[i]=raw_money_flow[i];else if(typical_price[i]<typical_price[i-1])negative[i]=raw_money_flow[i]}const positive_flow:(number|null)[]=Array(x.close.length).fill(null),negative_flow:(number|null)[]=Array(x.close.length).fill(null),money_flow_ratio:(number|null)[]=Array(x.close.length).fill(null),mfi:(number|null)[]=Array(x.close.length).fill(null);let ps=0,ns=0;for(let i=0;i<x.close.length;i++){ps+=positive[i];ns+=negative[i];if(i>=p){ps=Math.max(0,ps-positive[i-p]);ns=Math.max(0,ns-negative[i-p])}if(i<p)continue;positive_flow[i]=ps;negative_flow[i]=ns;if(ps===0&&ns===0){money_flow_ratio[i]=1;mfi[i]=50}else if(ns===0){money_flow_ratio[i]=null;mfi[i]=100}else if(ps===0){money_flow_ratio[i]=0;mfi[i]=0}else{money_flow_ratio[i]=ps/ns;mfi[i]=100*ps/(ps+ns)}}return{typical_price,raw_money_flow,positive_flow,negative_flow,money_flow_ratio,mfi}}
export function volume_price_trend(close:number[],volume:number[],initial=0){close=series(close,"close",false,true);volume=series(volume,"volume",true);aligned(close,volume);if(!Number.isFinite(initial))throw new Error("initial must be finite");const price_return=Array(close.length).fill(0),volume_contribution=Array(close.length).fill(0),vpt=Array(close.length).fill(initial);for(let i=1;i<close.length;i++){price_return[i]=(close[i]-close[i-1])/close[i-1];volume_contribution[i]=price_return[i]*volume[i];vpt[i]=vpt[i-1]+volume_contribution[i]}return{price_return,volume,volume_contribution,vpt}}
export function force_index(close:number[],volume:number[],p=13){period(p,"period");close=series(close,"close");volume=series(volume,"volume",true);aligned(close,volume);const change:(number|null)[]=[null,...close.slice(1).map((v,i)=>v-close[i])],raw_force:(number|null)[]=[null,...close.slice(1).map((_,i)=>(change[i+1] as number)*volume[i+1])],ema_seed:(number|null)[]=Array(close.length).fill(null),output:(number|null)[]=Array(close.length).fill(null);if(close.length>p){let value=(raw_force.slice(1,p+1) as number[]).reduce((a,b)=>a+b,0)/p;ema_seed[p]=value;output[p]=value;const alpha=2/(p+1);for(let i=p+1;i<close.length;i++){value=alpha*(raw_force[i] as number)+(1-alpha)*value;output[i]=value}}return{change,volume,raw_force,ema_seed,force_index:output}}
The embedded lab now expands to its full document height, keeping the article as the only scroll surface.