@idealic/poker-engine/STATS.md

Professional poker game engine and hand evaluator with built-in iterator utilities

This is definition of all the stats and metrics recorded by Poker Engine system.

```SQL
-- Create a view that defines the base metrics template
CREATE OR REPLACE VIEW player_metrics_definition AS
SELECT
-- This view provides the base aggregations only, no derived metrics

    -- Basic metrics
    -- Total number of aggressive actions (bets or raises)
    SUM(aggressions) as aggressions,
    -- Total number of passive actions (calls or checks)
    SUM(passivities) as passivities,
    -- Total number of decisions made (fold, call, check, bet, raise)
    SUM(decisions) as decisions,
    -- Total number of bets made
    SUM(bets) as bets,
    -- Total number of raises made
    SUM(raises) as raises,
    -- Total number of calls made
    SUM(calls) as calls,
    -- Total number of checks made
    SUM(checks) as checks,
    -- Total number of folds made
    SUM(folds) as folds,
    -- Total number of times player went all-in
    SUM(all_ins) as all_ins,
    -- Times player voluntarily put money in pot (VPIP)
    SUM(voluntary_put_money_in_pot_times) as voluntary_put_money_in_pot_times,
    -- Times player made the first aggressive action on a street
    SUM(first_aggressions) as first_aggressions,
    -- Times player made the last aggressive action on a street
    SUM(last_aggressions) as last_aggressions,

    -- Opportunities and outcomes
    -- Times player called with no prior raises pre-flop
    SUM(limps) as limps,
    -- Opportunities to limp pre-flop
    SUM(limp_opportunities) as limp_opportunities,
    -- Times a limp resulted in winning the hand
    SUM(success * limps) as limp_successes,
    -- Times player made a 3-bet (a re-raise)
    SUM(three_bets) as three_bets,
    -- Opportunities to make a 3-bet
    SUM(three_bet_opportunities) as three_bet_opportunities,
    -- Times a 3-bet resulted in winning the hand
    SUM(success * three_bets) as three_bet_successes,
    -- Times player folded to a 3-bet
    SUM(three_bet_folds) as three_bet_folds,
    -- Times player faced a 3-bet
    SUM(three_bet_challenges) as three_bet_challenges,
    -- Times player won the hand after facing a 3-bet
    SUM(success * three_bet_challenges) as three_bet_defenses,
    -- Times player made a 4-bet (a re-re-raise)
    SUM(four_bets) as four_bets,
    -- Opportunities to make a 4-bet
    SUM(four_bet_opportunities) as four_bet_opportunities,
    -- Times a 4-bet resulted in winning the hand
    SUM(success * four_bets) as four_bet_successes,
    -- Times player folded to a 4-bet
    SUM(four_bet_folds) as four_bet_folds,
    -- Times player faced a 4-bet
    SUM(four_bet_challenges) as four_bet_challenges,
    -- Times player won the hand after facing a 4-bet
    SUM(success * four_bet_challenges) as four_bet_defenses,
    -- Times player made a continuation bet
    SUM(cbet) as cbet,
    -- Opportunities to make a continuation bet
    SUM(cbet_opportunities) as cbet_opportunities,
    -- Times a continuation bet resulted in winning the hand
    SUM(success * cbet) as cbet_successes,
    -- Times player folded to a continuation bet
    SUM(cbet_folds) as cbet_folds,
    -- Times player faced a continuation bet
    SUM(cbet_challenges) as cbet_challenges,
    -- Times player won the hand after facing a continuation bet
    SUM(success * cbet_challenges) as cbet_defenses,
    -- Times player attempted to steal the blinds from a late position
    SUM(steals) as steals,
    -- Opportunities to steal the blinds
    SUM(steal_opportunities) as steal_opportunities,
    -- Times a steal attempt resulted in winning the hand
    SUM(success * steals) as steal_successes,
    -- Times player folded to a steal attempt
    SUM(steal_folds) as steal_folds,
    -- Times player faced a steal attempt
    SUM(steal_challenges) as steal_challenges,
    -- Times player won the hand after facing a steal attempt
    SUM(success * steal_challenges) as steal_defenses,
    -- Times player made a donk bet (betting out of position into the previous street's aggressor)
    SUM(donk_bets) as donk_bets,
    -- Opportunities to make a donk bet
    SUM(donk_bet_opportunities) as donk_bet_opportunities,
    -- Times a donk bet resulted in winning the hand
    SUM(success * donk_bets) as donk_bet_successes,
    -- Times player folded to a donk bet
    SUM(donk_bet_folds) as donk_bet_folds,
    -- Times player faced a donk bet
    SUM(donk_bet_challenges) as donk_bet_challenges,
    -- Times player won the hand after facing a donk bet
    SUM(success * donk_bet_challenges) as donk_bet_defenses,
    -- Times player made a check-raise
    SUM(check_raises) as check_raises,
    -- Opportunities to make a check-raise
    SUM(check_raise_opportunities) as check_raise_opportunities,
    -- Times a check-raise resulted in winning the hand
    SUM(success * check_raises) as check_raise_successes,
    -- Times player folded to a check-raise
    SUM(check_raise_folds) as check_raise_folds,
    -- Times player faced a check-raise
    SUM(check_raise_challenges) as check_raise_challenges,
    -- Times player won the hand after facing a check-raise
    SUM(success * check_raise_challenges) as check_raise_defenses,
    -- Times player folded to an all-in bet
    SUM(shove_folds) as shove_folds,
    -- Times player faced an all-in bet
    SUM(shove_challenges) as shove_challenges,
    -- Times player won the hand after facing an all-in bet
    SUM(success * shove_challenges) as shove_defenses,
    -- Times player open-shoved (went all-in as the first to bet)
    SUM(open_shoves) as open_shoves,
    -- Opportunities to open-shove
    SUM(open_shove_opportunities) as open_shove_opportunities,
    -- Times an open-shove resulted in winning the hand
    SUM(success * open_shoves) as open_shove_successes,
    -- Times player folded to an open-shove
    SUM(open_shove_folds) as open_shove_folds,
    -- Times player faced an open-shove
    SUM(open_shove_challenges) as open_shove_challenges,
    -- Times player won the hand after facing an open-shove
    SUM(success * open_shove_challenges) as open_shove_defenses,

    -- Success metrics
    -- Total number of hands won
    SUM(success) as success,
    -- Times hand went to showdown
    SUM(went_to_showdown) as went_to_showdown,
    -- Times player won the hand at showdown
    SUM(won_at_showdown) as won_at_showdown,
    -- Times player won the hand before showdown
    SUM(won_without_showdown) as won_without_showdown,

    -- Financial metrics
    -- Average big blind size for the session
    AVG(big_blind)::decimal as big_blind,
    -- Total number of hands won
    SUM(won) as won,
    -- Total number of hands lost
    SUM(lost) as lost,
    -- Currency conversion rate
    AVG(currency_rate)::decimal as currency_rate,
    -- Total amount invested in pots, in big blinds
    SUM(investments)::decimal as investments,
    -- Net profit (winnings - investments)
    SUM(profits)::decimal as profits,
    -- Overall financial balance change (winnings - losses)
    SUM(balance)::decimal as balance,
    -- Total amount won from pots, in big blinds
    SUM(winnings)::decimal as winnings,
    -- Total amount lost in pots, in big blinds
    SUM(losses)::decimal as losses,
    -- Total rake paid, in big blinds
    SUM(rake)::decimal as rake,

    -- Total time spent on decisions, in milliseconds
    SUM(decision_duration) as decision_duration,
    -- Distinct count with placeholder
    -- Total number of unique hands played
    COUNT(DISTINCT game_id) as distinct_game_count

FROM player_street_stats;

-- Create a view that defines the derived metrics based on the base metrics
-- These metics are NOT stored in database, and instead produced on demand
-- They however can be used in ranked metrics.
CREATE OR REPLACE VIEW player_derived_metrics_definition AS
SELECT
-- Frequency of limping when given the chance
(limps / COALESCE(NULLIF(limp_opportunities, 0), 1)::decimal) as limp_frequency,
-- Success rate of limps
(limp_successes / COALESCE(NULLIF(limps, 0), 1)::decimal) as limp_success_frequency,
-- Ratio of aggressive actions to passive calls
((bets + raises) / COALESCE(NULLIF(calls, 0), 1)::decimal) as aggression_factor,
-- Frequency of taking an aggressive action
((bets + raises) / COALESCE(NULLIF(bets + raises + calls + folds, 0), 1)::decimal) as aggression_frequency,
-- Frequency of making a continuation bet
(cbet / COALESCE(NULLIF(cbet_opportunities, 0), 1)::decimal) as cbet_frequency,
-- Success rate of continuation bets
(cbet_successes / COALESCE(NULLIF(cbet, 0), 1)::decimal) as cbet_success_frequency,
-- Frequency of folding to a continuation bet
(cbet_folds / COALESCE(NULLIF(cbet_challenges, 0), 1)::decimal) as cbet_fold_frequency,
-- Frequency of winning against a continuation bet
(cbet_defenses / COALESCE(NULLIF(cbet_challenges, 0), 1)::decimal) as cbet_defense_frequency,
-- Frequency of making a 3-bet
(three_bets / COALESCE(NULLIF(three_bet_opportunities, 0), 1)::decimal) as three_bet_frequency,
-- Success rate of 3-bets
(three_bet_successes / COALESCE(NULLIF(three_bets, 0), 1)::decimal) as three_bet_success_frequency,
-- Frequency of folding to a 3-bet
(three_bet_folds / COALESCE(NULLIF(three_bet_challenges, 0), 1)::decimal) as three_bet_fold_frequency,
-- Frequency of winning against a 3-bet
(three_bet_defenses / COALESCE(NULLIF(three_bet_challenges, 0), 1)::decimal) as three_bet_defense_frequency,
-- Frequency of making a 4-bet
(four_bets / COALESCE(NULLIF(four_bet_opportunities, 0), 1)::decimal) as four_bet_frequency,
-- Success rate of 4-bets
(four_bet_successes / COALESCE(NULLIF(four_bets, 0), 1)::decimal) as four_bet_success_frequency,
-- Frequency of folding to a 4-bet
(four_bet_folds / COALESCE(NULLIF(four_bet_challenges, 0), 1)::decimal) as four_bet_fold_frequency,
-- Frequency of winning against a 4-bet
(four_bet_defenses / COALESCE(NULLIF(four_bet_challenges, 0), 1)::decimal) as four_bet_defense_frequency,
-- Frequency of attempting to steal blinds
(steals / COALESCE(NULLIF(steal_opportunities, 0), 1)::decimal) as steal_frequency,
-- Success rate of steal attempts
(steal_successes / COALESCE(NULLIF(steals, 0), 1)::decimal) as steal_success_frequency,
-- Frequency of folding to a steal attempt
(steal_folds / COALESCE(NULLIF(steal_challenges, 0), 1)::decimal) as steal_fold_frequency,
-- Frequency of winning against a steal attempt
(steal_defenses / COALESCE(NULLIF(steal_challenges, 0), 1)::decimal) as steal_defense_frequency,
-- Frequency of making a donk bet
(donk_bets / COALESCE(NULLIF(donk_bet_opportunities, 0), 1)::decimal) as donk_bet_frequency,
-- Success rate of donk bets
(donk_bet_successes / COALESCE(NULLIF(donk_bets, 0), 1)::decimal) as donk_bet_success_frequency,
-- Frequency of folding to a donk bet
(donk_bet_folds / COALESCE(NULLIF(donk_bet_challenges, 0), 1)::decimal) as donk_bet_fold_frequency,
-- Frequency of winning against a donk bet
(donk_bet_defenses / COALESCE(NULLIF(donk_bet_challenges, 0), 1)::decimal) as donk_bet_defense_frequency,
-- Frequency of making a check-raise
(check_raises / COALESCE(NULLIF(check_raise_opportunities, 0), 1)::decimal) as check_raise_frequency,
-- Success rate of check-raises
(check_raise_successes / COALESCE(NULLIF(check_raises, 0), 1)::decimal) as check_raise_success_frequency,
-- Frequency of folding to a check-raise
(check_raise_folds / COALESCE(NULLIF(check_raise_challenges, 0), 1)::decimal) as check_raise_fold_frequency,
-- Frequency of winning against a check-raise
(check_raise_defenses / COALESCE(NULLIF(check_raise_challenges, 0), 1)::decimal) as check_raise_defense_frequency,
-- Frequency of making an open-shove
(open_shoves / COALESCE(NULLIF(open_shove_opportunities, 0), 1)::decimal) as open_shove_frequency,
-- Success rate of open-shoves
(open_shove_successes / COALESCE(NULLIF(open_shoves, 0), 1)::decimal) as open_shove_success_frequency,
-- Frequency of folding to an open-shove
(open_shove_folds / COALESCE(NULLIF(open_shove_challenges, 0), 1)::decimal) as open_shove_fold_frequency,
-- Frequency of winning against an open-shove
(open_shove_defenses / COALESCE(NULLIF(open_shove_challenges, 0), 1)::decimal) as open_shove_defense_frequency,
-- Frequency of hands going to showdown
(went_to_showdown / COALESCE(NULLIF(decisions, 0), 1)::decimal) as went_to_showdown_frequency,
-- Win rate at showdown
(won_at_showdown / COALESCE(NULLIF(went_to_showdown, 0), 1)::decimal) as won_at_showdown_frequency,
-- Frequency of winning without showdown
(won_without_showdown / COALESCE(NULLIF(decisions, 0), 1)::decimal) as won_without_showdown_frequency,
-- Average time per decision
(decision_duration / COALESCE(NULLIF(decisions, 0), 1)::decimal) as decision_duration_average,
-- Ratio of profit to investment
(profits / COALESCE(NULLIF(investments, 0), 1)::decimal) as profit_factor,
-- Big blinds won per 100 hands
((profits / big_blind) / COALESCE(NULLIF(distinct_game_count / 100.0, 0), 1)::decimal) as bb100,
-- Return on investment percentage
((profits \* 100) / COALESCE(NULLIF(investments, 0), 1)::decimal) as return_on_investment_factor,
-- Average winnings per hand
(winnings / COALESCE(NULLIF(distinct_game_count, 0), 1)::decimal) as winnings_average,
-- Average investment per hand
(investments / COALESCE(NULLIF(distinct_game_count, 0), 1)::decimal) as investments_average,
-- Average profit per hand
(profits / COALESCE(NULLIF(distinct_game_count, 0), 1)::decimal) as profit_average,
-- Average losses per hand
(losses / COALESCE(NULLIF(distinct_game_count, 0), 1)::decimal) as losses_average

FROM player_metrics_definition;

DROP VIEW IF EXISTS player_ranked_mexrics_definition;
CREATE OR REPLACE VIEW player_ranked_metrics_definition AS
SELECT
-- Sketch for aggression factor distribution
uddsketch(50, 0.01, aggression_factor) AS aggression_factor_digest,
-- Placeholder for a new metric distribution
uddsketch(50, 0.01, 123) AS abcdefg,
-- Sketch for bb/100 distribution
uddsketch(50, 0.01, bb100) AS bb100_digest
FROM player_derived_metrics_definition;
```