API

SQLAlchemy interface

ispyb.sqlalchemy.enable_debug_logging()[source]

Write debug level logging output for every executed SQL query.

This setting will persist throughout the Python process lifetime and affect all existing and future sqlalchemy sessions. This should not be used in production as it can be expensive, can leak sensitive information, and, once enabled, cannot be disabled.

ispyb.sqlalchemy.session(credentials=None)[source]

Create an SQLAlchemy session.

Warning

This function is deprecated.

Parameters:

credentials – a config file or a Python dictionary containing database credentials. See function url() for details.

Returns:

The SQLAlchemy session.

ispyb.sqlalchemy.url(credentials=None) str[source]

Return an SQLAlchemy connection URL

Parameters:

credentials

a config file or a Python dictionary containing database credentials. If credentials=None then look for a credentials file in the ISPYB_CREDENTIALS environment variable.

Example credentials file:

[ispyb_sqlalchemy]
username = user
password = password
host = localhost
port = 3306
database = ispyb_build

Example credentials dictionary:

{
    "username": "user",
    "password": "password",
    "host": localhost",
    "port": 3306,
    "database": "ispyb",
}

Returns:

A string containing the SQLAlchemy connection URL.

Connecting to ISPyB

exception ispyb.ConnectionError[source]

Bases: ISPyBException

Unable to connect or connection has been closed.

exception ispyb.ISPyBException[source]

Bases: Exception

Base class for all exceptions

exception ispyb.NoResult[source]

Bases: ISPyBException

Query returned no result.

exception ispyb.ReadWriteError[source]

Bases: ISPyBException

Record could not be read, inserted, updated or deleted. This could be due to illegal values, the wrong number of parameters, a violation of table or index constraints, a permissions error, or a database failure.

ispyb.open(credentials=None, configuration_file=None)[source]

Create an ISPyB connection.

Parameters:

credentials

a config file containing database credentials. If credentials=None then look for a credentials file in the “ISPYB_CREDENTIALS” environment variable.

Example credentials file:

[ispyb_mariadb_sp]
user = ispyb_api
pw = password_1234
host = localhost
port = 3306
db = ispybtest
reconn_attempts = 6
reconn_delay = 1

Returns:

The ISPyB connection object.

Accessing records using the object model

Warning

This has now been deprecated, please use the ispyb.sqlalchemy interface instead.

The connection object offers the following accessor functions to get object-like representations of database entries:

class ispyb.model.interface.ObjectModelMixIn[source]

Object model accessor functions for Connector classes.

get_data_collection(dcid)[source]

Return a DataCollection object representing the information about the selected data collection.

get_data_collection_group(dcgid)[source]

Return a DataCollectionGroup object representing the information about the selected data collection group.

get_detector(detectorid)[source]

Return a Detector object representing a Detector database entry.

get_processing_job(jobid)[source]

Return a ProcessingJob object representing the information about the selected processing job.

get_processing_program(appid)[source]

Return a ProcessingProgram object representing the information about a processing program invocation.

get_sample(sample_id)[source]

Return a Sample object representing a BLSample database entry.

get_sample_group(sample_group_id)[source]

Return a Sample object representing a BLSample database entry.

get_screening(screening_id)[source]

Return a Screening object representing the information about a Screening result.

get_screening_output(screening_output_id)[source]

Return a ScreeningOutput object representing the information about a ScreeningOutput result.

get_screening_output_lattice(screening_output_lattice_id)[source]

Return a ScreeningOutputLattice object representing the information about a ScreeningOutputLattice result.

get_screening_strategy(screening_strategy_id)[source]

Return a ScreeningStrategy object representing the information about a ScreeningStrategy result.

get_screening_strategy_sub_wedge(screening_strategy_sub_wedge_id)[source]

Return a ScreeningStrategySubWedge object representing the information about a ScreeningStrategySubWedge result.

get_screening_strategy_wedge(screening_strategy_wedge_id)[source]

Return a ScreeningStrategyWedge object representing the information about a ScreeningStrategyWedge result.

DataCollection and DataCollectionGroup

Warning

This has now been deprecated, please use ispyb.sqlalchemy.DataCollection and ispyb.sqlalchemy.DataCollectionGroup instead.

class ispyb.model.datacollection.DataCollection(dcid, db_area, preload=None)[source]

An object representing a DataCollection database entry. The object lazily accesses the underlying database when necessary and exposes record data as python attributes.

property comment

A free comment field for the data collection.

property dcgid

Returns the Data Collection Group ID associated with this data collection. You can use .group to get the data collection group model object instead

property dcid

Returns the DataCollectionID.

property detector

Returns the Detector object associated with this DC.

property detector_2theta

2Theta angle between the main beam and the detector normal in degrees

property detector_distance

Distance from the sample to the detector in mm

property detector_id

A unique identifier for the detector used in this acquisition. You can access the detector model object via .detector directly.

property file_directory

Fully qualified path to the image files

property file_template

Template for file names with the character ‘#’ standing in for image number digits.

property file_template_full

Template for file names with full directory path. As with file_template ‘#’ characters stand in for image number digits.

property file_template_full_python

Template for file names that can be used in python string templates (for use with the % operator), with %0xd standing in for the x image number digits.

property group

Returns a DataCollectionGroup object.

property image_quality

Returns the list of ImageQualityIndicators objects associated with this DC.

