mirror of
https://github.com/K-Dense-AI/claude-scientific-skills.git
synced 2026-03-27 07:09:27 +08:00
Support EdgarTools to access and analyze SEC Edgar filings, XBRL financial statements, 10-K, 10-Q, and 8-K reports
This commit is contained in:
Timothy Kassis
274
scientific-skills/edgartools/references/financial-data.md
Normal file
274
scientific-skills/edgartools/references/financial-data.md
Normal file
@@ -0,0 +1,274 @@
|
||||
# edgartools — Financial Data Reference
|
||||
|
||||
## Table of Contents
|
||||
- [Quick Start](#quick-start)
|
||||
- [Available Statements](#available-statements)
|
||||
- [Convenience Methods](#convenience-methods)
|
||||
- [Detail Levels (Views)](#detail-levels-views)
|
||||
- [DataFrame Export](#dataframe-export)
|
||||
- [Quarterly vs Annual](#quarterly-vs-annual)
|
||||
- [Multi-Period Analysis](#multi-period-analysis)
|
||||
- [Raw XBRL Facts Query](#raw-xbrl-facts-query)
|
||||
- [API Quick Reference](#api-quick-reference)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
```python
|
||||
from edgar import Company
|
||||
|
||||
company = Company("AAPL")
|
||||
|
||||
# Annual (from latest 10-K)
|
||||
financials = company.get_financials()
|
||||
income = financials.income_statement()
|
||||
|
||||
# Quarterly (from latest 10-Q)
|
||||
quarterly = company.get_quarterly_financials()
|
||||
income = quarterly.income_statement()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Available Statements
|
||||
|
||||
```python
|
||||
financials = company.get_financials()
|
||||
|
||||
income = financials.income_statement()
|
||||
balance = financials.balance_sheet()
|
||||
cashflow = financials.cashflow_statement() # note: no underscore
|
||||
equity = financials.statement_of_equity()
|
||||
comprehensive = financials.comprehensive_income()
|
||||
```
|
||||
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| `income_statement()` | Revenue, COGS, operating income, net income |
|
||||
| `balance_sheet()` | Assets, liabilities, equity |
|
||||
| `cashflow_statement()` | Operating, investing, financing cash flows |
|
||||
| `statement_of_equity()` | Changes in stockholders' equity |
|
||||
| `comprehensive_income()` | Net income + other comprehensive income |
|
||||
|
||||
---
|
||||
|
||||
## Convenience Methods
|
||||
|
||||
Get single values directly:
|
||||
|
||||
```python
|
||||
financials = company.get_financials()
|
||||
|
||||
revenue = financials.get_revenue()
|
||||
net_income = financials.get_net_income()
|
||||
total_assets = financials.get_total_assets()
|
||||
total_liabs = financials.get_total_liabilities()
|
||||
equity = financials.get_stockholders_equity()
|
||||
op_cash_flow = financials.get_operating_cash_flow()
|
||||
free_cash_flow = financials.get_free_cash_flow()
|
||||
capex = financials.get_capital_expenditures()
|
||||
current_assets = financials.get_current_assets()
|
||||
current_liabs = financials.get_current_liabilities()
|
||||
|
||||
# All key metrics at once
|
||||
metrics = financials.get_financial_metrics() # dict
|
||||
|
||||
# Prior period: period_offset=1 (previous), 0=current
|
||||
prev_revenue = financials.get_revenue(period_offset=1)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Detail Levels (Views)
|
||||
|
||||
Control the level of detail in financial statements:
|
||||
|
||||
```python
|
||||
income = financials.income_statement()
|
||||
|
||||
# Summary: ~15-20 rows, matches SEC Viewer
|
||||
df_summary = income.to_dataframe(view="summary")
|
||||
|
||||
# Standard (default): ~25-35 rows, matches filing document
|
||||
df_standard = income.to_dataframe(view="standard")
|
||||
|
||||
# Detailed: ~50+ rows, all dimensional breakdowns
|
||||
df_detailed = income.to_dataframe(view="detailed")
|
||||
```
|
||||
|
||||
| View | Use Case |
|
||||
|------|----------|
|
||||
| `"summary"` | Quick overview, validating against SEC Viewer |
|
||||
| `"standard"` | Display, full context (default) |
|
||||
| `"detailed"` | Data extraction, segment analysis |
|
||||
|
||||
**Example — Apple Revenue breakdown:**
|
||||
- Summary: `Revenue $391,035M`
|
||||
- Standard: `Products $298,085M`, `Services $92,950M`
|
||||
- Detailed: iPhone, Mac, iPad, Wearables separately
|
||||
|
||||
---
|
||||
|
||||
## DataFrame Export
|
||||
|
||||
```python
|
||||
income = financials.income_statement()
|
||||
|
||||
# Convert to DataFrame
|
||||
df = income.to_dataframe()
|
||||
df = income.to_dataframe(view="detailed")
|
||||
|
||||
# Export
|
||||
df.to_csv("apple_income.csv")
|
||||
df.to_excel("apple_income.xlsx")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quarterly vs Annual
|
||||
|
||||
| Need | Method |
|
||||
|------|--------|
|
||||
| Annual (10-K) | `company.get_financials()` |
|
||||
| Quarterly (10-Q) | `company.get_quarterly_financials()` |
|
||||
|
||||
```python
|
||||
quarterly = company.get_quarterly_financials()
|
||||
q_income = quarterly.income_statement()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Multi-Period Analysis
|
||||
|
||||
Use `XBRLS` to analyze trends across multiple filings:
|
||||
|
||||
```python
|
||||
from edgar.xbrl import XBRLS
|
||||
|
||||
# Get last 3 annual filings (use amendments=False)
|
||||
filings = company.get_filings(form="10-K", amendments=False).head(3)
|
||||
|
||||
# Stitch together
|
||||
xbrls = XBRLS.from_filings(filings)
|
||||
|
||||
# Get aligned multi-period statements
|
||||
income = xbrls.statements.income_statement()
|
||||
income_detailed = xbrls.statements.income_statement(view="detailed")
|
||||
|
||||
balance = xbrls.statements.balance_sheet()
|
||||
cashflow = xbrls.statements.cashflow_statement()
|
||||
|
||||
# Convert to DataFrame (periods as columns)
|
||||
df = income.to_dataframe()
|
||||
print(df)
|
||||
```
|
||||
|
||||
**Why `amendments=False`?** Amended filings (10-K/A) sometimes contain only corrected sections, not complete financial statements, which breaks multi-period stitching.
|
||||
|
||||
---
|
||||
|
||||
## Raw XBRL Facts Query
|
||||
|
||||
For research or custom calculations:
|
||||
|
||||
```python
|
||||
xbrl = filing.xbrl()
|
||||
|
||||
# Find revenue facts
|
||||
revenue_facts = xbrl.facts.query()\
|
||||
.by_concept("Revenue")\
|
||||
.to_dataframe()
|
||||
|
||||
# Search by label
|
||||
rd_facts = xbrl.facts.query()\
|
||||
.by_label("Research", exact=False)\
|
||||
.to_dataframe()
|
||||
|
||||
# Filter by value range
|
||||
large_items = xbrl.facts.query()\
|
||||
.by_value(min_value=1_000_000_000)\
|
||||
.to_dataframe()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Quick Reference
|
||||
|
||||
### Company-Level
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| `company.get_financials()` | Latest annual (10-K) |
|
||||
| `company.get_quarterly_financials()` | Latest quarterly (10-Q) |
|
||||
|
||||
### Financials Object
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| `financials.income_statement()` | Income statement |
|
||||
| `financials.balance_sheet()` | Balance sheet |
|
||||
| `financials.cashflow_statement()` | Cash flow |
|
||||
| `financials.get_revenue()` | Revenue scalar |
|
||||
| `financials.get_net_income()` | Net income scalar |
|
||||
| `financials.get_total_assets()` | Total assets scalar |
|
||||
| `financials.get_financial_metrics()` | Dict of all key metrics |
|
||||
|
||||
### Statement Object
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| `statement.to_dataframe()` | Convert to DataFrame |
|
||||
| `statement.to_dataframe(view="summary")` | SEC Viewer format |
|
||||
| `statement.to_dataframe(view="standard")` | Filing document format |
|
||||
| `statement.to_dataframe(view="detailed")` | All dimensional breakdowns |
|
||||
|
||||
### Filing-Level (More Control)
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| `filing.xbrl()` | Parse XBRL from filing |
|
||||
| `xbrl.statements.income_statement()` | Income statement |
|
||||
| `xbrl.facts.query()` | Query individual facts |
|
||||
|
||||
### Multi-Period
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| `XBRLS.from_filings(filings)` | Stitch multiple filings |
|
||||
| `xbrls.statements.income_statement()` | Aligned multi-period |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "No financial data found"
|
||||
```python
|
||||
filing = company.get_filings(form="10-K").latest()
|
||||
if filing.xbrl():
|
||||
print("XBRL available")
|
||||
else:
|
||||
# Older/smaller companies may not have XBRL
|
||||
text = filing.text() # fallback to raw text
|
||||
```
|
||||
|
||||
### "Statement is empty"
|
||||
Try the detailed view:
|
||||
```python
|
||||
df = income.to_dataframe(view="detailed")
|
||||
```
|
||||
|
||||
### "Numbers don't match SEC website"
|
||||
Check the reporting periods:
|
||||
```python
|
||||
xbrl = filing.xbrl()
|
||||
print(xbrl.reporting_periods)
|
||||
```
|
||||
|
||||
### Accessing financials from a 10-K filing
|
||||
```python
|
||||
# WRONG: filing.financials does not exist
|
||||
filing.financials # AttributeError!
|
||||
|
||||
# CORRECT:
|
||||
tenk = filing.obj()
|
||||
if tenk and tenk.financials:
|
||||
income = tenk.financials.income_statement
|
||||
```
|
||||
Reference in New Issue
Block a user