Skip to content

docs: explain how the dividend adjustment is calculated - #3031

Open
aakashbansalgit wants to merge 1 commit into
ranaroussi:mainfrom
aakashbansalgit:docs-dividend-adjustment
Open

aakashbansalgit wants to merge 1 commit into
ranaroussi:mainfrom
aakashbansalgit:docs-dividend-adjustment

Conversation

@aakashbansalgit

Copy link
Copy Markdown

Addresses #2070. The price adjustment page says what auto_adjust does but not how the dividend adjustment is calculated, which is behind several questions about returns not matching other sources. This adds three short sections to doc/source/advanced/price_adjustment.rst:

  • How the dividend adjustment is calculated: the per-ex-date factor, 1 - dividend / previous close, and a snippet that rebuilds Adj Close from auto_adjust=False data.
  • Adjusted prices change over time: each new dividend rescales all earlier prices, so stored adjusted prices drift from fresh downloads, and appending new adjusted rows to old ones creates a false jump.
  • Adjusted close and total return: returns from adjusted prices are the same as reinvesting at the previous close minus the dividend, which is why they differ slightly from published total returns.

I checked the numbers before writing them down. The snippet matches Yahoo's Adj Close to within 0.004% over the full histories of KO, SPY, AGG and AAPL (KO goes back to 1962). The basis-point gaps in the last section are from January 2023 to September 2026 data.

Docs only, no code changes. Based on main because that is where the page is (#2992).

Adds the adjustment formula with a snippet that rebuilds Adj Close, notes that adjusted history is rewritten at every ex-date, and explains why returns from Adj Close differ slightly from published total returns. Addresses ranaroussi#2070.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant