API reference

Code organization

• Plate.py, Well.py and Picklist.py implement the central objects Plate, Well, and Picklist.

• The containers folder contains specific classes of Plate and Well with predefined dimensions, capacity, dead volume, etc.

• The parsers folder contains all methods to generate Plates or Picklists from machine files and data.

• The exporters folder contains all methods to export plates and picklists in human- or machine-readable format.

Plates

This module implements the Base class for all plates.

See plateo.container for more specific plate subclasses, with set number of wells, well format, etc.

exception plateo.containers.Plate.NoUniqueWell

NoUniqueWell exception class.

class plateo.containers.Plate.Plate(name=None, wells_data=None, plate_data=None)

Base class for all plates.

See the builtin_containers for usage classes, such as generic microplate classes (Plate96, Plate384, etc).

Parameters:

• name – Name or ID of the Plate as it will appear in strings and reports

• wells_data – A dict {“A1”: {data}, “A2”: …}. The format of the data is left free

• plate_data – plate data

apply_to_wells(fun)

Run fun(well) for every name:well in self.wells_dict

find_unique_well_by_condition(condition)

Return the unique well of the plate satisfying the condition.

The condition method should have a signature of Well=>True/False.

Raises a NoUniqueWell error if 0 or several wells satisfy the condition.

find_unique_well_containing(query)

Return the unique well whose content contains the query.

get_well_at_index(index, direction='row')

Return the well at the corresponding index.

Examples

>>> plate.get_well_at_index(1)  # well A1
>>> plate.get_well_at_index(2)  # well A2
>>> plate.get_well_at_index(2, direction="column")  # well B1

index_to_wellname(index, direction='row')

Return the name of the well at the corresponding index.

Examples

>>> plate.index_to_wellname(1)  # "A1"
>>> plate.get_well_at_index(2)  # "A2"
>>> plate.get_well_at_index(2, direction="column")  # "B1"

iter_wells(direction='row')

Iter through the wells either by row or by column.

Examples

>>> for well in plate.iter_wells():
>>>     print (well.name)

last_nonempty_well(direction='row')

Return the last non-empty well found when traversing the plate.

list_filtered_wells(well_filter)

List filtered wells.

Examples

>>> def condition(well):
>>>     return well.volume > 50
>>> for well in myplate.list_filtered_wells(well_filter):
>>>     print( well.name )

list_well_data_fields()

Return all fields used in well data in the plate.

list_wells_in_column(column_number)

Return the list of all wells of the plate in the given column.

Examples

>>> for well in plate.list_wells_in_column(5):
>>>      print(well.name)

list_wells_in_row(row)

Return the list of all wells of the plate in the given row.

The row can be either a row number (1,2,3) or row letter(s) (A,B,C).

Examples

>>> for well in plate.list_wells_in_row("H"):
>>>      print(well.name)

merge_data_from(other_plate, overwrite=True)

Adds a new field field_name to the

Note that fun can also return nothing and simply transform the wells.

to_dict(replace_nans_by='null')

Convert plate to dict.

to_pandas_dataframe(fields=None, direction='row')

Return a dataframe with the info on each well.

well_class

alias of Well

wellname_to_index(wellname, direction='row')

Return the index of the well in the plate.

Examples

>>> plate.wellname_to_index("A1")  # 1
>>> plate.wellname_to_index("A2")  # 2
>>> plate.wellname_to_index("A1", direction="column")  # 9 (8x12 plate)

wells_grouped_by(data_field=None, key=None, sort_keys=False, ignore_none=False, direction_of_occurence='row')

Return wells grouped by key.

wells_sorted_by(sortkey)

Return wells sorted by sortkey.

This module contains a generic class for a well.

class plateo.containers.Well.Well(plate, row, column, name, data=None)

Generic class for a well.

Parameters:

• plate – The plate on which the well is located

• row – The well’s row (a number, starting from 0)

• column – The well’s column (a number, starting from 0)

• name – The well’s name, for instance “A1”

• data – A dictionary storing data on the well, used in algorithms and reports.

add_content(components_quantities, volume=None, unit_volume='L')

Add content to well.

Parameters:

• components_quantities – Dictionary of components and quantities (default: gram). Example {“Compound_1”: 5}.

• volume – Volume (default: liter).

