westpa 2022.12__cp313-cp313-macosx_11_0_arm64.whl

westpa/oldtools/aframe/iter_range.py

@@ -0,0 +1,200 @@
+import logging
+
+import numpy as np
+
+
+import westpa
+from westpa.oldtools.aframe import AnalysisMixin, ArgumentError
+
+log = logging.getLogger(__name__)
+
+
+class IterRangeMixin(AnalysisMixin):
+    '''A mixin for limiting the range of data considered for a given analysis. This should go after
+    DataManagerMixin'''
+
+    def __init__(self):
+        super().__init__()
+
+        self.first_iter = None
+        self.last_iter = None
+        self.iter_step = 1
+
+        include_args = self.include_args.setdefault('IterRangeMixin', {})
+        include_args.setdefault('first_iter', True)
+        include_args.setdefault('last_iter', True)
+        include_args.setdefault('iter_step', True)
+
+    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('analysis range')
+        if self.include_args['IterRangeMixin']['first_iter']:
+            group.add_argument(
+                '--start',
+                '--begin',
+                '--first',
+                dest='first_iter',
+                type=int,
+                metavar='N_ITER',
+                default=1,
+                help='''Begin analysis at iteration N_ITER (default: %(default)d).''',
+            )
+        if self.include_args['IterRangeMixin']['last_iter']:
+            group.add_argument(
+                '--stop',
+                '--end',
+                '--last',
+                dest='last_iter',
+                type=int,
+                metavar='N_ITER',
+                help='''Conclude analysis with N_ITER, inclusive (default: last completed iteration).''',
+            )
+        if self.include_args['IterRangeMixin']['iter_step']:
+            group.add_argument(
+                '--step', dest='iter_step', type=int, metavar='STEP', help='''Analyze/report in blocks of STEP iterations.'''
+            )
+
+    def process_args(self, args, upcall=True):
+        if self.include_args['IterRangeMixin']['first_iter']:
+            self.first_iter = args.first_iter or 1
+        if self.include_args['IterRangeMixin']['last_iter']:
+            self.last_iter = args.last_iter
+        if self.include_args['IterRangeMixin']['iter_step']:
+            self.iter_step = args.iter_step or 1
+
+        if upcall:
+            try:
+                upfunc = super().process_args
+            except AttributeError:
+                pass
+            else:
+                upfunc(args)
+
+    def check_iter_range(self):
+        assert hasattr(self, 'data_manager') and self.data_manager is not None
+
+        self.first_iter = int(max(self.first_iter, 1))
+        if self.last_iter is None or self.last_iter > self.data_manager.current_iteration - 1:
+            self.last_iter = int(self.data_manager.current_iteration - 1)
+
+        if self.first_iter == self.last_iter:
+            raise ArgumentError('first and last iterations are the same')
+
+        westpa.rc.pstatus(
+            'Processing iterations from {self.first_iter:d} to {self.last_iter:d}, inclusive (step size {self.iter_step:d})'.format(
+                self=self
+            )
+        )
+
+    def iter_block_iter(self):
+        '''Return an iterable of (block_first,block_last+1) over the blocks of iterations
+        selected by --first/--last/--step.  NOTE WELL that the second of the pair follows Python
+        iterator conventions and returns one past the last element of the block.'''
+
+        for blkfirst in range(self.first_iter, self.last_iter + 1, self.iter_step):
+            yield (blkfirst, min(self.last_iter, blkfirst + self.iter_step - 1) + 1)
+
+    def n_iter_blocks(self):
+        '''Return the number of blocks of iterations (as returned by ``iter_block_iter``) selected by --first/--last/--step.'''
+        npoints = self.last_iter - self.first_iter + 1
+        if npoints % self.iter_step == 0:
+            return npoints // self.iter_step
+        else:
+            return npoints // self.iter_step + 1
+
+    def record_data_iter_range(self, h5object, first_iter=None, last_iter=None):
+        '''Store attributes ``first_iter`` and ``last_iter`` on the given HDF5 object (group/dataset)'''
+        first_iter = first_iter or self.first_iter
+        last_iter = last_iter or self.last_iter
+        h5object.attrs['first_iter'] = first_iter
+        h5object.attrs['last_iter'] = last_iter
+
+    def record_data_iter_step(self, h5object, iter_step=None):
+        '''Store attribute ``iter_step`` on the given HDF5 object (group/dataset).'''
+        iter_step = iter_step or self.iter_step
+        h5object.attrs['iter_step'] = iter_step
+
+    def check_data_iter_range_least(self, h5object, first_iter=None, last_iter=None):
+        '''Check that the given HDF5 object contains (as denoted by its ``first_iter``/``last_iter`` attributes) at least the
+        data range specified.'''
+        first_iter = first_iter or self.first_iter
+        last_iter = last_iter or self.last_iter
+
+        obj_first_iter = h5object.attrs.get('first_iter')
+        obj_last_iter = h5object.attrs.get('last_iter')
+
+        return obj_first_iter <= first_iter and obj_last_iter >= last_iter
+
+    def check_data_iter_range_equal(self, h5object, first_iter=None, last_iter=None):
+        '''Check that the given HDF5 object contains per-iteration data for exactly the specified iterations (as denoted by the
+        object's ``first_iter`` and ``last_iter`` attributes'''
+
+        first_iter = first_iter or self.first_iter
+        last_iter = last_iter or self.last_iter
+
+        obj_first_iter = h5object.attrs.get('first_iter')
+        obj_last_iter = h5object.attrs.get('last_iter')
+
+        return obj_first_iter == first_iter and obj_last_iter == last_iter
+
+    def check_data_iter_step_conformant(self, h5object, iter_step=None):
+        '''Check that the given HDF5 object contains per-iteration data at an iteration stride suitable for extracting data
+        with the given stride.  (In other words, is the given ``iter_step`` a multiple of the stride with
+        which data was recorded.)'''
+
+        iter_step = iter_step or self.iter_step
+        obj_iter_step = h5object.attrs.get('iter_step')
+        return obj_iter_step % iter_step == 0
+
+    def check_data_iter_step_equal(self, h5object, iter_step=None):
+        '''Check that the given HDF5 object contains per-iteration data at an iteration stride the same as
+        that specified.'''
+        iter_step = iter_step or self.iter_step
+        obj_iter_step = h5object.attrs.get('iter_step')
+        return obj_iter_step == iter_step
+
+    def slice_per_iter_data(self, dataset, first_iter=None, last_iter=None, iter_step=None, axis=0):
+        '''Return the subset of the given dataset corresponding to the given iteration range and stride. Unless
+        otherwise specified, the first dimension of the dataset is the one sliced.'''
+
+        first_iter = first_iter or self.first_iter
+        last_iter = last_iter or self.last_iter
+        iter_step = iter_step or self.iter_step
+
+        ds_first_iter = dataset.attrs['first_iter']
+        ds_last_iter = dataset.attrs['last_iter']
+        ds_iter_step = dataset.attrs.get('iter_step', 1)
+
+        if first_iter < ds_first_iter or last_iter > ds_last_iter or ds_iter_step % iter_step > 0:
+            raise IndexError(
+                'Cannot slice requested iterations [{:d},{:d}] (stride={:d}) from dataset {!r} with range [{:d},{:d}] (stride={:d}).'.format(
+                    first_iter, last_iter, iter_step, dataset, ds_first_iter, ds_last_iter, ds_iter_step
+                )
+            )
+
+        dimslices = []
+        for idim in range(len(dataset.shape)):
+            if idim == axis:
+                dimslices.append(slice(first_iter - ds_first_iter, last_iter - ds_first_iter + iter_step, iter_step))
+            else:
+                dimslices.append(slice(None, None, None))
+
+        dimslices = tuple(dimslices)
+        log.debug('slicing {!r} with {!r}'.format(dataset, dimslices))
+        data = dataset[dimslices]
+        log.debug('resulting data is of shape {!r}'.format(data.shape))
+        return data
+
+    def iter_range(self, first_iter=None, last_iter=None, iter_step=None):
+        first_iter = first_iter or self.first_iter
+        last_iter = last_iter or self.last_iter
+        iter_step = iter_step or self.iter_step
+
+        return np.arange(first_iter, last_iter + 1, iter_step)

