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

-- |
-- Module: Numeric.Eproc.Merge
-- Copyright: (c) 2026 Jared Tobin
-- License: MIT
-- Maintainer: Jared Tobin <jared@ppad.tech>
--
-- Merging e-values, and choosing among the hypotheses they test.
--
-- An e-value for a null @H_0@ is a nonnegative statistic @E@ with
-- @E[E] <= 1@ under @H_0@. Two ways of merging them keep that
-- property:
--
--   * The mean of any e-values for one null is an e-value for it,
--     however they depend on one another ('log_mean'): the merge a
--     test over several observables makes, paying a factor of their
--     number.
--
--   * The product of e-values each valid given those before it (for
--     instance, computed on independent data) is an e-value
--     ('log_product'): the merge of a test continued on fresh data.
--
-- An e-process evaluated at a stopping time is an e-value, so both
-- apply to e-processes stopped when the caller likes.
--
-- Given e-values for several nulls, one each, 'ebh' chooses which to
-- reject: the e-BH procedure of Wang & Ramdas (2022), whose false
-- discovery rate is at most its level under any dependence between
-- the e-values.
--
-- Every function here takes and returns e-values as their natural
-- logarithms, as the test modules' @log_evalue@ accessors report
-- them.

module Numeric.Eproc.Merge (
    log_mean
  , log_product
  , ebh
  ) where

import qualified Data.List as L
import Data.Ord (Down(..), comparing)

import Numeric.Eproc.Common (log_sum_exps)

-- | The log of the mean of e-values given as logs: an e-value for
--   the null they share, whatever their dependence. The mean of no
--   e-values is taken to be one.
--
--   >>> round (exp (log_mean [log 2, log 4]) * 1000)
--   3000
--   >>> log_mean []
--   0.0
--   >>> log_mean [1 / 0, 0]
--   Infinity
log_mean :: [Double] -> Double
log_mean :: [Double] -> Double
log_mean [Double]
les = case [Double]
les of
  [] -> Double
0
  [Double]
_ -> [Double] -> Double
log_sum_exps [Double]
les Double -> Double -> Double
forall a. Num a => a -> a -> a
- Double -> Double
forall a. Floating a => a -> a
log (Int -> Double
forall a b. (Integral a, Num b) => a -> b
fromIntegral ([Double] -> Int
forall a. [a] -> Int
forall (t :: * -> *) a. Foldable t => t a -> Int
length [Double]
les))
{-# INLINE log_mean #-}

-- | The log of the product of e-values given as logs: an e-value
--   where each is valid given those before it.
--
--   >>> log_product [log 2, log 3] == log 6
--   True
log_product :: [Double] -> Double
log_product :: [Double] -> Double
log_product = (Double -> Double -> Double) -> Double -> [Double] -> Double
forall b a. (b -> a -> b) -> b -> [a] -> b
forall (t :: * -> *) b a.
Foldable t =>
(b -> a -> b) -> b -> t a -> b
L.foldl' Double -> Double -> Double
forall a. Num a => a -> a -> a
(+) Double
0
{-# INLINE log_product #-}

-- | The e-BH discoveries at a level among e-values, one per null,
--   given as logs: the indices of the @k@ largest, for the largest
--   @k@ whose @k@-th largest e-value is at least @n \/ (alpha k)@, for
--   @n@ of them, in decreasing order of e-value. The expected share
--   of discoveries whose null holds is at most @alpha@, under any
--   dependence between the e-values.
--
--   >>> ebh 0.1 [log 100, 0, log 14]
--   [0]
--   >>> ebh 0.1 [log 100, 0, log 15]
--   [0,2]
ebh :: Double -> [Double] -> [Int]
ebh :: Double -> [Double] -> [Int]
ebh !Double
alpha [Double]
les = Int -> [Int] -> [Int]
forall a. Int -> [a] -> [a]
take Int
k [Int]
ranked
  where
    !n :: Double
n = Int -> Double
forall a b. (Integral a, Num b) => a -> b
fromIntegral ([Double] -> Int
forall a. [a] -> Int
forall (t :: * -> *) a. Foldable t => t a -> Int
length [Double]
les) :: Double
    ranked :: [Int]
ranked = ((Int, Double) -> Int) -> [(Int, Double)] -> [Int]
forall a b. (a -> b) -> [a] -> [b]
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap (Int, Double) -> Int
forall a b. (a, b) -> a
fst (((Int, Double) -> (Int, Double) -> Ordering)
-> [(Int, Double)] -> [(Int, Double)]
forall a. (a -> a -> Ordering) -> [a] -> [a]
L.sortBy (((Int, Double) -> Down Double)
-> (Int, Double) -> (Int, Double) -> Ordering
forall a b. Ord a => (b -> a) -> b -> b -> Ordering
comparing (Double -> Down Double
forall a. a -> Down a
Down (Double -> Down Double)
-> ((Int, Double) -> Double) -> (Int, Double) -> Down Double
forall b c a. (b -> c) -> (a -> b) -> a -> c
. (Int, Double) -> Double
forall a b. (a, b) -> b
snd)) ([Int] -> [Double] -> [(Int, Double)]
forall a b. [a] -> [b] -> [(a, b)]
zip [Int
0 ..] [Double]
les))
    sorted :: [Double]
sorted = (Double -> Double -> Ordering) -> [Double] -> [Double]
forall a. (a -> a -> Ordering) -> [a] -> [a]
L.sortBy ((Double -> Down Double) -> Double -> Double -> Ordering
forall a b. Ord a => (b -> a) -> b -> b -> Ordering
comparing Double -> Down Double
forall a. a -> Down a
Down) [Double]
les
    !k :: Int
k = (Int -> Int -> Int) -> Int -> [Int] -> Int
forall b a. (b -> a -> b) -> b -> [a] -> b
forall (t :: * -> *) b a.
Foldable t =>
(b -> a -> b) -> b -> t a -> b
L.foldl' Int -> Int -> Int
forall a. Ord a => a -> a -> a
max Int
0
      [ Int
j
      | (Int
j, Double
e) <- [Int] -> [Double] -> [(Int, Double)]
forall a b. [a] -> [b] -> [(a, b)]
zip [ Int
1 .. ] [Double]
sorted
      , Double
e Double -> Double -> Bool
forall a. Ord a => a -> a -> Bool
>= Double -> Double
forall a. Floating a => a -> a
log (Double
n Double -> Double -> Double
forall a. Fractional a => a -> a -> a
/ (Double
alpha Double -> Double -> Double
forall a. Num a => a -> a -> a
* Int -> Double
forall a b. (Integral a, Num b) => a -> b
fromIntegral Int
j)) ]