Support functions for CLI

Functionalities that support the creation of the command lines interface.

class mdacli.libcli.KwargsDict(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)[source]

Convert input string to a dictionary.

If string points to a “.json” file, reads the file. Else, attempts to convert string to dictionary using json.loads.

mdacli.libcli.add_cli_universe(parser, name='')[source]

Add universe parameters to an given argparse.ArgumentParser.

instance. The parameters topology, topology_format, atom_style, coordinates and trajectory_format are added to the parse.

Parameters:

  • analysis_class_parser (argparse.ArgumentParser) – The ArgumentsParser instance to which the run grorup is added

  • name (str) – suffix for the argument names

mdacli.libcli.add_output_group(analysis_class_parser)[source]

Add output group parameters to argparse.ArgumentParser instance.

The run group adds the parameters output_prefix and output_directory to the parser.

Parameters:

analysis_class_parser (argparse.ArgumentParser) – The ArgumentsParser instance to which the run grorup is added

mdacli.libcli.add_run_group(analysis_class_parser)[source]

Add run group parameters to an given argparse.ArgumentParser instance.

The run group adds the parameters start, stop, step, verbose to the parser.

Parameters:

analysis_class_parser (argparse.ArgumentParser) – The ArgumentsParser instance to which the run grorup is added

mdacli.libcli.convert_analysis_parameters(analysis_callable, analysis_parameters, reference_universe=None)[source]

Convert parameters from the command line suitable for anlysis.

Special types (i.e AtomGroups, Universes) are converted from the command line strings into the correct format. Parameters are changed inplace. Note that only keys are converted and no new key are added if present in the doc of the analysis_callable but not in the analysis_parameters dict.

AtomGroup selection with type None are ignored since these could be default arguments.

The following types are converted:

  • AtomGroup: Select atoms based on universe.select_atoms

  • list[AtomGroup]: Select atoms based on universe.select_atoms for every element in list

  • Universe: Created from parameters.

Parameters:

  • analysis_callable (function) – Analysis class for which the analysis should be performed.

  • analysis_parameters (dict) – parameters to be processed

  • reference_universe (MDAnalysis.Universe) – Universe from which the AtomGroup selection are done.

Returns:

universe (Universe) – The universe created from the anaylysis parameters or None of no ine is created

Raises:

ValueError – If an Atomgroup does not contain any atoms

mdacli.libcli.create_cli(sub_parser, interface_name, parameters)[source]

Add subparsers to cli_parser.

Subparsers parameters are divided in the following categories:

  1. Analysis Run parameters

    time frame as begin, end, step and vebosity

  2. Saving Parameters

    output_prefix and output_directory

  3. Mandatory Parameters

    mandatory parameters are defined in the CLI as named parameters as per design

  4. Optional Parameters

    Named parameters in the Analysis class

  5. Reference Universe Parameters

    A reference Universe for selection commands. Only is created if AtomGroup arguments exist.

All CLI’s parameters are named parameters.

Parameters:

  • sub_parser (argparse.sub_parser) – A sub parser where the new parser will be added.

  • interface_name (str) – Name of the interface.

  • parameters (dict) – Parameters needed to fill the argparse requirements for the CLI interface.

Returns:

None

mdacli.libcli.create_universe(topology, coordinates=None, topology_format=None, trajectory_format=None, atom_style=None, dimensions=None)[source]

Initilize a MDAnalysis universe instance.