• unit_volume – Unit of volume (default: liter). Options: liter (L), milliliter (mL), microliter (uL), nanoliter (nL).

property coordinates

Return (well.row, well.column).

empty_completely()

Empty the well.

index_in_plate(direction='row')

Return the index of the well in the plate.

is_after(other, direction='row')

Return whether this well is located strictly after the other well.

Examples

Iterate over all free wells after the last non-free well:

>>> direction = 'row'
>>> last_occupied_well = plate.last_nonempty_well(direction=direction)
>>> free_wells = (w for w in plate.iter_wells(direction=direction)
>>>               if w.is_after(last_occupied_well))
>>> for well in free_wells: ...

property is_empty

Return true if the well’s volume is 0.

iterate_sources_tree()

Iterate through the tree of sources.

pretty_summary()

Return a summary string of the well.

subtract_content(components_quantities, volume=0)

Subtract content from well.

to_dict()

Convert well to dict.

property volume

Return volume.

Plate parsers

From tables

plateo.parsers.plate_from_dataframe(dataframe, wellname_field='wellname', num_wells='infer', data=None)

Create a plate from a Pandas dataframe where each row contains the name of a well and data on the well.

it is assumed that the dataframe’s index is given by the well names.

This function is used e.g. in plate_from_list_spreadsheet.

Parameters:

• dataframe – A Pandas dataframe

• wellname_field – The name of the Pandas dataframe column indicating the name of the wells.

• num_wells – Number of wells in the Plate to be created. If left to default ‘infer’, the size of the plate will be chosen as the smallest format (out of 96, 384 and 1536 wells) which contains all the well names.

• data – Metadata information for the plate.

plateo.parsers.plate_from_list_spreadsheet(filename, sheet_name=0, num_wells='infer', wellname_field='wellname')

Create a plate from a Pandas dataframe where each row contains the name of a well and metadata on the well.

Parameters:

• filename – Path to the spreadsheet file.

• sheet_name – Index or name of the spreadsheet to use.

• num_wells – Number of wells in the Plate to be created. If left to default ‘infer’, the size of the plate will be chosen as the smallest format (out of 96, 384 and 1536 wells) which contains all the well names.

• wellname_field="wellname" – Name of the column of the spreadsheet giving the well names

plateo.parsers.plate_from_platemap_spreadsheet(file_handle, file_type='auto', original_filename=None, data_field='info', num_wells='infer', plate_class=None, multiply_by=None, headers=True, sheet_name=0, skiprows=None)

Parse spreadsheets representing a plate map.

Parameters:

• file_handle – Either a file handle or a file path to a CSV/Excel spreadsheet. If a file handle is provided, then the file_type must be set, or at least the “original_filename”.

• file_type – Either “csv”, “xls”, “xlsx” or “auto” (in which case the type is determined based on the provided file path in file_handle or original_filename)

• original_filename – Original filename (optional if file_handle is already a file path or if file_type is specified)

• data_field – Data field of the well under which platemap’s information will be stored

• num_wells – Number of wells in the Plate to be created. If left to default ‘infer’, the size of the plate will be chosen as the smallest format (out of 96, 384 and 1536 wells) which contains all the well names.

• headers – Whether the spreadsheet actually writes the “A” “B”, and “1” “2”

skiprows

Number of rows to skip (= rows before the platemap starts)

The spreadsheet should be either a 8 rows x 12 columns csv/excel file, or have headers like this

   1  2  3  4  5  6  7  8  9  10 11 12
A  .  .  .  .  .  .  .  .  .  .  .  .
B  .  .  .  .  .  .  .  .  .  .  .  .
C  .  .  .  .  .  .  .  .  .  .  .  .
D  .  .  .  .  .  .  .  .  .  .  .  .
E  .  .  .  .  .  .  .  .  .  .  .  .
F  .  .  .  .  .  .  .  .  .  .  .  .
G  .  .  .  .  .  .  .  .  .  .  .  .
H  .  .  .  .  .  .  .  .  .  .  .  .

From Fragment analyzer data

plateo.parsers.plate_from_aati_fragment_analyzer_peaktable(filename)

“Return a Plate96 object with a data field for the bands.

