Corporate Actions & Announcements
Relevant source files
The following files were used as context for generating this wiki page:
- DO NOT DELETE EDL PIPELINE/fetch_nse_corporate_actions.py
- DO NOT DELETE EDL PIPELINE/build_corporate_action_ledger.py
- DO NOT DELETE EDL PIPELINE/filing_classification.py
- DO NOT DELETE EDL PIPELINE/fetch_corporate_actions.py
- DO NOT DELETE EDL PIPELINE/filing_source_labels.json
- frontend/src/components/AnnouncementsPanel.tsx
The Corporate Actions & Announcements system manages the ingestion, classification, and presentation of official exchange events and regulatory disclosures. It integrates data from the National Stock Exchange (NSE) and ScanX to build a traceable ledger of market events, including dividends, stock splits, and corporate filings.
This module provides the necessary logic to calculate price adjustment factors for historical data and classifies regulatory announcements into specific topics using rule-based text analysis. The processed data is consumed by the scanner to mark events on charts and filter stocks based on recent corporate activities.
Sources: DO NOT DELETE EDL PIPELINE/README.md, DO NOT DELETE EDL PIPELINE/fetch_nse_corporate_actions.py:8-12
Data Ingestion Architecture
The system utilizes multiple fetchers to collect event data. The primary source for corporate actions is the official NSE API, while ScanX serves as a fallback for earnings-related events.
NSE Corporate Actions
The pipeline fetches the official NSE corporate-action ledger for equities. It identifies actions such as splits, bonuses, and dividends by parsing the event subject line against predefined regex patterns.
The ingestion process includes a proxy fallback via ScraperAPI if direct requests to the NSE API are blocked.
Sources: DO NOT DELETE EDL PIPELINE/fetch_nse_corporate_actions.py:21-36, DO NOT DELETE EDL PIPELINE/fetch_nse_corporate_actions.py:89-106
Earnings Events Fallback
fetch_corporate_actions.py retrieves quarterly result announcements from ScanX. This script specifically targets QUARTERLY RESULT ANNOUNCEMENT types to fill gaps in the primary NSE feed.
Sources: DO NOT DELETE EDL PIPELINE/fetch_corporate_actions.py:7-9
Corporate Action Ledger & Adjustments
The system builds a corporate_action_ledger.json to store traceable events. A key component of this ledger is the calculation of deterministic adjustment factors for price and shares.
Adjustment Logic
The system automatically calculates adjustment factors only when the action is deemed "deterministic." This applies to specific categories:
- Splits and Consolidations: Calculated by comparing the old and new face values parsed from the subject.
- Bonuses: Calculated using the ratio of issued shares to held shares.
| Mode | Trigger Condition | Outcome |
|---|---|---|
| deterministic | Purely Split, Bonus, or Consolidation with valid ratios. | Provides priceFactor and shareFactor. |
| manual-review | Includes Schemes, Demergers, Mergers, or Amalgamations. | Requires human intervention; factors remain null. |
| context-only | Categories that do not affect price directly (e.g., Address change). | Informational only. |
Sources: DO NOT DELETE EDL PIPELINE/fetch_nse_corporate_actions.py:53-84, DO NOT DELETE EDL PIPELINE/build_corporate_action_ledger.py:39-44
Adjustment Formula Examples
- Split (Face Value 10 to 2):
shareFactor = 10 / 2 = 5.0;priceFactor = 1 / 5.0 = 0.2. - Bonus (1:2):
shareFactor = (2 + 1) / 2 = 1.5;priceFactor = 1 / 1.5 = 0.666....
Sources: DO NOT DELETE EDL PIPELINE/fetch_nse_corporate_actions.py:59-71
Filing Classification System
The filing_classification.py module categorizes regulatory disclosures into stable IDs and groups using a rule-based engine. It processes captions and news bodies to extract evidence-based topics.
Topic Taxonomy
Disclosures are grouped into high-level categories to facilitate filtering in the frontend.
| Group | Example Stable IDs |
|---|---|
| results | financial_results, annual_report |
| business | order_win, capex, product_launch |
| strategic | acquisition, merger, joint_venture |
| capital | bonus_split, dividend, fundraise |
| legal | litigation, debt_default, insolvency |
| governance | kmp_change, auditor_change, related_party |
Sources: DO NOT DELETE EDL PIPELINE/filing_classification.py:12-73
Processing Flow
- Clause Segmentation: The engine splits filing text into individual clauses using punctuation and keyword boundaries.
- Regex Matching: Each clause is checked against regex rules mapped to topics.
- Status Identification: The system identifies the status of an event (e.g.,
proposed,approved,completed,cancelled). - Evidence Extraction: A literal, bounded window of text is retained as evidence for the match.
Frontend Presentation
The AnnouncementsPanel.tsx component displays processed filings and actions to the user. It allows filtering by year and provides detailed evidence for each classification.
- Timeline View: Displays announcements sorted by time with Indian Standard Time (IST) conversion.
- Detail View: Shows the specific "evidence" excerpt generated during the classification phase.
- Source Linking: Provides direct links to the original PDF documents or exchange filings.
Sources: frontend/src/components/AnnouncementsPanel.tsx:14-25, frontend/src/components/AnnouncementsPanel.tsx:37-43
Summary
The Corporate Actions & Announcements module ensures that the scanner uses accurate, adjusted price data and provides deep visibility into regulatory events. By automating the calculation of share factors and categorizing complex filings into searchable topics, the system allows researchers to track corporate health and significant market events with high traceability.
Sources: DO NOT DELETE EDL PIPELINE/README.md, DO NOT DELETE EDL PIPELINE/build_corporate_action_ledger.py:65-71