The governed definitions this build depends on. Read them first if a term is unfamiliar.
- PrimaryUpside/Downside Volume RatioUpside/Downside Volume Ratio is advancing or upside volume divided by declining or downside volume.
- PrerequisiteDown VolumeDown Volume is reported share volume allocated to declining issues under a declared methodology.
- PrerequisiteUp VolumeUp Volume is reported share volume allocated to advancing issues under a declared methodology.
- ImportantTotal VolumeTotal Volume is the reported trading volume for a declared market scope and session.
- ImportantVolume Adjustment BasisA volume adjustment basis declares how reported volume values are represented and adjusted within a series.
The hidden decision
The most important upside/downside volume result is sometimes not a number at all—it is the topology of the denominator.
Upside/Downside Volume Ratio answers one bounded question: how many shares traded in advancing issues for each share traded in declining issues? Its value is not a prediction. Its value is an auditable state whose inputs, time, units, and failure conditions are visible.
By the end, you will be able to calculate the method, reproduce its synthetic case, inspect its implementation trace, and decide when the output must be withheld.
Build the mental model
Divide advancing-issue volume by declining-issue volume for one declared session, while publishing denominator topology beside the result.
The ratio is memoryless and scale-free. The Advance/Decline Volume Line accumulates signed shares and depends on its seed.
The highlighted family card is a scope boundary. Count breadth, volume composition, recursive pressure, intraday sampling, and causal divergence can all produce lines, but their units and state memories are not interchangeable.
Freeze the contract before calculating
The selected formulation is:
Keep the raw volume ratio and publish the denominator state beside it. Publication invariant: Positive upside volume over zero downside volume is unbounded; 0/0 is incomplete and never converted to 1.
The input table in the canonical README defines row fields and units. The parameter table distinguishes a sourced method from package choices such as equality behavior, seed, zero policy, sampling grid, normalized breadth scale, and event timestamp.
Up Volume Down Volume Indicators, Chapter 8 supports this bounded source role: upside and downside volume are distinct breadth components and their ratio is a recognized transform. It does not override the limitations recorded in REFERENCES.md, and it does not establish historical performance.
Reproduce the synthetic result
Every observation below is synthetic. The arithmetic is author-derived:
| State | Advancing volume | Declining volume | Published result |
|---|---|---|---|
| Canonical | 120,000,000 | 60,000,000 | 2.0000 |
| Zero numerator | 0 | 60,000,000 | 0.0000 |
| Unbounded | 120,000,000 | 0 | unbounded, value withheld |
| No classified volume | 0 | 0 | incomplete, value withheld |
The canonical ratio is 120,000,000 / 60,000,000 = 2.0000. The two zero-denominator rows deliberately do not serialize infinity.
The expected output is:
{
"status": "resolved",
"value": 2.0
}
The SVG is not a decorative output card. It isolates the algorithm's actual learning obstacle: a ratio chart can conceal whether a large value is finite or caused by a zero denominator. Notice the labels and dashed or branched boundaries; color is supplementary.
Calculation flow
The Mermaid diagram renders from visuals/mermaid/calculation-flow.md and follows this pseudocode:
validate nonnegative synchronized volume legs
if declining_volume > 0: return advancing_volume / declining_volume
if advancing_volume > 0: return unbounded and withhold value
return incomplete no_classified_volume
Validation comes first so bad evidence cannot mutate later state. That rule is especially important for recursive lines, timestamp grids, arming clocks, and right-side pivot confirmation.
Read the implementation
Python and TypeScript both:
- validate finite inputs and the topic's identity/clock rules;
- compute the named intermediate values;
- preserve the trace needed to audit the result; and
- return a numeric value or typed event only when the publication boundary passes.
They share datasets/canonical-fixture.json, including expected output and parameters. The code avoids provider SDKs and hidden network calls so the teaching arithmetic is fully inspectable.
Use the guided lab
Open visuals/animated/playground.html. Its objective is to compare finite, zero, unbounded, and 0/0 states without manufacturing a number.
The initial screen is the completed canonical state. Back and Step reveal one observation at a time; Play uses the same transition function; Pause stops it; Reset restores the scenario and parameter. Comparison isolates a nearby outcome, while Failure / boundary demonstrates a reason code rather than a persuasive fake value. Reduced-motion Play advances one deterministic step without starting a timer.
The diagnostic panel and audit table should be read together. A smooth chart alone cannot prove denominator topology, chronological completeness, sampling continuity, or causal confirmation.
Operational interpretation
Use the ratio to compare composition rather than absolute activity, and preserve whether the result is finite, unbounded, or incomplete.
Do not misuse it: Do not cap positive-over-zero to a large finite value or coerce zero-over-zero to 1; both operations invent information.
Passing the implementation checks proves definition fidelity. It does not prove reversal prediction, causal market explanation, trading profitability, transferability to another universe, or performance after costs.
Edge cases worth testing
- Positive advancing volume over zero declining volume is unbounded, not infinite JSON.
- Zero over zero is incomplete because no classified-volume composition exists.
- Zero advancing volume over positive declining volume resolves exactly to 0.
- Scaling both legs by the same positive constant leaves the ratio unchanged.
Provider corrections require recomputing the affected tail or event set. A corrected observation that becomes available later must not leak into an earlier point-in-time result.
Evidence and historical boundary
A named historical reconstruction remains deferred. Publication would require a licensed point-in-time universe, exact classification rules, synchronized observations, session and sampling policy, correction lineage, the selected calculation convention, a knowledge cutoff, and redistribution rights.
Using a famous chart without that bundle would make the story stronger and the evidence weaker. The labelled synthetic fixture is therefore the responsible public example.
Summary and handoff
You can now calculate UDVR_t = V^+_t/V^-_t, interpret advancing-volume shares per declining-volume share, audit the method-specific boundary, and reproduce matching Python and TypeScript behavior. Review Advance/Decline Volume Line for the immediate input concept. Continue with Arms Index (TRIN) in the dependency path.
Rendered from the canonical Mermaid sources linked by this article.
Calculation Flow — Upside/Downside Volume Ratio
Purpose: A ratio chart can conceal whether a large value is finite or caused by a zero denominator.
Takeaway: Publish the denominator state with the ratio.
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.
Claim-to-source map
| Source ID | What it supports | Boundary |
|---|---|---|
STOCKCHARTS-UPDOWN | Upside and downside volume are distinct breadth components and their ratio is a recognized transform. | Interpretation is explanatory; it does not determine the package's zero-state policy. |
STOCKCHARTS-CATALOG | A named provider publishes distinct advancing-volume, declining-volume, and upside/downside-volume-ratio series. | Catalog presence does not expose the underlying proprietary observations or make its symbol convention universal. |
NYSE-VOLUME | The versioned official volume product identifies venue/listing coverage and fields, so volume provenance and product version must be retained. | The specification does not publish a free advancing/declining classification series or grant redistribution rights. |
The formula/concept source and the data-provenance source do different jobs. Exchange product documentation establishes venue fields, versioned feeds, and licensing boundaries; it does not silently define every derived indicator. Package-selected zero, seed, refresh, sampling, scale, and confirmation rules remain implementation choices.
STOCKCHARTS-UPDOWN — Up Volume Down Volume Indicators, Chapter 8
- Organization or authors: Greg Morris, StockCharts
- Source type: Institutional technical-method article
- Publication or effective date: 2015-11-04
- Version or retrieval state: Exact page or PDF retrieved 2026-07-26
- URL: https://articles.stockcharts.com/article/articles-dancing-2015-11-up-volume-down-volume-indicators-chap-8--cgmbi/
- Accessed: 2026-07-26
- Jurisdiction or applicability: Technical-analysis volume-breadth conventions
- Evidence role: sourced/provider convention
- Supports: Upside and downside volume are distinct breadth components and their ratio is a recognized transform.
- Limitations: Interpretation is explanatory; it does not determine the package's zero-state policy.
STOCKCHARTS-CATALOG — NYSE Breadth Symbol Catalog
- Organization or authors: StockCharts
- Source type: Maintained provider catalog
- Publication or effective date: Current catalog
- Version or retrieval state: Exact page or PDF retrieved 2026-07-26
- URL: https://stockcharts.com/freecharts/catalog/?sl=nu
- Accessed: 2026-07-26
- Jurisdiction or applicability: StockCharts NYSE series
- Evidence role: sourced/provider convention
- Supports: A named provider publishes distinct advancing-volume, declining-volume, and upside/downside-volume-ratio series.
- Limitations: Catalog presence does not expose the underlying proprietary observations or make its symbol convention universal.
NYSE-VOLUME — Volume Summary Client Specification v1.1d
- Organization or authors: New York Stock Exchange
- Source type: Official market-data technical specification
- Publication or effective date: 2026-04-20, version 1.1d
- Version or retrieval state: Exact page or PDF retrieved 2026-07-26
- URL: https://www.nyse.com/publicdocs/nyse/data/Volume_Summary_Client_Spec_v1.1d.pdf
- Accessed: 2026-07-26
- Jurisdiction or applicability: NYSE Group equities
- Evidence role: sourced/provider convention
- Supports: The versioned official volume product identifies venue/listing coverage and fields, so volume provenance and product version must be retained.
- Limitations: The specification does not publish a free advancing/declining classification series or grant redistribution rights.
Historical-example decision
Deferred. A named reconstruction requires the exact point-in-time universe, classification method, timestamps, correction lineage, session rules, calculation convention, and redistribution rights. This public package publishes labelled synthetic inputs and author-derived arithmetic instead. It makes no historical-association, prediction, causation, or profitability claim.
Full dependency-light reference implementations in both supported languages.
export type Result = Record<string, any>;
const numberValue = (value: unknown, name: string): number => {
if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${name} must be a finite number`);
return value;
};
export function calculate(row:any):Result {
if(row.ready===false)return{status:"incomplete",reason:"unready observation",value:null};
const up=numberValue(row.advancing_volume,"advancing_volume"),down=numberValue(row.declining_volume,"declining_volume");
if(up<0||down<0)return{status:"incomplete",reason:"negative volume",value:null};
if(down===0)return up>0?{status:"unbounded",reason:"zero declining volume",value:null}:{status:"incomplete",reason:"no classified volume",value:null};
return{status:"resolved",value:up/down};
}
The embedded lab now expands to its full document height, keeping the article as the only scroll surface.