westpa 2022.12__cp313-cp313-macosx_11_0_arm64.whl

westpa/mclib/__init__.py

@@ -0,0 +1,271 @@
+'''A package for performing Monte Carlo bootstrap estimates of
+statistics.'''
+
+import numpy as np
+from numpy.random import Generator, MT19937
+
+from ._mclib import mcbs_correltime, get_bssize, mcbs_ci
+
+
+def msort(input_array):
+    return np.sort(input_array, axis=0)
+
+
+def mcbs_ci_correl(
+    estimator_datasets,
+    estimator,
+    alpha,
+    n_sets=None,
+    args=None,
+    autocorrel_alpha=None,
+    autocorrel_n_sets=None,
+    subsample=None,
+    do_correl=True,
+    mcbs_enable=None,
+    estimator_kwargs={},
+):
+    '''Perform a Monte Carlo bootstrap estimate for the (1-``alpha``) confidence interval
+    on the given ``dataset`` with the given ``estimator``.  This routine is appropriate
+    for time-correlated data, using the method described in Huber & Kim, "Weighted-ensemble
+    Brownian dynamics simulations for protein association reactions" (1996),
+    doi:10.1016/S0006-3495(96)79552-8 to determine a statistically-significant correlation time
+    and then reducing the dataset by a factor of that correlation time before running a "classic"
+    Monte Carlo bootstrap.
+
+    Returns ``(estimate, ci_lb, ci_ub, correl_time)`` where ``estimate`` is the application of the
+    given ``estimator`` to the input ``dataset``, ``ci_lb`` and ``ci_ub`` are the
+    lower and upper limits, respectively, of the (1-``alpha``) confidence interval on
+    ``estimate``, and ``correl_time`` is the correlation time of the dataset, significant to
+    (1-``autocorrel_alpha``).
+
+    ``estimator`` is called as ``estimator(dataset, *args, **kwargs)``. Common estimators include:
+      * np.mean -- calculate the confidence interval on the mean of ``dataset``
+      * np.median -- calculate a confidence interval on the median of ``dataset``
+      * np.std -- calculate a confidence interval on the standard deviation of ``datset``.
+
+    ``n_sets`` is the number of synthetic data sets to generate using the given ``estimator``,
+    which will be chosen using `get_bssize()`_ if ``n_sets`` is not given.
+
+    ``autocorrel_alpha`` (which defaults to ``alpha``) can be used to adjust the significance
+    level of the autocorrelation calculation. Note that too high a significance level (too low an
+    alpha) for evaluating the significance of autocorrelation values can result in a failure to
+    detect correlation if the autocorrelation function is noisy.
+
+    The given ``subsample`` function is used, if provided, to subsample the dataset prior to running
+    the full Monte Carlo bootstrap. If none is provided, then a random entry from each correlated
+    block is used as the value for that block.  Other reasonable choices include ``np.mean``,
+    ``np.median``, ``(lambda x: x[0])`` or ``(lambda x: x[-1])``.  In particular, using
+    ``subsample=np.mean`` will converge to the block averaged mean and standard error,
+    while accounting for any non-normality in the distribution of the mean.
+    '''
+
+    if alpha > 0.5:
+        raise ValueError('alpha ({}) > 0.5'.format(alpha))
+
+    autocorrel_alpha = alpha if not autocorrel_alpha else autocorrel_alpha
+
+    # We're now passing in dataset as a dict, so we need to enforce that for compatibility with older tools.
+    # This just takes our dataset and puts it into a dict, as it's likely that we're using
+    # mean or median as our estimators, which take "a" as argument input.
+    if not isinstance(estimator_datasets, dict):
+        # Enforcing the data structure.
+        pre_calculated = estimator_datasets
+        estimator_datasets = {'a': estimator_datasets}
+        # This also probably means our estimator isn't going to handle kwargs, so we'll watch out for that later in testing.
+        # We may have to replace the 'simple' estimator with a slightly more complex lambda function which simply ditches extra arguments.
+    for key, dset in estimator_datasets.items():
+        estimator_datasets[key] = np.asanyarray(dset)
+        dlen = dset.shape[0]
+
+    # Why do we have 'estimator_datasets'?
+    # Estimators may require many different sets of data to properly function; while we can send this in via the kwargs,
+    # we may wish to decimate only a certain subset (due to the block bootstrapping) of the input parameters.
+    # Therefore, 'estimator_datasets' should consist of datasets that must be sliced/decimated with the subsampling function.
+    # Some estimators (such as the reweighting) may not be able to be decimated in a straightforward manner with a subsample function,
+    # as we cannot pre-estimate the quantity without introducing error or bias.  In those cases, we may wish to pass on all the data,
+    # but ensure that our estimator only includes certain iterations (and only in a certain way).
+
+    n_sets = n_sets or get_bssize(alpha)
+    autocorrel_n_sets = autocorrel_n_sets or get_bssize(autocorrel_alpha)
+
+    if mcbs_enable is False:
+        # While it's odd to support NOT doing the bootstrap in a library specifically designed for bootstrapping,
+        # supporting this functionality here makes writing the code a lot easier, as we can just pass in a flag.
+        # Specifically, this is for situations in which error is not desired (that is, only a reasonable mean is desired).
+        # It's often useful when doing a quick analysis.
+        estimator_datasets.update(estimator_kwargs)
+        try:
+            estimator_datasets.update({'stride': 1})
+        except Exception:
+            pass
+
+        return_set = estimator(**estimator_datasets)
+        # We don't try and pretend we're doing any error analysis.
+        return return_set, return_set, return_set, 0, 1
+
+    rng = Generator(MT19937())  # RNG
+
+    # We need to pre-generate the data; why not do it here?  We're already set up for it...
+    precalc_kwargs = estimator_kwargs.copy()
+    precalc_kwargs['stride'] = 1
+    pre_calculated = []
+    for block in range(1, dlen + 1):
+        for key, dset in estimator_datasets.items():
+            precalc_kwargs[key] = dset[0:block]
+        pre_calculated.append(estimator(**precalc_kwargs))
+    # We need to get rid of any NaNs.
+    pre_calculated = np.asanyarray(pre_calculated)
+    pre_calculated = pre_calculated[np.isfinite(pre_calculated)]
+    # If this happens, we have a huge NaN problem.  That is, our estimator is failing to return meaningful
+    # numbers.  We should catch this when it happens, and so raise an exception, here.
+    # This is almost certainly due to estimator failure.  Double check that calculation.
+    if pre_calculated.shape == (0,):
+        raise NameError("Looks like the estimator failed.  This is likely a programming issue, and should be reported.")
+    # If pre-calculated is not None, we'll use that instead of dataset.
+    # We can also assume that it's a 1 dimensional set with nothing needed, so 'key' should work.
+    if do_correl is True:
+        correl_len = mcbs_correltime(pre_calculated, autocorrel_alpha, autocorrel_n_sets)
+    else:
+        correl_len = 0
+    if correl_len == len(pre_calculated):
+        # too correlated for meaningful calculations
+        estimator_datasets.update(estimator_kwargs)
+        try:
+            estimator_datasets.update({'stride': 1})
+        except Exception:
+            pass
+
+        return estimator(**estimator_datasets), pre_calculated.min(), pre_calculated.max(), (np.std(pre_calculated)), correl_len
+
+    # else, do a blocked bootstrap
+    stride = correl_len + 1
+
+    if stride == 1:
+        # Some estimators may require the stride, so we pass it in.
+        estimator_kwargs['stride'] = stride
+        return mcbs_ci(
+            dataset=estimator_datasets,
+            estimator=estimator,
+            alpha=alpha,
+            dlen=dlen,
+            n_sets=n_sets,
+            args=args,
+            kwargs=estimator_kwargs,
+            sort=msort,
+        ) + (correl_len,)
+    else:
+        subsample = subsample or (lambda x: x[rng.integers(len(x))])
+        # Let's make sure we decimate every array properly...
+        decim_list = {}
+        for key, dset in estimator_datasets.items():
+            dset_shape = list(dset.shape)
+            n_slices = dset_shape[0] // stride
+            dset_shape[0] = n_slices
+            decim_set = np.empty((dset_shape), dtype=dset.dtype)
+            for iout, istart in enumerate(range(0, dset.shape[0] - stride + 1, stride)):
+                sl = dset[istart : istart + stride]
+                # We assume time is the 0th axis.
+                # Okay, so non-optimal.  Population requires the axis subsampling to be done just so...
+                try:
+                    decim_set[iout] = subsample(sl, axis=0)
+                except Exception:
+                    decim_set[iout] = subsample(sl)
+            decim_list[key] = decim_set
+            dlen = dset_shape[0]
+            estimator_kwargs['stride'] = stride
+
+        return mcbs_ci(
+            dataset=decim_list,
+            estimator=estimator,
+            alpha=alpha,
+            dlen=dlen,
+            n_sets=n_sets,
+            args=args,
+            kwargs=estimator_kwargs,
+            sort=msort,
+        ) + (correl_len,)
+
+
+# These are blocks designed to evaluate simple information sets.
+# Whether they should go here or in westtoools is somewhat up for debate.
+# Currently, nothing actually uses them, so there's that.
+
+
+def _1D_simple_eval_block(
+    iblock,
+    start,
+    stop,
+    nstates,
+    data_input,
+    name,
+    mcbs_alpha,
+    mcbs_nsets,
+    mcbs_acalpha,
+    do_correl,
+    mcbs_enable,
+    subsample=np.mean,
+    **extra
+):
+    # This is actually appropriate for anything with a directly measured, 1D dataset, i.e.,
+    # Fluxes, color populations, and state populations.
+    results = []
+    for istate in range(nstates):
+        # Not sure if we need a jstate for these estimators, but we'll see.
+        # kwargs = {'istate': istate, 'jstate': 'B'}
+        estimator_datasets = {'dataset': data_input['dataset'][:, istate]}
+        ci_res = mcbs_ci_correl(
+            estimator_datasets,
+            estimator=(lambda stride, dataset: np.mean(dataset)),
+            alpha=mcbs_alpha,
+            n_sets=mcbs_nsets,
+            autocorrel_alpha=mcbs_acalpha,
+            subsample=subsample,
+            do_correl=do_correl,
+            mcbs_enable=mcbs_enable,
+        )
+
+        results.append((name, iblock, istate, (start, stop) + ci_res))
+
+    return results
+
+
+def _2D_simple_eval_block(
+    iblock,
+    start,
+    stop,
+    nstates,
+    data_input,
+    name,
+    mcbs_alpha,
+    mcbs_nsets,
+    mcbs_acalpha,
+    do_correl,
+    mcbs_enable,
+    subsample=np.mean,
+    **extra
+):
+    # This is really just a simple 2D block for less complex datasets, but there it is.
+    # It's probably limited in this use case to conditional_fluxes, but anything that's an i to j process that is directly measured
+    # is suitable for use with this.
+    results = []
+    for istate in range(nstates):
+        for jstate in range(nstates):
+            if istate == jstate:
+                continue
+            # kwargs = {'istate': istate, 'jstate': jstate}
+            # dataset = {'dataset': cond_fluxes[:, istate, jstate]}
+            estimator_datasets = {'dataset': data_input['dataset'][:, istate, jstate]}
+            ci_res = mcbs_ci_correl(
+                estimator_datasets,
+                estimator=(lambda stride, dataset: np.mean(dataset)),
+                alpha=mcbs_alpha,
+                n_sets=mcbs_nsets,
+                autocorrel_alpha=mcbs_acalpha,
+                subsample=subsample,
+                do_correl=do_correl,
+                mcbs_enable=mcbs_enable,
+            )
+
+            results.append((name, iblock, istate, jstate, (start, stop) + ci_res))
+
+    return results

