return_stats.hpp

Go to the documentation of this file.

#pragma once
 
#include <cstddef>
#include <cstdint>
#include <limits>
#include <optional>
#include <string_view>
#include <vector>
 
namespace pineforge::hpo {
 
inline constexpr std::string_view kReturnStatsContract = "pineforge-hpo-return-stats/v1";
 
inline constexpr std::string_view kReturnBlocksContract = "pineforge-hpo-return-blocks/v1";
 
inline constexpr double kReturnStatsRiskFreeAnnual = 0.02;
 
inline constexpr std::int64_t kReturnStatsUtcMinMs = -1099511627775000;
 
inline constexpr std::int64_t kReturnStatsUtcMaxMs = 1099511627775999;
 
inline constexpr std::size_t kReturnStatisticCount = 9;
 
inline constexpr std::size_t kReturnStatsMetricCount = 18;
 
enum class ReturnSeries : std::uint8_t {
    Bar,      
    Monthly,  
};
 
enum class ReturnStatistic : std::uint8_t {
    Count,            
    Skipped,          
    PeriodsPerYear,   
    Mean,             
    Std,              
    SharpePerPeriod,  
    Skew,             
    KurtRaw,          
    Status,           
};
 
enum class ReturnStatsStatus : std::uint8_t {
    Ok = 0,                 
    InsufficientCount = 1,  
    ZeroVariance = 2,       
    NonfiniteInput = 4,     
    PeriodUnavailable = 6,  
    UnsupportedTimezone = 7,  
    DerivedNonfinite = 8,   
};
 
enum class ReturnPeriodFailure : std::uint8_t {
    None,             
    TooFewPoints,     
    NonPositiveSpan,  
    SpanOverflow,     
    UtcRange,         
};
 
struct EquityPointsView {
    const void* records = nullptr;  
    std::size_t count = 0;          
    std::size_t stride = 0;         
    std::size_t time_offset = 0;    
    std::size_t equity_offset = 0;  
};
 
template <typename Record>
EquityPointsView make_equity_points_view(const Record* records,
                                         std::size_t count,
                                         std::int64_t Record::*time_ms,
                                         double Record::*equity) noexcept {
    EquityPointsView view;
    view.records = records;
    view.count = count;
    view.stride = sizeof(Record);
    if (records != nullptr && count != 0) {
        const auto* base = reinterpret_cast<const unsigned char*>(records);
        view.time_offset = static_cast<std::size_t>(
            reinterpret_cast<const unsigned char*>(&(records->*time_ms)) - base);
        view.equity_offset = static_cast<std::size_t>(
            reinterpret_cast<const unsigned char*>(&(records->*equity)) - base);
    }
    return view;
}
 
struct ReturnStatsRequest {
    bool bar = false;      
    bool monthly = false;  
    std::string_view chart_timezone;
};
 
struct ReturnSeriesStats {
    ReturnStatsStatus status = ReturnStatsStatus::NonfiniteInput;
    std::optional<std::int64_t> count;    
    std::optional<std::int64_t> skipped;  
    double periods_per_year = std::numeric_limits<double>::quiet_NaN();  
    double mean = std::numeric_limits<double>::quiet_NaN();               
    double std_dev = std::numeric_limits<double>::quiet_NaN();            
    double sharpe_per_period = std::numeric_limits<double>::quiet_NaN();  
    double skew = std::numeric_limits<double>::quiet_NaN();               
    double kurt_raw = std::numeric_limits<double>::quiet_NaN();           
 
    ReturnPeriodFailure period_failure = ReturnPeriodFailure::None;
    std::int64_t intervals = 0;
    std::int64_t nonfinite_returns = 0;
 
    double value(ReturnStatistic statistic) const noexcept;
 
    bool all_fields_finite() const noexcept;
 
    bool status_invariant_holds() const noexcept;
 
    void enforce_status_invariant() noexcept;
};
 
struct ReturnStatsResult {
    std::optional<ReturnSeriesStats> bar;      
    std::optional<ReturnSeriesStats> monthly;  
};
 
ReturnStatsResult compute_return_stats(const EquityPointsView& points,
                                       const ReturnStatsRequest& request) noexcept;
 
bool is_utc_chart_timezone(std::string_view chart_timezone) noexcept;
 
std::string_view return_stats_metric_name(ReturnSeries series, ReturnStatistic statistic) noexcept;
 
struct ReturnStatsMetric {
    ReturnSeries series = ReturnSeries::Bar;           
    ReturnStatistic statistic = ReturnStatistic::Count;  
};
 
std::optional<ReturnStatsMetric> parse_return_stats_metric(std::string_view name) noexcept;
 
bool return_stats_contraction_free() noexcept;
 
// ---------------------------------------------------------------------------------------------
// Return blocks (contract pineforge-hpo-return-blocks/v1)
//
// Per trial, the block object reports how many intervals every block of the bar-return series
// holds and their sum and centred second moment; the result-level object declares the layout all
// of its rows were reduced under. Only three of the statuses below are wire texts: the others are
// library outcomes that are never published as a payload status.
// ---------------------------------------------------------------------------------------------
 
enum class ReturnBlocksStatus : std::uint8_t {
    NotRequested = 0,  
    Ok = 1,            
    NonPositiveEquity = 2,
    Nonfinite = 3,
    UnusableCurve = 4,
    UnusableLayout = 5,
};
 
std::string_view return_blocks_status_text(ReturnBlocksStatus status) noexcept;
 
struct ReturnBlockLayout {
    std::uint32_t blocks = 0;    
    std::int64_t intervals = 0;  
    bool usable = false;         
    std::vector<std::int64_t> n_b;               
    std::vector<std::int64_t> boundary_time_ms;  
};
 
struct ReturnBlockMoments {
    ReturnBlocksStatus status = ReturnBlocksStatus::NotRequested;
    std::vector<std::int64_t> count;  
    std::vector<double> sum;          
    std::vector<double> m2;           
};
 
ReturnBlockLayout compute_block_layout(const EquityPointsView& points,
                                       std::uint32_t blocks);
 
ReturnBlockMoments reduce_return_blocks(const EquityPointsView& points,
                                        const ReturnBlockLayout& layout);
 
}  // namespace pineforge::hpo