Utilities API

Introduction

The ccdc.utilities module contains general purpose classes.

The main classes of the ccdc.utilities module are:

• ccdc.utilities.Logger

• ccdc.utilities.FileLogger

• ccdc.utilities.Histogram

• ccdc.utilities.Grid

• ccdc.utilities.Licence

• ccdc.utilities.ApplicationInterface

• ccdc.utilities.Resources

See also

Descriptive utilities documentation.

See also

Descriptive documentation for grids.

API

class ccdc.utilities.Logger

Handles CCDC log messages and Python API messages.

fatal(msg, contact=True)

Log a critical message and exit.

Parameters

• msg – str

• contact – whether to include CCDC contact details in the message

ignore_line_numbers(tf=True)

Format line numbers or not for output lines.

Parameters

tf – bool

classmethod reset()

Reset the logger.

set_ccdc_log_level(value)

Set the log level of the CCDC logger.

Parameters

value – int

set_ccdc_minimum_log_level(value)

Set the minimum log level of the CCDC logger.

Note that a minimum log level of 1 produces an enormous amount of output. A minimum log level of 3 is recommended.

Parameters

value – int

set_log_level(value)

Set the log level of Python log messages.

Parameters

value – Logger.LOGLEVEL

set_output_file(file_name)

Specify an output file to use, rather than the default stdout.

Parameters

file_name – str

class ccdc.utilities.FileLogger(fname)

A context manager to set logger output to a file.

Use it like this:

with FileLogger('/tmp/ccdc.log') as log:
    ...
    log.info('Something happened')
    ...

The file will be closed on exit and the logger reset to stderr.

class ccdc.utilities.Histogram(start_value, end_value, nbins)

A histogram.

add_value(v)

Add a single value to the histogram.

add_values(vs)

Add an iterable of values.

property bin_width

The width of a bin.

compare(other, method='jensen_shannon')

Compare two histograms.

Parameters

• other – ccdc.utilities.Histogram instance

• method – either ‘jensen_shannon’ or ‘kullback_leibler’ or a prefix of either

Returns

a disimilarity measure

property end_value

The last value.

property frequencies

The frequency counts of each bin.

property nbins

The number of bins.

property noverflow

Number of overflowing values.

property nunderflow

Number of underflowing values.

property nvalues

How many observations were made.

property overflow

Whether over- or underflow occured in the histogram.

property start_value

The starting value.

class ccdc.utilities.Grid(origin=None, far_corner=None, spacing=None, default=0.0, _grid=None)

An orthonormal grid of values.

property bounding_box

The origin and farthest corner of the grid.

contract()

Contracts a grid by eliminating points with a zero-valued neighbour.

copy()

Make a copy of the grid.

count_grid()

The number of non-zero points in the grid.

count_neighbours()

Sets the value at a grid point to the number of neighbours with a non-zero value.

dilate()

Expands a grid to include points with a non-zero neighbour.

property extrema

The minimum and maximum value of the grid.

flood_fill(other: object, i: int, j: int, k: int, threshold: float, value: float, x_periodic: bool = False, y_periodic: bool = False, z_periodic: bool = False)

Sets all connected points of the other grid with values at or above threshold to a given value.

x|y|z_periodic flags allow the flood fill to be carried out using periodic boundary conditions in the given axis.

Parameters

• other – a ccdc.utilities.Grid object containing connected points

• i – x grid index to start flood fill

• j – y grid index to start flood fill

• k – z grid index to start flood fill

• threshold – at or above threshold value used for selecting connected points

• value – fill value

• x_periodic – flag for periodicity along x axis

• y_periodic – flag for periodicity along y axis

• z_periodic – flag for periodicity along z axis

Returns

a subgrid containing the connected region.

from_dict(dic)

Use a dictionary to set the values of the grid.

static from_file(file_name, format=None)

Reads a grid from file.

Parameters

• file_name – from which the grid will be written.

• format – either ‘acnt’ or ‘grd’ indicating a Sybyl or an InsightII formatted file.

from_vector(vector)

