ensemble utilities

[pavlis]

Working on an implementation of the multichannel correlation and stacking algorithm derived from dbxcor led me to create a set of utility functions for ensemble objects. I'll give my proposal in a moment but there are some issues I'd like the group to consider before I proceed too far down this road:

1. Do you concur the functions I'm proposing below would be a useful addition to the code base?
2. Is the API sensible? i.e. are the kwarg keywords sensible, the options reasonable, and usage and limitations clear?
3. Where should these go in the file python file tree? They don't really belong in algortithms. Seems to me either mspasspy.util or mspasspy.seismic. I tend to think mspass.seismic would make more sense and to put them in a module called mspasspy.seismic.ensemble_utilities. opinions?

Here are the functions. I've already created these but haven't finished testing them. I'm only including the def lines and the docstrings:

def number_live(ensemble)->int:
    """
    Scans an ensemble and returns the number of live members.  If the 
    ensemble is marked dead it immediately return 0.  Otherwise it loops 
    through the members countinng the number live.
    :param ensemble:  ensemble to be scanned
    :type ensemble:  Must be a `TimeSeriesEnsemble` or `SeismogramEnsemble` or 
    it will throw a TypeError exception. 
    """

def ensemble_time_range(ensemble,metric="inner")->TimeWindow:
    """
    Scans a Seismic data ensemble returning a measure of the 
    time span of members.   The metric returned ban be either 
    smallest time range containing all the data, the range 
    defined by the minimum start time and maximum endtime, 
    or the median of the vector of startime and endtime 
    values.   
    
    :param ensemble:  ensemble container to be scanned for 
    time range. 
    :type ensemble:  `TimeSeriesEnsemble` or `SeismogramEnsemble`. 
    :param metric:   measure to use to define the time range.  
    Accepted values are:
      "inner" - (default) return range defined by largest 
          start time to smallest end time.
      "outer" - return range defined by minimum start time and 
          largest end time (maximum time span of data)
      "median" - return range as the median of the extracted 
          vectors of start time and end time values. 
      "mean" - return range as arithmetic average of 
          start and end time vectors 
    :return:  `TimeWindow` object with start and end times.
    """

def regularize_sampling(ensemble,dt_expected,Nsamp=10000,abort_on_error=False):
    """
    This is a utility function that can be used to validate that all the members 
    of an ensemble have a sample interval that is indistinguishable from a specified 
    constant (dt_expected)   The test for constant is soft to allow handling 
    data created by some older digitizers that skewed the recorded sample interval to force 
    time computed from N*dt to match time stamps on successive data packets.   
    The formula used is the datum dt is declared constant if the difference from 
    the expected dt is less than or equal to dt_expected/2*(Nsamp-1).  That means 
    the computed endtime difference from that using dt_expected is less than 
    or equal to dt/2.  
    
    The function by default will kill members that have mismatched sample
    intervals and log an informational message to the datum's elog container.
    In this mode the entire ensemble can end up marked dead if all the members 
    are killed (That situation can easily happen if the entire data set has the wrong dt.);
    If the argument `abort_on_errors` is set True a ValueError exception will be 
    thrown if ANY member of the input ensemble.  
    
    An important alternative to this function is to pass a data set 
    through the MsPASS `resample` function found in mspasspy.algorithms.resample.  
    That function will guarantee all live data have the same sample interval 
    and not kill them like this function will.   Use this function for 
    algorithms that can't be certain the input data will have been resampled 
    and need to be robust for what might otherwise be considered a user error.  
    
    :param ensemble:  ensemble container of data to be scanned for irregular 
    sampling.
    :type ensemble:  `TimeSeriesEnsemble` or `SeismogramEnsemble`.   The 
    function does not test for type and will abort with an undefined method
    error if sent anything else.
    :param dt_expected:  constant data sample interval expected.   
    :type dt_expected:  float
    :param Nsamp:   Nominal number of samples expected in the ensemble members. 
    This number is used to compute the soft test to allow for slippery clocks 
    discussed above.   (Default 10000) 
    :type Nsamp:  integer
    :param abort_on_error:  Controls what the function does if it 
    encountered a datum with a sample interval different that dt_expected. 
    When True the function aborts with a ValueError exception if ANY 
    ensemble member does not have a matching sample interval.  When 
    False (the default) the function uses the MsPASS error logging
    to hold a message an kills any member datum with a problem.
    :type abort_on_error:  boolean
    
    """