w_reweight
westpa.cli.tools.w_reweight module
- class westpa.cli.tools.w_reweight.WESTMasterCommand
Bases:
WESTTool
Base class for command-line tools that employ subcommands
- subparsers_title = None
- subcommands = None
- include_help_command = True
- add_args(parser)
Add arguments specific to this tool to the given argparse parser.
- process_args(args)
Take argparse-processed arguments associated with this tool and deal with them appropriately (setting instance variables, etc)
- go()
Perform the analysis associated with this tool.
- class westpa.cli.tools.w_reweight.WESTParallelTool(wm_env=None)
Bases:
WESTTool
Base class for command-line tools parallelized with wwmgr. This automatically adds and processes wwmgr command-line arguments and creates a work manager at self.work_manager.
- make_parser_and_process(prog=None, usage=None, description=None, epilog=None, args=None)
A convenience function to create a parser, call add_all_args(), and then call process_all_args(). The argument namespace is returned.
- add_args(parser)
Add arguments specific to this tool to the given argparse parser.
- process_args(args)
Take argparse-processed arguments associated with this tool and deal with them appropriately (setting instance variables, etc)
- go()
Perform the analysis associated with this tool.
- main()
A convenience function to make a parser, parse and process arguments, then run self.go() in the master process.
- class westpa.cli.tools.w_reweight.WESTKineticsBase(parent)
Bases:
WESTSubcommand
Common argument processing for w_direct/w_reweight subcommands. Mostly limited to handling input and output from w_assign.
- add_args(parser)
Add arguments specific to this component to the given argparse parser.
- process_args(args)
Take argparse-processed arguments associated with this component and deal with them appropriately (setting instance variables, etc)
- class westpa.cli.tools.w_reweight.AverageCommands(parent)
Bases:
WESTKineticsBase
- default_output_file = 'direct.h5'
- add_args(parser)
Add arguments specific to this component to the given argparse parser.
- process_args(args)
Take argparse-processed arguments associated with this component and deal with them appropriately (setting instance variables, etc)
- stamp_mcbs_info(dataset)
- open_files()
- open_assignments()
- print_averages(dataset, header, dim=1)
- run_calculation(pi, nstates, start_iter, stop_iter, step_iter, dataset, eval_block, name, dim, do_averages=False, **extra)
- westpa.cli.tools.w_reweight.generate_future(work_manager, name, eval_block, kwargs)
- westpa.cli.tools.w_reweight.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 givendataset
with the givenestimator
. 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)
whereestimate
is the application of the givenestimator
to the inputdataset
,ci_lb
andci_ub
are the lower and upper limits, respectively, of the (1-alpha
) confidence interval onestimate
, andcorrel_time
is the correlation time of the dataset, significant to (1-autocorrel_alpha
).estimator
is called asestimator(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 givenestimator
, which will be chosen using `get_bssize()`_ ifn_sets
is not given.autocorrel_alpha
(which defaults toalpha
) 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 includenp.mean
,np.median
,(lambda x: x[0])
or(lambda x: x[-1])
. In particular, usingsubsample=np.mean
will converge to the block averaged mean and standard error, while accounting for any non-normality in the distribution of the mean.
- westpa.cli.tools.w_reweight.reweight_for_c(rows, cols, obs, flux, insert, indices, nstates, nbins, state_labels, state_map, nfbins, istate, jstate, stride, bin_last_state_map, bin_state_map, return_obs, obs_threshold=1)
- class westpa.cli.tools.w_reweight.RWMatrix(parent)
Bases:
WESTKineticsBase
,FluxMatrix
- subcommand = 'init'
- default_kinetics_file = 'reweight.h5'
- default_output_file = 'reweight.h5'
- help_text = 'create a color-labeled transition matrix from a WESTPA simulation'
- description = 'Generate a colored transition matrix from a WE assignment file. The subsequent\nanalysis requires that the assignments are calculated using only the initial and\nfinal time points of each trajectory segment. This may require downsampling the\nh5file generated by a WE simulation. In the future w_assign may be enhanced to optionally\ngenerate the necessary assignment file from a h5file with intermediate time points.\nAdditionally, this analysis is currently only valid on simulations performed under\neither equilibrium or steady-state conditions without recycling target states.\n\n-----------------------------------------------------------------------------\nOutput format\n-----------------------------------------------------------------------------\n\nThe output file (-o/--output, by default "reweight.h5") contains the\nfollowing datasets:\n\n ``/bin_populations`` [window, bin]\n The reweighted populations of each bin based on windows. Bins contain\n one color each, so to recover the original un-colored spatial bins,\n one must sum over all states.\n\n ``/iterations`` [iteration]\n *(Structured -- see below)* Sparse matrix data from each\n iteration. They are reconstructed and averaged within the\n w_reweight {kinetics/probs} routines so that observables may\n be calculated. Each group contains 4 vectors of data:\n\n flux\n *(Floating-point)* The weight of a series of flux events\n cols\n *(Integer)* The bin from which a flux event began.\n cols\n *(Integer)* The bin into which the walker fluxed.\n obs\n *(Integer)* How many flux events were observed during this\n iteration.\n\n-----------------------------------------------------------------------------\nCommand-line options\n-----------------------------------------------------------------------------\n'
- add_args(parser)
Add arguments specific to this component to the given argparse parser.
- process_args(args)
Take argparse-processed arguments associated with this component and deal with them appropriately (setting instance variables, etc)
- go()
- class westpa.cli.tools.w_reweight.RWReweight(parent)
Bases:
AverageCommands
- help_text = 'Parent class for all reweighting routines, as they all use the same estimator code.'
- add_args(parser)
Add arguments specific to this component to the given argparse parser.
- process_args(args)
Take argparse-processed arguments associated with this component and deal with them appropriately (setting instance variables, etc)
- accumulate_statistics(start_iter, stop_iter)
This function pulls previously generated flux matrix data into memory. The data is assumed to exist within an HDF5 file that is available as a property. The data is kept as a single dimensional numpy array to use with the cython estimator.
- generate_reweight_data()
This function ensures all the appropriate files are loaded, sets appropriate attributes necessary for all calling functions/children, and then calls the function to load in the flux matrix data.
- class westpa.cli.tools.w_reweight.RWRate(parent)
Bases:
RWReweight
- subcommand = 'kinetics'
- help_text = 'Generates rate and flux values from a WESTPA simulation via reweighting.'
- default_kinetics_file = 'reweight.h5'
- default_output_file = 'reweight.h5'
- description = 'Calculate average rates from weighted ensemble data using the postanalysis\nreweighting scheme. Bin assignments (usually "assign.h5") and pre-calculated\niteration flux matrices (usually "reweight.h5") data files must have been\npreviously generated using w_reweight matrix (see "w_assign --help" and\n"w_reweight init --help" for information on generating these files).\n\n-----------------------------------------------------------------------------\nOutput format\n-----------------------------------------------------------------------------\nThe output file (-o/--output, usually "kinrw.h5") contains the following\ndataset:\n\n /avg_rates [state,state]\n (Structured -- see below) State-to-state rates based on entire window of\n iterations selected.\n\n /avg_total_fluxes [state]\n (Structured -- see below) Total fluxes into each state based on entire\n window of iterations selected.\n\n /avg_conditional_fluxes [state,state]\n (Structured -- see below) State-to-state fluxes based on entire window of\n iterations selected.\n\nIf --evolution-mode is specified, then the following additional datasets are\navailable:\n\n /rate_evolution [window][state][state]\n (Structured -- see below). State-to-state rates based on windows of\n iterations of varying width. If --evolution-mode=cumulative, then\n these windows all begin at the iteration specified with\n --start-iter and grow in length by --step-iter for each successive\n element. If --evolution-mode=blocked, then these windows are all of\n width --step-iter (excluding the last, which may be shorter), the first\n of which begins at iteration --start-iter.\n\n /target_flux_evolution [window,state]\n (Structured -- see below). Total flux into a given macro state based on\n windows of iterations of varying width, as in /rate_evolution.\n\n /conditional_flux_evolution [window,state,state]\n (Structured -- see below). State-to-state fluxes based on windows of\n varying width, as in /rate_evolution.\n\nThe structure of these datasets is as follows:\n\n iter_start\n (Integer) Iteration at which the averaging window begins (inclusive).\n\n iter_stop\n (Integer) Iteration at which the averaging window ends (exclusive).\n\n expected\n (Floating-point) Expected (mean) value of the observable as evaluated within\n this window, in units of inverse tau.\n\n ci_lbound\n (Floating-point) Lower bound of the confidence interval of the observable\n within this window, in units of inverse tau.\n\n ci_ubound\n (Floating-point) Upper bound of the confidence interval of the observable\n within this window, in units of inverse tau.\n\n stderr\n (Floating-point) The standard error of the mean of the observable\n within this window, in units of inverse tau.\n\n corr_len\n (Integer) Correlation length of the observable within this window, in units\n of tau.\n\nEach of these datasets is also stamped with a number of attributes:\n\n mcbs_alpha\n (Floating-point) Alpha value of confidence intervals. (For example,\n *alpha=0.05* corresponds to a 95% confidence interval.)\n\n mcbs_nsets\n (Integer) Number of bootstrap data sets used in generating confidence\n intervals.\n\n mcbs_acalpha\n (Floating-point) Alpha value for determining correlation lengths.\n\n\n-----------------------------------------------------------------------------\nCommand-line options\n-----------------------------------------------------------------------------\n '
- w_postanalysis_reweight()
This function ensures the data is ready to send in to the estimator and the bootstrapping routine, then does so. Much of this is simply setting up appropriate args and kwargs, then passing them in to the ‘run_calculation’ function, which sets up future objects to send to the work manager. The results are returned, and then written to the appropriate HDF5 dataset. This function is specific for the rates and fluxes from the reweighting method.
- go()
- class westpa.cli.tools.w_reweight.RWStateProbs(parent)
Bases:
RWReweight
- subcommand = 'probs'
- help_text = 'Calculates color and state probabilities via reweighting.'
- default_kinetics_file = 'reweight.h5'
- description = 'Calculate average populations from weighted ensemble data using the postanalysis\nreweighting scheme. Bin assignments (usually "assign.h5") and pre-calculated\niteration flux matrices (usually "reweight.h5") data files must have been\npreviously generated using w_reweight matrix (see "w_assign --help" and\n"w_reweight init --help" for information on generating these files).\n\n-----------------------------------------------------------------------------\nOutput format\n-----------------------------------------------------------------------------\n\nThe output file (-o/--output, usually "direct.h5") contains the following\ndataset:\n\n /avg_state_probs [state]\n (Structured -- see below) Population of each state across entire\n range specified.\n\n /avg_color_probs [state]\n (Structured -- see below) Population of each ensemble across entire\n range specified.\n\nIf --evolution-mode is specified, then the following additional datasets are\navailable:\n\n /state_pop_evolution [window][state]\n (Structured -- see below). State populations based on windows of\n iterations of varying width. If --evolution-mode=cumulative, then\n these windows all begin at the iteration specified with\n --start-iter and grow in length by --step-iter for each successive\n element. If --evolution-mode=blocked, then these windows are all of\n width --step-iter (excluding the last, which may be shorter), the first\n of which begins at iteration --start-iter.\n\n /color_prob_evolution [window][state]\n (Structured -- see below). Ensemble populations based on windows of\n iterations of varying width. If --evolution-mode=cumulative, then\n these windows all begin at the iteration specified with\n --start-iter and grow in length by --step-iter for each successive\n element. If --evolution-mode=blocked, then these windows are all of\n width --step-iter (excluding the last, which may be shorter), the first\n of which begins at iteration --start-iter.\n\nThe structure of these datasets is as follows:\n\n iter_start\n (Integer) Iteration at which the averaging window begins (inclusive).\n\n iter_stop\n (Integer) Iteration at which the averaging window ends (exclusive).\n\n expected\n (Floating-point) Expected (mean) value of the observable as evaluated within\n this window, in units of inverse tau.\n\n ci_lbound\n (Floating-point) Lower bound of the confidence interval of the observable\n within this window, in units of inverse tau.\n\n ci_ubound\n (Floating-point) Upper bound of the confidence interval of the observable\n within this window, in units of inverse tau.\n\n stderr\n (Floating-point) The standard error of the mean of the observable\n within this window, in units of inverse tau.\n\n corr_len\n (Integer) Correlation length of the observable within this window, in units\n of tau.\n\n\nEach of these datasets is also stamped with a number of attributes:\n\n mcbs_alpha\n (Floating-point) Alpha value of confidence intervals. (For example,\n *alpha=0.05* corresponds to a 95% confidence interval.)\n\n mcbs_nsets\n (Integer) Number of bootstrap data sets used in generating confidence\n intervals.\n\n mcbs_acalpha\n (Floating-point) Alpha value for determining correlation lengths.\n\n\n-----------------------------------------------------------------------------\nCommand-line options\n-----------------------------------------------------------------------------\n'
- w_postanalysis_stateprobs()
This function ensures the data is ready to send in to the estimator and the bootstrapping routine, then does so. Much of this is simply setting up appropriate args and kwargs, then passing them in to the ‘run_calculation’ function, which sets up future objects to send to the work manager. The results are returned, and then written to the appropriate HDF5 dataset. This function is specific for the color (steady-state) and macrostate probabilities from the reweighting method.
- go()
- class westpa.cli.tools.w_reweight.RWAll(parent)
Bases:
RWMatrix
,RWStateProbs
,RWRate
- subcommand = 'all'
- help_text = 'Runs the full suite, including the generation of the flux matrices.'
- default_kinetics_file = 'reweight.h5'
- default_output_file = 'reweight.h5'
- description = 'A convenience function to run init/kinetics/probs. Bin assignments,\nincluding macrostate definitions, are required. (See\n"w_assign --help" for more information).\n\nFor more information on the individual subcommands this subs in for, run\nw_reweight {init/kinetics/probs} --help.\n\n-----------------------------------------------------------------------------\nCommand-line options\n-----------------------------------------------------------------------------\n'
- go()
- class westpa.cli.tools.w_reweight.RWAverage(parent)
Bases:
RWStateProbs
,RWRate
- subcommand = 'average'
- help_text = 'Averages and returns fluxes, rates, and color/state populations.'
- default_kinetics_file = 'reweight.h5'
- default_output_file = 'reweight.h5'
- description = 'A convenience function to run kinetics/probs. Bin assignments,\nincluding macrostate definitions, are required. (See\n"w_assign --help" for more information).\n\nFor more information on the individual subcommands this subs in for, run\nw_reweight {kinetics/probs} --help.\n\n-----------------------------------------------------------------------------\nCommand-line options\n-----------------------------------------------------------------------------\n'
- go()
- class westpa.cli.tools.w_reweight.WReweight
Bases:
WESTMasterCommand
,WESTParallelTool
- prog = 'w_reweight'
- subcommands = [<class 'westpa.cli.tools.w_reweight.RWMatrix'>, <class 'westpa.cli.tools.w_reweight.RWAverage'>, <class 'westpa.cli.tools.w_reweight.RWRate'>, <class 'westpa.cli.tools.w_reweight.RWStateProbs'>, <class 'westpa.cli.tools.w_reweight.RWAll'>]
- subparsers_title = 'reweighting kinetics analysis scheme'
- westpa.cli.tools.w_reweight.entry_point()