aiden-shared-calculations-unified 1.0.35 → 1.0.37

package/README.MD

@@ -1,78 +1,78 @@
-# Unified Calculations Package (`aiden-shared-calculations-unified`)
-
-**Version:** 1.0.0
-
-## Overview
-
-This package centralizes all data calculation logic for the BullTrackers project. It provides a standardized structure for calculations run by the unified Computation System and includes shared utility functions. Calculations are dynamically loaded and categorized.
-
-## Package Structure
-
-### `/utils`
-
-Shared utility functions used by calculations or the systems consuming them.
-
-* `firestore_utils.js`: Provides a resilient `withRetry` wrapper for Firestore operations using exponential backoff.
-* `sector_mapping_provider.js`: Provides functions (`loadInstrumentMappings`, `getInstrumentSectorMap`) to fetch and cache instrument-to-ticker and instrument-to-sector mappings from Firestore.
-
-### `/calculations`
-
-Contains the core calculation logic, organized into subdirectories representing categories.
-
-* **Calculation Class Structure:** Each `.js` file defines a class responsible for a specific metric. Every class **must** implement:
-    * `constructor()`: Initializes any internal state needed for aggregation.
-    * `process(portfolioData, userId, context)` OR `process(todayPortfolio, yesterdayPortfolio, userId)`: Processes a single user's data. The signature depends on whether the calculation requires historical comparison. `context` provides shared data like mappings.
-    * `getResult()`: Returns the final, calculated result for the aggregation period. **Crucially, this method must perform any final averaging (e.g., sum/count) itself.** It should return the final value or object ready for storage, not raw components.
-    * `reset()`: (Optional but recommended) Resets the internal state, often used by the calling system between processing batches or days.
-
-* **Categories (Examples based on your files):**
-    * `/asset_metrics`: Calculations focused on individual assets (e.g., `asset_dollar_metrics`, `asset_position_size`).
-    * `/behavioural`: Calculations analyzing user trading patterns (e.g., `drawdown_response`, `gain_response`, `paper_vs_diamond_hands`, `position_count_pnl`, `smart_money_flow`).
-    * `/pnl`: Profit and Loss related calculations (e.g., `asset_pnl_status`, `average_daily_pnl_all_users`, `average_daily_pnl_per_sector`, `average_daily_pnl_per_stock`, `average_daily_position_pnl`, `pnl_distribution_per_stock`, `profitability_migration`, `profitability_ratio_per_stock`, `profitability_skew_per_stock`, `user_profitability_tracker`).
-    * `/sanity`: Basic checks and counts (e.g., `users_processed`).
-    * `/sectors`: Calculations aggregated by market sector (e.g., `diversification_pnl`, `sector_dollar_metrics`, `sector_rotation`, `total_long_per_sector`, `total_short_per_sector`).
-    * `/sentiment`: Calculations related to market sentiment (e.g., `crowd_conviction_score`).
-    * `/short_and_long_stats`: Specific counts for short and long positions (e.g., `long_position_per_stock`, `sentiment_per_stock`, `short_position_per_stock`, `total_long_figures`, `total_short_figures`).
-    * `/speculators`: Calculations **specifically** for the 'speculator' user type, often involving leverage, stop-loss, or take-profit data (e.g., `distance_to_stop_loss_per_leverage`, `distance_to_tp_per_leverage`, `entry_distance_to_sl_per_leverage`, `entry_distance_to_tp_per_leverage`, `holding_duration_per_asset`, `leverage_per_asset`, `leverage_per_sector`, `risk_appetite_change`, `risk_reward_ratio_per_asset`, `speculator_asset_sentiment`, `speculator_danger_zone`, `stop_loss_distance_by_sector_short_long_breakdown`, `stop_loss_distance_by_ticker_short_long_breakdown`, `stop_loss_per_asset`, `take_profit_per_asset`, `tsl_effectiveness`, `tsl_per_asset`).
-
-* **Output Formats:** Calculations should adhere to the standardized output formats defined in `docs/Notes/output_formats.md`.
-
-## Usage
-
-This package is intended to be consumed primarily by the unified Computation System.
-
-```javascript
-// Example usage within Computation System
-const { calculations, utils } = require('aiden-shared-calculations-unified');
-
-const CalculationClass = calculations.pnl.average_daily_pnl_per_stock;
-const calculator = new CalculationClass();
-
-// ... load data ...
-
-// In a loop for each user:
-calculator.process(portfolioData, userId, context);
-
-// After processing all users:
-const results = await calculator.getResult();
-
-// ... store results ...
-````
-
-## Contributing
-
-*(Outline the process for adding new calculations)*
-
-1.  **Determine Category:** Decide which subdirectory (`/calculations/<category>`) the new metric belongs to. Create a new category if necessary.
-2.  **Create File:** Create a new `.js` file using kebab-case (e.g., `my-new-metric.js`).
-3.  **Implement Class:** Define the calculation class, ensuring it has `constructor`, `process`, and `getResult` methods adhering to the standards. Remember `getResult` must return the *final* computed value.
-4.  **Add to Manifest:** The main `index.js` uses `require-all`, so the new calculation should be automatically included in the exports upon the next package build/publish, assuming the file naming and structure are correct.
-5.  **Publish:** Bump the package version (`npm version patch` or minor/major as appropriate) and publish (`npm publish --access public`).
-6.  **Update Consumer:** Update the version dependency in the Computation System's `package.json`.
-
-<!-- end list -->
-
-```
-
----
+# Unified Calculations Package (`aiden-shared-calculations-unified`)
+
+**Version:** 1.0.0
+
+## Overview
+
+This package centralizes all data calculation logic for the BullTrackers project. It provides a standardized structure for calculations run by the unified Computation System and includes shared utility functions. Calculations are dynamically loaded and categorized.
+
+## Package Structure
+
+### `/utils`
+
+Shared utility functions used by calculations or the systems consuming them.
+
+* `firestore_utils.js`: Provides a resilient `withRetry` wrapper for Firestore operations using exponential backoff.
+* `sector_mapping_provider.js`: Provides functions (`loadInstrumentMappings`, `getInstrumentSectorMap`) to fetch and cache instrument-to-ticker and instrument-to-sector mappings from Firestore.
+
+### `/calculations`
+
+Contains the core calculation logic, organized into subdirectories representing categories.
+
+* **Calculation Class Structure:** Each `.js` file defines a class responsible for a specific metric. Every class **must** implement:
+    * `constructor()`: Initializes any internal state needed for aggregation.
+    * `process(portfolioData, userId, context)` OR `process(todayPortfolio, yesterdayPortfolio, userId)`: Processes a single user's data. The signature depends on whether the calculation requires historical comparison. `context` provides shared data like mappings.
+    * `getResult()`: Returns the final, calculated result for the aggregation period. **Crucially, this method must perform any final averaging (e.g., sum/count) itself.** It should return the final value or object ready for storage, not raw components.
+    * `reset()`: (Optional but recommended) Resets the internal state, often used by the calling system between processing batches or days.
+
+* **Categories (Examples based on your files):**
+    * `/asset_metrics`: Calculations focused on individual assets (e.g., `asset_dollar_metrics`, `asset_position_size`).
+    * `/behavioural`: Calculations analyzing user trading patterns (e.g., `drawdown_response`, `gain_response`, `paper_vs_diamond_hands`, `position_count_pnl`, `smart_money_flow`).
+    * `/pnl`: Profit and Loss related calculations (e.g., `asset_pnl_status`, `average_daily_pnl_all_users`, `average_daily_pnl_per_sector`, `average_daily_pnl_per_stock`, `average_daily_position_pnl`, `pnl_distribution_per_stock`, `profitability_migration`, `profitability_ratio_per_stock`, `profitability_skew_per_stock`, `user_profitability_tracker`).
+    * `/sanity`: Basic checks and counts (e.g., `users_processed`).
+    * `/sectors`: Calculations aggregated by market sector (e.g., `diversification_pnl`, `sector_dollar_metrics`, `sector_rotation`, `total_long_per_sector`, `total_short_per_sector`).
+    * `/sentiment`: Calculations related to market sentiment (e.g., `crowd_conviction_score`).
+    * `/short_and_long_stats`: Specific counts for short and long positions (e.g., `long_position_per_stock`, `sentiment_per_stock`, `short_position_per_stock`, `total_long_figures`, `total_short_figures`).
+    * `/speculators`: Calculations **specifically** for the 'speculator' user type, often involving leverage, stop-loss, or take-profit data (e.g., `distance_to_stop_loss_per_leverage`, `distance_to_tp_per_leverage`, `entry_distance_to_sl_per_leverage`, `entry_distance_to_tp_per_leverage`, `holding_duration_per_asset`, `leverage_per_asset`, `leverage_per_sector`, `risk_appetite_change`, `risk_reward_ratio_per_asset`, `speculator_asset_sentiment`, `speculator_danger_zone`, `stop_loss_distance_by_sector_short_long_breakdown`, `stop_loss_distance_by_ticker_short_long_breakdown`, `stop_loss_per_asset`, `take_profit_per_asset`, `tsl_effectiveness`, `tsl_per_asset`).
+
+* **Output Formats:** Calculations should adhere to the standardized output formats defined in `docs/Notes/output_formats.md`.
+
+## Usage
+
+This package is intended to be consumed primarily by the unified Computation System.
+
+```javascript
+// Example usage within Computation System
+const { calculations, utils } = require('aiden-shared-calculations-unified');
+
+const CalculationClass = calculations.pnl.average_daily_pnl_per_stock;
+const calculator = new CalculationClass();
+
+// ... load data ...
+
+// In a loop for each user:
+calculator.process(portfolioData, userId, context);
+
+// After processing all users:
+const results = await calculator.getResult();
+
+// ... store results ...
+````
+
+## Contributing
+
+*(Outline the process for adding new calculations)*
+
+1.  **Determine Category:** Decide which subdirectory (`/calculations/<category>`) the new metric belongs to. Create a new category if necessary.
+2.  **Create File:** Create a new `.js` file using kebab-case (e.g., `my-new-metric.js`).
+3.  **Implement Class:** Define the calculation class, ensuring it has `constructor`, `process`, and `getResult` methods adhering to the standards. Remember `getResult` must return the *final* computed value.
+4.  **Add to Manifest:** The main `index.js` uses `require-all`, so the new calculation should be automatically included in the exports upon the next package build/publish, assuming the file naming and structure are correct.
+5.  **Publish:** Bump the package version (`npm version patch` or minor/major as appropriate) and publish (`npm publish --access public`).
+6.  **Update Consumer:** Update the version dependency in the Computation System's `package.json`.
+
+<!-- end list -->
+
+```
+
+---
 ```

package/calculations/activity/historical/activity_by_pnl_status.js

@@ -1,86 +1,86 @@
-/**
- * @fileoverview Analyzes *why* users were active by checking the P&L status
- * of positions just before they were closed.
- * This measures "Profit Taking" vs. "Capitulation".
- */
-class ActivityByPnlStatus {
-    constructor() {
-        this.total_positions_yesterday = {
-            in_profit: 0,
-            in_loss: 0
-        };
-        this.closed_positions_today = {
-            profit_taken: 0,
-            loss_realized: 0
-        };
-    }
-
-    _getPortfolioMap(portfolio) {
-        // We MUST use PositionID here to track specific trades, not just the asset
-        const positions = portfolio?.AggregatedPositions || portfolio?.PublicPositions;
-        if (!positions || !Array.isArray(positions)) {
-            return new Map();
-        }
-        // Map<PositionID, NetProfit>
-        return new Map(positions.map(p => [p.PositionID, p.NetProfit || 0]));
-    }
-
-    process(todayPortfolio, yesterdayPortfolio, userId) {
-        if (!todayPortfolio || !yesterdayPortfolio) {
-            return;
-        }
-
-        const yPosMap = this._getPortfolioMap(yesterdayPortfolio);
-        const tPosMap = this._getPortfolioMap(todayPortfolio);
-
-        if (yPosMap.size === 0) {
-            return; // No positions yesterday to analyze
-        }
-
-        for (const [yPosId, yNetProfit] of yPosMap.entries()) {
-            // 1. Bucket yesterday's P&L state
-            if (yNetProfit > 0) {
-                this.total_positions_yesterday.in_profit++;
-            } else if (yNetProfit < 0) {
-                this.total_positions_yesterday.in_loss++;
-            }
-
-            // 2. Check if this position was closed
-            if (!tPosMap.has(yPosId)) {
-                // Position was closed. Check its P&L from yesterday.
-                if (yNetProfit > 0) {
-                    this.closed_positions_today.profit_taken++;
-                } else if (yNetProfit < 0) {
-                    this.closed_positions_today.loss_realized++;
-                }
-            }
-        }
-    }
-
-    getResult() {
-        const { in_profit, in_loss } = this.total_positions_yesterday;
-        const { profit_taken, loss_realized } = this.closed_positions_today;
-
-        // Calculate rates to normalize the data
-        const profit_taking_rate = (in_profit > 0) ? (profit_taken / in_profit) * 100 : 0;
-        const capitulation_rate = (in_loss > 0) ? (loss_realized / in_loss) * 100 : 0;
-
-        return {
-            profit_taking_rate_pct: profit_taking_rate, // % of profitable positions that were closed
-            capitulation_rate_pct: capitulation_rate,   // % of losing positions that were closed
-            raw_counts: {
-                profit_positions_closed: profit_taken,
-                loss_positions_closed: loss_realized,
-                total_profit_positions_available: in_profit,
-                total_loss_positions_available: in_loss
-            }
-        };
-    }
-
-    reset() {
-        this.total_positions_yesterday = { in_profit: 0, in_loss: 0 };
-        this.closed_positions_today = { profit_taken: 0, loss_realized: 0 };
-    }
-}
-
+/**
+ * @fileoverview Analyzes *why* users were active by checking the P&L status
+ * of positions just before they were closed.
+ * This measures "Profit Taking" vs. "Capitulation".
+ */
+class ActivityByPnlStatus {
+    constructor() {
+        this.total_positions_yesterday = {
+            in_profit: 0,
+            in_loss: 0
+        };
+        this.closed_positions_today = {
+            profit_taken: 0,
+            loss_realized: 0
+        };
+    }
+
+    _getPortfolioMap(portfolio) {
+        // We MUST use PositionID here to track specific trades, not just the asset
+        const positions = portfolio?.AggregatedPositions || portfolio?.PublicPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return new Map();
+        }
+        // Map<PositionID, NetProfit>
+        return new Map(positions.map(p => [p.PositionID, p.NetProfit || 0]));
+    }
+
+    process(todayPortfolio, yesterdayPortfolio, userId) {
+        if (!todayPortfolio || !yesterdayPortfolio) {
+            return;
+        }
+
+        const yPosMap = this._getPortfolioMap(yesterdayPortfolio);
+        const tPosMap = this._getPortfolioMap(todayPortfolio);
+
+        if (yPosMap.size === 0) {
+            return; // No positions yesterday to analyze
+        }
+
+        for (const [yPosId, yNetProfit] of yPosMap.entries()) {
+            // 1. Bucket yesterday's P&L state
+            if (yNetProfit > 0) {
+                this.total_positions_yesterday.in_profit++;
+            } else if (yNetProfit < 0) {
+                this.total_positions_yesterday.in_loss++;
+            }
+
+            // 2. Check if this position was closed
+            if (!tPosMap.has(yPosId)) {
+                // Position was closed. Check its P&L from yesterday.
+                if (yNetProfit > 0) {
+                    this.closed_positions_today.profit_taken++;
+                } else if (yNetProfit < 0) {
+                    this.closed_positions_today.loss_realized++;
+                }
+            }
+        }
+    }
+
+    getResult() {
+        const { in_profit, in_loss } = this.total_positions_yesterday;
+        const { profit_taken, loss_realized } = this.closed_positions_today;
+
+        // Calculate rates to normalize the data
+        const profit_taking_rate = (in_profit > 0) ? (profit_taken / in_profit) * 100 : 0;
+        const capitulation_rate = (in_loss > 0) ? (loss_realized / in_loss) * 100 : 0;
+
+        return {
+            profit_taking_rate_pct: profit_taking_rate, // % of profitable positions that were closed
+            capitulation_rate_pct: capitulation_rate,   // % of losing positions that were closed
+            raw_counts: {
+                profit_positions_closed: profit_taken,
+                loss_positions_closed: loss_realized,
+                total_profit_positions_available: in_profit,
+                total_loss_positions_available: in_loss
+            }
+        };
+    }
+
+    reset() {
+        this.total_positions_yesterday = { in_profit: 0, in_loss: 0 };
+        this.closed_positions_today = { profit_taken: 0, loss_realized: 0 };
+    }
+}
+
 module.exports = ActivityByPnlStatus;

package/calculations/activity/historical/daily_asset_activity.js

@@ -1,86 +1,86 @@
-/**
- * @fileoverview Tracks the flow of unique users opening or closing positions
- * on a per-asset basis. This measures the "focus" of the crowd's activity.
- */
-const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
-
-class DailyAssetActivity {
-    constructor() {
-        // We will store { [instrumentId]: { new_users: Set(), closed_users: Set() } }
-        this.assetActivity = new Map();
-        this.mappings = null;
-    }
-
-    _initAsset(instrumentId) {
-        if (!this.assetActivity.has(instrumentId)) {
-            this.assetActivity.set(instrumentId, {
-                new_users: new Set(),
-                closed_users: new Set()
-            });
-        }
-    }
-
-    _getInstrumentIds(portfolio) {
-        const positions = portfolio?.AggregatedPositions || portfolio?.PublicPositions;
-        if (!positions || !Array.isArray(positions)) {
-            return new Set();
-        }
-        return new Set(positions.map(p => p.InstrumentID).filter(Boolean));
-    }
-
-    process(todayPortfolio, yesterdayPortfolio, userId) {
-        if (!todayPortfolio || !yesterdayPortfolio) {
-            return;
-        }
-
-        const yIds = this._getInstrumentIds(yesterdayPortfolio);
-        const tIds = this._getInstrumentIds(todayPortfolio);
-
-        // Find new positions (in today but not yesterday)
-        for (const tId of tIds) {
-            if (!yIds.has(tId)) {
-                this._initAsset(tId);
-                this.assetActivity.get(tId).new_users.add(userId);
-            }
-        }
-
-        // Find closed positions (in yesterday but not today)
-        for (const yId of yIds) {
-            if (!tIds.has(yId)) {
-                this._initAsset(yId);
-                this.assetActivity.get(yId).closed_users.add(userId);
-            }
-        }
-    }
-
-    async getResult() {
-        if (!this.mappings) {
-            this.mappings = await loadInstrumentMappings();
-        }
-
-        const result = {};
-        for (const [instrumentId, data] of this.assetActivity.entries()) {
-            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
-            
-            const openCount = data.new_users.size;
-            const closeCount = data.closed_users.size;
-            
-            if (openCount > 0 || closeCount > 0) {
-                result[ticker] = {
-                    opened_by_user_count: openCount,
-                    closed_by_user_count: closeCount,
-                    // "Net User Flow" - positive means more users joined than left
-                    net_user_flow: openCount - closeCount 
-                };
-            }
-        }
-        return result;
-    }
-
-    reset() {
-        this.assetActivity.clear();
-        this.mappings = null;
-    }
-}
-
+/**
+ * @fileoverview Tracks the flow of unique users opening or closing positions
+ * on a per-asset basis. This measures the "focus" of the crowd's activity.
+ */
+const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
+
+class DailyAssetActivity {
+    constructor() {
+        // We will store { [instrumentId]: { new_users: Set(), closed_users: Set() } }
+        this.assetActivity = new Map();
+        this.mappings = null;
+    }
+
+    _initAsset(instrumentId) {
+        if (!this.assetActivity.has(instrumentId)) {
+            this.assetActivity.set(instrumentId, {
+                new_users: new Set(),
+                closed_users: new Set()
+            });
+        }
+    }
+
+    _getInstrumentIds(portfolio) {
+        const positions = portfolio?.AggregatedPositions || portfolio?.PublicPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return new Set();
+        }
+        return new Set(positions.map(p => p.InstrumentID).filter(Boolean));
+    }
+
+    process(todayPortfolio, yesterdayPortfolio, userId) {
+        if (!todayPortfolio || !yesterdayPortfolio) {
+            return;
+        }
+
+        const yIds = this._getInstrumentIds(yesterdayPortfolio);
+        const tIds = this._getInstrumentIds(todayPortfolio);
+
+        // Find new positions (in today but not yesterday)
+        for (const tId of tIds) {
+            if (!yIds.has(tId)) {
+                this._initAsset(tId);
+                this.assetActivity.get(tId).new_users.add(userId);
+            }
+        }
+
+        // Find closed positions (in yesterday but not today)
+        for (const yId of yIds) {
+            if (!tIds.has(yId)) {
+                this._initAsset(yId);
+                this.assetActivity.get(yId).closed_users.add(userId);
+            }
+        }
+    }
+
+    async getResult() {
+        if (!this.mappings) {
+            this.mappings = await loadInstrumentMappings();
+        }
+
+        const result = {};
+        for (const [instrumentId, data] of this.assetActivity.entries()) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            
+            const openCount = data.new_users.size;
+            const closeCount = data.closed_users.size;
+            
+            if (openCount > 0 || closeCount > 0) {
+                result[ticker] = {
+                    opened_by_user_count: openCount,
+                    closed_by_user_count: closeCount,
+                    // "Net User Flow" - positive means more users joined than left
+                    net_user_flow: openCount - closeCount 
+                };
+            }
+        }
+        return result;
+    }
+
+    reset() {
+        this.assetActivity.clear();
+        this.mappings = null;
+    }
+}
+
 module.exports = DailyAssetActivity;