Provided a filename of an AATI fragment analyzer Peak table (these are generally named {DATE} Peak Table.csv), it generates a Plate96 object where each well has a data attribute “bands” of the form {peak_id: {attrs}} where the peak_id is a number (>1) and the attrs attribute has fields such as Size (bp), % (Conc.), nmole/L, ng/ul, RFU.

Note that the concentration column name must be either % (Conc.) or % (Conc.) (ng/uL).

plateo.parsers.plate_from_aati_fragment_analyzer_zip(filename)

“Return a Plate96 object with data for bands and migration image.

Provided a zip output of an AATI fragment analyzer, it will find the relevant files and extract band sizes and gel images, and store these in each well’s data.

In the final plate, each well has a data attribute “bands” of the form {peak_id: {attrs}} where the peak_id is a number (>1) and the attrs attribute has fields such as Size (bp), % (Conc.), nmole/L, ng/ul, RFU.

Each well also has a data["migration_image"] which is a WxH array, a greyscale version of the image.

Plate Exporters

plateo.exporters.plate_to_bokeh_plot(plate, hover_data=(), well_to_html=None, well_color_function=None)

Return an interactive bokeh plot of the plate.

Hovering the wells displays some data on the wells.

Parameters:

• plate – The plate to be converted

• hover_data – list or tuple of all fields from the well’s data that should be displayed when hovering a well

• well_to_html – Html that sould be displayed when hovering a well (only works if hover_data is left empty).

• well_color_function – A function well=> #a103ba associating a color to fill each well

plateo.exporters.plate_to_genesift_sequencing_order_spreadsheet(plate, output_file, sample_name_function, well_filter=None, direction='row')

Generate an excel spreadsheet for ordering through Genesift

Parameters:

• plate

• output_file

• sample_name_function – A function f(well) => Sample name

• well_filter – A function f(well) => True/false

Examples

>>> plate_to_genesift_sequencing_order_spreadsheet(
        plate,
        output_file="genesift.xls",
        sample_name_function= lambda well: data['part_name'] ,
        well_filter=lambda well: data.get('part_name', False)
        direction='column')

plateo.exporters.plate_to_pandas_dataframe(plate, fields=None, direction='row')

Return a dataframe with the info on each well

plateo.exporters.plate_to_platemap_spreadsheet(plate, wellinfo_function, filepath=None, sheet_name='plate_map', headers=True)

Generate a spreadsheet with a map of the plate.

Parameters:

• plate – A Plate object

• filepath – Path to a “.csv” or “.xls(x)” file. Or a Pandas ExcelWriter object.

• wellinfo_function –

  A function f(well) -> info where well is a Well object of the plate and the returned info is an information about the well that will be displayed in the well’s cell in the final spreadsheet. The info can be a string or any other object that can be converted to a string

     1  2  3  4  5  6  7  8  9  10 11 12
  A  .  .  .  .  .  .  .  .  .  .  .  .
  B  .  .  .  .  .  .  .  .  .  .  .  .
  C  .  .  .  .  .  .  .  .  .  .  .  .
  D  .  .  .  .  .  .  .  .  .  .  .  .
  E  .  .  .  .  .  .  .  .  .  .  .  .
  F  .  .  .  .  .  .  .  .  .  .  .  .
  G  .  .  .  .  .  .  .  .  .  .  .  .
  H  .  .  .  .  .  .  .  .  .  .  .  .
  

Plotters

plateo.exporters.PlateTextPlotter(text_function, line_length=None, fontdict=None)

Plot a plate’s well statistic as text at the well’s positions.

Parameters:

• text_function – A function (well) => text

• with_colorbar – It true a colorbar giving a scale for color values will be plotted alongside the map

plateo.exporters.PlateColorsPlotter(stat_function, colormap=None, plot_colorbar=False, well_radius='full', vmin=None, vmax=None, alpha=1.0, edge_width=1)

Plot a plate’s well statistic with wells colored differently.

Parameters:

• stat_function – The function to be plotted, with signature (well) => value

• with_colorbar – It true a colorbar giving a scale for color values will be plotted alongside the map

plateo.exporters.PlateGraphsPlotter(plot_function, subplot_size=(0.7, 0.7))

Plot a graph (for instance time series) for each well of the plate

The result has the shape of a plate, with each well replaced by a graph.

Parameters:

• plot_function – A function f(well, well_ax) which plots something on the provided well_ax depending on the well.

