LPATH API Documentation

lpath.discretize	Discretize your MD trajectories (or WE simulations) into states.
lpath.extract	Extract successful trajectories from MD trajectories (or WE simulations).
lpath.match	Pattern match your extracted trajectories and cluster pathways classes.
lpath.plot	Plot your lpath results.
lpath.lpath	Main function to run everything! Discretize, extract, match, in that order.

Shared Parameters

All steps take the following parameters.

usage: lpath {discretize,extract,match,plot,all} [-h] [-od OUT_DIR]
                                                 [-st STRIDE] [-s] [--debug]
                                                 [-we] [-W WEST_NAME]
                                                 [-A ASSIGN_NAME] [-r RCFILE]

Shared Parameters

-od, --out-dir, --output-directory

Directory to save your output files. Path relative to $PWD. Default: succ_traj

Default: 'succ_traj'

-st, --stride

Dictates how much data to use in analysis. If used in standard MD, this will be the step size (at a per file basis during load time). For a WE simulation, this will be how many sub-tau frames used from each segment, starting from the last frame and then counting backwards.

Default: 1

-s, --stats, --statistics

Enable results statistics output.

Default: False

--debug, -v

Enable debug mode.

Default: False

WE-specific Shared Parameters

-we, -WE, --weighted-ensemble, --WEIGHTED-ENSEMBLE

Run analysis on a weight ensemble simulation.

Default: False

-W, --west, --WEST_H5FILE, --west-h5file

The path to your h5 file. If it’s a multi.h5 file from w_multi_west, make sure the --ibstates option successfully merged your initial and basis states. If you’re analyzing regular MD trajectories, ignore.

Default: 'west.h5'

-A, --assign, --assign-h5file, --ASSIGN-H5FILE

Path to your assign.h5 file for WE simulations. Not used if analyzing an MD trajectory.

Default: 'ANALYSIS/TEST/assign.h5'

-r, --rcfile

The path to your RCFILE / WEST run-time configuration file (default: ‘west.cfg’)

Default: 'west.cfg'

Discretization Step

The discretize step allows you to assign MD trajectories (or WE simulations) into discrete states.

usage: lpath discretize [-h] [--input INPUT_NAME] [--output EXTRACT_INPUT]
                        [--assign-func ASSIGN_FUNC] [-ar ASSIGN_ARGS]

Discretize Specific Parameters

--input, -i, -I, -di, -DI