westpa/oldtools/aframe/kinetics.py

@@ -0,0 +1,117 @@
+import itertools
+import logging
+import re
+
+import numpy as np
+
+import westpa
+from westpa.oldtools.aframe import AnalysisMixin
+
+log = logging.getLogger(__name__)
+
+
+class KineticsAnalysisMixin(AnalysisMixin):
+    def __init__(self):
+        super().__init__()
+
+        self.dt = None
+        self.analysis_initial_bins = None
+        self.analysis_final_bins = 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('kinetics analysis options')
+        group.add_argument(
+            '--dt', dest='dt', type=float, default=1.0, help='Assume input data has a time spacing of DT (default: %(default)s).'
+        )
+        group.add_argument(
+            '--initial-bins',
+            dest='ibins_string',
+            metavar='ILIST',
+            help='''Only calculate statistics for transitions starting in bin ILIST.  This may be specified as a
+                             comma-separated list of integers or ranges, as in "0,2-4,5,9"''',
+        )
+        group.add_argument(
+            '--final-bins',
+            dest='fbins_string',
+            metavar='FLIST',
+            help='''Only calculate statistics for transitions ending in bin FLIST.  This may be specified as a
+                             comma-separated list of integers or ranges, as in "0,2-4,5,9"''',
+        )
+
+    def process_args(self, args, upcall=True):
+        self.dt = args.dt
+        westpa.rc.pstatus('Assuming input data timestep of {:g}'.format(self.dt))
+
+        if args.ibins_string:
+            self.analysis_initial_bins = self.parse_bin_range(args.ibins_string)
+            westpa.rc.pstatus(
+                'Will calculate kinetics data from transitions beginning in the following bins: {!s}'.format(
+                    sorted(self.analysis_initial_bins)
+                )
+            )
+        else:
+            westpa.rc.pstatus('Will calculate kinetics data from transitions beginning in any bin.')
+
+        if args.fbins_string:
+            self.analysis_final_bins = self.parse_bin_range(args.fbins_string)
+            westpa.rc.pstatus(
+                'Will calculate kinetics data from transitions ending in the following bins: {!s}'.format(
+                    sorted(self.analysis_final_bins)
+                )
+            )
+        else:
+            westpa.rc.pstatus('Will calculate kinetics data from transitions ending in any bin.')
+
+        if upcall:
+            try:
+                upfunc = super().process_args
+            except AttributeError:
+                pass
+            else:
+                upfunc(args)
+
+    def parse_bin_range(self, range_string):
+        try:
+            entries = set()
+            fields = re.split(r'\s*,\s*', range_string)
+            for field in fields:
+                if '-' in field:
+                    lb, ub = list(map(int, re.split(r'\s*-\s*', field)))
+                    entries.update(list(range(lb, ub + 1)))
+                else:
+                    entries.add(int(field))
+        except (ValueError, TypeError):
+            raise ValueError('invalid bin range string {!r}'.format(range_string))
+        else:
+            return entries
+
+    def check_bin_selection(self, n_bins=None):
+        '''Check to see that the bin ranges selected by the user conform to the available bins (i.e.,
+        bin indices are within the permissible range).  Also assigns the complete bin range if the
+        user has not explicitly limited the bins to be considered.'''
+
+        n_bins = n_bins or self.n_bins
+
+        if self.analysis_initial_bins:
+            if (np.array(list(self.analysis_initial_bins)) >= n_bins).any():
+                raise ValueError('One or more initial bin indices is out of range.')
+        else:
+            self.analysis_initial_bins = set(range(n_bins))
+
+        if self.analysis_final_bins:
+            if (np.array(list(self.analysis_final_bins)) >= n_bins).any():
+                raise ValueError('One or more final bin indices is out of range.')
+        else:
+            self.analysis_final_bins = set(range(n_bins))
+
+    @property
+    def selected_bin_pair_iter(self):
+        return (tuple(pair) for pair in itertools.product(self.analysis_initial_bins, self.analysis_final_bins))