property integrations

Returns the list of IntegrationResult objects associated with this DC.

property pdb

Returns a PDB object for the sample of this datacollection.

reload()[source]

Load/update information from the database.

property resolution

Inscribed resolution circle in Angstrom. Currently only well-defined for data collections with 2theta=0

property sample

Returns the Sample associated with this DC.

property sample_groups

Returns the list of SampleGroups associated with this DC.

property screenings

Returns the list of Screening objects associated with this DC.

property snapshot1

One of four possible fields to store file paths to image files relating to the data collection

property snapshot2

One of four possible fields to store file paths to image files relating to the data collection

property snapshot3

One of four possible fields to store file paths to image files relating to the data collection

property snapshot4

One of four possible fields to store file paths to image files relating to the data collection

property status

Returns a string representing the current data collection status.

property time_exposure

Exposure time per frame in seconds

property transmission

Beam transmission, in per cent

property wavelength

Beam wavelength in Angstrom

class ispyb.model.datacollection.DataCollectionGroup(dcgid, db_conn, preload=None)[source]

An object representing a DataCollectionGroup database entry. The object lazily accesses the underlying database when necessary and exposes record data as python attributes.

property container

Returns the container information for the DataCollectionGroup sample.

property dcgid

Returns the DataCollectionGroupID.

property experiment_type

The type of the underlying experiment,for example ‘Mesh’ describes what is also known as a grid scan

property gridinfo

Returns a GridInfo object.

reload()[source]

Load/update information from the database.

Detector

Warning

This has now been deprecated, please use ispyb.sqlalchemy.Detector instead.

class ispyb.model.detector.Detector(detectorid, db_conn, preload=None)[source]

An object representing a Detector database entry. The object lazily accesses the underlying database when necessary and exposes record data as python attributes.

property distance_max

The maximum sample-detector distance (mm)

property distance_min

The minimum sample-detector distance (mm)

property id

Returns the detectorId

property manufacturer

The detector manufacturer

property model

The detector model

property pixel_size_horizontal

The pixel size in the horizonal direction (µm)

property pixel_size_vertical

The pixel size in the vertical direction (µm)

property pixels_x

Detector number of pixels in x

property pixels_y

Detector number of pixels in y

reload()[source]

Load/update information from the database.

property sensor_thickness

The detector sensor thickness (µm)

property serial_number

The detector serial number

property type

The detector type, e.g. ‘Photon Counting’ or ‘CCD’

ProcessingJob

Warning

This has now been deprecated, please use ispyb.sqlalchemy.ProcessingJob instead.

class ispyb.model.processingjob.ProcessingJob(jobid, db_area)[source]

An object representing a ProcessingJob database entry. The object lazily accesses the underlying database when necessary and exposes record data as python attributes.

property DCID

Returns the main data collection id.

property automatic

Returns whether this processing job was initiated as part of automatic data processing.

property data_collection

Returns the DataCollection model object for the main data collection of the ProcessingJob.

property jobid

Returns the ProcessingJob ID.

reload()[source]

Load/update information from the database.

property sweeps

Returns a list of ProcessingJobImageSweeps involved in this processing job.

class ispyb.model.processingjob.ProcessingJobImageSweep(dcid, start, end, sweep_id, db_area)[source]

An object representing an image sweep for a processing job. Each image sweep has a data collection id, a start and an end image, and an image sweep id.

property DCID

Returns the data collection id.

property data_collection

Returns the DataCollection model object for the data collection of this sweep.

property end

Returns the end image number of the sweep

property start

Returns the start image number of the sweep

property sweep_id

Returns the processingJobImageSweepId

class ispyb.model.processingjob.ProcessingJobImageSweeps(jobid, db_area)[source]

An object representing the list of image sweeps for a ProcessingJob database entry. The object lazily accesses the underlying database when necessary and exposes the sweeps as a list.

reload()[source]

Load/update information from the database.

class ispyb.model.processingjob.ProcessingJobParameterValue(key, value, parameter_id)[source]

An object representing a key/value parameter pair. The object behaves like the value string, but also contains a .key and .parameter_id attribute.

property key

Returns the parameterKey

property parameter_id

Returns the processingJobParameterId

class ispyb.model.processingjob.ProcessingJobParameters(jobid, db_area)[source]

An object representing the parameters for a ProcessingJob database entry. The object lazily accesses the underlying database when necessary and exposes the parameters both as a list and in a dictionary-like fashion.

reload()[source]

Load/update information from the database.

class ispyb.model.processingjob.ProcessingJobPrograms(jobid, db_area)[source]

An object representing the programs working on a ProcessingJob. The object lazily accesses the underlying database when necessary and exposes the programs as a list of AutoProcProgam objects.

reload()[source]

Load/update information from the database.

ProcessingProgram

Warning

This has now been deprecated, please use ispyb.sqlalchemy.AutoProcProgram instead.

These objects correspond to entries in the ISPyB table AutoProcProgram.

class ispyb.model.processingprogram.ProcessingProgram(app_id, db_area, preload=None)[source]

An object representing an AutoProcProgram database entry. The object lazily accesses the underlying database when necessary and exposes record data as python attributes.

property app_id

Returns the AutoProcProgramID.

property job_id

Returns the associated ProcessingJob ID (if any).

reload()[source]

Load/update information from the database.

property status_text

Returns a human-readable status.