{-# OPTIONS_HADDOCK prune #-}
{-# LANGUAGE BangPatterns #-}
{-# LANGUAGE RecordWildCards #-}

-- |
-- Module: Numeric.Eproc.Bounded
-- Copyright: (c) 2026 Jared Tobin
-- License: MIT
-- Maintainer: Jared Tobin <jared@ppad.tech>
--
-- Two-sided bounded-mean anytime-valid test.
--
-- For samples @x_t@ in @[lo, hi]@, tests
--
--     @H_0: E[x_t | F_{t-1}] = m   for all t@
--
-- against the negation. Here @F_{t-1}@ is the filtration generated
-- by everything observed strictly before time @t@; the conditional
-- form is what anytime validity actually requires. For i.i.d.
-- samples this reduces to the usual marginal statement
-- @E[x] = m@; for adaptively-collected or otherwise non-i.i.d.
-- streams the conditional statement is the right thing to think
-- about.
--
-- 'configInterval' generalises the null from a point to an
-- interval:
--
--     @H_0: m_lo <= E[x_t | F_{t-1}] <= m_hi   for all t@
--
-- The positive-direction process is centred at @m_hi@ and the
-- negative-direction process at @m_lo@, so each side's wealth is a
-- nonnegative supermartingale under /every/ conditional mean in
-- the interval, and the convex-hedge guarantee carries over
-- unchanged. The point null is the degenerate case
-- @m_lo = m_hi@. An interval null buys tolerance: a systematic
-- effect smaller than the interval half-width accumulates no
-- evidence, which is the honest null when the measurement channel
-- itself carries a small, bounded systematic that is not the
-- effect under test.
--
-- Internally two one-sided e-processes are run in parallel: a
-- /positive-direction/ process @K^+_t@ betting against the
-- alternative @E[x_t | F_{t-1}] > m@ (using centred observations
-- @z = x - m@), and a /negative-direction/ process @K^-_t@ betting
-- against @E[x_t | F_{t-1}] < m@ (using @-z@). Each maintains its
-- own log-wealth and bettor state.
--
-- The two sides are combined via the /hedged capital process/ of
-- Waudby-Smith & Ramdas (2024) §4: their average
-- @K_t = (K^+_t + K^-_t) \/ 2@ is itself an e-process (convex
-- combinations preserve the supermartingale property), with
-- @E[K_0] = 1@. By Ville's inequality
-- @P(sup_t K_t >= 1 \/ alpha) <= alpha@, so the test rejects when
-- the supremum of @K^+_t + K^-_t@ has ever crossed @2 \/ alpha@.
--
-- This is strictly more powerful than the naive Bonferroni union
-- (reject when @max(K^+_t, K^-_t) >= 2 \/ alpha@): the convex-hedge
-- rejection region contains Bonferroni's (since
-- @K^+ + K^- >= max(K^+, K^-)@), with the same alpha guarantee.
-- For one-sided alternatives the gap is small (the losing-direction
-- bettor stays near @1@); for genuinely two-sided alternatives it
-- can be substantial.
--
-- The test is /anytime-valid/: under @H_0@ the wealth process is a
-- nonnegative supermartingale, so by Ville's inequality the
-- probability of /ever/ crossing the threshold is at most @alpha@,
-- regardless of when the user decides to stop streaming samples.
-- Rejection is /latched/ in the running state -- once a side has
-- crossed threshold, 'decide' continues to return 'Reject' even if
-- the current log-wealth has since dropped back below threshold.
--
-- == Example
--
-- Test @H_0: E[x] = 0.5@ for @x@ in @[0, 1]@ at level @alpha = 1e-3@
-- against a stream with empirical mean @0.8@:
--
-- >>> let Right cfg = config 0.5 0.0 1.0 1.0e-3 Newton
-- >>> let xs  = concat (replicate 30 [1, 1, 0, 1, 1, 0, 1, 1, 1, 1])
-- >>> decide cfg (foldl' (update cfg) (initial cfg) xs)
-- Reject

module Numeric.Eproc.Bounded (
  -- * Test configuration and state
    Config
  , State
  , Verdict(..)
  , ConfigError(..)

  -- * Bettor strategies
  , Bettor(..)

  -- * Construction
  , config
  , configInterval
  , initial

  -- * Streaming
  , update
  , decide

  -- * Inspection
  , log_wealth
  , log_wealth_sup
  , log_evalue
  , log_evalue_sup
  , p_value
  , samples
  ) where

import GHC.Float (log1p)
import Numeric.Eproc.Common (
    Bettor(..), Verdict(..), ConfigError(..)
  , BetState, init_bet, bet_lambda, step_bet
  , finite, log_sum_exp, log2_dbl
  )

-- types ----------------------------------------------------------------------

-- here, the centred observation @z_t@ referenced in
-- "Numeric.Eproc.Common" is per-direction: @x_t - m_hi@ for the
-- positive side and @x_t - m_lo@ for the negative side, with
-- @m_lo = m_hi@ under a point null ('config'). The per-direction
-- safe-bet ceilings @lambda_max@ are derived from the sample
-- bounds (see 'config' \/ 'configInterval').

-- | Bounded-mean test configuration. Build with 'config' (point
--   null) or 'configInterval' (interval null).
--
--   Carries the bettor strategy, the null-mean endpoints (equal
--   under a point null), the significance level, the precomputed
--   convex-hedge log-wealth threshold, and the per-direction
--   safe-bet ceilings (see 'config' for how the latter are derived
--   from the sample bounds).
data Config = Config {
    -- ^ bettor strategy
    Config -> Bettor
cfg_bettor      :: !Bettor
    -- ^ positive-direction safe-bet ceiling
  , Config -> Double
cfg_lam_max_pos :: {-# UNPACK #-} !Double
    -- ^ negative-direction safe-bet ceiling
  , Config -> Double
cfg_lam_max_neg :: {-# UNPACK #-} !Double
    -- ^ lower null mean @m_lo@ (negative-direction centre)
  , Config -> Double
cfg_null_lo     :: {-# UNPACK #-} !Double
    -- ^ upper null mean @m_hi@ (positive-direction centre)
  , Config -> Double
cfg_null_hi     :: {-# UNPACK #-} !Double
    -- ^ significance level @alpha@
  , Config -> Double
cfg_alpha       :: {-# UNPACK #-} !Double
    -- ^ rejection threshold @log(2 \/ alpha)@
  , Config -> Double
cfg_log_thresh  :: {-# UNPACK #-} !Double
  }

-- | Streaming test state. Construct with 'initial' and fold
--   observations through 'update'.
--
--   The two log-wealth fields track the running log-wealth of the
--   positive- and negative-direction e-processes separately; the
--   /sup log-sum/ field latches the supremum so far of
--   @log(K^+_t + K^-_t)@, which is the test statistic the
--   convex-hedge construction actually monitors. The per-direction
--   bettor states carry whatever the chosen 'Bettor' needs (running
--   sums, current bet, etc.).
data State = State {
    State -> Int
st_n           :: {-# UNPACK #-} !Int     -- ^ sample count
  , State -> Double
st_log_w_pos   :: {-# UNPACK #-} !Double  -- ^ log-wealth, pos
  , State -> Double
st_log_w_neg   :: {-# UNPACK #-} !Double  -- ^ log-wealth, neg
  , State -> Double
st_sup_log_sum :: {-# UNPACK #-} !Double  -- ^ sup log(K^+ + K^-)
  , State -> BetState
st_bet_pos     :: !BetState               -- ^ bettor state, pos
  , State -> BetState
st_bet_neg     :: !BetState               -- ^ bettor state, neg
  }

-- construction ---------------------------------------------------------------

-- | Build a 'Config' for the bounded-mean test.
--
--   Each per-direction safe-bet ceiling @lambda_max@ is set so that
--   the wealth factor stays nonnegative for every admissible
--   observation:
--
--   * The positive-direction factor is @1 + lambda_p * (x - m)@.
--     Since @x@ can dip to @lo@, @x - m@ can reach @lo - m@ (the
--     most negative value), so we need
--     @lambda_p <= 1 \/ (m - lo)@. The ceiling stored is half this
--     to leave numerical margin -- the WSR safety recommendation.
--
--   * The negative-direction factor is @1 - lambda_n * (x - m)@.
--     Since @x@ can rise to @hi@, @x - m@ can reach @hi - m@, so we
--     need @lambda_n <= 1 \/ (hi - m)@; again the ceiling is set to
--     half this.
--
--   The log-wealth rejection threshold is precomputed as
--   @log(2 \/ alpha)@; the 2 reflects that the convex-hedge test
--   monitors the sum @K^+_t + K^-_t@, whose initial value is @2@
--   (each side starts at @K = 1@).
--
--   Returns 'Left' with a 'ConfigError' on inputs that would leave
--   the mathematical regime: any of @m@, @lo@, @hi@, @alpha@
--   non-finite (NaN or infinite); @alpha@ outside @(0, 1)@;
--   @lo >= hi@; or @m@ outside the open interval @(lo, hi)@
--   (strict, to avoid the safe-bet ceilings dividing by zero).
--
--   >>> let Right cfg = config 0.5 0.0 1.0 1.0e-3 Newton
config
  :: Double  -- ^ null mean @m@
  -> Double  -- ^ sample lower bound @lo@
  -> Double  -- ^ sample upper bound @hi@
  -> Double  -- ^ significance level @alpha@
  -> Bettor  -- ^ bettor strategy
  -> Either ConfigError Config
config :: Double
-> Double
-> Double
-> Double
-> Bettor
-> Either ConfigError Config
config !Double
m !Double
lo !Double
hi !Double
alpha !Bettor
b
  | Bool -> Bool
not (Double -> Bool
finite Double
alpha Bool -> Bool -> Bool
&& Double
alpha Double -> Double -> Bool
forall a. Ord a => a -> a -> Bool
> Double
0 Bool -> Bool -> Bool
&& Double
alpha Double -> Double -> Bool
forall a. Ord a => a -> a -> Bool
< Double
1) =
      ConfigError -> Either ConfigError Config
forall a b. a -> Either a b
Left (Double -> ConfigError
InvalidAlpha Double
alpha)
  | Bool -> Bool
not (Double -> Bool
finite Double
lo Bool -> Bool -> Bool
&& Double -> Bool
finite Double
hi Bool -> Bool -> Bool
&& Double
lo Double -> Double -> Bool
forall a. Ord a => a -> a -> Bool
< Double
hi) =
      ConfigError -> Either ConfigError Config
forall a b. a -> Either a b
Left (Double -> Double -> ConfigError
InvalidBounds Double
lo Double
hi)
  | Bool -> Bool
not (Double -> Bool
finite Double
m Bool -> Bool -> Bool
&& Double
lo Double -> Double -> Bool
forall a. Ord a => a -> a -> Bool
< Double
m Bool -> Bool -> Bool
&& Double
m Double -> Double -> Bool
forall a. Ord a => a -> a -> Bool
< Double
hi) =
      ConfigError -> Either ConfigError Config
forall a b. a -> Either a b
Left (Double -> Double -> Double -> ConfigError
InvalidNullMean Double
m Double
lo Double
hi)
  | Bool
otherwise = Config -> Either ConfigError Config
forall a b. b -> Either a b
Right (Double -> Double -> Double -> Double -> Double -> Bettor -> Config
mk_config Double
m Double
m Double
lo Double
hi Double
alpha Bettor
b)
{-# INLINE config #-}

-- | Build a 'Config' for the interval-null bounded-mean test
--
--     @H_0: m_lo <= E[x_t | F_{t-1}] <= m_hi   for all t@
--
--   The positive-direction process centres its observations at
--   @m_hi@ (betting against @E[x] > m_hi@) and the
--   negative-direction process at @m_lo@ (betting against
--   @E[x] < m_lo@). Each side's wealth factor has conditional
--   expectation at most @1@ under every mean in the interval, so
--   the convex-hedge combination and its @log(2 \/ alpha)@
--   threshold apply exactly as under a point null. The safe-bet
--   ceilings generalise accordingly: @lambda_p <= 1 \/ (m_hi - lo)@
--   and @lambda_n <= 1 \/ (hi - m_lo)@, each halved for numerical
--   margin as in 'config'.
--
--   A conditional mean strictly inside the interval makes both
--   sides strict supermartingales, so the test is conservative in
--   the interior and tightest at the endpoints — where the type-I
--   guarantee is still @alpha@.
--
--   @configInterval m m@ is equivalent to @config m@; passing
--   @m_lo > m_hi@, or endpoints outside the open sample interval,
--   returns 'Left' 'InvalidNullInterval'. Other inputs are
--   validated as in 'config'.
--
--   >>> let Right cfg = configInterval 0.45 0.55 0.0 1.0 1.0e-3 Newton
configInterval
  :: Double  -- ^ lower null mean @m_lo@
  -> Double  -- ^ upper null mean @m_hi@
  -> Double  -- ^ sample lower bound @lo@
  -> Double  -- ^ sample upper bound @hi@
  -> Double  -- ^ significance level @alpha@
  -> Bettor  -- ^ bettor strategy
  -> Either ConfigError Config
configInterval :: Double
-> Double
-> Double
-> Double
-> Double
-> Bettor
-> Either ConfigError Config
configInterval !Double
mlo !Double
mhi !Double
lo !Double
hi !Double
alpha !Bettor
b
  | Bool -> Bool
not (Double -> Bool
finite Double
alpha Bool -> Bool -> Bool
&& Double
alpha Double -> Double -> Bool
forall a. Ord a => a -> a -> Bool
> Double
0 Bool -> Bool -> Bool
&& Double
alpha Double -> Double -> Bool
forall a. Ord a => a -> a -> Bool
< Double
1) =
      ConfigError -> Either ConfigError Config
forall a b. a -> Either a b
Left (Double -> ConfigError
InvalidAlpha Double
alpha)
  | Bool -> Bool
not (Double -> Bool
finite Double
lo Bool -> Bool -> Bool
&& Double -> Bool
finite Double
hi Bool -> Bool -> Bool
&& Double
lo Double -> Double -> Bool
forall a. Ord a => a -> a -> Bool
< Double
hi) =
      ConfigError -> Either ConfigError Config
forall a b. a -> Either a b
Left (Double -> Double -> ConfigError
InvalidBounds Double
lo Double
hi)
  | Bool -> Bool
not (Double -> Bool
finite Double
mlo Bool -> Bool -> Bool
&& Double -> Bool
finite Double
mhi Bool -> Bool -> Bool
&& Double
lo Double -> Double -> Bool
forall a. Ord a => a -> a -> Bool
< Double
mlo Bool -> Bool -> Bool
&& Double
mlo Double -> Double -> Bool
forall a. Ord a => a -> a -> Bool
<= Double
mhi Bool -> Bool -> Bool
&& Double
mhi Double -> Double -> Bool
forall a. Ord a => a -> a -> Bool
< Double
hi) =
      ConfigError -> Either ConfigError Config
forall a b. a -> Either a b
Left (Double -> Double -> Double -> Double -> ConfigError
InvalidNullInterval Double
mlo Double
mhi Double
lo Double
hi)
  | Bool
otherwise = Config -> Either ConfigError Config
forall a b. b -> Either a b
Right (Double -> Double -> Double -> Double -> Double -> Bettor -> Config
mk_config Double
mlo Double
mhi Double
lo Double
hi Double
alpha Bettor
b)
{-# INLINE configInterval #-}

-- shared constructor behind 'config' and 'configInterval'; assumes
-- its arguments already validated.
mk_config :: Double -> Double -> Double -> Double -> Double -> Bettor -> Config
mk_config :: Double -> Double -> Double -> Double -> Double -> Bettor -> Config
mk_config !Double
mlo !Double
mhi !Double
lo !Double
hi !Double
alpha !Bettor
b = Config {
    cfg_bettor :: Bettor
cfg_bettor      = Bettor
b
  , cfg_lam_max_pos :: Double
cfg_lam_max_pos = Double
0.5 Double -> Double -> Double
forall a. Fractional a => a -> a -> a
/ (Double
mhi Double -> Double -> Double
forall a. Num a => a -> a -> a
- Double
lo)
  , cfg_lam_max_neg :: Double
cfg_lam_max_neg = Double
0.5 Double -> Double -> Double
forall a. Fractional a => a -> a -> a
/ (Double
hi Double -> Double -> Double
forall a. Num a => a -> a -> a
- Double
mlo)
  , cfg_null_lo :: Double
cfg_null_lo     = Double
mlo
  , cfg_null_hi :: Double
cfg_null_hi     = Double
mhi
  , cfg_alpha :: Double
cfg_alpha       = Double
alpha
  , cfg_log_thresh :: Double
cfg_log_thresh  = Double -> Double
forall a. Floating a => a -> a
log (Double
2 Double -> Double -> Double
forall a. Fractional a => a -> a -> a
/ Double
alpha)
  }
{-# INLINE mk_config #-}

-- | The initial 'State' for a fresh streaming test.
--
--   Both per-direction log-wealths start at @0@ (i.e., @K = 1@);
--   the sup-log-sum starts at @log 2@ (since @K^+_0 + K^-_0 = 2@);
--   both bettors start in the per-strategy initial state
--   appropriate for the 'Bettor' chosen in the 'Config'.
--
--   >>> let s0 = initial cfg
initial :: Config -> State
initial :: Config -> State
initial Config{Double
Bettor
cfg_bettor :: Config -> Bettor
cfg_lam_max_pos :: Config -> Double
cfg_lam_max_neg :: Config -> Double
cfg_null_lo :: Config -> Double
cfg_null_hi :: Config -> Double
cfg_alpha :: Config -> Double
cfg_log_thresh :: Config -> Double
cfg_bettor :: Bettor
cfg_lam_max_pos :: Double
cfg_lam_max_neg :: Double
cfg_null_lo :: Double
cfg_null_hi :: Double
cfg_alpha :: Double
cfg_log_thresh :: Double
..} =
  let !s0 :: BetState
s0 = Bettor -> BetState
init_bet Bettor
cfg_bettor
  in  State {
        st_n :: Int
st_n           = Int
0
      , st_log_w_pos :: Double
st_log_w_pos   = Double
0
      , st_log_w_neg :: Double
st_log_w_neg   = Double
0
      , st_sup_log_sum :: Double
st_sup_log_sum = Double
log2_dbl
      , st_bet_pos :: BetState
st_bet_pos     = BetState
s0
      , st_bet_neg :: BetState
st_bet_neg     = BetState
s0
      }
{-# INLINE initial #-}

-- streaming ------------------------------------------------------------------

-- | Fold one observation into the running 'State'.
--
--   Computes the per-direction centred observations
--   @z_p = x - m_hi@ and @z_n = x - m_lo@ (identical under a point
--   null, where @m_lo = m_hi = m@), queries the two directional
--   bettors for their predictable bets, accumulates per-direction
--   log-wealth via
--
--       @log_w' = log_w + log (1 + lambda * z)@
--
--   (with the symmetric @-lambda@ for the negative direction), then
--   updates the running supremum of @log(K^+ + K^-)@ via
--   log-sum-exp and steps the bettor states given the newly
--   observed centred values.
--
--   /Precondition/: @x@ must lie in the @[lo, hi]@ interval given
--   to 'config' \/ 'configInterval'. The type-I error guarantee of
--   the test depends on this. Out-of-range observations can drive
--   the wealth factor negative, taking the construction out of the
--   supermartingale regime entirely; the function does not check
--   for this.
--
--   >>> let s1 = update cfg s0 0.7
update :: Config -> State -> Double -> State
update :: Config -> State -> Double -> State
update Config{Double
Bettor
cfg_bettor :: Config -> Bettor
cfg_lam_max_pos :: Config -> Double
cfg_lam_max_neg :: Config -> Double
cfg_null_lo :: Config -> Double
cfg_null_hi :: Config -> Double
cfg_alpha :: Config -> Double
cfg_log_thresh :: Config -> Double
cfg_bettor :: Bettor
cfg_lam_max_pos :: Double
cfg_lam_max_neg :: Double
cfg_null_lo :: Double
cfg_null_hi :: Double
cfg_alpha :: Double
cfg_log_thresh :: Double
..} State{Double
Int
BetState
st_n :: State -> Int
st_log_w_pos :: State -> Double
st_log_w_neg :: State -> Double
st_sup_log_sum :: State -> Double
st_bet_pos :: State -> BetState
st_bet_neg :: State -> BetState
st_n :: Int
st_log_w_pos :: Double
st_log_w_neg :: Double
st_sup_log_sum :: Double
st_bet_pos :: BetState
st_bet_neg :: BetState
..} !Double
x =
  let !zp :: Double
zp      = Double
x Double -> Double -> Double
forall a. Num a => a -> a -> a
- Double
cfg_null_hi
      !zn :: Double
zn      = Double
x Double -> Double -> Double
forall a. Num a => a -> a -> a
- Double
cfg_null_lo
      !lam_p :: Double
lam_p   = Bettor -> Double -> BetState -> Double
bet_lambda Bettor
cfg_bettor Double
cfg_lam_max_pos BetState
st_bet_pos
      !lam_n :: Double
lam_n   = Bettor -> Double -> BetState -> Double
bet_lambda Bettor
cfg_bettor Double
cfg_lam_max_neg BetState
st_bet_neg
      !logw_p :: Double
logw_p  = Double
st_log_w_pos Double -> Double -> Double
forall a. Num a => a -> a -> a
+ Double -> Double
forall a. Floating a => a -> a
log1p (Double
lam_p Double -> Double -> Double
forall a. Num a => a -> a -> a
* Double
zp)
      !logw_n :: Double
logw_n  = Double
st_log_w_neg Double -> Double -> Double
forall a. Num a => a -> a -> a
+ Double -> Double
forall a. Floating a => a -> a
log1p (Double -> Double
forall a. Num a => a -> a
negate Double
lam_n Double -> Double -> Double
forall a. Num a => a -> a -> a
* Double
zn)
      -- Skip 'log_sum_exp' when the cheap upper bound
      --   log_sum_exp a b <= max a b + log 2
      -- already sits at or below the running max: no update can
      -- move it. Under H_0 (calibration) this is the common case.
      !cheap_ub :: Double
cheap_ub = Double -> Double -> Double
forall a. Ord a => a -> a -> a
max Double
logw_p Double
logw_n Double -> Double -> Double
forall a. Num a => a -> a -> a
+ Double
log2_dbl
      !sup_sum :: Double
sup_sum
        | Double
cheap_ub Double -> Double -> Bool
forall a. Ord a => a -> a -> Bool
<= Double
st_sup_log_sum = Double
st_sup_log_sum
        | Bool
otherwise                  =
            Double -> Double -> Double
forall a. Ord a => a -> a -> a
max Double
st_sup_log_sum (Double -> Double -> Double
log_sum_exp Double
logw_p Double
logw_n)
      !sp :: BetState
sp      = Bettor -> Double -> BetState -> Double -> BetState
step_bet Bettor
cfg_bettor Double
cfg_lam_max_pos BetState
st_bet_pos Double
zp
      !sn :: BetState
sn      = Bettor -> Double -> BetState -> Double -> BetState
step_bet Bettor
cfg_bettor Double
cfg_lam_max_neg BetState
st_bet_neg (Double -> Double
forall a. Num a => a -> a
negate Double
zn)
  in  Int -> Double -> Double -> Double -> BetState -> BetState -> State
State (Int
st_n Int -> Int -> Int
forall a. Num a => a -> a -> a
+ Int
1) Double
logw_p Double
logw_n Double
sup_sum BetState
sp BetState
sn
{-# INLINE update #-}

-- | Compute the current 'Verdict' from the running 'State'.
--
--   'Reject' iff the supremum-so-far of @log(K^+_t + K^-_t)@ has
--   ever crossed the threshold @log(2 \/ alpha)@ — equivalently,
--   the convex-hedge e-process @(K^+ + K^-) \/ 2@ has exceeded
--   @1 \/ alpha@ at some point in the stream so far. Under @H_0@,
--   by Ville's inequality, the probability of this ever happening
--   is at most @alpha@ -- and crucially this bound holds at /every/
--   sample size simultaneously, so the user is free to peek at the
--   verdict as often as they like and stop on the first 'Reject'.
--
--   >>> decide cfg s0
--   Continue
decide :: Config -> State -> Verdict
decide :: Config -> State -> Verdict
decide Config{Double
Bettor
cfg_bettor :: Config -> Bettor
cfg_lam_max_pos :: Config -> Double
cfg_lam_max_neg :: Config -> Double
cfg_null_lo :: Config -> Double
cfg_null_hi :: Config -> Double
cfg_alpha :: Config -> Double
cfg_log_thresh :: Config -> Double
cfg_bettor :: Bettor
cfg_lam_max_pos :: Double
cfg_lam_max_neg :: Double
cfg_null_lo :: Double
cfg_null_hi :: Double
cfg_alpha :: Double
cfg_log_thresh :: Double
..} State{Double
Int
BetState
st_n :: State -> Int
st_log_w_pos :: State -> Double
st_log_w_neg :: State -> Double
st_sup_log_sum :: State -> Double
st_bet_pos :: State -> BetState
st_bet_neg :: State -> BetState
st_n :: Int
st_log_w_pos :: Double
st_log_w_neg :: Double
st_sup_log_sum :: Double
st_bet_pos :: BetState
st_bet_neg :: BetState
..}
  | Double
st_sup_log_sum Double -> Double -> Bool
forall a. Ord a => a -> a -> Bool
>= Double
cfg_log_thresh = Verdict
Reject
  | Bool
otherwise                        = Verdict
Continue
{-# INLINE decide #-}

-- inspection -----------------------------------------------------------------

-- | The current @log(K^+_t + K^-_t)@ -- the running log-wealth of
--   the convex-hedge combination at the present sample count.
--
--   Unlike 'log_wealth_sup' this is not monotone: adverse
--   observations decrease it. It is bounded above by
--   'log_wealth_sup', which is what 'decide' tests against the
--   rejection threshold.
--
--   Starts at @log 2@ (since @K^+_0 + K^-_0 = 2@).
--
--   >>> log_wealth s0
--   0.6931471805599453
log_wealth :: State -> Double
log_wealth :: State -> Double
log_wealth State{Double
Int
BetState
st_n :: State -> Int
st_log_w_pos :: State -> Double
st_log_w_neg :: State -> Double
st_sup_log_sum :: State -> Double
st_bet_pos :: State -> BetState
st_bet_neg :: State -> BetState
st_n :: Int
st_log_w_pos :: Double
st_log_w_neg :: Double
st_sup_log_sum :: Double
st_bet_pos :: BetState
st_bet_neg :: BetState
..} = Double -> Double -> Double
log_sum_exp Double
st_log_w_pos Double
st_log_w_neg
{-# INLINE log_wealth #-}

-- | The supremum-so-far of @log(K^+_t + K^-_t)@, taken across all
--   sample counts up to the current one. This is the test statistic
--   the convex-hedge construction actually monitors: it is monotone
--   nondecreasing in the sample count, and 'decide' rejects exactly
--   when it crosses @log(2 \/ alpha)@.
--
--   Starts at @log 2@ (since @K^+_0 + K^-_0 = 2@).
--
--   >>> log_wealth_sup s0
--   0.6931471805599453
log_wealth_sup :: State -> Double
log_wealth_sup :: State -> Double
log_wealth_sup State{Double
Int
BetState
st_n :: State -> Int
st_log_w_pos :: State -> Double
st_log_w_neg :: State -> Double
st_sup_log_sum :: State -> Double
st_bet_pos :: State -> BetState
st_bet_neg :: State -> BetState
st_n :: Int
st_log_w_pos :: Double
st_log_w_neg :: Double
st_sup_log_sum :: Double
st_bet_pos :: BetState
st_bet_neg :: BetState
..} = Double
st_sup_log_sum
{-# INLINE log_wealth_sup #-}

-- | The current log e-value of the convex-hedge e-process: the log
--   of @(K^+_t + K^-_t) \/ 2@, i.e. 'log_wealth' minus @log 2@.
--
--   Unlike 'log_wealth', this is normalized so that a fresh state
--   sits at @0@ (e-value @1@): it is directly comparable across
--   test modules regardless of their internal hedging, and is the
--   form to use when convex-combining several e-processes. Not
--   monotone; bounded above by 'log_evalue_sup'.
--
--   >>> log_evalue s0
--   0.0
log_evalue :: State -> Double
log_evalue :: State -> Double
log_evalue State
s = State -> Double
log_wealth State
s Double -> Double -> Double
forall a. Num a => a -> a -> a
- Double
log2_dbl
{-# INLINE log_evalue #-}

-- | The supremum-so-far of the log e-value: 'log_wealth_sup' minus
--   @log 2@. Monotone nondecreasing, starting at @0@; 'decide'
--   rejects exactly when it crosses @log(1 \/ alpha)@.
--
--   >>> log_evalue_sup s0
--   0.0
log_evalue_sup :: State -> Double
log_evalue_sup :: State -> Double
log_evalue_sup State
s = State -> Double
log_wealth_sup State
s Double -> Double -> Double
forall a. Num a => a -> a -> a
- Double
log2_dbl
{-# INLINE log_evalue_sup #-}

-- | The anytime-valid p-value: the reciprocal of the largest
--   e-value attained so far, @min 1 (exp (negate (log_evalue_sup
--   s)))@.
--
--   Monotone nonincreasing in the sample count, and valid under
--   optional stopping: under @H_0@,
--   @P(exists t: p_t <= alpha) <= alpha@ for every @alpha@
--   simultaneously. 'decide' returns 'Reject' exactly when this
--   value has reached the configured @alpha@ or below.
--
--   >>> p_value s0
--   1.0
p_value :: State -> Double
p_value :: State -> Double
p_value State
s = Double -> Double -> Double
forall a. Ord a => a -> a -> a
min Double
1 (Double -> Double
forall a. Floating a => a -> a
exp (Double -> Double
forall a. Num a => a -> a
negate (State -> Double
log_evalue_sup State
s)))
{-# INLINE p_value #-}

-- | The number of samples consumed so far.
--
--   >>> samples s0
--   0
samples :: State -> Int
samples :: State -> Int
samples = State -> Int
st_n
{-# INLINE samples #-}