westpa/oldtools/aframe/mcbs.py

@@ -0,0 +1,153 @@
+'''
+Tools for Monte Carlo bootstrap error analysis
+'''
+
+import logging
+import math
+
+import numpy as np
+from numpy.random import Generator, MT19937
+
+import westpa
+from westpa.oldtools.aframe import AnalysisMixin
+
+log = logging.getLogger(__name__)
+
+
+def msort(input_array):
+    return np.sort(input_array, axis=0)
+
+
+class MCBSMixin(AnalysisMixin):
+    def __init__(self):
+        super().__init__()
+        self.mcbs_alpha = None
+        self.mcbs_nsets = None
+        self.mcbs_display_confidence = 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('Monte Carlo bootstrap options')
+        group.add_argument(
+            '--confidence',
+            dest='mcbs_confidence',
+            type=float,
+            default=0.95,
+            metavar='P',
+            help='''Construct a confidence interval of width P (default: 0.95=95%%).''',
+        )
+        group.add_argument(
+            '--bssize',
+            dest='mcbs_nsets',
+            type=int,
+            metavar='NSETS',
+            help='''Use NSETS synthetic data sets to calculate confidence intervals (default:
+                                   calculated based on confidence level, but not less than 1000).''',
+        )
+
+    def process_args(self, args, upcall=True):
+        self.mcbs_alpha = 1 - args.mcbs_confidence
+        self.mcbs_nsets = args.mcbs_size if args.mcbs_nsets else min(1000, calc_mcbs_nsets(self.mcbs_alpha))
+        self.mcbs_display_confidence = '{:.{cp}f}'.format(
+            100 * args.mcbs_confidence, cp=-int(math.floor(math.log10(self.mcbs_alpha))) - 2
+        )
+        westpa.rc.pstatus(
+            'Using bootstrap of {:d} sets to calculate {:s}% confidence interval (alpha={:g}).'.format(
+                self.mcbs_nsets, self.mcbs_display_confidence, self.mcbs_alpha
+            )
+        )
+
+        if upcall:
+            try:
+                upfunc = super().process_args
+            except AttributeError:
+                pass
+            else:
+                upfunc(args)
+
+    def calc_mcbs_nsets(self, alpha=None):
+        alpha = alpha or self.mcbs_alpha
+        return calc_mcbs_nsets(alpha)
+
+    def calc_ci_bound_indices(self, n_sets=None, alpha=None):
+        n_sets = n_sets or self.mcbs_nsets
+        alpha = alpha or self.mcbs_alpha
+        return calc_ci_bound_indices(n_sets, alpha)
+
+
+ciinfo_dtype = np.dtype([('expectation', np.float64), ('ci_lower', np.float64), ('ci_upper', np.float64)])
+
+
+def calc_mcbs_nsets(alpha):
+    '''Return a bootstrap data set size appropriate for the given confidence level.'''
+    return int(10 ** (math.ceil(-math.log10(alpha)) + 1))
+
+
+def calc_ci_bound_indices(n_sets, alpha):
+    return (int(math.floor(n_sets * alpha / 2)), int(math.ceil(n_sets * (1 - alpha / 2))))
+
+
+def bootstrap_ci_ll(estimator, data, alpha, n_sets, storage, sort, eargs=(), ekwargs={}, fhat=None):
+    '''Low-level routine for calculating bootstrap error estimates.  Arguments and return values are as those for
+    ``bootstrap_ci``, except that no argument is optional except additional arguments for the estimator (``eargs``, ``ekwargs``).
+    ``data`` must be an array (or subclass), and an additional array ``storage`` must be provided, which
+    must be appropriately shaped and typed to hold ``n_sets`` results from ``estimator``.  Further, if the
+    value ``fhat`` of the estimator must be pre-calculated to allocate ``storage``, then its value may be
+    passed; otherwise, ``estimator(data,*eargs,**kwargs)`` will be called to calculate it.'''
+
+    rng = Generator(MT19937())
+
+    if fhat is None:
+        fhat = estimator(data, *eargs, **ekwargs)
+    dlen = len(data)
+
+    for iset in range(n_sets):
+        indices = rng.integers(dlen, size=(dlen,))
+        storage[iset] = estimator(data[indices], *eargs, **ekwargs)
+
+    synth_sorted = sort(storage)
+    lbi = int(math.floor(n_sets * alpha / 2))
+    ubi = int(math.ceil(n_sets * (1 - alpha / 2)))
+
+    lb = synth_sorted[lbi]
+    ub = synth_sorted[ubi]
+
+    try:
+        return (fhat, lb, ub, ub - lb, abs((ub - lb) / fhat) if fhat else 0, max(ub - fhat, fhat - lb))
+    finally:
+        del fhat, lb, ub, indices
+
+
+def bootstrap_ci(estimator, data, alpha, n_sets=None, sort=msort, eargs=(), ekwargs={}):
+    '''Perform a Monte Carlo bootstrap of a (1-alpha) confidence interval for the given ``estimator``.
+    Returns (fhat, ci_lower, ci_upper), where fhat is the result of ``estimator(data, *eargs, **ekwargs)``,
+    and ``ci_lower`` and ``ci_upper`` are the lower and upper bounds of the surrounding confidence
+    interval, calculated by calling ``estimator(syndata, *eargs, **ekwargs)`` on each synthetic data
+    set ``syndata``.  If ``n_sets`` is provided, that is the number of synthetic data sets generated,
+    otherwise an appropriate size is selected automatically (see ``calc_mcbs_nsets()``).
+
+    ``sort``, if given, is applied to sort the results of calling ``estimator`` on each
+    synthetic data set prior to obtaining the confidence interval. This function must sort
+    on the last index.
+
+    Individual entries in synthetic data sets are selected by the first index of ``data``, allowing this
+    function to be used on arrays of multidimensional data.
+
+    Returns (fhat, lb, ub, ub-lb, abs((ub-lb)/fhat), and max(ub-fhat,fhat-lb)) (that is, the estimated value, the
+    lower and upper bounds of the confidence interval, the width of the confidence interval, the relative
+    width of the confidence interval, and the symmetrized error bar of the confidence interval).'''
+
+    data = np.asanyarray(data)
+    fhat = np.squeeze(estimator(data, *eargs, **ekwargs))
+    n_sets = n_sets or calc_mcbs_nsets(alpha)
+    fsynth = np.empty((n_sets,), dtype=fhat.dtype)
+    try:
+        return bootstrap_ci_ll(estimator, data, alpha, n_sets or calc_mcbs_nsets(alpha), fsynth, sort, eargs, ekwargs, fhat)
+    finally:
+        del fsynth

