nt8-sdk/src/NT8.Core/Analytics/AttributionModels.cs

using System;
using System.Collections.Generic;

namespace NT8.Core.Analytics
{
    /// <summary>
    /// Dimensions used for PnL attribution analysis.
    /// </summary>
    public enum AttributionDimension
    {
        /// <summary>
        /// Strategy-level attribution.
        /// </summary>
        Strategy,

        /// <summary>
        /// Trade grade attribution.
        /// </summary>
        Grade,

        /// <summary>
        /// Volatility and trend regime attribution.
        /// </summary>
        Regime,

        /// <summary>
        /// Time-of-day attribution.
        /// </summary>
        Time,

        /// <summary>
        /// Symbol attribution.
        /// </summary>
        Symbol,

        /// <summary>
        /// Risk mode attribution.
        /// </summary>
        RiskMode
    }

    /// <summary>
    /// PnL and performance slice for one dimension value.
    /// </summary>
    public class AttributionSlice
    {
        /// <summary>
        /// Dimension display name.
        /// </summary>
        public string DimensionName { get; set; }

        /// <summary>
        /// Value of the dimension.
        /// </summary>
        public string DimensionValue { get; set; }

        /// <summary>
        /// Total PnL in the slice.
        /// </summary>
        public double TotalPnL { get; set; }

        /// <summary>
        /// Average PnL per trade.
        /// </summary>
        public double AvgPnL { get; set; }

        /// <summary>
        /// Number of trades in slice.
        /// </summary>
        public int TradeCount { get; set; }

        /// <summary>
        /// Win rate in range [0,1].
        /// </summary>
        public double WinRate { get; set; }

        /// <summary>
        /// Profit factor ratio.
        /// </summary>
        public double ProfitFactor { get; set; }

        /// <summary>
        /// Contribution to total PnL in range [-1,+1] or more if negative totals.
        /// </summary>
        public double Contribution { get; set; }
    }

    /// <summary>
    /// Full attribution report for one dimension analysis.
    /// </summary>
    public class AttributionReport
    {
        /// <summary>
        /// Dimension used for the report.
        /// </summary>
        public AttributionDimension Dimension { get; set; }

        /// <summary>
        /// Report generation time.
        /// </summary>
        public DateTime GeneratedAtUtc { get; set; }

        /// <summary>
        /// Total trades in scope.
        /// </summary>
        public int TotalTrades { get; set; }

        /// <summary>
        /// Total PnL in scope.
        /// </summary>
        public double TotalPnL { get; set; }

        /// <summary>
        /// Attribution slices.
        /// </summary>
        public List<AttributionSlice> Slices { get; set; }

        /// <summary>
        /// Additional metadata.
        /// </summary>
        public Dictionary<string, object> Metadata { get; set; }

        /// <summary>
        /// Creates a new attribution report.
        /// </summary>
        public AttributionReport()
        {
            GeneratedAtUtc = DateTime.UtcNow;
            Slices = new List<AttributionSlice>();
            Metadata = new Dictionary<string, object>();
        }
    }

    /// <summary>
    /// Contribution analysis model for factor-level effects.
    /// </summary>
    public class ContributionAnalysis
    {
        /// <summary>
        /// Factor name.
        /// </summary>
        public string Factor { get; set; }

        /// <summary>
        /// Aggregate contribution value.
        /// </summary>
        public double ContributionValue { get; set; }

        /// <summary>
        /// Contribution percentage.
        /// </summary>
        public double ContributionPercent { get; set; }

        /// <summary>
        /// Statistical confidence in range [0,1].
        /// </summary>
        public double Confidence { get; set; }
    }

    /// <summary>
    /// Drawdown period definition.
    /// </summary>
    public class DrawdownPeriod
    {
        /// <summary>
        /// Drawdown start time.
        /// </summary>
        public DateTime StartTime { get; set; }

        /// <summary>
        /// Drawdown trough time.
        /// </summary>
        public DateTime TroughTime { get; set; }

        /// <summary>
        /// Recovery time if recovered.
        /// </summary>
        public DateTime? RecoveryTime { get; set; }

        /// <summary>
        /// Peak equity value.
        /// </summary>
        public double PeakEquity { get; set; }

        /// <summary>
        /// Trough equity value.
        /// </summary>
        public double TroughEquity { get; set; }

        /// <summary>
        /// Drawdown amount.
        /// </summary>
        public double DrawdownAmount { get; set; }

        /// <summary>
        /// Drawdown percentage.
        /// </summary>
        public double DrawdownPercent { get; set; }

        /// <summary>
        /// Duration until trough.
        /// </summary>
        public TimeSpan DurationToTrough { get; set; }

        /// <summary>
        /// Duration to recovery.
        /// </summary>
        public TimeSpan? DurationToRecovery { get; set; }
    }

    /// <summary>
    /// Drawdown attribution details.
    /// </summary>
    public class DrawdownAttribution
    {
        /// <summary>
        /// Primary cause descriptor.
        /// </summary>
        public string PrimaryCause { get; set; }

        /// <summary>
        /// Trade count involved.
        /// </summary>
        public int TradeCount { get; set; }

        /// <summary>
        /// Worst symbol contributor.
        /// </summary>
        public string WorstSymbol { get; set; }

        /// <summary>
        /// Worst strategy contributor.
        /// </summary>
        public string WorstStrategy { get; set; }

        /// <summary>
        /// Grade-level contributors.
        /// </summary>
        public Dictionary<string, double> GradeContributions { get; set; }

        /// <summary>
        /// Creates drawdown attribution model.
        /// </summary>
        public DrawdownAttribution()
        {
            GradeContributions = new Dictionary<string, double>();
        }
    }

    /// <summary>
    /// Aggregate drawdown report.
    /// </summary>
    public class DrawdownReport
    {
        /// <summary>
        /// Maximum drawdown amount.
        /// </summary>
        public double MaxDrawdownAmount { get; set; }

        /// <summary>
        /// Maximum drawdown percentage.
        /// </summary>
        public double MaxDrawdownPercent { get; set; }

        /// <summary>
        /// Current drawdown amount.
        /// </summary>
        public double CurrentDrawdownAmount { get; set; }

        /// <summary>
        /// Average drawdown percentage.
        /// </summary>
        public double AverageDrawdownPercent { get; set; }

        /// <summary>
        /// Number of drawdowns.
        /// </summary>
        public int NumberOfDrawdowns { get; set; }

        /// <summary>
        /// Longest drawdown duration.
        /// </summary>
        public TimeSpan LongestDuration { get; set; }

        /// <summary>
        /// Average recovery time.
        /// </summary>
        public TimeSpan AverageRecoveryTime { get; set; }

        /// <summary>
        /// Drawdown periods.
        /// </summary>
        public List<DrawdownPeriod> DrawdownPeriods { get; set; }

        /// <summary>
        /// Creates a drawdown report.
        /// </summary>
        public DrawdownReport()
        {
            DrawdownPeriods = new List<DrawdownPeriod>();
        }
    }
}