polo.crystallography package

Submodules

polo.crystallography.cocktail module

class polo.crystallography.cocktail.Cocktail(number=None, well_assignment=None, commercial_code=None, pH=None, reagents=[])

Bases: object

Cocktail instances are used to hold a collection of Reagent instances that form one chemical cocktail. Cocktails also hold other metadata including their commercial code, the cocktail pH and the well they are assigned to. Currently, cocktails are only supported for HWIRuns.

Parameters

• number (str, optional) – The cocktail number, defaults to None

• well_assignment (int, optional) – Well number in the screening plate this cocktail belongs to, defaults to None

• commercial_code (str, optional) – Commercial code of cocktail, defaults to None

• pH (float, optional) – pH of the cocktail, defaults to None

• reagents (Reagent, optional) – list of Reagent instances that make up the contents of the cocktail, defaults to None

add_reagent(new_reagent)

Adds a Reagent to the existing list of reagents referenced by the reagents attribute.

Parameters

new_reagent (Reagent) – Reagent to add to this cocktail

property cocktail_index

Attempt to pull out the cocktail number as an integer from the number attribute. This property is dependent on consistent formating between cocktail menus that has not checked at this time.

Returns

Cocktail number

Return type

int

property well_assignment

Return the current well assignment for this Cocktail.

Returns

well assignment

Return type

int

class polo.crystallography.cocktail.Reagent(chemical_additive=None, concentration=None, chemical_formula=None, stock_con=None)

Bases: object

Reagent instances represent one specific kind of chemical compound at a specific concentration. Multiple Reagents make up a cocktail. Reagents are generally created from the contents of HWI cocktail csv files which describe all 1536 cocktails and the reagents that compose them in one file. The cocktail csv files can be found in the data directory.

Parameters

• chemical_additive (str, optional) – Name of the chemical reagent, defaults to None

• concentration (UnitValue, optional) – Concentration of the reagent, defaults to None

• chemical_formula (Formula, optional) – Chemical formula for this reagent, defaults to None

• stock_con (UnitValue, optional) – Concentration of this reagent’s stock solution, defaults to None

property chemical_formula

The chemical formula for of this Reagent. Not all Reagents have available chemical formulas as cocktail csv files do not include formulas for all reagents. See the setter method for more details on how chemical formulas are converted from strings to Formula objects.

Returns

Chemical formula

Return type

Formula

property concentration

The current concentration of this Reagent. Concentration ultimately refers back to a condition in a specific screening well.

Returns

Chemical concentration

Return type

UnitValue

property molar_mass

Attempt to calculate the molar mass of this reagent. Closely related to the molarity property. The molar mass of the Reagent cannot be calculated for all HWI reagents.

Returns

Molar mass of the Reagent if it is calculable, False otherwise.

Return type

UnitValue or bool

property molarity

Attempt to calculate the molarity of this Reagent at its current concentration. This calculation is not certain to return a value as HWI cocktail menu files use a variety of units to describe chemical concentrations, including %w/v or %v/v.

%w/v is defined as grams of colute per 100 ml of solution * 100. This can be converted to molarity when the molar mass of the Reagent is known.

%v/v is defined as the volume of solute over the total volume of solution * 100. The density of the Reagent is required to convert %w/v to molarity which is not included in HWI cocktail menu files. This makes conversion from %w/v out of reach for now.

If the Reagent concentration cannot be converted to molarity then this function will return False.

Returns

molarity or False

Return type

UnitValue or Bool

peg_parser(peg_string)

Attempts to pull out a molar mass from a PEG species since the molar mass is often included in the name of PEG species. A string is considered to be a potential PEG species if it contains ‘PEG’ or ‘Polyethylene glycol’ in it.

Parameters

peg_string (str) – String to look for PEG species in

Returns

molar mass if found to be valid PEG species, False otherwise.

Return type

float or Bool

stock_volume(target_volume)

Attempt to calculate the required amount of stock solution to produce the Reagent’s set concentration in the given target_volume argument. Stock concentration is taken from the stock_con attribute. If stock_con is not set or the molarity of the Reagent can not be calculated this method will return False.

Parameters

target_volume (UnitValue) – Volume in which stock will be diluted into

Returns

Volume of stock or False

Return type

UnitValue or False

units = ['M', '(w/v)', '(v/v)']

