pynkowski.stats.extrema

  1'''This submodule contains the functions to compute the density distribution (and total number) of local maxima and minima of a field.'''
  2import numpy as np
  3from .utils_st import subsample_us, define_ubins
  4from ..data.base_da import DataField
  5from ..theory.base_th import TheoryField
  6
  7try:
  8    from tqdm.auto import tqdm
  9except:
 10    tqdm = lambda x: x
 11    print('tqdm not loaded')
 12
 13def maxima(field, us, edges=False, verbose=True):
 14    """Compute the density distribution of maxima and the total number of maxima of a field.
 15
 16    Parameters
 17    ----------
 18    field : DataField or TheoryField
 19        Field on which to compute the maxima distribution, which can be a theoretical field or a data field.
 20        
 21    us : np.array
 22        The thresholds where the distribution is computed.
 23        
 24    edges : bool, optional
 25        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.
 26        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. 
 27        In the latter case, the effective thresholds are the central value of the given bins.
 28        
 29    verbose : bool, optional
 30        If True (default), progress bars are shown for some computations on data.
 31    
 32    Returns
 33    -------
 34    maxima_dist : np.array()
 35        The density distribution of the maxima at the given thresholds.
 36
 37    number_total : float
 38        The total number of maxima.
 39    
 40    """
 41    us = np.atleast_1d(us)
 42    
 43    if isinstance(field, TheoryField):
 44        us, dus = define_ubins(us, edges)
 45        us = subsample_us(us, dus)
 46        try:
 47            return np.nanmean(field.maxima_dist(us), axis=1), field.maxima_total()
 48        except AttributeError:
 49            raise NotImplementedError(f"The theoretical expectation of the maxima distribution for {field.name} fields is not implemented. If you know an expression, please get in touch.")
 50        
 51    if isinstance(field, DataField):
 52        try:
 53            max_list = field.maxima_list()
 54        except AttributeError:                
 55            raise NotImplementedError(f"The computation of the maxima distribution for {field.name} fields is not implemented. If you know a method, please get in touch.")
 56
 57        if not edges:
 58            if us.shape == (1,):
 59                du = 0.1
 60            else:
 61                du = us[1] - us[0]
 62            us = np.hstack([us-du/2, us[-1]+du/2])
 63
 64        return np.histogram(max_list, bins=us, density=True)[0], max_list.shape[0]
 65        
 66    else:
 67        raise TypeError(f"The field must be either TheoryField or DataField (or a subclass).")
 68    
 69def minima(field, us, edges=False, verbose=True):
 70    """Compute the density distribution of minima and the total number of minima of a field.
 71
 72    Parameters
 73    ----------
 74    field : DataField or TheoryField
 75        Field on which to compute the minima distribution, which can be a theoretical field or a data field.
 76        
 77    us : np.array
 78        The thresholds where the distribution is computed.
 79        
 80    edges : bool, optional
 81        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.
 82        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. 
 83        In the latter case, the effective thresholds are the central value of the given bins.
 84        
 85    verbose : bool, optional
 86        If True (default), progress bars are shown for the computations on data.
 87    
 88    Returns
 89    -------
 90    minima_dist : np.array()
 91        The density distribution of the minima at the given thresholds.
 92
 93    number_total : float
 94        The total number of minima.
 95    
 96    """
 97    us = np.atleast_1d(us)
 98    
 99    if isinstance(field, TheoryField):
100        us, dus = define_ubins(us, edges)
101        us = subsample_us(us, dus)
102        try:
103            return np.nanmean(field.minima_dist(us), axis=1), field.minima_total()
104        except AttributeError:
105            raise NotImplementedError(f"The theoretical expectation of the minima distribution for {field.name} fields is not implemented. If you know an expression, please get in touch.")
106        
107    if isinstance(field, DataField):
108        try:
109            min_list = field.minima_list()
110        except AttributeError:                
111            raise NotImplementedError(f"The computation of the minima distribution for {field.name} fields is not implemented. If you know a method, please get in touch.")
112
113        if not edges:
114            if us.shape == (1,):
115                du = 0.1
116            else:
117                du = us[1] - us[0]
118            us = np.hstack([us-du/2, us[-1]+du/2])
119
120        return np.histogram(min_list, bins=us, density=True)[0], min_list.shape[0]
121        
122    else:
123        raise TypeError(f"The field must be either TheoryField or DataField (or a subclass).")
124    
125
126
127__all__ = ["maxima", "minima"]
128
129__docformat__ = "numpy"