The path to your input file for discretization. Ideally, this would be a text file or a NumPy file with the features use to define source and target states. If the -WE` flag is specified, w_assign will run on --west-h5file instead to label your states.

Default: 'input.dat'

--output, -o, -O, -do, -DO

The path to your output numpy file for after discretization. If -WE flag is specified, --assign-h5file will be used instead.

Default: 'states.npy'

--assign-func, -af, --assign-function

User provided function used to discretize MD trajectories.

Default: 'default_assign'

WE-specific Discretize Parameters

-ar, --assign-args, --assign-arguments

A string of arguments to pass onto w_assign as you would input in the command line to w_assign. Either use the defaults (leave blank for the TEST scheme in west.cfg or at a minimum, you need to specify --config-from-file --scheme NAME_OF_SCHEME to read the config from your west.cfg file. Whatever inputted here takes precedence over any –west-file, –assign-file, and –rc-file options for LPATH.

Default: ''

Discretize your MD trajectories (or WE simulations) into states.

lpath.discretize.assign(input_array)

This is an example function for mapping a list of features to state IDs. This should be replaced by passing a similar function (catered to your system) to --assign-function.

Parameters:

input_array (numpy.ndarray or list) – An array generated from expanded_load.

Returns:

state_list – A list containing

Return type:

list

lpath.discretize.main(arguments)

Main function that executes the whole match step.

If it’s been run with arguments.we, it’ll just run w_assign.

Parameters:

arguments (argparse.Namespace) – A Namespace object will all the necessary parameters.

Extract Step

The extract step allows you to extract successful trajectories from MD trajectories (or WE simulations) based on definitions from disretize.

usage: lpath extract [-h] [--extract-input EXTRACT_INPUT]
                     [--extract-output EXTRACT_OUTPUT]
                     [--source SOURCE_STATE_NUM] [--target TARGET_STATE_NUM]
                     [--pcoord] [--extract-pcoord FEATURIZATION_NAME]
                     [--feature-stride FEATURE_STRIDE] [--trace-basis]
                     [--exclude-min-length EXCLUDE_SHORT] [--use-ray]
                     [--no-ray] [--threads THREADS] [--first-iter FIRST_ITER]
                     [--last-iter LAST_ITER] [--hdf5] [--aux [AUXDATA ...]]
                     [-aa [AUXDATA]] [--rewrite-weights] [--out-traj]
                     [--out-traj-ext OUT_TRAJ_EXT]
                     [--out-state-ext OUT_STATE_EXT] [--out-top OUT_TOP]

Extract Specific Parameters

--extract-input, -ei, -EI

The path to your output numpy file from discretize step. If the -WE flag is specified, this will be ignored as --west-h5file and --assign-h5file will be used instead.

Default: 'states.npy'

--extract-output, -eo, -EO

Name of the output pickle object file. This will be saved relative to $pwd.

Default: 'succ_traj/output.pickle'

--source, -ss, --source-state, --SOURCE-STATE

Index of the source state. If the -WE flag is specified, this should match the index specified in w_assign.

Default: 0

--target, -ts, --target-state, --TARGET-STATE

Index of the target state. If the -WE flag is specified, this should match the index specified in w_assign.

Default: 1

--pcoord, -pc, -p

Output progress coordinate (or featurization) into the pickle file. If the -WE flag is specified, the data will be obtained from the H5 file. Otherwise, do specify a file name using the --extract-featurization flag.

Default: False

--extract-pcoord, -ef, -EF, --extract-featurization

The path to your feature dataset to be saved in the output pickle file. For most people, this would be the input used for the discretize step. This option is only for standard simulations. You MUST manually specify the --pcoord flag for this to work.

--feature-stride, -fs

Dictates the step size to which the --extract-featurization is read in. You will want this to match --stride used in discretize. Ignored for a WE simulation.

Default: 1

--trace-basis, -tb, -b

Whether to trace all the way back to the “basis state”. False by default. For WE simulations, this (as it is aptly named) output the trajectory all the way back to the basis state. For standard simulations, This will either be the first frame of the trajectory or, if it had previously reached the target state, the first time it returned to the source state after it has left the target state.

Default: False

--exclude-min-length, -el, --exclude-length, --exclude-short

Exclude trajectories shorter than provided value during matching. Default is 0, which will include trajectories of all lengths.

Default: 0

Extract Ray options

--use-ray, -R, --ray

Use Ray work manager. On by default.

Default: True

--no-ray, -NR

Do not use Ray. This overrides --use-ray.

Default: True

--threads, -t

Number of threads to use with Ray. The default of 0 uses all available resources detected.

Default: 0

WE-specific Extract Parameters

--first-iter, --first, --FIRST-ITER

First iteration to look for successful trajectories, inclusive.

Default: 1

--last-iter, --last, --LAST-ITER

Last iteration to look for successful trajectories, inclusive. Default is 0, which will use all available iterations.

Default: 0

--hdf5, -hdf5

Default: False

--aux, -a, --AUX, --auxdata, --AUXDATA

Names of additional auxiliary datasets to be combined.

-aa, --auxall

Combine all auxiliary datasets.

--rewrite-weights, -rw

Option to zero out the weights of all segments that are not part of the successful trajectory ensemble. Note this generates a new H5 file with the _succ suffix added, meaning the default name is west_succ.h5.

Default: False

--out-traj, -oj, --output-trajectory

Option to output trajectory files into out_dir.

Default: False

--out-traj-ext, -oe, --output-trajectory-extension

Extension of the segment files. The name of the file is assumed to be seg, meaning the default name of the file is seg.nc.

Default: '.nc'

--out-state-ext, -se, --output-state-extension

Extension of the restart files. The name of the file is assumed to be seg, meaning the default name the file is seg.ncrst.

Default: '.ncrst'

--out-top, -ot, --output-topology

Name of the topology file. Name is relative to $PWD.

Default: 'system.prmtop'

Extract successful trajectories from MD trajectories (or WE simulations).

lpath.extract.assign_color_frame(source_indices, target_indices)

Assign color to each target frame.

Parameters:

• source_indices (list or numpy.ndarray) – A list or array of indices assigned source state.

• target_indices (list or numpy.ndarray) – A list or array of indices assigned sink state.

Returns:

target_colors – A list mapping each target index in target_indices with a frame it should trace back to. Essentially the frame when the color of the trajectory switched from sink to source.

Return type:

dictionary

lpath.extract.clean_self_to_self(input_array)

Clean up duplicates which might contain self to self transitions.

Parameters:

input_array (list) – A list or numpy array of the shape (n_transitions, 2).

Returns:

output_array – A reduced list or numpy array of the shape (n_transitions, 2).

Return type:

numpy.ndarray

lpath.extract.count_tmatrix_row(source_index, trajectory, n_states, source_num, target_num)

Count transitions for the source –> states row for the weights. Used to calculate the weights of each successful trajectory.

Parameters:

• source_index (numpy.ndarray) – An array of indices where it last visited the source state.

• trajectory (numpy.ndarray) – A list of the states as inputted.

• n_states (int) – Number of total states defined. Does not include the Unknown State.

• source_num (int) – Index of the source state as defined in discretize.

• target_num (int) – Index of the target state as defined in discretize.

Returns:

st_weight – Total weight of all the source –> target transitions.

Return type:

float

lpath.extract.create_pickle_obj(transitions, states, weight, features=None)

Main function that transforms a list of frame transitions into the pickle object. For standard simulations only.

Parameters:

• transitions (list or numpy.ndarray) – A list of shape (successful transitions, 2). Indicates the start/end frame a transition has been made.

• states (list) – A list of the states as inputted.

• weight (float) – Weight of each successful transition.

• features (list or numpy.ndarray or None) – If specified by the user, you can save extra information in to the pickle object.

Returns:

output_list – An list to be outputted, prepared for the output.pickle.

Return type:

list

lpath.extract.find_min_distance(ref_value, indices)

Search for the closest value in indices that is >= to ref_value.

Parameters:

• ref_value (int or float) – Reference point you want to anchor the search.

• indices (list or numpy.ndarray) – A list or array of potential values you want to search for.

Returns:

minimum value – The closest index (in indices) to ref_value.

Return type:

float, int

lpath.extract.find_transitions(input_array, source_index, target_index)

Find all successful transitions in standard MD simulations.

Parameters:

• input_array (numpy.ndarray) – An array of states assignments. Should be of shape (n_frames).

• source_index (int or float) – The assignment of the source state.

• target_index (int or float) – The assignment of the target state.

Returns:

• source_indices (numpy.ndarray) – An array of all indices where the input data visited the source state.

• target_indices (numpy.ndarray) – An array of all indices where the input data visited the target state.

• transitions (numpy.ndarray) – An array of shape (n_transitions, 2) showing all steps.

lpath.extract.main(arguments)

Main function that executes the match step.

Parameters:

arguments (argparse.Namespace) – A Namespace object will all the necessary parameters.

lpath.extract.raise_warnings(output_array, statistics)

Raise warnings and Errors towards common failure modes.

Parameters:

• output_array (list) – A list of lists containing traced trajectories

• statistics (bool, default: False) – A flag to report statistics.

lpath.extract.standard(arguments)

Main function that executes the whole standard extract procedure. :Parameters: arguments (argparse.Namespace) – A Namespace object will all the necessary parameters.

lpath.extract.we(arguments)

Main function that executes the whole WE extract procedure.

Parameters:

arguments (argparse.Namespace) – A Namespace object will all the necessary parameters.

Match Step

The match step allows you to compare and cluster pathways from the extract step.

usage: lpath match [-h] [--input-pickle EXTRACT_OUTPUT]
                   [--output-pickle OUTPUT_PICKLE] [--cl-output CL_OUTPUT]
                   [--match-exclude-min-length EXCLUDE_SHORT]
                   [--reassign REASSIGN_METHOD] [--subsequence | --substring |
                   --match-metric MATCH_METRIC] [--match-length-reward-off]
                   [--remove-ends] [--condense CONDENSE] [--no-remake]
                   [--remake-file DMATRIX_SAVE]
                   [--remake-parallel DMATRIX_PARALLEL]
                   [--clusters [CLUSTERS ...]] [--ex-h5]
                   [--file-pattern FILE_PATTERN]

Match Specific Parameters

--input-pickle, -ip, --IP, --pickle

Path to pickle object from the extract step.

Default: 'succ_traj/output.pickle'

--output-pickle, -op, --OP

Path to reassigned object to be outputted from the match step.

Default: 'succ_traj/pathways.pickle'

--cl-output, -co, --cluster-label-output, --cluster-labels-output

Output file location for cluster labels.

Default: 'succ_traj/cluster_labels.npy'

--match-exclude-min-length, -me, --match-exclude-length, --match-exclude-short

Exclude trajectories shorter than provided value during matching. Default is 0, which will include trajectories of all lengths.

Default: 0

--reassign, -ra, --reassign-method, --reassign-function

Reassign method to use. Could be one of the defaults or a module to load. Defaults are reassign_identity, reassign_statelabel, reassign_segid, and reassign_custom.

Default: 'reassign_identity'

--subsequence, -seq, --longest-common-subsequence

Use the longest common subsequence metric. The final answer is a total of common discontinuous characters. This is the default.

Default: 'longest_common_subsequence'

--substring, -str, --longest-common-substring

Use the longest common substring metric. The final answer is a length of common continuous characters. This is not the default and (probably) should only be used when comparing segment ids with trace_basis turned on in extract.

Default: 'longest_common_subsequence'

--match-metric, -mm, --metric

Use a custom similarity metric for match step. This defaults to longest_common_subsequence.

Default: 'longest_common_subsequence'

--match-length-reward-off, --match-reward-off, -mr, --match-vanilla, -mv, -mp

Revert to “vanilla” form of similarity metric, the version without the reward term for sequences of different length. Default behavior: similarity = 2 * lcs(str1, str2) / (len(str1) + len(str2)). If -mp is invoked: similarity = 2 * lcs(str1, str2) / (len(str1) + len(str2) - (abs(len(str1) - len(str2))/ 2)). See the LPATH manuscript for more information.

Default: False

--remove-ends, -re

Remove the end states (source and sink) during matching.

Default: False

--condense, -cc, --condense-consecutive

Condense consecutively occurring states in state string during matching. Automatically removes repeating characters and repeating pairs (in that order). Takes any non-negative integer as input, corresponding to the n-tuple to be removed. 0 corresponds to no condense, 1 would condense any consecutive characters (e.g., ‘AAAABABC’ –> ‘ABABC’) and 2 would remove any consecutive characters then any consecutive pairs (e.g., ‘ABABABABAAAAA’ –> ‘ABA’), etc. Defaults to 0.

Default: 0

--no-remake, -dN, -nd

Do not remake distance matrix.

Default: True

--remake-file, --remade-file, -dF

Path to pre-calculated distance matrix. Make sure the --no-remake flag is specified.

Default: 'succ_traj/distmat.npy'

--remake-parallel, -dP

Number of jobs to run with the pairwise distance calculations. The default=None issues one job. A value of -1 uses all available resources. This is directly passed to the n_jobs parameter for sklearn.metrics.pairwise_distances().

--clusters, -c

Clusters to export. 0-indexed. The default None will output all clusters.

WE-specific Match Parameters

--ex-h5, -ex, --export-h5

Export each cluster as an independent H5 file.

Default: False

--file-pattern, -fp, --fp

Pattern to name per-cluster HDF5 files.

Default: 'west_succ_c{}.h5'

Pattern match your extracted trajectories and cluster pathways classes.

lpath.match.ask_number_clusters(num_clusters=None, timeout=None)

Asks how many clusters you want to separate the trajectories into.

lpath.match.calc_dist(seq1, seq2, dictionary, pbar, condense=0)

Pattern match and calculate the similarity between two state string sequences.

Parameters:

• seq1 (numpy.ndarray) – First string to be compared.

• seq2 (numpy.ndarray) – Second string to be compared.

• dictionary (dict) – Dictionary mapping state_id (float/int) to state string (characters).

• pbar (tqdm.tqdm) – A tqdm.tqdm object for the progress bar.

• condense (int, default: 0) – Set to a positive int to shorten consecutive characters in state strings.

Returns:

1 - similarity – Similarity score.

Return type:

float

lpath.match.calc_dist_substr(seq1, seq2, dictionary, pbar, condense=0)

Pattern match and calculate the similarity between two state string substrings. Used when you’re comparing segment ids.

Parameters:

• seq1 (numpy.ndarray) – First string to be compared.

• seq2 (numpy.ndarray) – Second string to be compared.

• dictionary (dict) – Dictionary mapping state_id (float/int) to state string (characters).

• pbar (tqdm.tqdm) – A tqdm.tqdm object for the progress bar.

• condense (int, default: 0) – Set to a positive int to shorten consecutive characters in state strings.

Returns:

1 - similarity – Similarity score.

Return type:

float

lpath.match.calc_dist_substr_vanilla(seq1, seq2, dictionary, pbar, condense=0)

Pattern match and calculate the similarity between two state string substrings. Used when you’re comparing segment ids. This version does not include the reward term for segments of different length.

Parameters:

• seq1 (numpy.ndarray) – First string to be compared.

• seq2 (numpy.ndarray) – Second string to be compared.

• dictionary (dict) – Dictionary mapping state_id (float/int) to state string (characters).

• pbar (tqdm.tqdm) – A tqdm.tqdm object for the progress bar.

• condense (int, default: 0) – Set to a positive int to shorten consecutive characters in state strings.

Returns:

1 - similarity – Similarity score.

Return type:

float

lpath.match.calc_dist_vanilla(seq1, seq2, dictionary, pbar, condense=0)

Pattern match and calculate the similarity between two state string sequences. This version does not include the reward term for segments of different length.

Parameters:

• seq1 (numpy.ndarray) – First string to be compared.

• seq2 (numpy.ndarray) – Second string to be compared.

• dictionary (dict) – Dictionary mapping state_id (float/int) to state string (characters).

• pbar (tqdm.tqdm) – A tqdm.tqdm object for the progress bar.

• condense (int, default: 0) – Set to a positive int to shorten consecutive characters in state strings.

Returns:

1 - similarity – Similarity score.

Return type:

float

lpath.match.calc_linkage(distmat)

Given distance matrix, calculate and return the linkage.

lpath.match.condense_string(string: str, n: int) → str

Function that takes in a string and remove any consecutive duplicates. Starts from 1, slowly works up to n.

Parameters:

• string (str) – Input string.

• n (int) – How many consecutive duplicates to remove. 0 for none. 1 for just consecutive characters, 2 for consecutive pairs (e.g., ABABABA –> AB)

lpath.match.determine_clusters(cluster_labels, clusters=None)

Determine how many clusters to output.

Parameters:

• cluster_labels (numpy.ndarray) – An array with cluster assignments for each pathway.

• clusters (list or None) – Straight from the argparser.

Returns:

clusters – A list of clusters to output.

Return type:

list

lpath.match.determine_metric(match_metric, match_vanilla)

Argument processing to determine function to reassign trajectories.

Parameters:

• match_metric (str , default: ‘longest_common_subsequence’) – String from argument.match_metric, straight from argparser.

• match_vanilla (bool, default: False) – Which similarity metric to use. False to use similarity metric with reward term.

Returns:

metric – The matching function.

Return type:

function

lpath.match.determine_reassign(reassign_method)

Argument processing to determine function to reassign trajectories.

Parameters:

reassign_method (str , default: ‘reassign_identity’) – String from argument.reassign_identity, straight from argparser.

Returns:

reassign – The reassignment function.

Return type:

function

lpath.match.determine_rerun(z, out_path='plots', mpl_colors=['tomato', 'dodgerblue', 'orchid', 'mediumseagreen', 'darkorange', 'mediumpurple', 'grey'], ax=None, timeout=None)

Asks if you want to regenerate the dendrogram.

Parameters:

• z (numpy.ndarray) – A numpy.ndarray from sch.linkage.

• out_path (str, default: ‘plots’) – Path to output plots.

• mpl_colors (list or default_dendrogram_colors) – A list of colors for coloring the dendrogram.

• ax (matplotlib.Axes, Default: None) – Matplotlib.Axes object to be inherited.

• timeout (int, default: 30) – Input timeout in seconds.

lpath.match.export_pickle(pathways, output_path)

Option to output the reassigned pickle object.

Parameters:

• pathways (numpy.ndarray) – A reassigned pathway object

• output_path (str) – Path to output pickle object.

lpath.match.export_std_files(data_arr, weights, cluster_labels, clusters=None, out_dir='succ_traj')

Export data for standard simulations.

Parameters:

• data_arr (numpy.ndarray) – The array with all the pathways.

• weights (numpy.ndarray) – Weight information of the pathways.

• cluster_labels (numpy.ndarray) – An array with cluster assignments for each pathway.

• clusters (list or None) – A list of clusters to output, straight from the argparser.

• out_dir (str) – Directory to output files.

lpath.match.export_we_files(data_arr, weights, cluster_labels, clusters, file_pattern='west_succ_c{}.h5', out_dir='succ_traj', west_name='west.h5')

Export each group of successful trajectories into independent west.h5 file.

Parameters:

• data_arr (numpy.ndarray) – The array with all the pathways.

• weights (numpy.ndarray) – Weight information of the pathways.

• cluster_labels (numpy.ndarray) – An array with cluster assignments for each pathway.

• clusters (list or None) – A list of clusters to output.

• file_pattern (str) – String pattern of how files should be outputted.

• out_dir (str) – Directory to output files.

• west_name (str) – Name of west.h5 file to use as base.

lpath.match.gen_dist_matrix(pathways, dictionary, file_name='succ_traj/distmat.npy', remake=True, metric=<function calc_dist>, condense=0, n_jobs=None)

Generate the path_string to path_string similarity distance matrix.

Parameters:

• pathways (numpy.ndarray) – An array with all the sequences to be compared.

• dictionary (dict) – A dictionary to map pathways states to characters.

• file_name (str, default : ‘distmat.npy’) – The file to output the distance matrix.

• remake (bool, default : True) – Indicates whether to remake distance matrix or not.

• metric (bool, default : calc_dist) – Metric function to use.

• condense (int, default: 0) – Set to a positive int to shorten consecutive characters in state strings.

• n_jobs (int, default : None) – Number of jobs to run for the pairwise_distances() calculation. The default issues one job.

Returns:

• distmat (numpy.ndarray) – A condensed form of the distance matrix (Upper Triangle).

• weights (ndarray) – An array of the weights of each successful pathway (as taken from the last frame).

lpath.match.hcluster(z, n_clusters)

Scikit-learn Hierarchical Clustering of the different pathways.

lpath.match.load_data(file_name)

Load in the pickle data from extract.

Parameters:

file_name (str) – File name of the pickle object from extract

Returns:

• data (list) – A list with the data necessary to reassign, as extracted from output.pickle.

• pathways (numpy.ndarray) – An empty array with shapes for iter_id/seg_id/state_id/pcoord_or_auxdata/frame#/weight.

lpath.match.main(arguments)

Main function that executes the whole match step.

Pathways are processed in the following order:

1. Assign extra “padding” frames as unknown state for segments too short.

2. Remove pathways that are too short (if specified).

3. Remove end frames (source and target states).

4. During pairwise calculation, condense the frames during comparison and remove frames in “unknown” state.

Parameters:

arguments (argparse.Namespace) – A Namespace object will all the necessary parameters.

lpath.match.process_shorter_traj(pathways, dictionary, threshold_length, remove_ends)

Assigns a non-state to pathways which are shorter than the max length.

Parameters:

• pathways (numpy.ndarray or list) – An array with shapes for iter_id/seg_id/state_id/pcoord_or_auxdata/frame#/weight.

• dictionary (dict) – Maps each state_id to a corresponding string.

• threshold_length (int or float, default: 0) – A parameter such that trajectories < threshold_length are excluded from pattern matching.

• remove_ends (bool, default: False) – If True, remove the first and last frames (source and target frames).

lpath.match.reassign_custom(data, pathways, dictionary, assign_file=None)

Reclassify/assign frames into different states. This is highly specific to the system. If w_assign’s definition is sufficient, you can proceed with what’s made in the previous step using reassign_identity.

In this example, the dictionary maps state idx to its corresponding state_string. We suggest using alphabets as states.

Parameters:

• data (list) – An array with the data necessary to reassign, as extracted from output.pickle.

• pathways (numpy.ndarray) – An empty array with shapes for iter_id/seg_id/state_id/pcoord_or_auxdata/frame#/weight.

• dictionary (dict) – An empty dictionary obj for mapping state_id with state string. The last entry in the dictionary should be the “unknown” state.

• assign_file (str, default : None) – A string pointing to the assign.h5 file. Needed as a parameter for all functions, but is ignored if it’s an MD trajectory.

Returns:

dictionary – A dictionary mapping each state_id (float/int) with a state string (character). The last entry in the dictionary should be the “unknown” state.

Return type:

dict

lpath.match.reassign_identity(data, pathways, dictionary, assign_file=None)

Use assign.h5 states as is. Does not attempt to map assignment to state_labels from assign.h5.

Parameters:

• data (list) – An list with the data necessary to reassign, as extracted from output.pickle.

• pathways (numpy.ndarray) – An empty array with shapes for iter_id/seg_id/state_id/pcoord_or_auxdata/frame#/weight.

• dictionary (dict) – An empty dictionary obj for mapping state_id with state string.

• assign_file (str) – A string pointing to the assign.h5 file. Needed as a parameter, but ignored if it’s an MD trajectory.

Returns:

dictionary – A dictionary mapping each state_id (float/int) with a state string (character).

Return type:

dict

lpath.match.reassign_segid(data, pathways, dictionary, assign_file=None)

Use seg ids as state labels.

Parameters:

• data (list) – An list with the data necessary to reassign, as extracted from output.pickle.

• pathways (numpy.ndarray) – An empty array with shapes for iter_id/seg_id/state_id/pcoord_or_auxdata/frame#/weight.

• dictionary (dict) – An empty dictionary obj for mapping state_id with state string.

• assign_file (str) – A string pointing to the assign.h5 file. Needed as a parameter, but ignored if it’s an MD trajectory.

Returns:

dictionary – A dictionary mapping each state_id (float/int) with a state string (character).

Return type:

dict

lpath.match.reassign_statelabel(data, pathways, dictionary, assign_file)

Use assign.h5 states as is with state_labels. Does not reclassify/assign frames into new states.

In this example, the dictionary maps state idx to its state_labels, as defined in the assign.h5. We suggest using alphabets as state_labels to allow for more than 9 states.

Parameters:

• data (list) – An list with the data necessary to reassign, as extracted from output.pickle.

• pathways (numpy.ndarray) – An empty array with shapes for iter_id/seg_id/state_id/pcoord_or_auxdata/frame#/weight.

• dictionary (dict) – An empty dictionary obj for mapping state_id with “state string”.

• assign_file (str) – A string pointing to the assign.h5 file. Needed as a parameter, but ignored if it’s an MD trajectory.

Returns:

dictionary – A dictionary mapping each state_id (float/int) with a state string (character).

Return type:

dict

lpath.match.report_statistics(n_clusters, cluster_labels, weights, segid_status=False)

Report statistics about the final clusters.

Parameters:

• n_clusters (int) – Number of clusters.

• cluster_labels (numpy.ndarray) – An array mapping pathways to cluster

• weights (numpy.ndarray) – Weight information

• segid_status (bool, default: False) – Status of whether we’re using seg_ids or not.

lpath.match.select_rep(data_arr, weights, cluster_labels, icluster)

Small function to determine representative array/weight

Parameters:

• data_arr (numpy.ndarray) – The array with all the pathways.

• weights (numpy.ndarray) – Weight information of the pathways.

• cluster_labels (numpy.ndarray) – An array with cluster assignments for each pathway.

• icluster (int) – Index of cluster to look at.

Returns:

• data_cl (list) – A list of pathways from icluster.

• rep_weight (float) – The weight of the representative structure of icluster.

lpath.match.tostr(b)

Convert a nonstandard string object b to str with the handling of the case where b is bytes.

lpath.match.visualize(z, threshold, out_path='plots', show_fig=True, mpl_colors=None, ax=None)

Visualize the Dendrogram to determine hyper-parameters (n-clusters). Theoretically done only once to check.

Returns:

plt.gca() – A matplotlib.Axes object, which should be the axes which is used to plot the dendrogram.

Return type:

matplotlib.Axes

Plot Step

The plot step allows you to plot relevant plots from the data generated in the match step.

usage: lpath plot [-h] [-ipl OUTPUT_PICKLE] [-icl CL_OUTPUT]
                  [--plot-dmatrix-file DMATRIX_SAVE]
                  [--plot-out-path OUT_PATH] [-sty MPL_STYLES]
                  [-mpl MATPLOTLIB_ARGS] [-col MPL_COLORS [MPL_COLORS ...]]
                  [--dendrogram-threshold DENDROGRAM_THRESHOLD] [--plots-hide]
                  [--n-clusters NUM_CLUSTERS] [--timeout PLOT_TIMEOUT]
                  [--relabel RELABEL_METHOD]

Plot Specific Parameters

-ipl, --IPL, --plot, --plot-input

Path to pickle object from the match step.

-icl, --ICL, --plot-cl, --plot-cluster-label

Input file location for cluster labels.

--plot-dmatrix-file, -pdF, -pdf, -PDF

Path to pre-calculated distance matrix. Make sure the --no-remake flag is specified. This is defaulted to what’s provided in match step.

Default: 'succ_traj/distmat.npy'

--plot-out-path, -pod, -POD, --plot-output-path

Directory to save your plotting output files. Path relative to $PWD. Default: plots

Default: 'plots'

-sty, --STY, --mpl-styles, --matplotlib-styles

Path to custom style script. Defaults to our recommendations.

Default: 'default'

-mpl, --MPL, --matplotlib-args, --mpl-subplot-args

A string of kwargs to pass onto matplotlib.pyplot.subplots() function. Keywords should be separated by , ``, and the value should be assigned without space. Example: ``-mpl="nrows=1, ncols=5".

Default: ''

-col, --colors, --mpl-col, --mpl-colors

A sequence of matplotlib colors names separated by spaces. E.g., --colors blue tab:green. The last color will be reserved for branches above the threshold horizontal line if used to plot a dendrogram.

Default: ['tomato', 'dodgerblue', 'orchid', 'mediumseagreen', 'darkorange', 'mediumpurple', 'grey']

--dendrogram-threshold, -pdt, --dendro-threshold, -dt, --plot-dendro-threshold, --plot-dendrogram-threshold

Horizontal threshold line for the dendrogram.

Default: 0.5

--plots-hide, -pth, --dendrogram-hide, -pdh, --dendro-hide, -dh

Do not show dendrogram. Overrides --dendrogram-show.

Default: True

--n-clusters, -nc, --num-clusters

For cases where you know in advance how many clusters you want for the hierarchical clustering.

--timeout, -pto, --plot-timeout

Timeout (in seconds) for asking input.

--relabel, -prl, --plot-relabel-method, --plot-relabel-method

Relabel method to use. Could be one of the defaults or a module to load. Defaults are relabel_identity, and relabel_custom.

Default: 'relabel_identity'

Plot your lpath results.

class lpath.plot.LPATHPlot(arguments)

A class consisting of a bunch of pre-made data for plotting.

determine_plot_axes(ax_idx=None, separate=False)

Determine which axes to plot and return a list of axes to plot.

Parameter

ax_idxlist of int or None, default: None

Which axes index to plot the graph.

separatebool, default: False

Whether to plot each cluster in separate subplots or not.

plot()

This is an example method for plotting things. You can set up subplots with fig and ax first with plt_config().

plot_network(ax_idx=None, separate=False)

Plot network of target iteration vs. iteration number history number with customized colors defined by --mpl_colors.

Parameter

ax_idxlist of int or None, default: None

Which axes index to plot the graph.

separatebool, default: False

Whether to plot each cluster in separate subplots or not.

plotdendro_branch_colors(ax_idx=None)

Plot dendrogram branches with customized colors defined by --mpl_colors.

Parameters:

ax_idx (list of int or None, default: None) – Which axes index to plot the graph.

plothist_event_duration(ax_idx=None, separate=False)

Plot histogram of vent duration time vs. iteration number history number with customized colors defined by --mpl_colors.

Parameter

ax_idxlist of int or None, default: None

Which axes index to plot the graph.

separatebool, default: False

Whether to plot each cluster in separate subplots or not.

plothist_target_iter(ax_idx=None, separate=False)

Plot network of transitions between different states.

Parameter

ax_idxlist of int or None, default: None

Which axes index to plot the graph.

separatebool, default: False

Whether to plot each cluster in separate subplots or not.

plothist_weight_cluster(ax_idx=None)

Plot histogram of cluster number vs. weight.

Parameter

ax_idxlist of int or None, default: None

Which axes index to plot the graph.

plt_config(ax_idx=None, separate=None)

Process matplotlib arguments and append fig/axis objects to class.

ax_idx = list or int

Index or list of indic

lpath.plot.determine_relabel(relabel_method)

Process argparse arguments to determine function to relabel trajectories.

Parameters:

relabel_method (str , default: ‘relabel_identity’) – String from argument.plot_relabel_identity, straight from argparser.

Returns:

relabel – The relabelling function.

Return type:

function

lpath.plot.main(arguments)

Main function that executes the whole plot step.

Parameters:

arguments (argparse.Namespace) – A Namespace object will all the necessary parameters.

lpath.plot.plot_custom()

Example custom function for custom plot script for plotting with the LPATHPlot class. In here, we plot each cluster in a separate subplot, and pathway onto a phi

lpath.plot.process_plot_args(arguments)

Process plot arguments.

Parameters:

arguments (argparse.Namespace) – Arguments Namespace object as processed by argparser.

Returns:

relabel – The relabeling function.

Return type:

function

lpath.plot.relabel_custom(data)

Relabel pathways (pcoord or states) from lpath match frames into different values. This is highly specific to the system. If lpath match’s definition is sufficient, you can proceed with what’s made in the previous step using relabel_identity.

In this example, we’re modifying it so the phi/psi angles (columns 3 and 4) are in (-180,180] instead.

Parameters:

data (LPATHPlot class) – An LPATHPlot class object.

Returns:

• pathways (numpy.ndarray) – A modified array with shapes for iter_id/seg_id/state_id/pcoord_or_auxdata/frame#/weight.

• cluster_labels (numpy.ndarray) – A modified array of cluster labels. Passed here just in case you want to do something fancy.

lpath.plot.relabel_identity(data)

Use lpath.match states as is. Does not attempt to relabel anything.

Parameters:

data (LPATHPlot class) – An LPATHPlot class object.

Returns:

• pathways (numpy.ndarray) – A (not-modified) array with shapes for iter_id/seg_id/state_id/pcoord_or_auxdata/frame#/weight.

• cluster_labels (numpy.ndarray) – A (not-modified) array of cluster labels. Passed here just in case you want to do something fancy.

All LPATH Steps

usage: lpath all [-h] [-od OUT_DIR] [-st STRIDE] [-s] [--debug] [-we]
                 [-W WEST_NAME] [-A ASSIGN_NAME] [-r RCFILE]
                 [--input INPUT_NAME] [--output EXTRACT_INPUT]
                 [--assign-func ASSIGN_FUNC] [-ar ASSIGN_ARGS]
                 [--extract-input EXTRACT_INPUT]
                 [--extract-output EXTRACT_OUTPUT] [--source SOURCE_STATE_NUM]
                 [--target TARGET_STATE_NUM] [--pcoord]
                 [--extract-pcoord FEATURIZATION_NAME]
                 [--feature-stride FEATURE_STRIDE] [--trace-basis]
                 [--exclude-min-length EXCLUDE_SHORT] [--use-ray] [--no-ray]
                 [--threads THREADS] [--first-iter FIRST_ITER]
                 [--last-iter LAST_ITER] [--hdf5] [--aux [AUXDATA ...]]
                 [-aa [AUXDATA]] [--rewrite-weights] [--out-traj]
                 [--out-traj-ext OUT_TRAJ_EXT] [--out-state-ext OUT_STATE_EXT]
                 [--out-top OUT_TOP] [--input-pickle EXTRACT_OUTPUT]
                 [--output-pickle OUTPUT_PICKLE] [--cl-output CL_OUTPUT]
                 [--match-exclude-min-length EXCLUDE_SHORT]
                 [--reassign REASSIGN_METHOD] [--subsequence | --substring |
                 --match-metric MATCH_METRIC] [--match-length-reward-off]
                 [--remove-ends] [--condense CONDENSE] [--no-remake]
                 [--remake-file DMATRIX_SAVE]
                 [--remake-parallel DMATRIX_PARALLEL]
                 [--clusters [CLUSTERS ...]] [--ex-h5]
                 [--file-pattern FILE_PATTERN] [-ipl OUTPUT_PICKLE]
                 [-icl CL_OUTPUT] [--plot-dmatrix-file DMATRIX_SAVE]
                 [--plot-out-path OUT_PATH] [-sty MPL_STYLES]
                 [-mpl MATPLOTLIB_ARGS] [-col MPL_COLORS [MPL_COLORS ...]]
                 [--dendrogram-threshold DENDROGRAM_THRESHOLD] [--plots-hide]
                 [--n-clusters NUM_CLUSTERS] [--timeout PLOT_TIMEOUT]
                 [--relabel RELABEL_METHOD]

Shared Parameters

-od, --out-dir, --output-directory

Directory to save your output files. Path relative to $PWD. Default: succ_traj

Default: 'succ_traj'

-st, --stride

Dictates how much data to use in analysis. If used in standard MD, this will be the step size (at a per file basis during load time). For a WE simulation, this will be how many sub-tau frames used from each segment, starting from the last frame and then counting backwards.

Default: 1

-s, --stats, --statistics

Enable results statistics output.

Default: False

--debug, -v

Enable debug mode.

Default: False

WE-specific Shared Parameters

-we, -WE, --weighted-ensemble, --WEIGHTED-ENSEMBLE

Run analysis on a weight ensemble simulation.

Default: False

-W, --west, --WEST_H5FILE, --west-h5file

The path to your h5 file. If it’s a multi.h5 file from w_multi_west, make sure the --ibstates option successfully merged your initial and basis states. If you’re analyzing regular MD trajectories, ignore.

Default: 'west.h5'

-A, --assign, --assign-h5file, --ASSIGN-H5FILE

Path to your assign.h5 file for WE simulations. Not used if analyzing an MD trajectory.

Default: 'ANALYSIS/TEST/assign.h5'

-r, --rcfile

The path to your RCFILE / WEST run-time configuration file (default: ‘west.cfg’)

Default: 'west.cfg'

Discretize Specific Parameters

--input, -i, -I, -di, -DI

The path to your input file for discretization. Ideally, this would be a text file or a NumPy file with the features use to define source and target states. If the -WE` flag is specified, w_assign will run on --west-h5file instead to label your states.

