quantitivecalc/dist/PerformanceMetrics/calculateUnderwaterData.js

A TypeScript library providing advanced quantitative finance functions for risk analysis, performance metrics, and technical indicators. (Currently in development)

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.calculateUnderwaterData = calculateUnderwaterData;
const calculateDrawdown_1 = require("./calculateDrawdown");
const calculateTimeUnderWater_1 = require("./calculateTimeUnderWater");
/**
 * Calculates comprehensive underwater data including both drawdown and time under water.
 *
 * This convenience function combines drawdown calculation with time under water calculation
 * to provide all the necessary data for underwater analysis. It adds both the current
 * drawdown percentage and the periods under water to each data point.
 *
 * @param data - An array of objects representing the time series data.
 * @param sourceColumn - The key in each object from which to read the numeric value for calculations.
 * @param drawdownColumn - The key to store the calculated drawdown values (default: 'drawdown').
 * @param timeUnderWaterColumn - The key to store the calculated time under water values (default: 'timeUnderWater').
 * @param drawdownAsPercentage - Whether to return drawdown as percentage (default: true).
 * @returns A new array of objects with both drawdown and time under water data for underwater charting.
 *
 * @remarks
 * - Drawdown values are typically negative or zero (0 at peaks, negative during declines).
 * - Time under water values are 0 at peaks and increment for each period below the peak.
 * - This function is optimized for underwater chart visualization where both metrics are needed.
 * - If the input data is empty or undefined, an empty array is returned.
 */
function calculateUnderwaterData(data, sourceColumn, drawdownColumn = 'drawdown', timeUnderWaterColumn = 'timeUnderWater', drawdownAsPercentage = true) {
    if (!data || data.length === 0) {
        return [];
    }
    // Calculate drawdown data
    let result = (0, calculateDrawdown_1.calculateDrawdown)(data, sourceColumn, drawdownColumn, drawdownAsPercentage);
    // Add time under water data
    result = (0, calculateTimeUnderWater_1.calculateTimeUnderWater)(result, sourceColumn, timeUnderWaterColumn);
    return result;
}