class polo.crystallography.cocktail.UnitValue(value=None, units=None)

Bases: object

UnitValues are used to help handle numbers with units. They are not the most robust but help to keep things more organized. UnitValues can be created by either passing values to the values and units args explicitly or by calling the classmethod make_from_string() which will use regex to pull out supported units and values.

classmethod make_from_string(string)

Create a UnitValue from a string containing a value and a unit. Utilizes the polo.unit_regex expression to pull out the units.

unit_string = '10.0 M'  # concentration of 10 molar
sv = UnitValue.make_from_string(unit_string)
# sv.value = 10 sv.units = 'M'

Parameters

string (str) – The string to extract the UnitValue from

Returns

UnitValue instance

Return type

UnitValue

saved_scalers = {'c': 0.01, 'm': 0.001, 'u': 1e-06}

scale(scale_key)

Scale the value using a key character that exists in the saved_scalers dictionary. First converts the value to its base unit and then divides by the scale_key argument value. The scale_key can be thought of as a SI prefix for a base unit.

# self.saved_scalers = {'u': 1e-6, 'm': 1e-3, 'c': 1e-2}
v_one = UnitValue(10, 'L')  # value of 10 liters
v_one = v_one.scale('u')  # get v_one in microliters

Parameters

scale_key (str) – Character in saved_scalers to convert value to.

Returns

UnitValue converted to scale_key unit prefix

Return type

UnitValue

set_from_string(string)

to_base()

Converts the value to the base unit, if it is not already in the base unit.

Returns

UnitValue converted to base unit

Return type

UnitValue

property value

polo.crystallography.image module

class polo.crystallography.image.Image(path=None, bites=None, well_number=None, human_class=None, machine_class=None, prediction_dict={}, plate_id=None, date=None, cocktail=None, spectrum=None, previous_image=None, next_image=None, alt_image=None, favorite=False, parent=None, **kwargs)

Bases: PyQt5.QtGui.QPixmap

Image objects hold the data relating to one image in a particular screening well of a paricular run. Images encode the actual image file as a file path to the image if it available on the local machine, as as a base64 encoded image held in memory or both.

Parameters

• path (str or Path, optional) – Path to the actual image file, defaults to None

• bites (str or bytes, optional) – Image encoded as base64, defaults to None

• well_number (int, optional) – Well number of the image, defaults to None

• human_class (str, optional) – Human classification of this image, defaults to None

• machine_class (str, optional) – MARCO classification of this image, defaults to None

• prediction_dict (dict, optional) – Dictionary containing MARCO model confidence for all image classifications, defaults to None

• plate_id (str, optional) – HWI given unique ID for plate this image belongs to , defaults to None

• date (Datetime, optional) – Date this image was taken on, defaults to None

• cocktail (Cocktail, optional) – Cocktail assigned to the well this image is of, defaults to None

• spectrum (str, optional) – Keyword describing the imaging tech used to take the image , defaults to None

• previous_image (Image, optional) – Image of the same well and sample but taken on a previous date , defaults to None

• next_image (Image, optional) – Image of the same well and sample but taken on a future date, defaults to None

• alt_image (Image, optional) – Image of the same well and sample but taken with a different imaging tech, defaults to None

property bites

classify_image()

Classify the Image using the MARCO CNN model. Sets the machine class and prediction_dict attributes based on the model results.

static clean_base64_string(string)

Image instances may contain byte strings that store their actual crystallization image encoded as base64. Previously, these byte strings were written directly into the json file as strings causing the b byte string identifier to be written along with the actual base64 data. This method removes those artifacts if they are present and returns a clean byte string with only the actual base64 data.

Parameters

string (str) – A string to interrogate for base64 compliance

Returns

byte string with non-data artifacts removed

Return type

bytes

property date

The date associated with this Image. Presumably should be the date the image was taken.

Returns

Datetime object representation of the Image’s imaging date

Return type

datetime

delete_all_pixmap_data()

Deletes the pixmap data for the Image instance this method is called on and for any other Image is linked to. This includes images referenced by the alt_image , next_image and previous_image attributes.

delete_pixmap_data()

Replaces the Image’s pixmap data with a null pixmap which effectively deletes the existing pixmap data. Used to free up memory after a pixmap is no longer needed.

property earliest_crystallization_date

encode_base64()

encode_bytes()

If the path attribute exists and is an image file then encodes that file as a base64 string and returns the encoded image data.

