pynkowski.stats.utils_st

 1'''This submodule contains utility functions that are useful for different statistics.'''
 2import numpy as np
 3
 4def subsample_us(us, dus, iters=1_000):
 5    """Return the thresholds where MFs (except for v0) are computed before averaging within the bins 'dus'.
 6
 7    Parameters
 8    ----------
 9    us : np.array
10        The thresholds at which MFs have to be computed.
11
12    dus : np.array
13        The width of the bins associated to the thresholds 'us'.
14        
15    iters : int, optional
16        the number of thresholds to consider within each bin.
17
18    Returns
19    -------
20    us : np.array
21        The sequence of thresholds where MFs are computed before averaging within each bin, with shape (us.shape, iters).
22    
23    """
24    return np.vstack([np.linspace(u-du/2, u+du/2, iters) for u, du in zip(us, dus)])
25
26def define_ubins(us, edges):
27    """Return the bins for the computation of statistics. They are returned as (centre of bin, width of bin).
28
29    Parameters
30    ----------
31    us : np.array
32        The thresholds at which MFs have to be computed.
33
34    edges : bool, optional
35        If False (default), the given `us` is assumed to be an array of uniformly distributed thresholds, which are taken as the central values of the bins.
36        If True, input `us` is assumed to be a monotonically increasing array of bin edges, including the rightmost edge, allowing for non-uniform distributions of thresholds. 
37        In the latter case, the effective thresholds are the central value of the given bins.
38
39    Returns
40    -------
41    us : np.array
42        The central value of the bins.
43        
44    dus : np.array
45        The width of the bins.
46    
47    """
48    us = np.atleast_1d(us)
49        
50    if edges:
51        dus = (us[1:]-us[:-1])
52        us = (us[1:]+us[:-1])/2.
53    else:
54        if us.shape == (1,):
55            dus = np.array([0.1])
56        else:
57            dus = (us[1]-us[0])*np.ones(us.shape[0])           
58            if not (np.isclose(us[1:]-us[:-1], dus[0])).all():
59                raise ValueError('The threshold distribution is not uniform. Please set `edges=True`.')
60    return us, dus
61
62
63
64__all__ = ["subsample_us", "define_ubins"]
65
66__docformat__ = "numpy"
67
68