Sets all points of the grid from the vector.

indices_at_value(value)

The tuple of indices where the grid has the given value.

islands(threshold)

The connected regions of the grid where all values are above the threshold.

masked_set(mask, value)

A grid containing this grid’s values where the mask is 0.0, otherwise value.

max_value_of_neighbours()

Sets the value at a grid point to the maximum value of its neighbours.

mean_value_of_neighbours()

Sets the value at a grid point to the mean of the neighbouring grid points.

min_value_of_neighbours()

Sets the value at a grid point to the minimum value of its neighbours.

property nsteps

A triple of nx, ny, nz for the grid.

score_molecule(molecule)

The dictionary of values for atoms’ coordinates on the grid.

set_sphere(point, radius, value, scaling='linear', mode='add')

Set a sphere of values in the grid.

Parameters

• point – the centre of the sphere to be set.

• radius – the radius of the sphere to be set.

• value – the value to set.

• scaling – either ‘linear’ for linear scaling of the value, or anything else for no scaling.

• mode – one of ‘add’, ‘replace’, ‘min’ or ‘max’ to control the method of overwriting the grid’s current value.

set_value(i, j, k, val)

Set the value at a grid point.

slice(plane)

Slices a grid with a plane.

Parameters

plane – a ccdc.descriptors.GeometricDescriptors.Plane instance.

Returns

a pair of ccdc.utilities.Grid, the first with zeros further away from the origin than the plane distance, the second with zeros nearer to the origin than the plane distance.

property spacing

The distance between successive grid points in one dimension.

sub_grid(region)

Extract the region of the grid given by the six indices in region.

static super_grid(padding, *grids)

Inject the grids into the smallest grid containing them.

to_dict()

A dictionary keyed by grid value with values the indices giving that value.

to_vector()

Return the tuple of values in the grid.

This makes it easy to create numpy arrays from a grid.

value(i, j, k)

The value at a point.

value_at_point(coords)

The value at a point.

If the point is outside the grid a default value of 0.0 will be returned. The value will be linearly interpolated from nearby grid point values.

write(file_name, title='', format=None)

Write the grid.

Parameters

• file_name – to which the grid will be written.

• title – will be written to a Sybyl format file as the title.

• format – either ‘acnt’ for a Sybyl format grid file, ‘grd’ for an InsightII format grid file or ‘ccp4’ for a CCP4Map format.

class ccdc.utilities.GridEnsemble(directory)

A collection of homogeneous ccdc.utilities.Grid instances.

All grids will be on a common volume and spacing. Provides a lazy dict-like interface: grids will not be loaded until asked for, and may be accessed by base name as a key. Grids may be added via __setitem__. The grid will automatically be written to the directory.

class ccdc.utilities.Timer

Collects timing statistics for the run.

Two methods of instrumenting code are available: a decorator for functions and methods, and a context manager for blocks of code.

The former is used as

timer = Timer()

@timer.decorate(‘Some tag’)

def method(self):

body_of_method

The latter is used as | with timer(‘Some tag’): | code_to_time…

At the end of the run, call

timer.report()

which will print to stdout (or another file) a sorted list of times accumulated by the given tags.

There is a staticmethod, ccdc.utilities.Timer.progress() which may be used to provide a progress meter for long running tasks.

if count % 1000 == 0:

Timer.progress(start_time, count, expected_total, message, file=sys.stderr)

to get periodic reports including percentage complete and expected length to wait for completion. An optional argument can also be provided to ccdc.utilities.Timer.progress() to provide in place output that overwrites the previous output.

Timer.progress(start_time, count, expected_total, message, file=sys.stderr, in_place=True)

class Manager(timer, tag)

The context manager.

decorate(tag)

Decorates a function or method to provide timing information.

static format_time(t)

Formats a time into hours:minutes:seconds.

static progress(start, count, total, message, file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, in_place=False)

Reports on progress of a long-running task.

Parameters

• start – the timestamp of the start of the task.

• count – how many times the code has been executed.

• total – how many times it is expected to call the code.

• message – a message to be printed.

