pycgtool.util

This module contains some general purpose utility functions used in PyCGTOOL.

Module Contents

Functions

circular_mean(values: Iterable[float]) → float	Calculate average of angles on a circle.
circular_variance(values: Iterable[float]) → float	Calculate variance of angles on a circle.
extend_graph_chain(extend, pairs)	Take list of tuples representing chained links in an undirected graph and extend the chain length.
transpose_and_sample(sequence: Iterable, n: Optional[int] = None) → List	Transpose a sequence of lists and sample to provide target number of rows.
dir_up(name, n=1)	Return the directory path n levels above a specified file/directory.
backup_file(path: PathLike) → pathlib.Path	Backup a file using the GROMACS backup naming scheme.
sliding(vals: Iterable)	Yield three values in a sliding window along an iterable.
cmp_file_whitespace_float(ref_filename, test_filename, rtol=0.01, verbose=False)	Compare two files ignoring spacing on a line and using a tolerance on floats
number_or_string(string: str) → Union[float, int, str]	Convert string into an int or float if possible.
cmp_whitespace_float(ref_lines, test_lines, rtol=0.01, verbose=False)	Compare two iterables of lines ignoring spacing on a line and using a tolerance on floats
file_write_lines(filename, lines=None, backup=True, append=False)	Open a file and write lines to it.
any_starts_with(iterable: Iterable, char: str) → bool	Return True if any string(s) in nested iterable starts with a given character.
load_optional_topology(trajfile: Union[str, pathlib.Path], topfile: Optional[Union[str, pathlib.Path]] = None) → mdtraj.Trajectory	Load an MDTraj trajectory with or without a separate topology file.
compare_trajectories(*trajectory_files: Union[str, pathlib.Path], topology_file: Optional[Union[str, pathlib.Path]] = None, rtol: float = 0.001) → bool	Compare multiple trajectory files for equality.

Attributes

logger
PathLike

pycgtool.util.logger

pycgtool.util.PathLike

exception pycgtool.util.EmptyIterableError

Bases: ValueError

Inappropriate argument value (of correct type).

pycgtool.util.circular_mean(values: Iterable[float]) → float

Calculate average of angles on a circle.

See https://en.wikipedia.org/wiki/Mean_of_circular_quantities

pycgtool.util.circular_variance(values: Iterable[float]) → float

Calculate variance of angles on a circle.

See https://en.wikipedia.org/wiki/Mean_of_circular_quantities

pycgtool.util.extend_graph_chain(extend, pairs)

Take list of tuples representing chained links in an undirected graph and extend the chain length.

Parameters

• extend – List of link tuples to extend

• pairs – Graph edges as list of tuples

Returns

List of link tuples for chain length one greater than input

pycgtool.util.transpose_and_sample(sequence: Iterable, n: Optional[int] = None) → List

Transpose a sequence of lists and sample to provide target number of rows.

Skip rows containing non-finite numbers (e.g. NaN).

Parameters

• sequence – 2d sequence object to transpose

• n – Number of samples to take

pycgtool.util.dir_up(name, n=1)

Return the directory path n levels above a specified file/directory.

Parameters

• name – Name of file/directory to start from

• n – Number of directory levels to go up

Returns

Directory n directories above name

pycgtool.util.backup_file(path: PathLike) → pathlib.Path

Backup a file using the GROMACS backup naming scheme. name -> #name.x#

Parameters

path – Path to file to backup

Returns

New name of file after backup

pycgtool.util.sliding(vals: Iterable)

Yield three values in a sliding window along an iterable.

Parameters

vals – Iterable to iterate over

Returns

Generator of tuples

pycgtool.util.cmp_file_whitespace_float(ref_filename, test_filename, rtol=0.01, verbose=False)

Compare two files ignoring spacing on a line and using a tolerance on floats

Parameters

• ref_filename – Name of reference file

• test_filename – Name of test file

• rtol (float) – Acceptable relative error on floating point numbers

• verbose (bool) – Print failing lines

Returns

True if files are the same, else False

pycgtool.util.number_or_string(string: str) → Union[float, int, str]

Convert string into an int or float if possible.

pycgtool.util.cmp_whitespace_float(ref_lines, test_lines, rtol=0.01, verbose=False)

Compare two iterables of lines ignoring spacing on a line and using a tolerance on floats

Parameters

• ref_lines – Iterable of reference lines

• test_lines – Iterable of test lines

• rtol (float) – Acceptable relative error on floating point numbers

• verbose (bool) – Print failing lines

Returns

True if all lines are the same, else False

pycgtool.util.file_write_lines(filename, lines=None, backup=True, append=False)

Open a file and write lines to it.

Parameters

• filename (str) – Name of file to open

• lines (iterable[str]) – Iterable of lines to write

• backup (bool) – Should the file be backed up if it exists? Disabled if appending

• append (bool) – Should lines be appended to an existing file?

pycgtool.util.any_starts_with(iterable: Iterable, char: str) → bool

Return True if any string(s) in nested iterable starts with a given character.

Parameters

• iterable (iterable) – Nested iterable of strings to check

• char (str) – Char to check each string

Return bool

True if any string in nested iterable starts with char, else False

pycgtool.util.load_optional_topology(trajfile: Union[str, pathlib.Path], topfile: Optional[Union[str, pathlib.Path]] = None) → mdtraj.Trajectory

Load an MDTraj trajectory with or without a separate topology file.

Parameters

• trajfile – Trajectory file

• topfile – Corresponding topology file

Returns

MDTraj trajectory

pycgtool.util.compare_trajectories(*trajectory_files: Union[str, pathlib.Path], topology_file: Optional[Union[str, pathlib.Path]] = None, rtol: float = 0.001) → bool

Compare multiple trajectory files for equality.

Parameters

• trajectory_files – Paths of trajectory file to compare

• topology_file – Topology file path

• coords_only – Only compare coordinates from trajectory - e.g. not box size