westpa/mclib/__main__.py

@@ -0,0 +1,28 @@
+if __name__ == '__main__':
+    from . import autocorrel_elem
+    import numpy
+    from scipy.signal import correlate
+
+    n = 16
+    x = numpy.linspace(0, n * numpy.pi, 16 * n + 1)
+    a = numpy.cos(x) + numpy.exp(-((x / 2.0) ** 2)) + numpy.exp(-(x / 4.0))
+    pa = numpy.zeros((10000 * len(a),), numpy.float64)
+    pa[: len(a)] = a
+
+    print('<a> =', a.mean())
+    print('<a^2> =', ((a - a.mean()) ** 2).sum())
+    print('scipy.signal.correlate:')
+    acf0 = correlate(a, a)
+    acf0 = acf0[-len(a) :]
+    acf0 /= acf0.max()
+    print(acf0[: len(acf0) / 4])
+
+    #    print 'scipy.signal.correlate (-mean):'
+    #    acf0 = correlate(a-a.mean(),a-a.mean())
+    #    acf0 = acf0[-len(a):]
+    #    acf0 /= acf0.max()
+    #    print acf0[:len(acf0)/4]
+
+    print('this module:')
+    acf = numpy.array([autocorrel_elem(pa, k) for k in range(len(a))])
+    print(acf[: len(acf) / 4])