report(file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)

Reports the time spent per tag.

class ccdc.utilities.Licence

Information about the current licensing.

property days_remaining

The number of days remaining before any part of the licence expires.

property features

The licensed features.

property files

Deprecated - The licence files in use.

property modules

The licensed modules.

class ccdc.utilities.Uncertainty(precision=0, uncertainty=0, _uncertainty=None)

Represents the uncertainty in a float value.

property precision

The precision of the uncertainty.

property uncertainty

The uncertainty in the measurement.

class ccdc.utilities.UncertainValue(f=0.0, u=None)

Represents a float with uncertainty.

static from_string(s)

Create from a string representation.

property precision

The number of decimal places supported.

property uncertainty

The uncertainty in the value.

property value

The value without the uncertainty.

class ccdc.utilities.HTMLReport(file_name, report_title='Report', ccdc_header=True, append=False, embed_images=False)

Utility class for writing HTML reports for API scripts.

Can be used as a context manager, which will automatically write the closing HTML tags and close the output file when closed:

with ccdc.utilities.HTMLReport(file_name=’output.html’, title=’Example Report’,

ccdc_header=True, append=False, embed_images=False) as report:

report.write_section_header(‘Headline’) report.write(‘Test content’)

close()

Write the HTML footer and close the output file.

write(content)

Write the given content to the file.

Parameters

content – (str or list) The HTML content to write to the file. If this is a list, each item in it will be written to a separate HTML paragraph. Otherwise, the entire content will be written to one paragraph.

write_figure(file_name, alt_text='Figure', caption=None, figure_id=None)

Add a figure, copying the given file name adjacent to the HTML report.

Parameters

• file_name – (str) The path to the image file for the figure.

• alt_text – (str) The HTML alt text for the figure.

• caption – (str) The caption for the figure, if any.

• figure_id – (str) The unique identifier to use for the HTML element.

write_figure_data(figure_data, caption=None, figure_id=None)

Add a figure, simply inserting the given figure data inside the <figure> tags.

This is useful for writing figures from SVG code.

Parameters

• figure_data – (str) The data to insert in the figure.

• caption – (str) The caption for the figure, if any.

• figure_id – (str) The unique identifier to use for the HTML element.

write_footer()

Write the HTML footer.

write_paragraph(content)

Write the given content to the file enclosed in <p></p> tags.

Parameters

content – (str or list) The HTML content to write to the file. If this is a list, each item in it will be written to a separate HTML paragraph. Otherwise, the entire content will be written to one paragraph.

write_report(content)

Shorthand for writing a complete HTML report in one swoop.

Parameters

content – (str) The HTML content to write to the file.

write_report_header()

Write the header for the report.

write_section_header(headline, section_id=None, level=2)

Write a section header.

Parameters

• headline – (str) The text to use for the section header.

• section_id – (str) The unique identifier to use for the HTML element.

• level – (int) The level of heading to write (as <h#>).

class ccdc.utilities.ApplicationInterface(description='', parse_commandline=True, show_progress=True)

Utility class to make interfacing the CSD Python API with external applications easier.

class CmdParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=<class 'argparse.HelpFormatter'>, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True)

Use a thin wrapper class to ArgumentParser.

So we can, if needed, redefine ArgumentParser’s methods.

property angles

list of int: The triplets of atom indices defining requested angles.

property ccdc_logo

str: The filename of a CCDC logo image in .png format.

commandline_parser

argparse.ArgumentParser: An argparse ArgumentParser to handle command line arguments passed to the script.

conquest_path

str: The full path to a CCDC ConQuest executable.

property current_entry

ccdc.entry.Entry: An Entry object for the currently selected structure.

database_path

str: The file name of the database to use.

property distances

list of int: The pairs of atom indices defining requested distances.

exit_with_error(message, exit_code=1)

Write a user-friendly error message to the output HTML file and exit the script.

Parameters

• message – (str) The text of the error message to display.

• exit_code – (int) The exit code to return from the script.

property file_path

str: The file name of the database to use.

