@railpath/finance-toolkit/dist/risk/calculateSemideviation.d.ts

Production-ready finance library for portfolio construction, risk analytics, quantitative metrics, and ML-based regime detection

import { SemideviationOptions } from '../schemas/SemideviationOptionsSchema';
import { SemideviationResult } from '../schemas/SemideviationResultSchema';
/**
 * Calculate Semideviation (Downside Deviation)
 *
 * Semideviation measures the volatility of returns below a specified threshold.
 * It's a key risk metric that focuses only on downside risk, ignoring positive volatility.
 *
 * Formula: σ⁻ = √(Σ(min(ri - threshold, 0)²) / n)
 * Where:
 * - ri = individual return
 * - threshold = minimum acceptable return (typically 0 or mean)
 * - n = total number of observations
 *
 * @param options - Returns, threshold, annualization factor
 * @returns Semideviation metrics including period and annualized values
 *
 * @example
 * ```typescript
 * const semideviation = calculateSemideviation({
 *   returns: [0.01, -0.02, 0.03, -0.01, -0.05, 0.02],
 *   threshold: 0, // Zero threshold
 *   annualizationFactor: 252
 * });
 *
 * console.log('Semideviation:', semideviation.semideviation);
 * console.log('Annualized:', semideviation.annualizedSemideviation);
 * console.log('Downside %:', semideviation.downsidePercentage); // 50%
 * ```
 */
export declare function calculateSemideviation(options: SemideviationOptions): SemideviationResult;