Default: 'input.dat'

--output, -o, -O, -do, -DO

The path to your output numpy file for after discretization. If -WE flag is specified, --assign-h5file will be used instead.

Default: 'states.npy'

--assign-func, -af, --assign-function

User provided function used to discretize MD trajectories.

Default: 'default_assign'

WE-specific Discretize Parameters

-ar, --assign-args, --assign-arguments

A string of arguments to pass onto w_assign as you would input in the command line to w_assign. Either use the defaults (leave blank for the TEST scheme in west.cfg or at a minimum, you need to specify --config-from-file --scheme NAME_OF_SCHEME to read the config from your west.cfg file. Whatever inputted here takes precedence over any –west-file, –assign-file, and –rc-file options for LPATH.

Default: ''

Extract Specific Parameters

--extract-input, -ei, -EI

The path to your output numpy file from discretize step. If the -WE flag is specified, this will be ignored as --west-h5file and --assign-h5file will be used instead.

Default: 'states.npy'

--extract-output, -eo, -EO

Name of the output pickle object file. This will be saved relative to $pwd.

Default: 'succ_traj/output.pickle'

--source, -ss, --source-state, --SOURCE-STATE

Index of the source state. If the -WE flag is specified, this should match the index specified in w_assign.

Default: 0

--target, -ts, --target-state, --TARGET-STATE

Index of the target state. If the -WE flag is specified, this should match the index specified in w_assign.

Default: 1

--pcoord, -pc, -p

Output progress coordinate (or featurization) into the pickle file. If the -WE flag is specified, the data will be obtained from the H5 file. Otherwise, do specify a file name using the --extract-featurization flag.

Default: False

--extract-pcoord, -ef, -EF, --extract-featurization

The path to your feature dataset to be saved in the output pickle file. For most people, this would be the input used for the discretize step. This option is only for standard simulations. You MUST manually specify the --pcoord flag for this to work.

--feature-stride, -fs

Dictates the step size to which the --extract-featurization is read in. You will want this to match --stride used in discretize. Ignored for a WE simulation.

Default: 1

--trace-basis, -tb, -b

Whether to trace all the way back to the “basis state”. False by default. For WE simulations, this (as it is aptly named) output the trajectory all the way back to the basis state. For standard simulations, This will either be the first frame of the trajectory or, if it had previously reached the target state, the first time it returned to the source state after it has left the target state.

Default: False

--exclude-min-length, -el, --exclude-length, --exclude-short

Exclude trajectories shorter than provided value during matching. Default is 0, which will include trajectories of all lengths.

Default: 0

Extract Ray options

--use-ray, -R, --ray

Use Ray work manager. On by default.

Default: True

--no-ray, -NR

Do not use Ray. This overrides --use-ray.

Default: True

--threads, -t

Number of threads to use with Ray. The default of 0 uses all available resources detected.

Default: 0

WE-specific Extract Parameters

--first-iter, --first, --FIRST-ITER

First iteration to look for successful trajectories, inclusive.

Default: 1

--last-iter, --last, --LAST-ITER

Last iteration to look for successful trajectories, inclusive. Default is 0, which will use all available iterations.

Default: 0

--hdf5, -hdf5

Default: False

--aux, -a, --AUX, --auxdata, --AUXDATA

Names of additional auxiliary datasets to be combined.

-aa, --auxall

Combine all auxiliary datasets.

--rewrite-weights, -rw

Option to zero out the weights of all segments that are not part of the successful trajectory ensemble. Note this generates a new H5 file with the _succ suffix added, meaning the default name is west_succ.h5.

Default: False

--out-traj, -oj, --output-trajectory

Option to output trajectory files into out_dir.

Default: False

--out-traj-ext, -oe, --output-trajectory-extension

Extension of the segment files. The name of the file is assumed to be seg, meaning the default name of the file is seg.nc.

Default: '.nc'

--out-state-ext, -se, --output-state-extension

Extension of the restart files. The name of the file is assumed to be seg, meaning the default name the file is seg.ncrst.

Default: '.ncrst'

--out-top, -ot, --output-topology

Name of the topology file. Name is relative to $PWD.

Default: 'system.prmtop'

Match Specific Parameters

--input-pickle, -ip, --IP, --pickle

Path to pickle object from the extract step.

Default: 'succ_traj/output.pickle'

--output-pickle, -op, --OP

Path to reassigned object to be outputted from the match step.

Default: 'succ_traj/pathways.pickle'

--cl-output, -co, --cluster-label-output, --cluster-labels-output

Output file location for cluster labels.

Default: 'succ_traj/cluster_labels.npy'

--match-exclude-min-length, -me, --match-exclude-length, --match-exclude-short

Exclude trajectories shorter than provided value during matching. Default is 0, which will include trajectories of all lengths.

Default: 0

--reassign, -ra, --reassign-method, --reassign-function

Reassign method to use. Could be one of the defaults or a module to load. Defaults are reassign_identity, reassign_statelabel, reassign_segid, and reassign_custom.

Default: 'reassign_identity'

--subsequence, -seq, --longest-common-subsequence

Use the longest common subsequence metric. The final answer is a total of common discontinuous characters. This is the default.

Default: 'longest_common_subsequence'

--substring, -str, --longest-common-substring

Use the longest common substring metric. The final answer is a length of common continuous characters. This is not the default and (probably) should only be used when comparing segment ids with trace_basis turned on in extract.

Default: 'longest_common_subsequence'

--match-metric, -mm, --metric

Use a custom similarity metric for match step. This defaults to longest_common_subsequence.

Default: 'longest_common_subsequence'

--match-length-reward-off, --match-reward-off, -mr, --match-vanilla, -mv, -mp

Revert to “vanilla” form of similarity metric, the version without the reward term for sequences of different length. Default behavior: similarity = 2 * lcs(str1, str2) / (len(str1) + len(str2)). If -mp is invoked: similarity = 2 * lcs(str1, str2) / (len(str1) + len(str2) - (abs(len(str1) - len(str2))/ 2)). See the LPATH manuscript for more information.

Default: False

--remove-ends, -re

Remove the end states (source and sink) during matching.

Default: False

--condense, -cc, --condense-consecutive

Condense consecutively occurring states in state string during matching. Automatically removes repeating characters and repeating pairs (in that order). Takes any non-negative integer as input, corresponding to the n-tuple to be removed. 0 corresponds to no condense, 1 would condense any consecutive characters (e.g., ‘AAAABABC’ –> ‘ABABC’) and 2 would remove any consecutive characters then any consecutive pairs (e.g., ‘ABABABABAAAAA’ –> ‘ABA’), etc. Defaults to 0.

Default: 0

--no-remake, -dN, -nd

Do not remake distance matrix.

Default: True

--remake-file, --remade-file, -dF

Path to pre-calculated distance matrix. Make sure the --no-remake flag is specified.

Default: 'succ_traj/distmat.npy'

--remake-parallel, -dP

Number of jobs to run with the pairwise distance calculations. The default=None issues one job. A value of -1 uses all available resources. This is directly passed to the n_jobs parameter for sklearn.metrics.pairwise_distances().

--clusters, -c

Clusters to export. 0-indexed. The default None will output all clusters.

WE-specific Match Parameters

--ex-h5, -ex, --export-h5

Export each cluster as an independent H5 file.

Default: False

--file-pattern, -fp, --fp

Pattern to name per-cluster HDF5 files.

Default: 'west_succ_c{}.h5'

Plot Specific Parameters

-ipl, --IPL, --plot, --plot-input

Path to pickle object from the match step.

-icl, --ICL, --plot-cl, --plot-cluster-label

Input file location for cluster labels.

--plot-dmatrix-file, -pdF, -pdf, -PDF

Path to pre-calculated distance matrix. Make sure the --no-remake flag is specified. This is defaulted to what’s provided in match step.

Default: 'succ_traj/distmat.npy'

--plot-out-path, -pod, -POD, --plot-output-path

Directory to save your plotting output files. Path relative to $PWD. Default: plots

Default: 'plots'

-sty, --STY, --mpl-styles, --matplotlib-styles

Path to custom style script. Defaults to our recommendations.

Default: 'default'

-mpl, --MPL, --matplotlib-args, --mpl-subplot-args

A string of kwargs to pass onto matplotlib.pyplot.subplots() function. Keywords should be separated by , ``, and the value should be assigned without space. Example: ``-mpl="nrows=1, ncols=5".

Default: ''

-col, --colors, --mpl-col, --mpl-colors

A sequence of matplotlib colors names separated by spaces. E.g., --colors blue tab:green. The last color will be reserved for branches above the threshold horizontal line if used to plot a dendrogram.

Default: ['tomato', 'dodgerblue', 'orchid', 'mediumseagreen', 'darkorange', 'mediumpurple', 'grey']

--dendrogram-threshold, -pdt, --dendro-threshold, -dt, --plot-dendro-threshold, --plot-dendrogram-threshold

Horizontal threshold line for the dendrogram.

Default: 0.5

--plots-hide, -pth, --dendrogram-hide, -pdh, --dendro-hide, -dh

Do not show dendrogram. Overrides --dendrogram-show.

Default: True

--n-clusters, -nc, --num-clusters

For cases where you know in advance how many clusters you want for the hierarchical clustering.

--timeout, -pto, --plot-timeout

Timeout (in seconds) for asking input.

--relabel, -prl, --plot-relabel-method, --plot-relabel-method

Relabel method to use. Could be one of the defaults or a module to load. Defaults are relabel_identity, and relabel_custom.

Default: 'relabel_identity'

Main function to run it all!

Parameters:

arguments (argparse.Namespace) – A namespace with all the parameter arguments

argparser

All argument parsing from commandline is dealt here.

class lpath.argparser.DefaultArgs

Convenience class that could be used to call all the default arguments for each subparser.

exception lpath.argparser.InvalidArgumentError(message='Invalid Argument.')

Custom Error for cases when invalid arguments are inputted.

lpath.argparser.add_all_args(parser=None)

This block process all the necessary arguments for all steps.

Parameters:

parser (argparse.ArgumentParser) – A parser passed in from each tool. Separated from each function because the catch-all tool to run everything in succession will only have 1 parser. This will auto create a parser if None is passed.

Returns:

parser – Returns an instance of the parser with all the new arguments added in.

Return type:

argparse.ArgumentParser

lpath.argparser.add_common_args(parser=None)

This block process all the common arguments for each module.

Parameters:

parser (argparse.ArgumentParser) – A parser passed in from each tool. Separated from each function because the catch-all tool to run everything in succession will only have 1 parser. This will auto-create a parser if None is passed.

Returns:

parser – Returns an instance of the parser with all the new arguments added in.

Return type:

argparse.ArgumentParser

lpath.argparser.add_discretize_args(parser=None)

This block process all the necessary arguments for the discretize.py module.

Parameters:

parser (argparse.ArgumentParser) – A parser passed in from each tool. Separated from each function because the catch-all tool to run everything in succession will only have 1 parser.

Returns:

parser – Returns an instance of the parser with all the new arguments added in.

Return type:

argparse.ArgumentParser

lpath.argparser.add_extract_args(parser=None)

This block process all the necessary arguments for the “extract.py” module.

Parameters:

parser (argparse.ArgumentParser) – A parser passed in from each tool. Separated from each function because the catch-all tool to run everything in succession will only have 1 parser. This will auto create a parser if None is passed.

Returns:

parser – Returns an instance of the parser with all the new arguments added in.

Return type:

argparse.ArgumentParser

lpath.argparser.add_match_args(parser=None)

This block process all the necessary arguments for the “match.py” module.

Parameters:

parser (argparse.ArgumentParser) – A parser passed in from each tool. Separated from each function because the catch-all tool to run everything in succession will only have 1 parser. This will auto create a parser if None is passed.

Returns:

parser – Returns an instance of the parser with all the new arguments added in.

Return type:

argparse.ArgumentParser

lpath.argparser.add_plot_args(parser=None)

This block process all the necessary arguments for the “plot.py” module.

Parameters:

parser (argparse.ArgumentParser) – A parser passed in from each tool. Separated from each function because the catch-all tool to run everything in succession will only have 1 parser. This will auto create a parser if None is passed.

Returns:

parser – Returns an instance of the parser with all the new arguments added in.

Return type:

argparse.ArgumentParser

lpath.argparser.check_argv()

Check to see if argv > 2 is empty. Print warning if so.

lpath.argparser.check_less_three(value)

Transform value into int and make sure it’s between 0 and 3 (inclusive).

Parameters:

value (str or float or int) – A value to check to see if it’s between 0 and 3 (inclusive)

Returns:

value – Only if int is greater than 0. Will transform it to int in the processes.

Return type:

int

Raises:

• InvalidArgumentError – If value is not valid.

• ArgumentTypeError – If value is not an integer or float.

lpath.argparser.check_non_neg(value)

Transform value into int and make sure it’s >= 0.

Parameters:

value (str or float or int) – A value to check to see if it’s >= 0. Will be transformed to int in the process.

Returns:

value – Only if int is greater or equal to 0.

Return type:

int

Raises:

• ArgumentError – If value is < 0.

• ArgumentTypeError – If value is not an integer or float.

lpath.argparser.check_non_neg_float(value)

Transform value into int and make sure it’s >= 0.

Parameters:

value (str or float or int) – A value to check to see if it’s >= 0. Will be transformed to float in the process.

Returns:

value – Only if float is greater or equal to 0.

Return type:

float

Raises:

• ArgumentError – If value is < 0.

• ArgumentTypeError – If value is not an integer or float.

lpath.argparser.check_positive(value)

Transform value into int and make sure it’s > 0 (positive number).

Parameters:

value (str or float or int) – A value to check to see if it’s > 0. Will be transformed into int in the process.

Returns:

value – Only if int is greater than 0.

Return type:

int

Raises:

• InvalidArgumentError – If value is <= 0.

• ArgumentTypeError – If value is not an integer or float.

lpath.argparser.create_parser()

Quickly create a parser.

Returns:

parser – Returns an instance of the parser.

Return type:

argparse.ArgumentParser

lpath.argparser.process_args(parser)

Actually process whatever passed to the parser.

Parameters:

parser (argparse.ArgumentParser) – An instance of argument parser.

Returns:

args – A Namespace object with all the arguments parsed.

Return type:

argparse.Namespace

lpath.argparser.process_assign_args(arguments)

Process arguments for w_assign.

Parameters:

arguments (argparse.Namespace) – Parsed arguments by parser.

lpath.argparser.process_extract_output(arguments)

Process discrepancy in arguments where extract_output does not contain out-dir while everything else does.

Parameters:

arguments (argparse.Namespace) – Parsed arguments by parser.

lpath.argparser.process_matplotlib_config(arguments)

Process arguments for matplotlib.subplots.

lpath.argparser.process_output_folder(arguments)

Modify all output files to be in out_dir if it’s not succ_traj.

Parameters:

arguments (argparse.Namespace) – Parsed arguments by parser.

Returns:

arguments – Modified parsed arguments by parser.

Return type:

argparse.Namespace