Returns

base64 encoded image

Return type

str

property formated_date

Get the image’s marco_date attribute formated in the month/date/year format. If the Image has no date returns an empty string.

Returns

Date

Return type

str

get_linked_images_by_date()

Get all Image instance by date. Image linking by date is accomplished by creating a bi-directional linked list between Image instances, where each Image acts as a node and the next_image and previous_images act as the forwards and backwards pointers respectively.

Returns

All Image by date

Return type

list

get_linked_images_by_spectrum()

Get all Image instance by spectrum. Linking images by spectrum is accomplished by creating a mono-directional circular linked list where Image instances serve as nodes and their alt_image attribute acts as the pointer to the next node.

Returns

List of all Images linked to this Image by spectrum

Return type

list

get_tool_tip()

Create a string to use as the tooltip for this Image.

Returns

Tooltip string

Return type

str

height()

Get the height of the Image’s pixmap. The pixmap must be set for this function to return an actual size.

Returns

Height of the Image’s pixmap

Return type

int

property is_placeholder

classmethod no_image()

Return an Image instance using the image data referenced by the polo.DEFAULT_IMAGE_PATH constant. The default image is used to fill in for missing data and when filters cannot find any matching results.

Returns

Default Image

Return type

Image

property path

Filepath for the image. Note that if this path is loaded from an xtal file, this path may not exists because the xtal file may have been created on a different machine.

Returns

Path to image file

Return type

str

property prediction_dict

setPixmap(scaling=None)

Loads the Image’s pixmap into memory which then allows for displaying the Image to the user. Image pixmap when the Image actually needs to be shown to the user as it is expensive to hold in memory.

Parameters

scaling (float, optional) – Scaler for the pixmap; between 0 and 1, defaults to None

standard_filter(image_types, human, marco, favorite)

Method that determines if this Image should be included in a set of filtered Image meets the filtering requirements specified by the method’s arguments, otherwise returns False.

Parameters

• image_types (list or set) – Collection of image classifications. The Image’s classification must in included in this collection for the method to return True.

• human (bool) – If True, use the Image’s human classification as the overall image classification.

• marco (bool) – If True, use the Image’s MARCO classification as the overall image classification.

Returns

True if the Image meets the filter requirements, False otherwise

Return type

bool

classmethod to_graphics_scene(image)

Convert an Image object to a QGraphicsScene with the Image added as a pixmap to the QGraphicsScene.

Parameters

image (Image) – Image instance

Returns

QGraphicsScene

Return type

QGraphicsScene

width()

Get the height of the Image’s pixmap. The pixmap must be set for this function to return an actual size.

Returns

Width of the Image’s pixmap

Return type

int

write_from_bites(path)

Write the Image instance to a file using the base64 encoded data stored in the bites attribute.

polo.crystallography.run module

class polo.crystallography.run.HWIRun(cocktail_menu, plate_id=None, num_wells=1536, alt_spectrum=None, next_run=None, previous_run=None, **kwargs)

Bases: polo.crystallography.run.Run

AllOWED_PLOTS = ['Classification Counts', 'MARCO Accuracy', 'Classification Progress', 'Plate Heatmaps']

add_images_from_dir()

Populates the images attribute with a list of Images instances read from the image_dir attribute filepath. Currently is dependent on having a cocktail Menu available.

get_linked_alt_runs()

Return all HWIRun is linked to by spectrum. See link_to_alt_spectrum().

Returns

List of runs linked to this run by spectrum

Return type

list

get_linked_date_runs()

get_tooltip()

The same as get_tooltip().

import_priority = 1

classmethod init_from_directory(image_dir, **kwargs)

Create a Run instance from a directory of images.

Parameters

dir_path (str, Path) – Path to directory

Returns

Run instance

Return type

Run

insert_into_alt_spec_chain()

When runs are first loaded into Polo they are automatically linked together. Normally, HWIRuns that are linked by date should contain only visible spectrum images and alt_spectrum attribute. This means that one could navigate from a visible spectrum HWIRun to all alt spectrum link_to_alt_spectrum.

link_to_alt_spectrum(other_run)

Similar to link_to_next_date() except instead of creating a linked list through the next_run and previous_run attributes this method does so through the alt_spectrum attribute. The linked list created is mono-directional so if a series of HWIRun’s are being linked the last run should be linked to the first run to circularize the linked list.