• subplot_size – (width, height) of subplots, between 0 and 1 (1 meaning the graphs of the different wells will have virtually no margin between them)

Container classes

Classes to represent plates

class plateo.containers.builtin_containers.Plate1536(name=None, wells_data=None, plate_data=None)

Base class for 1536-well plates (32 rows, 48 columns).

class plateo.containers.builtin_containers.Plate2x4(name=None, wells_data=None, plate_data=None)

Class for 8-well (2 x 4) plates such as colony plating plates.

class plateo.containers.builtin_containers.Plate384(name=None, wells_data=None, plate_data=None)

Base class for standard 384-well plates.

class plateo.containers.builtin_containers.Plate4ti0130(name=None, wells_data=None, plate_data=None)

96-well plate with 2ml deepwells from 4titude.

well_class

alias of Plate4ti0130Well

class plateo.containers.builtin_containers.Plate4ti0130Well(plate, row, column, name, data=None)

Well for 96-well plate with 2ml deepwells from 4titude.

class plateo.containers.builtin_containers.Plate4ti0960(name=None, wells_data=None, plate_data=None)

96-well plate from 4titude.

well_class

alias of Plate4ti0960Well

class plateo.containers.builtin_containers.Plate4ti0960Well(plate, row, column, name, data=None)

Well for 96-well plate from 4titude.

class plateo.containers.builtin_containers.Plate96(name=None, wells_data=None, plate_data=None)

Base class for standard 96-well plates.

class plateo.containers.builtin_containers.PlateLabcyteEchoLp0200Ldv(name=None, wells_data=None, plate_data=None)

Low dead volume 384-well Echo plate.

well_class

alias of PlateLabcyteEchoLp0200LdvWell

class plateo.containers.builtin_containers.PlateLabcyteEchoLp0200LdvWell(plate, row, column, name, data=None)

Well for low dead volume 384-well Echo plate.

class plateo.containers.builtin_containers.PlateLabcyteEchoP05525Pp(name=None, wells_data=None, plate_data=None)

Polypropylene 384-well ECHO plate.

well_class

alias of PlateLabcyteEchoP05525PpWell

class plateo.containers.builtin_containers.PlateLabcyteEchoP05525PpWell(plate, row, column, name, data=None)

Well for polypropylene 384-well ECHO plate.

class plateo.containers.builtin_containers.Trough8x1(name, wells_data=None, plate_data=None)

Eight positions share the same content.

Picklists

Representation of a list of well-to-well transfers.

param transfers_list:

A list of Transfer objects that will be part of the same dispensing operation, in the order in which they are meant to be simulated.

param data:

A dict with information on the picklist.

Picklist Parsers

plateo.parsers.picklist_from_labcyte_echo_logfile(logfile=None, logcontent=None, plates_dict=None)

Return a picklist of what was actually dispensed in the ECHO, based on the log file.

Picklist.metadata[“exceptions”] is a picklist of all transfers that went wrong.

Parameters:

• logfile – The path to the echo logfile.

• logcontent – Echo logfile content, can be provided instead of filename

• plates_dict – A dictionary of the form {‘Plate name’: Plate()} linking the plate names found in the Echo logs to Plateo Plate objects. If None is provided, plates are infered from the Echo logs (a bit experimental).

plateo.parsers.picklist_from_tecan_evo_picklist_file(filename, plates_dict)

Read a .gwl file into a PickList

Parameters:

• filename – A .gwl file

• plates_dict – A dictionnary linking the plate names inside the file to plate objects For instance { “PrimersPlate”: primers_plate, “SeqDestPlate”: … }

Tools

Miscellaneous useful functions.

In particular, methods for converting to and from plate coordinates.

plateo.tools.find_best_volume_unit(vols)

Find the best volume unit for a list of volumes.

plateo.tools.human_seq_size(n)

Return the given sequence as a human friendly 35b, 1.4k, 15k, etc.

plateo.tools.human_volume(vol, unit='auto')

Return a human-readable volume.

plateo.tools.replace_nans_in_dict(dictionary, replace_by='null')

Replace NaNs in a dictionary with a string.

Parameters:

• dictionary (dict) – the dictionary

• replace_by (str) – replacement

plateo.tools.round_at(value, rounding=None)

Round value to the nearest rounding.

Parameters:

value – the value to round.