westpa/oldtools/aframe/output.py

@@ -0,0 +1,39 @@
+import logging
+
+from westpa.oldtools.aframe import AnalysisMixin
+
+log = logging.getLogger(__name__)
+
+
+class CommonOutputMixin(AnalysisMixin):
+    def __init__(self):
+        super().__init__()
+
+        include_args = self.include_args.setdefault('CommonOutputMixin', {})
+        include_args.setdefault('suppress_headers', True)
+        include_args.setdefault('print_bin_labels', True)
+
+        self.output_suppress_headers = False
+        self.output_print_bin_labels = False
+
+    def add_common_output_args(self, parser_or_group):
+        if self.include_args['CommonOutputMixin']['suppress_headers']:
+            parser_or_group.add_argument(
+                '--noheaders',
+                dest='suppress_headers',
+                action='store_true',
+                help='Do not include headers in text output files (default: include headers)',
+            )
+        if self.include_args['CommonOutputMixin']['print_bin_labels']:
+            parser_or_group.add_argument(
+                '--binlabels',
+                dest='print_bin_labels',
+                action='store_true',
+                help='Print bin labels in output files, if available (default: do not print bin labels)',
+            )
+
+    def process_common_output_args(self, args):
+        if self.include_args['CommonOutputMixin']['suppress_headers']:
+            self.output_suppress_headers = bool(args.suppress_headers)
+        if self.include_args['CommonOutputMixin']['print_bin_labels']:
+            self.output_print_bin_labels = bool(args.print_bin_labels)