get_ccdc_logo()

Copy the CCDC logo to the current output directory and return the full file name.

Returns

(str) The filename of a CCDC logo image in .png format.

get_diagnostic_info(verbose=False)

Retrieve some diagnostic information about the API, Python version, etc.

Parameters

verbose – (bool) Whether to include all environment variables or just the default set

Returns

(list) A list containing various diagnostic information.

html_report(title='Report')

Return a HTMLReport object writing to the current output html file.

Parameters

title – (str) The title for the HTML report.

Returns

(ccdc.utilities.HTMLReport) The HTMLReport object..

identifier

str: The identifier of the structure currently selected in the application. This should be the structures you want the script to run on (if any).

input_cif_file

str: The full path to a CIF file of the current protein for use by scripts. This is derived from the output_base property for compatibility with Hermes.

property input_h2a_file

str: The full path to the JSON file of options passed in by the application.

property input_m2a_file

str: The full path to the JSON file of options passed in by the application.

input_mol2_file

str: The full path to a MOL2 file of the current structure for use by scripts. This MOL2 file contains the current state of the crystal in the applicaiton visualiser. This is derived from the output_base property for compatibility with Hermes and Mercury.

input_pdb_file

str: The full path to a PDB file of the current protein for use by scripts. This is derived from the output_base property for compatibility with Hermes.

interface_file

str: The absolute path of a JSON file specifying options.

log_file_name

str: The full path to a log file for use by scripts.

open_output_folder()

Open the output folder in a file browser.

options

dict: A dictionary of command-line arguments passed in. Filled by calling parse_commandline().

output_base

str: A prefix for output files, as an absolute path but without extension. When running via Mercury and Hermes, this is passed in via the interface file.

output_c2m_file

str: The full path to a Conquest2Mercury file for use by scripts.

output_cif_file

str: The full path to a CIF/mmCIF output file for use by scripts.

output_csv_file

str: The full path to a CSV output file for use by scripts.

output_directory_path

str: The absolute path of the output directory for the script.

output_file_name(suffix)

Return a file name appended with the given suffix.

Parameters

suffix – (str) The suffix to append to the base output file name.

Returns

(str) The full output file name with the given suffix.

output_gcd_file

str: The full path to a GCD output file for use by scripts.

output_gold_conf_file

str: The full path to a .conf file for GOLD docking settings.

output_html_file

str: The full path to a HTML output file for use by scripts.

output_mol2_file

str: The full path to a MOL2 output file for use by scripts.

output_morphology_file

str: The full path to a morphology CIF output file for use by scripts.

output_pdb_file

str: The full path to a PDB output file for use by scripts.

output_progress_file

str: The full path to a file for writing interactive progress information to.

output_sdf_file

str: The full path to an SDF file for use by scripts.

output_tsv_file

str: The full path to a TSV output file for use by scripts.

parse_commandline()

Parse any command-line parameters passed into the script.

property program_executable_path

str: The full path to the executable of the application calling the script.

program_path

str: The full path to the executable of the application calling the script.

script_name

str: The file name of the script that has imported the ApplicationInterface. In general, this should be the script that’s been run by the external application.

property selected_atoms

list of ccdc.molecule.Atom: The currently selected atoms in the structure.

property selected_indices

list of int: The indices of the selected atoms in the structure.

show_script_error(message)

Write a user-friendly error message to the output HTML file.

Parameters

message – (str) The text of the error message to display.

property torsion_angles

list of int: The 4-tuples of atom indices defining requested torsion angles.

update_progress(message, progress=None)

Write an update to the .progress file.

This will display the status message in the Python API script dialog in Hermes and Mercury.

Parameters

• message – (str) The progress message to display in the dialog.

• progress – (float) The fractional value of progress.

working_directory_path

str: The absolute path of the working directory.

write_report(title='Report', content=None, file_name=None)

Shorthand for writing a complete HTML report in one swoop.

Parameters

• title – (str) The HTML content to write to the file.

• content – (str) The HTML content to write to the file.

• file_name – (str) The name of the file to write the report to.