Utilities API

API

class ccdc.utilities.Logger[source]

Handles CCDC log messages and Python API messages.

fatal(msg, contact=True)[source]

Log a critical message and exit.

Parameters:
  • msg – str
  • contact – whether to include CCDC contact details in the message
ignore_line_numbers(tf=True)[source]

Format line numbers or not for output lines.

Parameters:tf – bool
classmethod reset()[source]

Reset the logger.

set_ccdc_log_level(value)[source]

Set the log level of the CCDC logger.

Parameters:value – int
set_ccdc_minimum_log_level(value)[source]

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)[source]

Set the log level of Python log messages.

Parameters:value – Logger.LOGLEVEL
set_output_file(file_name)[source]

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

Parameters:file_name – str
class ccdc.utilities.FileLogger(fname)[source]

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)[source]

A histogram.

add_value(v)[source]

Add a single value to the histogram.

add_values(vs)[source]

Add an iterable of values.

bin_width

The width of a bin.

compare(other, method='jensen_shannon')[source]

Compare two histograms.

Parameters:
  • otherccdc.utilities.Histogram instance
  • method – either ‘jensen_shannon’ or ‘kullback_leibler’ or a prefix of either
Returns:

a disimilarity measure

end_value

The last value.

frequencies

The frequency counts of each bin.

nbins

The number of bins.

noverflow

Number of overflowing values.

nunderflow

Number of underflowing values.

nvalues

How many observations were made.

overflow

Whether over- or underflow occured in the histogram.

start_value

The starting value.

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

An orthonormal grid of values.

bounding_box

The origin and farthest corner of the grid.

contract()[source]

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

copy()[source]

Make a copy of the grid.

count_grid()[source]

The number of non-zero points in the grid.

count_neighbours()[source]

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

dilate()[source]

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

extrema

The minimum and maximum value of the grid.

flood_fill(other, i, j, k, threshold, value)[source]

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

Returns:a subgrid containing the connected region.
from_dict(dic)[source]

Use a dictionary to set the values of the grid.

static from_file(file_name, format=None)[source]

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)[source]

Sets all points of the grid from the vector.

indices_at_value(value)[source]

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

islands(threshold)[source]

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

masked_set(mask, value)[source]

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

max_value_of_neighbours()[source]

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

mean_value_of_neighbours()[source]

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

min_value_of_neighbours()[source]

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

nsteps

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

score_molecule(molecule)[source]

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

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

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)[source]

Set the value at a grid point.

slice(plane)[source]

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.
spacing

The distance between successive grid points in one dimension.

sub_grid(region)[source]

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

static super_grid(padding, *grids)[source]

Inject the grids into the smallest grid containing them.

to_dict()[source]

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

to_vector()[source]

Return the tuple of values in the grid.

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

value(i, j, k)[source]

The value at a point.

value_at_point(coords)[source]

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)[source]

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)[source]

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[source]

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)[source]

The context manager.

decorate(tag)[source]

Decorates a function or method to provide timing information.

static format_time(t)[source]

Formats a time into hours:minutes:seconds.

static progress(start, count, total, message, file=<colorama.ansitowin32.StreamWrapper object>, in_place=False)[source]

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=<colorama.ansitowin32.StreamWrapper object>)[source]

Reports the time spent per tag.

class ccdc.utilities.Licence[source]

Information about the current licensing.

days_remaining

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

files

Deprecated - The licence files in use.

modules

The licensed modules.

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

Represents the uncertainty in a float value.

precision

The precision of the uncertainty.

uncertainty

The uncertainty in the measurement.

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

Represents a float with uncertainty.

static from_string(s)[source]

Create from a string representation.

precision

The number of decimal places supported.

uncertainty

The uncertainty in the value.

value

The value without the uncertainty.

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

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()[source]

Write the HTML footer and close the output file.

write(content)[source]

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)[source]

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)[source]

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 the HTML footer.

write_paragraph(content)[source]

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)[source]

Shorthand for writing a complete HTML report in one swoop.

Parameters:content – (str) The HTML content to write to the file.
write_report_header()[source]

Write the header for the report.

write_section_header(headline, section_id=None, level=2)[source]

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)[source]

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)[source]

Use a thin wrapper class to ArgumentParser.

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

angles

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

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

commandline_parser = None

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

conquest_path = None

str: The full path to a CCDC ConQuest executable.

current_entry

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

database_path = None

str: The file name of the database to use.

distances

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

exit_with_error(message, exit_code=1)[source]

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.
file_path

str: The file name of the database to use.

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)[source]

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')[source]

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 = None

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_h2a_file

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

input_m2a_file

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

input_mol2_file = None

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 = None

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 = None

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

log_file_name = None

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

open_output_folder()[source]

Open the output folder in a file browser.

options = None

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

output_base = None

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 = None

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

output_csv_file = None

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

output_directory_path = None

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

output_file_name(suffix)[source]

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 = None

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

output_gold_conf_file = None

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

output_html_file = None

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

output_mol2_file = None

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

output_morphology_file = None

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

output_pdb_file = None

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

output_progress_file = None

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

output_sdf_file = None

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

output_tsv_file = None

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

parse_commandline()[source]

Parse any command-line parameters passed into the script.

program_executable_path

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

program_path = None

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

script_name = None

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.

selected_atoms

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

selected_indices

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

show_script_error(message)[source]

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

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

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

update_progress(message, progress=None)[source]

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 = None

str: The absolute path of the working directory.

write_report(title='Report', content=None, file_name=None)[source]

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.