westpa/oldtools/__init__.py

@@ -0,0 +1,4 @@
+from . import aframe, miscfn
+
+
+__all__ = ['aframe', 'miscfn']

westpa/oldtools/aframe/__init__.py

@@ -0,0 +1,35 @@
+"""WEST Analyis framework -- an unholy mess of classes exploiting each other"""
+
+from . import atool
+from .atool import WESTAnalysisTool
+from .base_mixin import ArgumentError, AnalysisMixin
+from .binning import BinningMixin
+from .data_reader import WESTDataReaderMixin, ExtDataReaderMixin, BFDataManager
+from .iter_range import IterRangeMixin
+from .kinetics import KineticsAnalysisMixin
+from .mcbs import MCBSMixin
+from .output import CommonOutputMixin
+from .plotting import PlottingMixin
+from .trajwalker import TrajWalker
+from .transitions import TransitionAnalysisMixin, TransitionEventAccumulator, BFTransitionAnalysisMixin
+
+
+__all__ = [
+    'atool',
+    'AnalysisMixin',
+    'ArgumentError',
+    'WESTAnalysisTool',
+    'IterRangeMixin',
+    'WESTDataReaderMixin',
+    'ExtDataReaderMixin',
+    'BFDataManager',
+    'BinningMixin',
+    'MCBSMixin',
+    'TrajWalker',
+    'TransitionAnalysisMixin',
+    'TransitionEventAccumulator',
+    'BFTransitionAnalysisMixin',
+    'KineticsAnalysisMixin',
+    'CommonOutputMixin',
+    'PlottingMixin',
+]

