aiden-shared-calculations-unified 1.0.81 → 1.0.82

package/calculations/core/price-metrics.js

@@ -0,0 +1,372 @@
+/**
+ * @fileoverview Calculation (Pass 1 - Meta) for historical price metrics.
+ *
+ * This metric answers: "What is the Volatility, Sharpe Ratio, and Max Drawdown
+ * for all instruments over 7, 30, 90, and 365-day periods?"
+ *
+ * It also aggregates these metrics as an average for each sector.
+ */
+
+const RANGES = [7, 30, 90, 365];
+const TRADING_DAYS_PER_YEAR = 252;
+const MAX_LOOKBACK_DAYS = 5; // For finding a non-holiday/weekend price
+
+class CorePriceMetrics {
+
+    // #region --- Static Metadata & Schema ---
+
+    /**
+     * Statically defines all metadata for the manifest builder.
+     */
+    static getMetadata() {
+        return {
+            type: 'meta',
+            rootDataDependencies: [], // Relies on price data, not root data
+            isHistorical: true, // Needs up to 365d of price history
+            userType: 'n/a',
+            category: 'core_metrics' // Fits with other price/metric calcs
+        };
+    }
+
+    /**
+     * This is a Pass 1 calculation and has no dependencies on other calculations.
+     */
+    static getDependencies() {
+        return [];
+    }
+
+    /**
+     * Defines the output schema for this calculation.
+     */
+    static getSchema() {
+        // This is the sub-schema for a single instrument's metrics
+        const instrumentMetricsSchema = {
+            "type": "object",
+            "properties": {
+                "stdev_7d": { "type": ["number", "null"], "description": "7-day standard deviation of daily returns" },
+                "volatility_annualized_7d": { "type": ["number", "null"], "description": "7-day annualized volatility" },
+                "sharpe_ratio_7d": { "type": ["number", "null"], "description": "7-day annualized Sharpe ratio (rf=0)" },
+                "max_drawdown_7d": { "type": ["number", "null"], "description": "7-day max peak-to-trough drawdown" },
+
+                "stdev_30d": { "type": ["number", "null"], "description": "30-day standard deviation of daily returns" },
+                "volatility_annualized_30d": { "type": ["number", "null"], "description": "30-day annualized volatility" },
+                "sharpe_ratio_30d": { "type": ["number", "null"], "description": "30-day annualized Sharpe ratio (rf=0)" },
+                "max_drawdown_30d": { "type": ["number", "null"], "description": "30-day max peak-to-trough drawdown" },
+
+                "stdev_90d": { "type": ["number", "null"], "description": "90-day standard deviation of daily returns" },
+                "volatility_annualized_90d": { "type": ["number", "null"], "description": "90-day annualized volatility" },
+                "sharpe_ratio_90d": { "type": ["number", "null"], "description": "90-day annualized Sharpe ratio (rf=0)" },
+                "max_drawdown_90d": { "type": ["number", "null"], "description": "90-day max peak-to-trough drawdown" },
+
+                "stdev_365d": { "type": ["number", "null"], "description": "365-day standard deviation of daily returns" },
+                "volatility_annualized_365d": { "type": ["number", "null"], "description": "365-day annualized volatility" },
+                "sharpe_ratio_365d": { "type": ["number", "null"], "description": "365-day annualized Sharpe ratio (rf=0)" },
+                "max_drawdown_365d": { "type": ["number", "null"], "description": "365-day max peak-to-trough drawdown" }
+            },
+            "additionalProperties": false
+        };
+
+        // This is the sub-schema for a single sector's *averages*
+        const sectorMetricsSchema = {
+            "type": "object",
+            "properties": {
+                "average_stdev_7d": { "type": ["number", "null"], "description": "Average 7-day standard deviation for the sector" },
+                "average_volatility_annualized_7d": { "type": ["number", "null"], "description": "Average 7-day annualized volatility for the sector" },
+                "average_sharpe_ratio_7d": { "type": ["number", "null"], "description": "Average 7-day annualized Sharpe ratio for the sector" },
+                "average_max_drawdown_7d": { "type": ["number", "null"], "description": "Average 7-day max drawdown for the sector" },
+
+                "average_stdev_30d": { "type": ["number", "null"], "description": "Average 30-day standard deviation for the sector" },
+                "average_volatility_annualized_30d": { "type": ["number", "null"], "description": "Average 30-day annualized volatility for the sector" },
+                "average_sharpe_ratio_30d": { "type": ["number", "null"], "description": "Average 30-day annualized Sharpe ratio for the sector" },
+                "average_max_drawdown_30d": { "type": ["number", "null"], "description": "Average 30-day max drawdown for the sector" },
+
+                "average_stdev_90d": { "type": ["number", "null"], "description": "Average 90-day standard deviation for the sector" },
+                "average_volatility_annualized_90d": { "type": ["number", "null"], "description": "Average 90-day annualized volatility for the sector" },
+                "average_sharpe_ratio_90d": { "type": ["number", "null"], "description": "Average 90-day annualized Sharpe ratio for the sector" },
+                "average_max_drawdown_90d": { "type": ["number", "null"], "description": "Average 90-day max drawdown for the sector" },
+
+                "average_stdev_365d": { "type": ["number", "null"], "description": "Average 365-day standard deviation for the sector" },
+                "average_volatility_annualized_365d": { "type": ["number", "null"], "description": "Average 365-day annualized volatility for the sector" },
+                "average_sharpe_ratio_365d": { "type": ["number", "null"], "description": "Average 365-day annualized Sharpe ratio for the sector" },
+                "average_max_drawdown_365d": { "type": ["number", "null"], "description": "Average 365-day max drawdown for the sector" }
+            },
+            "additionalProperties": false
+        };
+
+        // This is the final, top-level schema
+        return {
+            "type": "object",
+            "description": "Calculates risk/return metrics (StdDev, Sharpe, Vol, Drawdown) for instruments and sectors.",
+            "properties": {
+                "by_instrument": {
+                    "type": "object",
+                    "description": "Metrics per instrument, keyed by Ticker.",
+                    "patternProperties": { "^[A-Z\\.]+$": instrumentMetricsSchema }, // Match tickers like 'NVDA' or 'BRK.B'
+                    "additionalProperties": instrumentMetricsSchema
+                },
+                "by_sector": {
+                    "type": "object",
+                    "description": "Average metrics per sector, keyed by Sector Name.",
+                    "patternProperties": { "^[a-zA-Z0-9_ ]+$": sectorMetricsSchema }, // Match sector names
+                    "additionalProperties": sectorMetricsSchema
+                }
+            },
+            "required": ["by_instrument", "by_sector"]
+        };
+    }
+
+    // #endregion --- Static Metadata & Schema ---
+
+
+    // #region --- Main Process ---
+
+    /**
+     * This is a 'meta' calculation. It runs once.
+     * @param {string} dateStr - The date string 'YYYY-MM-DD'.
+     * @param {object} dependencies - The shared dependencies (e.g., logger, calculationUtils).
+     * @param {object} config - The computation system configuration.
+     * @returns {Promise<object>} The calculation result.
+     */
+    async process(dateStr, dependencies, config) {
+        const { logger, calculationUtils } = dependencies;
+        
+        const priceMap = await calculationUtils.loadAllPriceData();
+        const mappings = await calculationUtils.loadInstrumentMappings();
+        
+        if (!priceMap || !mappings || !mappings.instrumentToTicker || !mappings.instrumentToSector) {
+            logger.log('ERROR', '[core-price-metrics] Failed to load priceMap or mappings.');
+            return { by_instrument: {}, by_sector: {} };
+        }
+
+        const { instrumentToTicker, instrumentToSector } = mappings;
+        const by_instrument = {};
+
+        // 1. Calculate Per-Instrument Metrics
+        for (const instrumentId in priceMap) {
+            const ticker = instrumentToTicker[instrumentId];
+            if (!ticker) continue; 
+
+            const priceHistoryObj = priceMap[instrumentId];
+            const instrumentMetrics = {};
+            
+            // Null-out all metrics by default to ensure consistent schema
+            for (const range of RANGES) {
+                instrumentMetrics[`stdev_${range}d`] = null;
+                instrumentMetrics[`volatility_annualized_${range}d`] = null;
+                instrumentMetrics[`sharpe_ratio_${range}d`] = null;
+                instrumentMetrics[`max_drawdown_${range}d`] = null;
+            }
+
+            for (const range of RANGES) {
+                // Get the price slice for the range (e.g., last 30 days)
+                // We need range + 1 prices to calculate `range` number of returns
+                const priceArray = this._getHistoricalPriceArray(priceHistoryObj, dateStr, range + 1);
+
+                if (priceArray.length < 2) {
+                    continue; // Not enough data for this range
+                }
+
+                // Calculate drawdown on prices
+                instrumentMetrics[`max_drawdown_${range}d`] = this._calculateMaxDrawdown(priceArray);
+
+                // Calculate returns and return-based metrics
+                const dailyReturns = this._calculateDailyReturns(priceArray);
+                if (dailyReturns.length < 2) {
+                    continue; // Not enough returns to calculate stddev
+                }
+
+                const meanReturn = this._calculateMean(dailyReturns);
+                const stdDev = this._calculateStdDev(dailyReturns, meanReturn);
+                
+                instrumentMetrics[`stdev_${range}d`] = stdDev;
+
+                if (stdDev > 0) {
+                    instrumentMetrics[`sharpe_ratio_${range}d`] = (meanReturn / stdDev) * Math.sqrt(TRADING_DAYS_PER_YEAR);
+                    instrumentMetrics[`volatility_annualized_${range}d`] = stdDev * Math.sqrt(TRADING_DAYS_PER_YEAR);
+                } else {
+                    instrumentMetrics[`sharpe_ratio_${range}d`] = 0;
+                    instrumentMetrics[`volatility_annualized_${range}d`] = 0;
+                }
+            }
+            
+            by_instrument[ticker] = instrumentMetrics;
+        }
+
+        // 2. Calculate Sector Aggregates
+        const by_sector = this._aggregateMetricsBySector(by_instrument, instrumentToTicker, instrumentToSector);
+
+        return {
+            by_instrument,
+            by_sector,
+        };
+    }
+
+    // #endregion --- Main Process ---
+
+
+    // #region --- Aggregation Helpers ---
+
+    _aggregateMetricsBySector(by_instrument, instrumentToTicker, instrumentToSector) {
+        const sectorAggregates = {}; // { [sector]: { metrics: { [metricName]: sum }, counts: { [metricName]: count } } }
+        const tickerToInstrument = Object.fromEntries(Object.entries(instrumentToTicker).map(([id, ticker]) => [ticker, id]));
+
+        for (const ticker in by_instrument) {
+            const instrumentId = tickerToInstrument[ticker];
+            const sector = instrumentToSector[instrumentId] || "Unknown";
+            const metrics = by_instrument[ticker];
+
+            if (!sectorAggregates[sector]) {
+                sectorAggregates[sector] = { metrics: {}, counts: {} };
+            }
+
+            for (const metricName in metrics) {
+                const value = metrics[metricName];
+                // Check for valid, non-null, finite numbers
+                if (value !== null && typeof value === 'number' && isFinite(value)) {
+                    if (!sectorAggregates[sector].metrics[metricName]) {
+                        sectorAggregates[sector].metrics[metricName] = 0;
+                        sectorAggregates[sector].counts[metricName] = 0;
+                    }
+                    sectorAggregates[sector].metrics[metricName] += value;
+                    sectorAggregates[sector].counts[metricName]++;
+                }
+            }
+        }
+
+        // Finalize averages
+        const by_sector = {};
+        for (const sector in sectorAggregates) {
+            by_sector[sector] = {};
+            const agg = sectorAggregates[sector];
+            
+            // Get all unique metric names from this sector's aggregation
+            const allMetricNames = Object.keys(agg.metrics);
+
+            for (const metricName of allMetricNames) {
+                const count = agg.counts[metricName];
+                if (count > 0) {
+                    by_sector[sector][`average_${metricName}`] = agg.metrics[metricName] / count;
+                } else {
+                    by_sector[sector][`average_${metricName}`] = null; // Ensure null if no valid data
+                }
+            }
+        }
+        return by_sector;
+    }
+
+    // #endregion --- Aggregation Helpers ---
+
+
+    // #region --- Math & Price Helpers ---
+
+    /**
+     * Re-implementation of the logic from price_data_provider.js's private helper.
+     * Finds the most recent available price on or before a given date.
+     */
+    _findPriceOnOrBefore(priceHistory, dateStr) {
+        if (!priceHistory) return null;
+
+        let checkDate = new Date(dateStr + 'T00:00:00Z');
+        
+        for (let i = 0; i < MAX_LOOKBACK_DAYS; i++) {
+            const checkDateStr = checkDate.toISOString().slice(0, 10);
+            const price = priceHistory[checkDateStr];
+            
+            if (price !== undefined && price !== null && price > 0) {
+                return price; // Found it
+            }
+            // If not found, look back one more day
+            checkDate.setUTCDate(checkDate.getUTCDate() - 1);
+        }
+        return null;
+    }
+
+    /**
+* Gets a gap-filled array of prices for a historical range.
+* @param {object} priceHistoryObj - The map of { "YYYY-MM-DD": price }
+* @param {string} endDateStr - The end date of the period (e.g., today).
+* @param {number} numDays - The number of calendar days to fetch prices for.
+* @returns {number[]} A sorted array of prices, oldest to newest.
+*/
+    _getHistoricalPriceArray(priceHistoryObj, endDateStr, numDays) {
+        const prices = [];
+        let currentDate = new Date(endDateStr + 'T00:00:00Z');
+        let lastPrice = null;
+
+        for (let i = 0; i < numDays; i++) {
+            const targetDateStr = currentDate.toISOString().slice(0, 10);
+            let price = this._findPriceOnOrBefore(priceHistoryObj, targetDateStr);
+            
+            // If price is null (e.g., new instrument), try to use the last known price
+            if (price === null) {
+                price = lastPrice; 
+            } else {
+                lastPrice = price; // Update last known price
+            }
+
+            if (price !== null) {
+                prices.push(price);
+            }
+            
+            // Go back one calendar day for the next data point
+            currentDate.setUTCDate(currentDate.getUTCDate() - 1);
+        }
+        
+        // We built the array from newest to oldest, so reverse it.
+        // And filter out any initial nulls if lastPrice was null at the start
+        return prices.reverse().filter(p => p !== null);
+    }
+
+
+    _calculateMean(arr) {
+        if (!arr || arr.length === 0) return 0;
+        const sum = arr.reduce((acc, val) => acc + val, 0);
+        return sum / arr.length;
+    }
+
+    _calculateStdDev(arr, mean) {
+        if (!arr || arr.length < 2) return 0;
+        const avg = mean === undefined ? this._calculateMean(arr) : mean;
+        // Use N-1 for sample standard deviation
+        const variance = arr.reduce((acc, val) => acc + (val - avg) ** 2, 0) / (arr.length - 1);
+        return Math.sqrt(variance);
+    }
+
+    _calculateDailyReturns(prices) {
+        const returns = [];
+        for (let i = 1; i < prices.length; i++) {
+            const prevPrice = prices[i - 1];
+            const currPrice = prices[i];
+            if (prevPrice !== 0 && prevPrice !== null && currPrice !== null) {
+                returns.push((currPrice - prevPrice) / prevPrice);
+            } else {
+                returns.push(0);
+            }
+        }
+        return returns;
+    }
+
+    _calculateMaxDrawdown(prices) {
+        if (!prices || prices.length < 2) return 0;
+        let maxDrawdown = 0;
+        let peak = -Infinity;
+
+        for (const price of prices) {
+            if (price > peak) {
+                peak = price;
+            }
+            if (peak > 0) { // Only calculate drawdown if peak is positive
+                const drawdown = (price - peak) / peak;
+                if (drawdown < maxDrawdown) {
+                    maxDrawdown = drawdown;
+                }
+            }
+        }
+        // Ensure result is a finite number, default to 0
+        return isFinite(maxDrawdown) ? maxDrawdown : 0;
+    }
+
+    // #endregion --- Math & Price Helpers ---
+}
+
+module.exports = CorePriceMetrics;

