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
237
scientific-skills/edgartools/references/data-objects.md
Normal file
237
scientific-skills/edgartools/references/data-objects.md
Normal file
@@ -0,0 +1,237 @@
|
||||
# edgartools — Data Objects Reference
|
||||
|
||||
Every SEC filing can be parsed into a structured Python object:
|
||||
|
||||
```python
|
||||
obj = filing.obj() # returns TenK, EightK, ThirteenF, Form4, etc.
|
||||
```
|
||||
|
||||
## Supported Forms
|
||||
|
||||
### Annual & Quarterly Reports (10-K / 10-Q) → TenK / TenQ
|
||||
|
||||
```python
|
||||
tenk = filing.obj() # or tenq for 10-Q
|
||||
|
||||
# Financial statements
|
||||
tenk.income_statement # formatted income statement
|
||||
tenk.balance_sheet # balance sheet
|
||||
tenk.financials # Financials object with all statements
|
||||
|
||||
# Document sections
|
||||
tenk.risk_factors # full risk factors text
|
||||
tenk.business # business description
|
||||
tenk.mda # management discussion & analysis
|
||||
|
||||
# Usage via Financials
|
||||
if tenk.financials:
|
||||
income = tenk.financials.income_statement
|
||||
balance = tenk.financials.balance_sheet
|
||||
cashflow = tenk.financials.cash_flow_statement
|
||||
```
|
||||
|
||||
**Note:** Always check `tenk.financials` before accessing — not all filings have XBRL data.
|
||||
|
||||
---
|
||||
|
||||
### Current Events (8-K) → EightK
|
||||
|
||||
```python
|
||||
eightk = filing.obj()
|
||||
|
||||
eightk.items # list of reported event codes (e.g. ["2.02", "9.01"])
|
||||
eightk.press_releases # attached press releases
|
||||
|
||||
print(f"Items: {eightk.items}")
|
||||
```
|
||||
|
||||
Common 8-K item codes:
|
||||
- `1.01` — Entry into material agreement
|
||||
- `2.02` — Results of operations (earnings)
|
||||
- `5.02` — Director/officer changes
|
||||
- `8.01` — Other events
|
||||
|
||||
---
|
||||
|
||||
### Insider Trades (Form 4) → Form4 (Ownership)
|
||||
|
||||
```python
|
||||
form4 = filing.obj()
|
||||
|
||||
form4.reporting_owner # insider name
|
||||
form4.transactions # buy/sell details with prices, shares, dates
|
||||
|
||||
# Get HTML table
|
||||
html = form4.to_html()
|
||||
```
|
||||
|
||||
Also covers:
|
||||
- Form 3 — Initial ownership statement
|
||||
- Form 5 — Annual changes in beneficial ownership
|
||||
|
||||
---
|
||||
|
||||
### Beneficial Ownership (SC 13D / SC 13G) → Schedule13D / Schedule13G
|
||||
|
||||
```python
|
||||
schedule = filing.obj()
|
||||
|
||||
schedule.total_shares # aggregate beneficial ownership
|
||||
schedule.items.item4_purpose_of_transaction # activist intent (13D only)
|
||||
schedule.items.item5_interest_in_securities # ownership percentage
|
||||
```
|
||||
|
||||
- **SC 13D**: Activist investors (5%+ with intent to influence)
|
||||
- **SC 13G**: Passive holders (5%+)
|
||||
|
||||
---
|
||||
|
||||
### Institutional Portfolios (13F-HR) → ThirteenF
|
||||
|
||||
```python
|
||||
thirteenf = filing.obj()
|
||||
|
||||
thirteenf.infotable # full holdings DataFrame
|
||||
thirteenf.total_value # portfolio market value
|
||||
|
||||
# Analyze holdings
|
||||
holdings_df = thirteenf.infotable
|
||||
print(holdings_df.head())
|
||||
print(f"Total AUM: ${thirteenf.total_value/1e9:.1f}B")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Proxy & Governance (DEF 14A) → ProxyStatement
|
||||
|
||||
```python
|
||||
proxy = filing.obj()
|
||||
|
||||
proxy.executive_compensation # pay tables (5-year DataFrame)
|
||||
proxy.proposals # shareholder vote items
|
||||
proxy.peo_name # "Mr. Cook" (principal exec officer)
|
||||
proxy.peo_total_comp # CEO total compensation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Private Offerings (Form D) → FormD
|
||||
|
||||
```python
|
||||
formd = filing.obj()
|
||||
|
||||
formd.offering # offering details and amounts
|
||||
formd.recipients # related persons
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Crowdfunding Offerings (Form C) → FormC
|
||||
|
||||
```python
|
||||
formc = filing.obj()
|
||||
|
||||
formc.offering_information # target amount, deadline, securities
|
||||
formc.annual_report_disclosure # issuer financials (C-AR)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Insider Sale Notices (Form 144) → Form144
|
||||
|
||||
```python
|
||||
form144 = filing.obj()
|
||||
|
||||
form144.proposed_sale_amount # shares to be sold
|
||||
form144.securities # security details
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Fund Voting Records (N-PX) → FundReport
|
||||
|
||||
```python
|
||||
npx = filing.obj()
|
||||
|
||||
npx.votes # vote records by proposal
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ABS Distribution Reports (Form 10-D) → TenD (CMBS only)
|
||||
|
||||
```python
|
||||
ten_d = filing.obj()
|
||||
|
||||
ten_d.loans # loan-level DataFrame
|
||||
ten_d.properties # property-level DataFrame
|
||||
ten_d.asset_data.summary() # pool statistics
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Municipal Advisors (MA-I) → MunicipalAdvisorForm
|
||||
|
||||
```python
|
||||
mai = filing.obj()
|
||||
mai.advisor_name # advisor details
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Foreign Private Issuers (20-F) → TwentyF
|
||||
|
||||
```python
|
||||
twentyf = filing.obj()
|
||||
twentyf.financials # financial data for foreign issuers
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complete Form → Class Mapping
|
||||
|
||||
| Form | Class | Key Attributes |
|
||||
|------|-------|----------------|
|
||||
| 10-K | TenK | `financials`, `income_statement`, `risk_factors`, `business` |
|
||||
| 10-Q | TenQ | `financials`, `income_statement`, `balance_sheet` |
|
||||
| 8-K | EightK | `items`, `press_releases` |
|
||||
| 20-F | TwentyF | `financials` |
|
||||
| 3 | Form3 | initial ownership |
|
||||
| 4 | Form4 | `reporting_owner`, `transactions` |
|
||||
| 5 | Form5 | annual ownership changes |
|
||||
| DEF 14A | ProxyStatement | `executive_compensation`, `proposals`, `peo_name` |
|
||||
| 13F-HR | ThirteenF | `infotable`, `total_value` |
|
||||
| SC 13D | Schedule13D | `total_shares`, `items` |
|
||||
| SC 13G | Schedule13G | `total_shares` |
|
||||
| NPORT-P | NportFiling | fund portfolio |
|
||||
| 144 | Form144 | `proposed_sale_amount`, `securities` |
|
||||
| N-PX | FundReport | `votes` |
|
||||
| Form D | FormD | `offering`, `recipients` |
|
||||
| Form C | FormC | `offering_information` |
|
||||
| 10-D | TenD | `loans`, `properties`, `asset_data` |
|
||||
| MA-I | MunicipalAdvisorForm | `advisor_name` |
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
```python
|
||||
from edgar import Company
|
||||
|
||||
apple = Company("AAPL")
|
||||
filing = apple.get_latest_filing("10-K")
|
||||
tenk = filing.obj() # returns TenK with all sections and financials
|
||||
```
|
||||
|
||||
If a form type is not yet supported, `filing.obj()` raises `UnsupportedFilingTypeError`.
|
||||
|
||||
## Pattern for Unknown Form Types
|
||||
|
||||
```python
|
||||
obj = filing.obj()
|
||||
if obj is None:
|
||||
# Fallback to raw content
|
||||
text = filing.text()
|
||||
html = filing.html()
|
||||
xbrl = filing.xbrl()
|
||||
```
|
||||
Reference in New Issue
Block a user