Raw MACD answers how many price units separate two EMAs. That magnitude changes when the same path is quoted in cents instead of dollars or when two instruments trade at very different levels. PPO answers the relative-gap question.
PPO divides the fast-minus-slow exponential moving-average spread by the slow EMA, turning a price-unit gap into a percentage. This makes the oscillator comparable across positive price scales while preserving the sign of the underlying EMA relationship. By the end of this tutorial, you will be able to calculate the line, audit its hidden state, reproduce its warm-up and boundary conventions, and explain why another platform can disagree.
Data note: every chart and number in this article uses deterministic synthetic teaching data. No historical return or investment-performance claim is made.
Start with the question the indicator actually answers
A trend system is useful only when its output has a precise meaning. The current package asks one bounded measurement question and refuses to turn a chart state into a forecast.
PPO divides the fast-minus-slow exponential moving-average spread by the slow EMA, turning a price-unit gap into a percentage. This makes the oscillator comparable across positive price scales while preserving the sign of the underlying EMA relationship.
The map is the implementation checklist: validate the bar, calculate the intermediate state, apply the exact boundary rule, then publish an aligned output with its diagnostic evidence.
Formula and selected convention
F and S are SMA-seeded fast and slow EMAs. G and H are a package
extension for teaching signal-line behavior; TA-Lib's PPO function publishes
the PPO line itself. If S_t = 0, this package publishes no PPO value and
restarts the signal seed after defined values resume.
Defaults are teaching choices rather than universal laws:
| Parameter | Package default |
|---|---|
fast_span | 12 |
slow_span | 26 |
signal_span | 9 |
Worked numerical example
With fast EMA 105, slow EMA 100, and signal 3.8%, PPO is 5%, while the histogram is 1.2 percentage points. Multiplying every input price by ten leaves those percentages unchanged.
The hand result is deliberately small enough to recalculate without either implementation. The canonical fixture then extends the same rules across five long, topic-specific paths.
From data contract to executable state
Use finalized, chronological observations with one declared source field, session calendar, time zone, and adjustment basis. Reject non-finite values, malformed high/low geometry, and invalid parameters. Do not sort inside the numeric kernel, fill missing bars with zero, or splice adjusted and unadjusted history.
The implementation returns one aligned entry per input row. Warm-up stays
None in Python and null in TypeScript. A revision to historical input
invalidates the recursive or rolling suffix from the earliest changed row.
Implementation walkthrough
The Python and TypeScript files favor direct state variables over clever vectorization. That makes seed, tie, clamp, displacement, and reversal behavior reviewable. Both languages read the same fixture and preserve the same null, numeric, string, and boolean semantics.
Complexity is linear in the number of observations. The reference code is optimized for readability; a production streaming implementation can retain only the active rolling/recursive state after validating parity.
Reconcile a platform disagreement systematically
| Dimension | This package | Maintained-platform context | What to compare |
|---|---|---|---|
| Moving-average type | EMA only | TA-Lib accepts multiple MA types; its current standard default is EMA | Align the MA type before comparing values. |
| Zero slow EMA | Unavailable; signal seed restarts | TA-Lib documents output zero | A zero-versus-null difference is intentional, not rounding. |
| Signal and histogram | Included as a labeled teaching extension | TA-Lib PPO returns the PPO line | Do not attribute the extension to the base PPO function. |
Start at the first row where the two outputs diverge. Compare source fields and parameters first, then the previous intermediate state, and only then the published line. This avoids treating a documented convention difference as a numerical defect.
Explore the exact state
Open the guided Percentage Price Oscillator playground. The initial state is already informative. Choose a scenario, scrub or step to a named checkpoint, compare the visible diagnostics, and inspect the last 12 published rows.
The lab uses 180 observations in each of five scenarios, not a tiny decorative sample. A recent-60, recent-120, or complete-history focus keeps the denser path readable. Reduced-motion Play advances one observation without starting a timer.
Use the five-scenario atlas
| Lesson | Scenario ID | What the controlled path isolates |
|---|---|---|
| Normalized regime tour | normalized-regime-tour | A long rise, shelf, shock, decline, and recovery reveal PPO warm-up, signal lag, and zero-line crossings. |
| Quote-scale twin | quote-scale-twin | The canonical path is multiplied by ten so the learner can verify positive scale invariance observation by observation. |
| Additive-shift contrast | additive-shift-contrast | The canonical path is shifted upward by 500 units, showing that PPO is scale-invariant but not translation-invariant. |
| Zero-denominator reset | denominator-reset | A zero-valued prefix forces PPO to remain unavailable until the slow EMA becomes nonzero and the signal can seed again. |
| Responsive-span comparison | responsive-spans | Shorter 5/13/4 spans make the same broad state transitions react faster and expose a different warm-up boundary. |
Each path contains five checkpoints: first guided state, transition, boundary, platform reconciliation, and mature-state audit. These labels explain deterministic calculation state; they do not classify future market behavior.
A production debugging ladder
- Verify finalized input fields, chronological order, calendar, time zone, and adjustment basis.
- Verify parameter values and the first-ready index.
- Reconcile fast EMA, slow EMA, normalized spread, signal seed, and denominator availability.
- Compare the shared fixture at the first divergent row.
- Recalculate one checkpoint independently before changing code.
- Record the convention version with every persisted output.
Boundaries that cause real implementation drift
- PPO is scale-invariant under positive multiplication but not under adding a constant.
- A zero slow EMA makes the ratio undefined; returning zero would hide the denominator failure.
- Different EMA seeds can materially change the early PPO and its signal line.
The strongest reconciliation workflow compares the first valid index, a steady-state row, an equality boundary, a reversal or reset, and the complete aligned suffix—not merely the last visible chart point.
Compare the family question, not the chart color
MACD is the absolute EMA spread in source units. PPO is the same spread divided by the slow EMA. Use MACD when the price-unit distance is meaningful and PPO when relative scale is the intended measurement.
Neighboring indicators can display a similar bullish/bearish state while measuring different inputs. Agreement is not independent confirmation when the systems reuse the same prices and smoothing primitives.
Testing proves calculation, not profitability
The release checks cover:
- all-five-scenario Python/TypeScript parity;
- exact first-ready behavior;
- invalid values and parameters;
- equality, zero, tie, displacement, clamp, or reversal semantics;
- SVG accessibility and fixture-derived values;
- deterministic playground controls and reduced motion;
- responsive reader and standalone rendering.
None of those checks estimates future returns. A strategy study would still need point-in-time constituents, execution clocks, fees, slippage, survivorship controls, and out-of-sample evaluation.
Historical-example decision
A named historical chart is not useful for this mechanism lesson. It would introduce vendor data, adjustment, identifier, session, licensing, and hindsight ambiguity without strengthening the arithmetic. The synthetic paths isolate the causal rule and can be redistributed with the package.
Common questions
Is Percentage Price Oscillator a prediction?
No. It is a deterministic transformation of observed bars under the selected convention.
Can I compare values across platforms?
Only after aligning the source field, price basis, windows, seed, boundary rules, and display displacement.
What should I log in production?
Log the parameters, first-ready index, current intermediate state, input revision identifier, and the exact convention version.
What is the next tutorial?
Continue to Aroon, which changes the trend-system question and makes a different state or normalization visible.
Rendered from the canonical Mermaid sources linked by this article.
Percentage Price Oscillator calculation flow
Takeaway: the displayed line is reproducible only when the hidden state and its boundary convention are preserved.
References5 primary 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.
Access date for web sources: 2026-07-26. Public artifacts use only deterministic synthetic data.
R1 — Gerald Appel's MACD/PPO work
- Organization or authors: Gerald Appel's MACD/PPO work
- Source type: Original or origin-attribution publication record
- Publication or effective date: See catalog record
- Version: Bibliographic record accessed 2026-07-26
- URL or DOI: https://search.worldcat.org/search?q=au%3AAppel%2C+Gerald
- Accessed: 2026-07-26
- Jurisdiction: General technical analysis; no regulatory jurisdiction
- Evidence role: Origin and historical-definition context
- Supports: Authorship/origin and the conceptual purpose of the method.
- Limitations: The public record does not by itself freeze every modern platform seed, tie, plotting, or rounding convention.
- Publication decision: Cite for origin; use maintained documentation and the package contract for executable semantics.
R2 — TA-Lib PPO
- Organization or authors: TA-Lib project or TradingView, as identified by the linked page
- Source type: Maintained official technical documentation
- Publication or effective date: Current page
- Version: Page accessed 2026-07-26
- URL or DOI: https://ta-lib.org/functions/ppo
- Accessed: 2026-07-26
- Jurisdiction: General technical analysis; platform applicability stated in the package
- Evidence role: Formula and maintained implementation-context evidence
- Supports: PPO divides the fast-minus-slow exponential moving-average spread by the slow EMA, turning a price-unit gap into a percentage. This makes the oscillator comparable across positive price scales while preserving the sign of the underlying EMA relationship.
- Limitations: Documentation cannot establish predictive power, profitability, or universal platform parity.
- Publication decision: Publish formula facts with the package's selected conventions visibly separated.
R3 — Pinned TA-Lib ta_PPO.c implementation
- Organization or authors: TA-Lib project or TradingView
- Source type: Pinned maintained source or maintained calculation guide
- Publication or effective date: Repository commit or current guide
- Version: e203f7c436a9c21fd08246661971cfcb7ee37517
- URL or DOI: https://github.com/TA-Lib/ta-lib/blob/e203f7c436a9c21fd08246661971cfcb7ee37517/src/ta_func/ta_PPO.c
- Accessed: 2026-07-26
- Jurisdiction: General technical analysis
- Evidence role: Executable or platform-convention evidence
- Supports: Executable loop order, warm-up behavior, and maintained reference semantics used to compare the package convention.
- Limitations: Source parity is not claimed where this package explicitly selects a clearer seed or zero-state convention.
- Publication decision: Use to regression-check semantics; document intentional differences instead of implying universal equivalence.
R4 — Canonical synthetic fixture and independent arithmetic
- Organization or authors: The Fintech Builder
- Source type: Author-derived calculation from synthetic teaching inputs
- Publication or effective date: 2026-07-26
- Version: Fixture schema 2.0
- URL or DOI: datasets/percentage-price-oscillator-fixtures.json
- Accessed: 2026-07-26
- Jurisdiction: Not applicable
- Evidence role: Reproducibility and Python/TypeScript parity
- Supports: Published worked values, warm-up, equality, reset, and scenario behavior.
- Limitations: Synthetic observations prove calculation behavior only; they are not market evidence.
- Publication decision: Redistributable with the package; label every use synthetic.
R5 — TA-Lib MACD function documentation
- Organization or authors: TA-Lib project or TradingView
- Source type: Maintained official technical documentation
- Publication or effective date: Current page
- Version: Page accessed 2026-07-26
- URL or DOI: https://ta-lib.org/functions/macd
- Accessed: 2026-07-26
- Jurisdiction: General technical analysis; platform applicability stated in the package
- Evidence role: Neighboring-function and platform-reconciliation evidence
- Supports: Neighboring absolute-spread definition and EMA-component context.
- Limitations: A maintained platform record documents its own convention and does not make the package convention universal.
- Publication decision: Use in the reconciliation matrix; retain package choices and intentional differences explicitly.
Full dependency-light reference implementations in both supported languages.
export type Numeric = number | null;
function validateSeries(values: number[], name: string): void {
if (!Array.isArray(values) || values.length === 0) throw new RangeError(`${name} must be a non-empty array`);
if (values.some((value) => typeof value !== "number" || !Number.isFinite(value))) {
throw new TypeError(`${name} must contain only finite numbers`);
}
}
function validateHL(high: number[], low: number[]): void {
validateSeries(high, "high");
validateSeries(low, "low");
if (high.length !== low.length) throw new RangeError("high and low lengths must match");
if (high.some((value, index) => value < low[index])) throw new RangeError("high must be >= low");
}
function validateHLC(high: number[], low: number[], close: number[]): void {
validateHL(high, low);
validateSeries(close, "close");
if (close.length !== high.length) throw new RangeError("high, low, and close lengths must match");
if (close.some((value, index) => value < low[index] || value > high[index])) {
throw new RangeError("close must lie inside each high-low range");
}
}
function ema(values: number[], period: number): Numeric[] {
if (!Number.isInteger(period) || period < 1) throw new RangeError("period must be a positive integer");
const output: Numeric[] = Array(values.length).fill(null);
if (values.length < period) return output;
let previous = values.slice(0, period).reduce((sum, value) => sum + value, 0) / period;
output[period - 1] = previous;
const alpha = 2 / (period + 1);
for (let index = period; index < values.length; index += 1) {
previous += alpha * (values[index] - previous);
output[index] = previous;
}
return output;
}
function segmentedEma(values: Numeric[], period: number): Numeric[] {
const output: Numeric[] = Array(values.length).fill(null);
const alpha = 2 / (period + 1);
let buffer: number[] = [];
let previous: number | null = null;
values.forEach((value, index) => {
if (value === null) {
buffer = [];
previous = null;
} else if (previous === null) {
buffer.push(value);
if (buffer.length === period) {
previous = buffer.reduce((sum, item) => sum + item, 0) / period;
output[index] = previous;
}
} else {
previous += alpha * (value - previous);
output[index] = previous;
}
});
return output;
}
export function ppo(values: number[], fastSpan = 12, slowSpan = 26, signalSpan = 9) {
validateSeries(values, "values");
if (![fastSpan, slowSpan, signalSpan].every((value) => Number.isInteger(value) && value > 0)) {
throw new RangeError("spans must be positive integers");
}
if (fastSpan >= slowSpan) throw new RangeError("fastSpan must be less than slowSpan");
const fast_ema = ema(values, fastSpan);
const slow_ema = ema(values, slowSpan);
const ppoValues: Numeric[] = values.map((_, index) => {
const fast = fast_ema[index];
const slow = slow_ema[index];
return fast === null || slow === null || slow === 0 ? null : (100 * (fast - slow)) / slow;
});
const signal = segmentedEma(ppoValues, signalSpan);
const histogram = ppoValues.map((value, index) =>
value === null || signal[index] === null ? null : value - (signal[index] as number),
);
return { fast_ema, slow_ema, ppo: ppoValues, signal, histogram };
}
The embedded lab now expands to its full document height, keeping the article as the only scroll surface.