package/node-graphviz/README.md

@@ -0,0 +1,123 @@
+# node-graphviz
+
+A JS + WASM module for compiling graphs written in DOT to images, using GraphViz in Node.js.
+
+No annoying native build system or native dependencies that need to be compiled.
+
+## Installation
+
+```
+npm install node-graphviz --save
+```
+
+## Usage
+
+See [The DOT Language](https://graphviz.gitlab.io/_pages/doc/info/lang.html) for more information about DOT, and [GraphViz Pocket Reference](https://graphs.grevian.org/example) for some examples.
+
+```js
+const fs = require('fs');
+const { graphviz } = require('node-graphviz');
+
+// Define a graph using DOT notation
+const graph = `
+    digraph {
+        a -> b;
+        b -> c;
+        c -> d;
+        d -> a;
+    }
+`;
+
+// Compile the graph to SVG using the `circo` layout algorithm
+graphviz.circo(graph, 'svg').then((svg) => {
+  // Write the SVG to file
+  fs.writeFileSync('graph.svg', svg);
+});
+```
+
+Running the above produces the following SVG:
+
+![SVG Image showing compiled graph](./tests/output.svg)
+
+## API
+
+The module exports the following API:
+
+```ts
+declare type Format = 'svg' | 'dot' | 'json' | 'dot_json' | 'xdot_json';
+
+declare type Engine = 'circo' | 'dot' | 'fdp' | 'neato' | 'osage' | 'patchwork' | 'twopi';
+
+export declare const graphviz = {
+    layout(dotSource: string, outputFormat?: Format, layoutEngine?: Engine): Promise<string>;
+    circo(dotSource: string, outputFormat?: Format): Promise<string>;
+    dot(dotSource: string, outputFormat?: Format): Promise<string>;
+    fdp(dotSource: string, outputFormat?: Format): Promise<string>;
+    neato(dotSource: string, outputFormat?: Format): Promise<string>;
+    osage(dotSource: string, outputFormat?: Format): Promise<string>;
+    patchwork(dotSource: string, outputFormat?: Format): Promise<string>;
+    twopi(dotSource: string, outputFormat?: Format): Promise<string>;
+};
+```
+
+### graphviz.layout(_dotSource_[, _outputFormat_][, _layoutengine_])
+
+Performs layout for the supplied `dotSource`.
+
+Where:
+
+- `outputFormat` is one of the following (see [Output Formats](https://graphviz.gitlab.io/_pages/doc/info/output.html) for details):
+  - `dot`
+  - `dot_json`
+  - `json`
+  - `svg` (default)
+  - `xdot_json`
+- `layoutEngine` is one of the following (see [Layout documentation](https://www.graphviz.org/documentation/) for details):
+  - `circo`
+  - `dot` (default)
+  - `fdp`
+  - `neato`
+  - `osage`
+  - `patchwork`
+  - `twopi`
+
+### graphviz.circo(_dotSource_[, _outputFormat_])
+
+Convenience function that performs **circo** layout, is equivalent to `layout(dotSource, outputFormat, 'circo')`.
+
+### graphviz.dot(_dotSource_[, _outputFormat_])
+
+Convenience function that performs **dot** layout, is equivalent to `layout(dotSource, outputFormat, 'dot')`.
+
+### graphviz.fdp(_dotSource_[, _outputFormat_])
+
+Convenience function that performs **circo** layout, is equivalent to `layout(dotSource, outputFormat, 'fdp')`.
+
+### graphviz.neato(_dotSource_[, _outputFormat_])
+
+Convenience function that performs **neato** layout, is equivalent to `layout(dotSource, outputFormat, 'neato')`.
+
+### graphviz.osage(_dotSource_[, _outputFormat_])
+
+Convenience function that performs **osage** layout, is equivalent to `layout(dotSource, outputFormat, 'osage')`.
+
+### graphviz.patchwork(_dotSource_[, _outputFormat_])
+
+Convenience function that performs **patchwork** layout, is equivalent to `layout(dotSource, outputFormat, 'patchwork')`.
+
+### graphviz.twopi(_dotSource_[, _outputFormat_])
+
+Convenience function that performs **twopi** layout, is equivalent to `layout(dotSource, outputFormat, 'twopi')`.
+
+## Credits
+
+This module is based on [hpcc-systems/hpcc-js-wasm](https://github.com/hpcc-systems/hpcc-js-wasm), which is designed for use in a browser, not Node.js. The following changes were made to support Node and simplify the module to include only GraphViz:
+
+- Rewrote WASM binary location and fetching to read from the filesystem
+- Added the compiled [WASM binary](https://unpkg.com/browse/@hpcc-js/wasm@0.3.14/dist/) to the source
+- Reduced the JS code by half to include only GraphViz, removed Expat and other unrelated code
+- Removed build system and TypeScript, in favor of a single source file (based on the compiled dist file from [hpcc-systems/hpcc-js-wasm](https://github.com/hpcc-systems/hpcc-js-wasm))
+
+## Licence
+
+[MIT](LICENSE)

package/node-graphviz/index.d.ts

@@ -0,0 +1,33 @@
+declare type Format = "svg" | "dot" | "json" | "dot_json" | "xdot_json";
+
+declare type Engine = "circo" | "dot" | "fdp" | "neato" | "osage" | "patchwork" | "twopi";
+
+interface Image {
+    path: string;
+    width: string;
+    height: string;
+}
+
+interface File {
+    path: string;
+    data: string;
+}
+
+interface Ext {
+    images?: Image[];
+    files?: File[];
+}
+
+export declare const graphviz: {
+    layout(dotSource: string, outputFormat?: Format, layoutEngine?: Engine, ext?: Ext | undefined): Promise<string>;
+    circo(dotSource: string, outputFormat?: Format, ext?: Ext | undefined): Promise<string>;
+    dot(dotSource: string, outputFormat?: Format, ext?: Ext | undefined): Promise<string>;
+    fdp(dotSource: string, outputFormat?: Format, ext?: Ext | undefined): Promise<string>;
+    neato(dotSource: string, outputFormat?: Format, ext?: Ext | undefined): Promise<string>;
+    osage(dotSource: string, outputFormat?: Format, ext?: Ext | undefined): Promise<string>;
+    patchwork(dotSource: string, outputFormat?: Format, ext?: Ext | undefined): Promise<string>;
+    twopi(dotSource: string, outputFormat?: Format, ext?: Ext | undefined): Promise<string>;
+};
+
+export {};
+