aiden-shared-calculations-unified 1.0.64 → 1.0.66

package/calculations/behavioural/historical/in_profit_asset_crowd_flow.js

@@ -1,100 +1,195 @@
-const { loadAllPriceData, getDailyPriceChange } = require('../../../utils/price_data_provider');
-const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
-
 /**
- * @fileoverview Calculates "Net Crowd Flow" for each asset, BUT
- * *only* for the cohort of users who are currently IN PROFIT
- * on their positions for that asset.
+ * @fileoverview Calculation (Pass 3) for "In Profit" cohort asset flow.
+ *
+ * This metric calculates the "Net Crowd Flow Percentage" for each asset,
+ * but *only* for the cohort of users who are currently *in profit*
+ * on that specific asset.
+ *
+ * This helps identify if winners are taking profit or adding to positions.
+ *
+ * This calculation *depends* on 'asset_pnl_status' to identify the cohort.
  */
+const { loadInstrumentMappings } = require('../../../utils/sector_mapping_provider');
+
 class InProfitAssetCrowdFlow {
     constructor() {
-        this.asset_values = {}; // Stores { day1_value_sum: 0, day2_value_sum: 0 }
-        this.user_count = 0;
-        this.priceMap = null;
+        this.assetData = new Map();
         this.mappings = null;
-        this.dates = {};
+        this.inProfitCohorts = null; // Map<ticker, Set<userId>>
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Calculates net capital flow % (price-adjusted) per asset, but only for the cohort of users currently in profit on that asset.",
+            "patternProperties": {
+                // Ticker
+                "^.*$": {
+                    "type": "object",
+                    "description": "Net flow metrics for a specific asset ticker from its 'in profit' cohort.",
+                    "properties": {
+                        "net_flow_percentage": {
+                            "type": "number",
+                            "description": "Net capital flow % from the 'in profit' cohort, adjusted for price changes."
+                        },
+                        "total_invested_today": { "type": "number" },
+                        "total_invested_yesterday": { "type": "number" },
+                        "cohort_size": { "type": "number" }
+                    },
+                    "required": ["net_flow_percentage", "total_invested_today", "total_invested_yesterday", "cohort_size"]
+                }
+            },
+            "additionalProperties": {
+                "type": "object",
+                "properties": {
+                    "net_flow_percentage": { "type": "number" },
+                    "total_invested_today": { "type": "number" },
+                    "total_invested_yesterday": { "type": "number" },
+                    "cohort_size": { "type": "number" }
+                }
+            }
+        };
+    }
+
+    /**
+     * Statically declare dependencies.
+     */
+    static getDependencies() {
+        return ['asset_pnl_status'];
+    }
+
+    _getPortfolioPositions(portfolio) {
+        return portfolio?.PublicPositions || portfolio?.AggregatedPositions;
     }
 
     _initAsset(instrumentId) {
-        if (!this.asset_values[instrumentId]) {
-            this.asset_values[instrumentId] = { day1_value_sum: 0, day2_value_sum: 0 };
+        if (!this.assetData.has(instrumentId)) {
+            this.assetData.set(instrumentId, {
+                total_invested_yesterday: 0,
+                total_invested_today: 0,
+                price_change_yesterday: 0,
+                cohort: new Set()
+            });
         }
     }
 
-    process(todayPortfolio, yesterdayPortfolio, userId, context) {
-        if (!todayPortfolio || !yesterdayPortfolio || !todayPortfolio.AggregatedPositions || !yesterdayPortfolio.AggregatedPositions) {
-            return;
+    /**
+     * Helper to get the cohort data from the dependency.
+     */
+    _getInProfitCohorts(fetchedDependencies) {
+        if (this.inProfitCohorts) {
+            return this.inProfitCohorts;
+        }
+        
+        const pnlStatusData = fetchedDependencies['asset_pnl_status'];
+        if (!pnlStatusData) {
+            return new Map();
+        }
+
+        // Re-structure the data for efficient lookup
+        // Map<ticker, Set<userId>>
+        this.inProfitCohorts = new Map();
+        for (const [ticker, data] of Object.entries(pnlStatusData)) {
+            const userSet = new Set(data.users_in_profit.map(u => u.userId));
+            this.inProfitCohorts.set(ticker, userSet);
         }
+        return this.inProfitCohorts;
+    }
 
-        if (!this.dates.today && context.todayDateStr && context.yesterdayDateStr) {
-            this.dates.today = context.todayDateStr;
-            this.dates.yesterday = context.yesterdayDateStr;
+    process(todayPortfolio, yesterdayPortfolio, userId, context, todayInsights, yesterdayInsights, fetchedDependencies) {
+        if (!todayPortfolio || !yesterdayPortfolio) {
+            return;
         }
 
-        const yesterdayPositions = new Map(yesterdayPortfolio.AggregatedPositions.map(p => [p.InstrumentID, p]));
-        const todayPositions = new Map(todayPortfolio.AggregatedPositions.map(p => [p.InstrumentID, p]));
+        if (!this.mappings) {
+            // Context contains the mappings loaded in Pass 1
+            this.mappings = context.mappings;
+        }
         
-        const allInstrumentIds = new Set([
-            ...yesterdayPositions.keys(),
-            ...todayPositions.keys()
-        ]);
+        const cohorts = this._getInProfitCohorts(fetchedDependencies);
+        if (cohorts.size === 0) {
+            return; // No dependency data
+        }
+
+        const yPos = this._getPortfolioPositions(yesterdayPortfolio);
+        const tPos = this._getPortfolioPositions(todayPortfolio);
+
+        const yPosMap = new Map(yPos?.map(p => [p.InstrumentID, p]) || []);
+        const tPosMap = new Map(tPos?.map(p => [p.InstrumentID, p]) || []);
+
+        const allInstrumentIds = new Set([...yPosMap.keys(), ...tPosMap.keys()]);
 
         for (const instrumentId of allInstrumentIds) {
-            const yPos = yesterdayPositions.get(instrumentId);
-            const tPos = todayPositions.get(instrumentId);
+            if (!instrumentId) continue;
             
-            // --- COHORT LOGIC ---
-            // Only aggregate if the user is in PROFIT on this asset.
-            // We check *today's* profit status as the primary signal.
-            const tNetProfit = tPos?.NetProfit || 0;
-            if (tNetProfit <= 0) {
-                continue; // Skip this asset for this user
-            }
-            // --- END COHORT LOGIC ---
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            const cohort = cohorts.get(ticker);
 
+            // This user is not in the "in profit" cohort for this asset, skip.
+            if (!cohort || !cohort.has(userId)) {
+                continue;
+            }
+            
+            // User *is* in the cohort, process their data
             this._initAsset(instrumentId);
-            this.asset_values[instrumentId].day1_value_sum += (yPos?.Value || 0);
-            this.asset_values[instrumentId].day2_value_sum += (tPos?.Value || 0);
+            const asset = this.assetData.get(instrumentId);
+            asset.cohort.add(userId); // Track cohort size
+
+            const yP = yPosMap.get(instrumentId);
+            const tP = tPosMap.get(instrumentId);
+
+            const yInvested = yP?.InvestedAmount || yP?.Amount || 0;
+            const tInvested = tP?.InvestedAmount || tP?.Amount || 0;
+
+            if (yInvested > 0) {
+                asset.total_invested_yesterday += yInvested;
+                const yPriceChange = (yP?.PipsRate || 0) / (yP?.OpenRate || 1);
+                asset.price_change_yesterday += yPriceChange * yInvested;
+            }
+            if (tInvested > 0) {
+                asset.total_invested_today += tInvested;
+            }
         }
-        this.user_count++; // Note: This is user_count of *all* users, which is fine for avg.
     }
 
     async getResult() {
-        if (this.user_count === 0 || !this.dates.today) return {};
-        if (!this.priceMap || !this.mappings) {
-            const [priceData, mappingData] = await Promise.all([
-                loadAllPriceData(),
-                loadInstrumentMappings()
-            ]);
-            this.priceMap = priceData;
-            this.mappings = mappingData;
+        if (!this.mappings) {
+            this.mappings = await loadInstrumentMappings();
         }
-        
-        const finalResults = {};
-        const todayStr = this.dates.today;
-        const yesterdayStr = this.dates.yesterday;
 
-        for (const instrumentId in this.asset_values) {
+        const result = {};
+
+        for (const [instrumentId, data] of this.assetData.entries()) {
             const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
-            
-            const avg_day1_value = this.asset_values[instrumentId].day1_value_sum / this.user_count;
-            const avg_day2_value = this.asset_values[instrumentId].day2_value_sum / this.user_count;
-            const priceChangePct = getDailyPriceChange(instrumentId, yesterdayStr, todayStr, this.priceMap);
 
-            if (priceChangePct === null) continue;
+            const { total_invested_yesterday, total_invested_today, price_change_yesterday, cohort } = data;
 
-            const expected_day2_value = avg_day1_value * (1 + priceChangePct);
-            const net_crowd_flow_pct = avg_day2_value - expected_day2_value;
+            if (total_invested_yesterday > 0) {
+                const avg_price_change_pct = price_change_yesterday / total_invested_yesterday;
+                const price_contribution = total_invested_yesterday * avg_price_change_pct;
+                const flow_contribution = total_invested_today - (total_invested_yesterday + price_contribution);
+                const net_flow_percentage = (flow_contribution / total_invested_yesterday) * 100;
 
-            finalResults[ticker] = {
-                net_crowd_flow_pct: net_crowd_flow_pct,
-                avg_value_day1_pct: avg_day1_value,
-                avg_value_day2_pct: avg_day2_value
-            };
+                result[ticker] = {
+                    net_flow_percentage: net_flow_percentage,
+                    total_invested_today: total_invested_today,
+                    total_invested_yesterday: total_invested_yesterday,
+                    cohort_size: cohort.size
+                };
+            }
         }
-        return finalResults;
+        return result;
     }
 
-    reset() { /*...reset all properties...*/ }
+    reset() {
+        this.assetData.clear();
+        this.mappings = null;
+        this.inProfitCohorts = null;
+    }
 }
+
 module.exports = InProfitAssetCrowdFlow;

package/calculations/behavioural/historical/paper_vs_diamond_hands.js

@@ -1,40 +1,107 @@
 /**
- * @fileoverview Calculates the "Paper Hands vs. Diamond Hands" index.
+ * @fileoverview Calculation (Pass 2) for Paper vs Diamond Hands.
+ *
+ * This metric provides a simple ratio of positions that were
+ * closed today ("paper hands") vs. positions that were held
+ * ("diamond hands").
+ *
+ * It gives a general sense of market turnover.
  */
-
 class PaperVsDiamondHands {
     constructor() {
-        this.newPositions = 0;
-        this.closedPositions = 0;
-        this.heldPositions = 0;
+        this.paper_hands = 0; // Positions closed
+        this.diamond_hands = 0; // Positions held
     }
 
-    process(todayPortfolio, yesterdayPortfolio, userId) {
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        return {
+            "type": "object",
+            "description": "Calculates the ratio of positions closed ('paper hands') vs. held ('diamond hands') from yesterday to today.",
+            "properties": {
+                "paper_hands_count": {
+                    "type": "number",
+                    "description": "Total count of positions that existed yesterday but were closed today."
+                },
+                "diamond_hands_count": {
+                    "type": "number",
+                    "description": "Total count of positions that existed yesterday and are still held today."
+                },
+                "total_positions_yesterday": {
+                    "type": "number",
+                    "description": "The sum of paper and diamond hands counts."
+                },
+                "paper_hands_ratio": {
+                    "type": "number",
+                    "description": "Ratio of paper hands to diamond hands (Paper / Diamond). Null if no diamond hands."
+                },
+                "paper_hands_pct": {
+                    "type": "number",
+                    "description": "Percentage of positions that were 'paper handed' (closed)."
+                },
+                "diamond_hands_pct": {
+                    "type": "number",
+                    "description": "Percentage of positions that were 'diamond handed' (held)."
+                }
+            },
+            "required": ["paper_hands_count", "diamond_hands_count", "total_positions_yesterday", "paper_hands_pct", "diamond_hands_pct"]
+        };
+    }
+
+    _getPortfolioPositionIds(portfolio) {
+        // We MUST use PositionID to track specific trades
+        const positions = portfolio?.AggregatedPositions || portfolio?.PublicPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return new Set();
+        }
+        return new Set(positions.map(p => p.PositionID).filter(Boolean));
+    }
+
+    process(todayPortfolio, yesterdayPortfolio) {
         if (!todayPortfolio || !yesterdayPortfolio) {
             return;
         }
 
-        const todayIds = new Set((todayPortfolio.PublicPositions || todayPortfolio.AggregatedPositions).map(p => p.PositionID || p.InstrumentID));
-        const yesterdayIds = new Set((yesterdayPortfolio.PublicPositions || yesterdayPortfolio.AggregatedPositions).map(p => p.PositionID || p.InstrumentID));
+        const yPosIds = this._getPortfolioPositionIds(yesterdayPortfolio);
+        const tPosIds = this._getPortfolioPositionIds(todayPortfolio);
 
-        const newPos = [...todayIds].filter(id => !yesterdayIds.has(id)).length;
-        const closedPos = [...yesterdayIds].filter(id => !todayIds.has(id)).length;
-        const heldPos = [...todayIds].filter(id => yesterdayIds.has(id)).length;
+        if (yPosIds.size === 0) {
+            return; // No positions yesterday to analyze
+        }
 
-        this.newPositions += newPos;
-        this.closedPositions += closedPos;
-        this.heldPositions += heldPos;
+        for (const yPosId of yPosIds) {
+            if (tPosIds.has(yPosId)) {
+                // Position was held
+                this.diamond_hands++;
+            } else {
+                // Position was closed
+                this.paper_hands++;
+            }
+        }
     }
 
     getResult() {
-        const totalPositions = this.newPositions + this.closedPositions + this.heldPositions;
-        if (totalPositions === 0) return {};
-
+        const total = this.paper_hands + this.diamond_hands;
+        
         return {
-            paper_hands_index: (this.closedPositions / totalPositions) * 100, // High turnover
-            diamond_hands_index: (this.heldPositions / totalPositions) * 100,   // Low turnover
+            paper_hands_count: this.paper_hands,
+            diamond_hands_count: this.diamond_hands,
+            total_positions_yesterday: total,
+            // Ratio of paper-to-diamond. Can be null if diamond_hands is 0.
+            paper_hands_ratio: (this.diamond_hands > 0) ? (this.paper_hands / this.diamond_hands) : null,
+            // Percentage of total positions
+            paper_hands_pct: (total > 0) ? (this.paper_hands / total) * 100 : 0,
+            diamond_hands_pct: (total > 0) ? (this.diamond_hands / total) * 100 : 0,
         };
     }
+
+    reset() {
+        this.paper_hands = 0;
+        this.diamond_hands = 0;
+    }
 }
 
 module.exports = PaperVsDiamondHands;

package/calculations/behavioural/historical/position_count_pnl.js

@@ -1,67 +1,119 @@
 /**
- * Aggregates P/L by the number of positions a user holds.
- * Used to create a dot plot.
+ * @fileoverview Calculation (Pass 2) for P&L by position count.
+ *
+ * This metric answers: "What is the average daily P&L for users,
+ * bucketed by the number of positions they hold?"
+ *
+ * This helps determine if holding more positions (diversifying)
+ * correlates with better or worse P&L.
  */
 class PositionCountPnl {
     constructor() {
-        // We will store sums and counts to calculate averages later
-        this.pnl_by_position_count = {};
-    }
-
-    _initBucket(count) {
-        if (!this.pnl_by_position_count[count]) {
-            this.pnl_by_position_count[count] = { pnl_sum: 0, count: 0 };
-        }
+        // We will store { [count_bucket]: { pnl_sum: 0, user_count: 0 } }
+        this.buckets = {
+            '1': { pnl_sum: 0, user_count: 0 },
+            '2-5': { pnl_sum: 0, user_count: 0 },
+            '6-10': { pnl_sum: 0, user_count: 0 },
+            '11-20': { pnl_sum: 0, user_count: 0 },
+            '21+': { pnl_sum: 0, user_count: 0 },
+        };
     }
 
     /**
-     * FIX: Helper function to calculate total P&L from positions
-     * @param {object} portfolio
-     * @returns {number|null}
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
      */
-    _calculateTotalPnl(portfolio) {
-        const positions = portfolio?.AggregatedPositions || portfolio?.PublicPositions;
-        if (positions && Array.isArray(positions)) {
-            // Sum all NetProfit fields, defaulting to 0 if a position has no NetProfit
-            return positions.reduce((sum, pos) => sum + (pos.NetProfit || 0), 0);
-        }
+    static getSchema() {
+        const bucketSchema = {
+            "type": "object",
+            "description": "Aggregated P&L metrics for a position count bucket.",
+            "properties": {
+                "average_daily_pnl": {
+                    "type": "number",
+                    "description": "The average daily P&L for users in this bucket."
+                },
+                "user_count": {
+                    "type": "number",
+                    "description": "The number of users in this bucket."
+                },
+                "pnl_sum": {
+                    "type": "number",
+                    "description": "The sum of all P&L for users in this bucket."
+                }
+            },
+            "required": ["average_daily_pnl", "user_count", "pnl_sum"]
+        };
+        
+        return {
+            "type": "object",
+            "description": "Average daily P&L bucketed by the number of positions a user holds.",
+            "properties": {
+                "1": bucketSchema,
+                "2-5": bucketSchema,
+                "6-10": bucketSchema,
+                "11-20": bucketSchema,
+                "21+": bucketSchema
+            },
+            "required": ["1", "2-5", "6-10", "11-20", "21+"]
+        };
+    }
+
+    _getBucket(count) {
+        if (count === 1) return '1';
+        if (count >= 2 && count <= 5) return '2-5';
+        if (count >= 6 && count <= 10) return '6-10';
+        if (count >= 11 && count <= 20) return '11-20';
+        if (count >= 21) return '21+';
         return null;
     }
 
-    process(todayPortfolio, yesterdayPortfolio, userId) {
-        // FIX: Only need todayPortfolio for this logic
+    process(todayPortfolio, yesterdayPortfolio) {
+        // This calculation only needs today's portfolio state
         if (!todayPortfolio) {
             return;
         }
 
         const positions = todayPortfolio.AggregatedPositions || todayPortfolio.PublicPositions;
+        const positionCount = Array.isArray(positions) ? positions.length : 0;
         
-        if (!positions || !Array.isArray(positions)) {
-            return; // Skip users with no positions array
-        }
-
-        const positionCount = positions.length;
         if (positionCount === 0) {
-            return; // Skip users with no positions
+            return;
         }
 
-        // FIX: Calculate dailyPnl by summing NetProfit from all positions
-        const dailyPnl = this._calculateTotalPnl(todayPortfolio);
-
-        if (dailyPnl === null) {
-            return; // Cannot calculate P&L for this user
+        const bucketKey = this._getBucket(positionCount);
+        if (!bucketKey) {
+            return;
         }
 
-        this._initBucket(positionCount);
-        this.pnl_by_position_count[positionCount].pnl_sum += dailyPnl;
-        this.pnl_by_position_count[positionCount].count++;
+        // Use the P&L from the summary, which is for the *day*
+        const dailyPnl = todayPortfolio.Summary?.NetProfit || 0;
+        
+        const bucket = this.buckets[bucketKey];
+        bucket.pnl_sum += dailyPnl;
+        bucket.user_count++;
     }
 
     getResult() {
-        // Return the aggregated object.
-        // Frontend will iterate keys, calculate avg (pnl_sum/count),
-        // and plot { x: positionCount, y: avg_pnl }
-        return this.pnl_by_position_count;
+        const result = {};
+        for (const key in this.buckets) {
+            const bucket = this.buckets[key];
+            result[key] = {
+                average_daily_pnl: (bucket.user_count > 0) ? (bucket.pnl_sum / bucket.user_count) : 0,
+                user_count: bucket.user_count,
+                pnl_sum: bucket.pnl_sum
+            };
+        }
+        return result;
+    }
+
+    reset() {
+        this.buckets = {
+            '1': { pnl_sum: 0, user_count: 0 },
+            '2-5': { pnl_sum: 0, user_count: 0 },
+            '6-10': { pnl_sum: 0, user_count: 0 },
+            '11-20': { pnl_sum: 0, user_count: 0 },
+            '21+': { pnl_sum: 0, user_count: 0 },
+        };
     }
 }