{-# OPTIONS_HADDOCK prune #-}

-- |
-- Module: Numeric.Eproc.Common
-- Copyright: (c) 2026 Jared Tobin
-- License: MIT
-- Maintainer: Jared Tobin <jared@ppad.tech>
--
-- Shared vocabulary for the eproc tests: the predictable bettor
-- strategies and the test verdict type. Re-exported from each test
-- module ("Numeric.Eproc.Bounded", "Numeric.Eproc.Paired",
-- "Numeric.Eproc.Bernoulli"); import this module directly only if
-- you need the types without picking a particular test.

module Numeric.Eproc.Common (
    Bettor(..)
  , Verdict(..)
  ) where

-- | A predictable bettor.
--
--   A bettor describes how, given the history of centred
--   observations @z_t@ (each test module specifies its own centring;
--   see the per-module documentation), the next predictable bet
--   @lambda_t@ is chosen. Predictability -- that is, @lambda_t@
--   depends only on data observed strictly before step @t@ -- is
--   what makes the resulting wealth process a nonnegative
--   supermartingale under @H_0@.
--
--   For 'Adaptive' and 'Newton', a safe-bet ceiling @lambda_max@
--   derived from the test's admissible-observation range is enforced
--   by clipping @lambda@ to @[0, lambda_max]@, so the wealth factor
--   stays nonnegative.
--
--   * 'Fixed' always bets the supplied constant @lambda@. The wager
--     does not respond to observed data; this strategy is useful
--     only as a baseline.
--
--   * 'Adaptive' is the aGRAPA (approximate growth-rate adaptive
--     predictable plug-in) bettor of Waudby-Smith & Ramdas (2024).
--     It tracks the empirical mean @mu@ and variance @sigma^2@ of
--     centred observations and bets the Kelly-optimal plug-in
--     @lambda* = mu \/ (sigma^2 + mu^2)@ clipped to
--     @[0, lambda_max]@. Fast to compute and competitive in
--     practice.
--
--   * 'Newton' is the online Newton step (ONS) bettor. The per-step
--     log-wealth loss @-log(1 + lambda * z)@ is convex in @lambda@;
--     ONS performs one Newton step per observation, accumulating
--     squared gradients to scale the update. Achieves logarithmic
--     regret against the best constant bet in hindsight and is in
--     practice the strongest of the three bettors under most signal
--     regimes.
data Bettor =
    Fixed {-# UNPACK #-} !Double
  | Adaptive
  | Newton
  deriving (Bettor -> Bettor -> Bool
(Bettor -> Bettor -> Bool)
-> (Bettor -> Bettor -> Bool) -> Eq Bettor
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: Bettor -> Bettor -> Bool
== :: Bettor -> Bettor -> Bool
$c/= :: Bettor -> Bettor -> Bool
/= :: Bettor -> Bettor -> Bool
Eq, Int -> Bettor -> ShowS
[Bettor] -> ShowS
Bettor -> String
(Int -> Bettor -> ShowS)
-> (Bettor -> String) -> ([Bettor] -> ShowS) -> Show Bettor
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: Int -> Bettor -> ShowS
showsPrec :: Int -> Bettor -> ShowS
$cshow :: Bettor -> String
show :: Bettor -> String
$cshowList :: [Bettor] -> ShowS
showList :: [Bettor] -> ShowS
Show)

-- | Test outcome at the current sample count.
--
--   'Reject' means the wealth process has crossed the rejection
--   threshold, so @H_0@ is rejected at level @alpha@. 'Continue'
--   means there is not yet enough evidence; collect more samples
--   (or stop and report no rejection -- the type-I error guarantee
--   holds for /any/ stopping rule).
data Verdict =
    Reject
  | Continue
  deriving (Verdict -> Verdict -> Bool
(Verdict -> Verdict -> Bool)
-> (Verdict -> Verdict -> Bool) -> Eq Verdict
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: Verdict -> Verdict -> Bool
== :: Verdict -> Verdict -> Bool
$c/= :: Verdict -> Verdict -> Bool
/= :: Verdict -> Verdict -> Bool
Eq, Int -> Verdict -> ShowS
[Verdict] -> ShowS
Verdict -> String
(Int -> Verdict -> ShowS)
-> (Verdict -> String) -> ([Verdict] -> ShowS) -> Show Verdict
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: Int -> Verdict -> ShowS
showsPrec :: Int -> Verdict -> ShowS
$cshow :: Verdict -> String
show :: Verdict -> String
$cshowList :: [Verdict] -> ShowS
showList :: [Verdict] -> ShowS
Show)