packages feed

ppad-eproc-0.5.4: lib/Numeric/Eproc/Merge.hs

{-# 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 les = case les of
  [] -> 0
  _ -> log_sum_exps les - log (fromIntegral (length 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 = L.foldl' (+) 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 !alpha les = take k ranked
  where
    !n = fromIntegral (length les) :: Double
    ranked = fmap fst (L.sortBy (comparing (Down . snd)) (zip [0 ..] les))
    sorted = L.sortBy (comparing Down) les
    !k = L.foldl' max 0
      [ j
      | (j, e) <- zip [ 1 .. ] sorted
      , e >= log (n / (alpha * fromIntegral j)) ]