Parameters

other_run (HWIRun) – HWIRun to link to this HWIRun by spectrum

link_to_next_date(other_run)

Link this HWIRun to another HWIRun instance that is of the same sample but photographed at a later date. This creates a bi-directional linked list structure between the two HWIRun instance will point to the other_run through the next_run attribute and other_run will point back to this HWIRun through its previous_run attribute. This method does not attempt to recognize which run was imaged first so this should be determined before calling, likely by sorting a list of HWIRun instances by their :attr:`~polo.crystallography.run.Run.date attribute.

Example:

# Starting with a collection of Run objects in a list
runs = [run_b, run_a, run_d, run_c]
# sort them by date
runs = sorted(runs, lambda r: r.date)
# link them together by date
[r[i].link_to_next_date(r[i+1]) for i in range(len(runs)-2)]

This would create a linked list with a structure link the representation below.

run_a <-> run_b <-> run_c <-> run_d

Parameters

other_run (HWIRun) – HWIRun instance representing the next imaging run

static parse_dirname_metadata(image_dir)

static parse_file_metadata(image_dir)

class polo.crystallography.run.Run(image_dir, run_name, image_spectrum=None, date=None, images=[], **kwargs)

Bases: object

Run objects represent one particular imaging run of a sample. They store Image objects that hold the actual imaging data as well as metadata associated with the imaging run and the sample.

Any objects holding image data should ultimately inherit from Run.

If you wish to create a Run object specific to your own experimental and data protocols note the following information. In almost all cases when Polo attempts to import a Run from some data source besides xtal files (rar archives and directories) the classmethod init_from_directory() will be called. Your subclass should override this method and include all code required to read / parse any metadata associated with the run. Additionally, you will probably want to override the value of the import_priority class variable. Since before a run is imported its type is unknown, Polo needs to run through all available Run subclasses and attempt to import the data as that subclass. If the order of this procedure was random Polo could attempt to import data as the base Run first instead of a more specific child-class resulting in a loss of metadata. Setting a higher import_priority value tells Polo (see polo.utils.io_utils.RunImporter) to attempt import of the child class before the base Run class.

Parameters

• image_dir (str of Path) – Directory that contains the screening images

• run_name (str) – Name of this run. Should be unique as it is used to uniquely identify each Run instance

• image_spectrum (str, optional) – Imaging technology used to capture the images in this run, defaults to None

• date (datetime, optional) – Date the images in this Run were taken, defaults to None

• images (list, optional) – List of all Image instances in this run, defaults to []

AllOWED_PLOTS = ['Classification Counts', 'MARCO Accuracy', 'Classification Progress']

add_images_from_dir()

Adds the contents of a directory to images attribute.

encode_images_to_base64()

Helper method that encodes all images in the class`~polo.crystallography.run.Run to base64.

property formated_name

get_current_hits()

get_images_by_classification(human=True)

Create a dictionary of image classifications. Keys are each type of classification and values are lists of Image s with classification equal to the key value. The human boolean determines what classifier should be used to determine the image type. Human = True sets the human as the classifier and False sets MARCO as the classifier.

get_tooltip()

image_filter_query(image_types, human, marco, favorite)

General use method for returning :class:`~polo.crystallography.image.Image`s based on a set of filters. Used whereever a user is allowed to narrow the set of :class:`~polo.crystallography.image.Image`s available for view.

Parameters

• image_types (list or set) – Returned images must have a classification that is included in this variable

• human (bool) – Qualify the classification type with a human classifier.

• marco (bool) – Qualify the classification type with a MARCO classifier.

• favorite (bool) – Returned images must be marked as favorite if set to True

import_priority = 0

classmethod init_from_directory(dir_path, **kwargs)

Create a Run instance from a directory of images.

Parameters

dir_path (str, Path) – Path to directory

Returns

Run instance

Return type

Run

unload_all_pixmaps(start=None, end=None, a=False)

Delete the pixmap data of all Image instances referenced by the images attribute. This method should be used to free up memory after the :class:`~polo.crystallography.run.Run`is no longer being viewed by the user.

Parameters

• start (int, optional) – Start index for range of images to unload, defaults to None

• end (int, optional) – End index for range of images to unload, defaults to None

• a – Flag to unload pixmap data for all Images this Image is linked to

Module contents