westpa/oldtools/aframe/atool.py

@@ -0,0 +1,75 @@
+import logging
+
+
+import h5py
+
+log = logging.getLogger(__name__)
+
+
+class WESTAnalysisTool:
+    def __init__(self):
+        super().__init__()
+        # Whether a west.cfg is required to run a program based on this tool
+        self.config_required = False
+
+        # Analysis HDF5 filename and object
+        self.anal_h5name = None
+        self.anal_h5file = None
+
+        # Whether this is being used in a brute analysis
+        self.bf_mode = False
+
+        # A way to override some arguments on a per-mixin basis without having to subclass
+        # (messy, but it doesn't seem crucial enough so far to make it cleaner)
+        self.include_args = {}
+
+    def add_args(self, parser, upcall=True):
+        '''Add arguments to a parser common to all analyses of this type.'''
+        if upcall:
+            try:
+                upfunc = super().add_args
+            except AttributeError:
+                pass
+            else:
+                upfunc(parser)
+
+        group = parser.add_argument_group('general analysis options')
+        group.add_argument(
+            '-A',
+            '--analysis-file',
+            dest='anal_h5name',
+            metavar='H5FILE',
+            default='analysis.h5',
+            help='Store intermediate and final results in H5FILE (default: %(default)s).',
+        )
+
+    def process_args(self, args, upcall=True):
+        self.anal_h5name = args.anal_h5name
+
+        if upcall:
+            try:
+                upfunc = super().process_args
+            except AttributeError:
+                pass
+            else:
+                upfunc(args)
+
+    def open_analysis_backing(self):
+        if self.anal_h5file is None:
+            self.anal_h5file = h5py.File(self.anal_h5name)
+
+    def close_analysis_backing(self):
+        try:
+            self.anal_h5file.close()
+            self.anal_h5file = None
+        except AttributeError:
+            pass
+
+    def require_analysis_group(self, groupname, replace=False):
+        self.open_analysis_backing()
+        if replace:
+            try:
+                del self.anal_h5file[groupname]
+            except KeyError:
+                pass
+        return self.anal_h5file.require_group(groupname)