Parameters:

  • topology (str, stream, ~MDAnalysis.core.topology.Topology, np.ndarray) – A CHARMM/XPLOR PSF topology file, PDB file or Gromacs GRO file; used to define the list of atoms. If the file includes bond information, partial charges, atom masses, … then these data will be available to MDAnalysis. Alternatively, an existing MDAnalysis.core.topology.Topology instance may be given, numpy coordinates, or None for an empty universe.

  • coordinates (str, stream, list of str, list of stream) – Coordinates can be provided as files of a single frame (eg a PDB, CRD, or GRO file); a list of single frames; or a trajectory file (in CHARMM/NAMD/LAMMPS DCD, Gromacs XTC/TRR, or generic XYZ format). The coordinates must be ordered in the same way as the list of atoms in the topology. See Table of supported coordinate formats for what can be read as coordinates. Alternatively, streams can be given.

  • topology_format (str, None) – Provide the file format of the topology file; None guesses it from the file extension. Can also pass a subclass of MDAnalysis.topology.base.TopologyReaderBase to define a custom reader to be used on the topology file.

  • trajectory_format (str or list or object) – provide the file format of the coordinate or trajectory file; None guesses it from the file extension. Note that this keyword has no effect if a list of file names is supplied because the “chained” reader has to guess the file format for each individual list member [None]. Can also pass a subclass of MDAnalysis.coordinates.base.ProtoReader to define a custom reader to be used on the trajectory file.

  • atom_style (str) – Customised LAMMPS atom_style information. Only works with topology_format = data

  • dimensions (iterable of floats) – vector that contains unit cell lengths and probable angles. Expected shapes are eithere (6, 0) or (1, 6) or for shapes of (3, 0) or (1, 3) all angles are set to 90 degrees.

Raises:

IndexError – If the dimesions of the dimensions argument are not 3 or 6.

Returns:

MDAnalysis.Universe

mdacli.libcli.find_classes_in_modules(cls, *module_names)[source]

Find classes that belong to cls in modules.

A series of names can be given as arguments.

Parameters:

  • cls (single class or list of classes) – parent reference class type to search for

  • module_names (str) – module to import import in absolute or relative terms (e.g. either pkg.mod or ..mod).

Returns:

  • list

  • list of found class objects. If no classes are found, return None.

mdacli.libcli.find_cls_members(cls, modules, ignore_warnings=False)[source]

Find members of a certain class in modules.

Parameters:

  • cls (class or list of classes) – parent reference class or list of classes to be searched for

  • modules (list) – list of modules for which members should be searched for

  • ignore_warnings (bool) – Flag to ignore warnings

mdacli.libcli.init_base_argparse(name, version, description)[source]

Create a basic ArgumentParser.

The parser has options for printing the version, running in debug mode and with a logfile. Note that the funtion only adds the options to the parser but not the logic for actually running in debug mode nor how to store the log file.

Parameters:

  • name (str) – Name of the cli program

  • version (str) – Version of the cli program

  • description (str) – Description of the cli program

Returns:

ArgumentParser

mdacli.libcli.run_analysis(analysis_callable, mandatory_analysis_parameters, optional_analysis_parameters=None, reference_universe_parameters=None, run_parameters=None, output_parameters=None)[source]

Perform main client logic.

Parameters:

  • analysis_callable (function) – Analysis class for which the analysis is performed.

  • mandatory_analysis_parameters (dict) – Mandatory parameters for executing the analysis

  • optional_analysis_parameters (dict) – Optional parameters for executing the analysis

  • run_parameters (dict) – time frame parameters: start, stop, step, verbose

  • output_parameters (dict) – output_prefix and output_directory

Returns:

MDAnalysis.analysis.base.AnalysisBase – AnalysisBase instance of the given analysis_callable after run.

mdacli.libcli.setup_clients(ap, title, members)[source]

Set up analysis clients for an ArgumentParser instance.

Parameters:

  • ap (argparse.ArgumentParser) – Argument parser instance

  • title (str) – title of the parser

  • members (list) – list containing Analysis classes for setting up the parser

mdacli.libcli.split_argparse_into_groups(parser, namespace)[source]

Split the populated namespace of argparse into groups.

https://stackoverflow.com/questions/31519997/is-it-possible-to- only-parse-one-argument-groups-parameters-with-argparse

Parameters:

  • parse (argparse.ArgumentParser) – argument parser instance

  • namespace (argparse.Namespace) – instance storing the parameters

Returns:

arg_grouped_dict (dict) – Dictionary containing parameters split according to their groups