westpa/oldtools/aframe/plotting.py

@@ -0,0 +1,90 @@
+import logging
+
+import numpy as np
+
+from westpa.oldtools.aframe import AnalysisMixin
+
+log = logging.getLogger(__name__)
+
+try:
+    import matplotlib
+except ImportError:
+    matplotlib = None
+    pyplot = None
+    cm_hovmol = None
+    cm_hovmol_r = None
+else:
+    try:
+        matplotlib.use('PDF')
+        from matplotlib import pyplot
+    except Exception as e:
+        log.info('could not select matplotlib PDF backend: {}'.format(e))
+        matplotlib = None
+        pyplot = None
+
+    cmap_data = np.array(
+        [
+            (124, 0, 24),
+            (211, 0, 32),
+            (244, 184, 0),
+            (245, 235, 0),
+            (129, 183, 2),
+            (32, 128, 38),
+            (21, 27, 87),
+            (36, 62, 137),
+            (178, 220, 245),
+            (255, 255, 255),
+        ],
+        np.float32,
+    )
+    cmap_data /= 255.0
+    cm_hovmol = matplotlib.colors.LinearSegmentedColormap.from_list('hovmol', cmap_data)
+    cm_hovmol_r = matplotlib.colors.LinearSegmentedColormap.from_list('hovmol_r', np.flipud(cmap_data))
+
+    _pdr_data = {
+        'red': [
+            (0.0, 1.0, 1.0),
+            (0.25, 1.0, 1.0),
+            (0.50, 1.0, 1.0),
+            (0.75, 0.0, 0.0),
+            (0.90, 0.50, 0.50),
+            (0.95, 0.0, 0.0),
+            (1.0, 1.0, 1.0),
+        ],
+        'green': [
+            (0.0, 1.0, 1.0),
+            (0.25, 0.0, 0.0),
+            (0.50, 1.0, 1.0),
+            (0.75, 1.0, 1.0),
+            (0.90, 0.86, 0.86),
+            (0.95, 0.0, 0.0),
+            (1.0, 1.0, 1.0),
+        ],
+        'blue': [(0.0, 1.0, 1.0), (0.25, 0.0, 0.0), (0.75, 0.0, 0.0), (0.90, 1.0, 1.0), (0.95, 1.0, 1.0), (1.0, 1.0, 1.0)],
+    }
+
+    cm_pdr = matplotlib.colors.LinearSegmentedColormap('pdr', _pdr_data, 2048)
+    cm_pdr_r = cm_pdr.reversed()
+
+    matplotlib.colormaps.register(cmap=cm_pdr, name='pdr')
+    matplotlib.colormaps.register(cmap=cm_pdr_r, name='pdr_r')
+    matplotlib.colormaps.register(cmap=cm_hovmol, name='hovmol')
+    matplotlib.colormaps.register(cmap=cm_hovmol_r, name='hovmol_r')
+
+    del cmap_data
+
+
+class PlottingMixin(AnalysisMixin):
+    def __init__(self):
+        global matplotlib, pyplot
+
+        super().__init__()
+
+        self.matplotlib_avail = matplotlib is not None and pyplot is not None
+
+    def require_matplotlib(self):
+        global matplotlib
+        if not self.matplotlib_avail:
+            raise RuntimeError('matplotlib is not available')
+        else:
+            return matplotlib