westpa/oldtools/aframe/base_mixin.py

@@ -0,0 +1,26 @@
+class ArgumentError(RuntimeError):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+
+class AnalysisMixin:
+    def __init__(self):
+        super().__init__()
+
+    def add_args(self, parser, upcall=True):
+        if upcall:
+            try:
+                upfunc = super().add_args
+            except AttributeError:
+                pass
+            else:
+                upfunc(parser)
+
+    def process_args(self, args, upcall=True):
+        if upcall:
+            try:
+                upfunc = super().process_args
+            except AttributeError:
+                pass
+            else:
+                upfunc(args)

westpa/oldtools/aframe/binning.py

@@ -0,0 +1,178 @@
+import logging
+
+import numpy as np
+
+import westpa
+from westpa.oldtools.aframe import AnalysisMixin
+
+log = logging.getLogger(__name__)
+
+
+class BinningMixin(AnalysisMixin):
+    '''A mixin for performing binning on WEST data.'''
+
+    def __init__(self):
+        super().__init__()
+
+        self.mapper = None
+        self.n_bins = None
+
+        self.discard_bin_assignments = False
+        self.binning_h5gname = 'binning'
+        self.binning_h5group = None
+        self.mapper_hash = None
+
+    def add_args(self, parser, upcall=True):
+        if upcall:
+            try:
+                upfunc = super().add_args
+            except AttributeError:
+                pass
+            else:
+                upfunc(parser)
+
+        group = parser.add_argument_group('binning options')
+        egroup = group.add_mutually_exclusive_group()
+        egroup.add_argument(
+            '--binexpr',
+            '--binbounds',
+            dest='binexpr',
+            help='''Construct rectilinear bins from BINEXPR. This must be a list of lists of bin boundaries
+                            (one list of bin boundaries for each dimension of the progress coordinate), formatted as a Python
+                            expression. E.g. "[[0,1,2,4,inf], [-inf,0,inf]]".''',
+        )
+        group.add_argument(
+            '--discard-bin-assignments',
+            dest='discard_bin_assignments',
+            action='store_true',
+            help='''Discard any existing bin assignments stored in the analysis HDF5 file.''',
+        )
+
+    def process_args(self, args, upcall=True):
+        if args.binexpr:
+            westpa.rc.pstatus("Constructing rectilinear bin boundaries from the following expression: '{}'".format(args.binexpr))
+            self.mapper = self.mapper_from_expr(args.binexpr)
+        else:
+            westpa.rc.pstatus('Loading bin boundaries from WEST system')
+            system = westpa.rc.get_system_driver()
+            self.mapper = system.bin_mapper
+
+        self.n_bins = self.mapper.nbins
+        _pdat, self.mapper_hash = self.mapper.pickle_and_hash()
+        westpa.rc.pstatus('  {:d} bins'.format(self.n_bins))
+        westpa.rc.pstatus('  identity hash {}'.format(self.mapper_hash))
+
+        self.discard_bin_assignments = bool(args.discard_bin_assignments)
+
+        if upcall:
+            try:
+                upfunc = super().process_args
+            except AttributeError:
+                pass
+            else:
+                upfunc(args)
+
+    def mapper_from_expr(self, expr):
+        from westpa.core.binning import RectilinearBinMapper
+
+        namespace = {'numpy': np, 'np': np, 'inf': float('inf')}
+
+        try:
+            return RectilinearBinMapper(eval(expr, namespace))
+        except TypeError as e:
+            if 'has no len' in str(e):
+                raise ValueError('invalid bin boundary specification; you probably forgot to make a list of lists')
+
+    def write_bin_labels(self, dest, header='# bin labels:\n', format='# bin {bin_index:{max_iwidth}d} -- {label!s}\n'):
+        '''Print labels for all bins in ``self.mapper`` to ``dest``.  If provided, ``header``
+        is printed before any labels.   The ``format`` string specifies how bin labels are to be printed.  Valid entries are:
+          * ``bin_index`` -- the zero-based index of the bin
+          * ``label`` -- the label, as obtained by ``bin.label``
+          * ``max_iwidth`` -- the maximum width (in characters) of the bin index, for pretty alignment
+        '''
+        dest.write(header or '')
+        max_iwidth = len(str(self.mapper.nbins - 1))
+        for ibin, label in enumerate(self.mapper.labels):
+            dest.write(format.format(bin_index=ibin, label=label, max_iwidth=max_iwidth))
+
+    def require_binning_group(self):
+        if self.binning_h5group is None:
+            self.binning_h5group = self.anal_h5file.require_group(self.binning_h5gname)
+        return self.binning_h5group
+
+    def delete_binning_group(self):
+        self.binning_h5group = None
+        del self.anal_h5file[self.binning_h5gname]
+
+    def record_data_binhash(self, h5object):
+        '''Record the identity hash for self.mapper as an attribute on the given HDF5 object (group or dataset)'''
+        h5object.attrs['binhash'] = self.mapper_hash
+
+    def check_data_binhash(self, h5object):
+        '''Check whether the recorded bin identity hash on the given HDF5 object matches the identity hash for self.mapper'''
+        return h5object.attrs.get('binhash') == self.mapper_hash
+
+    def assign_to_bins(self):
+        '''Assign WEST segment data to bins.  Requires the DataReader mixin to be in the inheritance tree'''
+        self.require_binning_group()
+
+        n_iters = self.last_iter - self.first_iter + 1
+        max_n_segs = self.max_iter_segs_in_range(self.first_iter, self.last_iter)
+        pcoord_len = self.get_pcoord_len(self.first_iter)
+
+        assignments = np.zeros((n_iters, max_n_segs, pcoord_len), np.min_scalar_type(self.n_bins))
+        populations = np.zeros((n_iters, pcoord_len, self.n_bins), np.float64)
+
+        westpa.rc.pstatus('Assigning to bins...')
+
+        for iiter, n_iter in enumerate(range(self.first_iter, self.last_iter + 1)):
+            westpa.rc.pstatus('\r  Iteration {:d}'.format(n_iter), end='')
+            seg_index = self.get_seg_index(n_iter)
+            pcoords = self.get_iter_group(n_iter)['pcoord'][...]
+            weights = seg_index['weight']
+
+            for seg_id in range(len(seg_index)):
+                assignments[iiter, seg_id, :] = self.mapper.assign(pcoords[seg_id, :, :])
+
+            for it in range(pcoord_len):
+                populations[iiter, it, :] = np.bincount(assignments[iiter, : len(seg_index), it], weights, minlength=self.n_bins)
+
+            westpa.rc.pflush()
+            del pcoords, weights, seg_index
+
+        assignments_ds = self.binning_h5group.create_dataset('bin_assignments', data=assignments, compression='gzip')
+        populations_ds = self.binning_h5group.create_dataset('bin_populations', data=populations, compression='gzip')
+
+        for h5object in (self.binning_h5group, assignments_ds, populations_ds):
+            self.record_data_iter_range(h5object)
+            self.record_data_iter_step(h5object, 1)
+            self.record_data_binhash(h5object)
+
+        westpa.rc.pstatus()
+
+    def require_bin_assignments(self):
+        self.require_binning_group()
+        do_assign = False
+        if self.discard_bin_assignments:
+            westpa.rc.pstatus('Discarding existing bin assignments.')
+            do_assign = True
+        elif 'bin_assignments' not in self.binning_h5group:
+            do_assign = True
+        elif not self.check_data_iter_range_least(self.binning_h5group):
+            westpa.rc.pstatus('Existing bin assignments are for incompatible first/last iterations; deleting assignments.')
+            do_assign = True
+        elif not self.check_data_binhash(self.binning_h5group):
+            westpa.rc.pstatus('Bin definitions have changed; deleting existing bin assignments.')
+            do_assign = True
+
+        if do_assign:
+            self.delete_binning_group()
+            self.assign_to_bins()
+        else:
+            westpa.rc.pstatus('Using existing bin assignments.')
+
+    def get_bin_assignments(self, first_iter=None, last_iter=None):
+        return self.slice_per_iter_data(self.binning_h5group['bin_assignments'], first_iter, last_iter)
+
+    def get_bin_populations(self, first_iter=None, last_iter=None):
+        return self.slice_per_iter_data(self.binning_h5group['bin_populations'], first_iter, last_iter)