pydent.planner.Planner

class pydent.planner.Planner(session_or_plan=None, plan_id=None)

Bases: pydent.planner.planner.AFTMatcher

A user-interface for making experimental plans and layouts.

__init__(session_or_plan=None, plan_id=None)

Initialize self. See help(type(self)) for accurate signature.

Methods

__init__([session_or_plan, plan_id])	Initialize self.
add_wire(fv1, fv2)	Add wire from one FieldValue to another FieldValue.
annotate(markdown, x, y, width, height)	Annotates the plan with Markdown text.
annotate_above_layout(markdown, width, height)	Annotates text directly above a layout.
annotate_operations(ops, markdown, width, height)	Annotates above the operations.
cache()
cache_plans(browser, plans)	rtype Iterable[Plan]
chain(*op_or_otnames[, category, return_as_dict])	Creates a chain of operations by guessing wires between operations based on the AllowableFieldTypes between the inputs and outputs of each operation type.
clean_wires()
combine(plans)	Merges a list of plans into a single plan by combining operations and wires.
copy()	Return a copy of this planner, with a new anonymous copy of the plan.
create()	Create the plan on Aquarium.
create_operation_by_name(operation_type_name)	Adds a new operation to the plan.
create_operation_by_type(ot[, status])	rtype Operation
create_operation_by_type_id(ot_id)	rtype Operation
distribute_items_of_object_type(object_type)	Distribute items of a particular object_type across non-planning operations across existing plans and these operations in this Planner instance.
draw()
get_available_items(field_value, item_preference)	rtype List[Item]
get_fv_predecessors(fv)	rtype List[FieldValue]
get_fv_successors(fv)	rtype List[FieldValue]
get_incoming_wires(fv)	rtype List[Wire]
get_op(id)	rtype Optional[Operation]
get_op_by_name(operation_type_name)	Find operations by their operation_type_name.
get_op_predecessors(op)	rtype List[Operation]
get_op_successors(op)	rtype List[Operation]
get_outgoing_wires(fv)	rtype List[Wire]
get_sample_routing_of_operation(op)	rtype Dict[str, List[FieldValue]]
get_wire(fv1, fv2)	rtype Optional[Wire]
ipython_link()
move_op(op, plan_id)
new_op(name_id_or_ot)	rtype Operation
open()
Planner.optimize_plan
prettify()	rtype None
quick_create_and_wire(otname1, otname2[, …])
quick_create_operation_by_name(otname)	rtype Operation
quick_wire(source, destination[, strict])	type source Union[Operation, FieldValue, Tuple[Operation, str]]
quick_wire_by_name(otname1, otname2)	Wires together the last added operations.
remove_operations(ops)
remove_wire(fv1, fv2)	Removes a wire between two field values from a plan.
replan()	Replan the plan, by ‘copying’ the plan using the Aquarium server.
reserved_items(items[, search_server])	Returns a dictionary of item_ids and the array of field_values that use them.
roots()	Get field values that have no predecessors (i.e.
save()	Saves the Plan to the Aquarium server.
set_field_value(field_value[, sample, item, …])	Changed in version 0.1.5a15: Argument container changed to object_type to keep consistency with other code.
set_field_value_and_propogate(field_value[, …])
set_input_field_value_array(op, field_value_name)	Finds the first ‘empty’ (no incoming wires and no sample set) field value and set the field value.
set_inputs_using_sample_properties(…[, …])	Map the sample field values to the operation inputs.
set_output_sample(fv[, sample, routing, setter])	Sets the output of the field value to the sample.
set_to_available_item(fv[, …])	Sets the item of the field value to the next available item.
split()	Split the plan into several distinct plans, if possible.
update()	Update the plan on Aquarium.
validate()	Validates sample routes in the plan.

Attributes

browser
graph
layout	rtype PlannerLayout
name
plan
url

class ITEM_ORDER_PREFERENCE

Bases: object

Item order options.

FIRST = 'FIRST'

select first item

LAST = 'LAST'

select last item

RANDOM = 'RANDOM'

select random item

_CHOICES = ['FIRST', 'LAST', 'RANDOM']

all choices

_DEFAULT = 'LAST'

the default choice

class ITEM_SELECTION_PREFERENCE

Bases: object

Item selection options.

ANY = 'ANY'

pick the first item that matches the set field_value

PREFERRED = 'PREFERRED'

(default) pick the item that matches the currently set aft, else

RESTRICT = 'RESTRICT'

restrict to the currently set allowable_field_type

RESTRICT_TO_ONE = 'RESTRICT TO ONE'

will not select item if its being used in another active operation

RESTRICT_TO_ONE_ON_SERVER = 'RESTRICT TO ONE ON SERVER'

will restrict to a single item across the plans on the server.

_CHOICES = ['ANY', 'RESTRICT', 'PREFERRED', 'RESTRICT TO ONE']

all choices

_DEFAULT = 'PREFERRED'

default item selection preference

classmethod _collect_matching_afts(source, destination)

Parameters

• source (FieldValue|Operation) – a field value or operation source

• destination (FieldValue|Operation) – a field value or operation destination

Returns

tuple of matching allowable_field_type (aft) pairs, matching field_value inputs and matching field_value outputs

Return type

tuple

static _find_matching_afts(src_ft, dest_ft)

Finds matching afts between two FieldTypes.

Return type

List[Tuple[AllowableFieldType, AllowableFieldType]]

static _json_update(model, **params)

Temporary method to update.

Return type

ModelBase

_routing_graph()

Get sample routing graph.

A property of a valid plan is that any two routing nodes that are connected by an edge must have the same sample. Edges are treated as ‘sample wires’

_select_empty_input_array(op, fvname)

Selects the first ‘empty’ (i.e. field_values with no Sample set) field value in the FieldValue array. Returns None if the FieldType is not an array. If there are no current ‘empty’ field values, a new one is instantiated and returned.

Parameters

• op (Operation) – Operation

• fvname (str) – FieldType/FieldValue name of the array

Return type

Optional[FieldValue]

Returns

add_from_template(plan)

Add Operation and Wires from the provided template plan to this planner.

Parameters

plan (Union[int, Plan, Planner]) – Plan id (int), Plan instance, or Planner instance

Return type

List[Operation]

Returns

list of operations that were added from template.

add_wire(fv1, fv2)

Add wire from one FieldValue to another FieldValue.

Parameters

• fv1 (FieldValue) – source FieldValue

• fv2 (FieldValue) – destination FieldValue

Return type

Wire

Returns

the new Wire

annotate(markdown, x, y, width, height)

Annotates the plan with Markdown text.

Parameters

• markdown (basestring) – text to annotate (in markdown format)

• x (int) – x-position

• y (int) – y-position

• width (int) – width of the text box

• height (int) – height of the text box

Returns

None

Return type

None

annotate_above_layout(markdown, width, height, layout=None)

Annotates text directly above a layout.

annotate_operations(ops, markdown, width, height)

Annotates above the operations.

Estimates the x-midpoint and y and makes a text annotation at that location.

Return type

dict

chain(*op_or_otnames, category=None, return_as_dict=False)

Creates a chain of operations by guessing wires between operations based on the AllowableFieldTypes between the inputs and outputs of each operation type. Sample inputs and outputs will be set along the wire if possible.

e.g.

# create four new operations based on their OperationType names
planner.chain("Make PCR Fragment", "Run Gel",
                          "Extract Gel Slice", "Purify Gel Slice")

# create four new operations based on their OperationType names by
# finding OperationTypes only in the "Cloning" category
planner.chain("Make PCR Fragment", "Run Gel",
                          "Extract Gel Slice", "Purify Gel Slice",
                          category="Cloning")

# create four new operations based on their OperationType names by
# finding OperationTypes only in the "Cloning" category,
# except find "Make PCR Fragment" in the "Cloning Sandbox" category
planner.chain(("Make PCR Fragment", "Cloning Sandbox"),
                           "Run Gel", "Extract Gel Slice",
                           "Purify Gel Slice", category="Cloning")

# create and wire new operations to an existing operations while
# routing samples
pcr_op = planner.create_operation_by_name("Make PCR Fragment")
planner.set_field_value(pcr_op.outputs[0], sample=my_sample)
new_ops = planner.chain(pcr_op, "Run Gel")
run_gel = new_ops[1]
planner.chain("Pour Gel", run_gel)

Return type

List[Operation]

static combine(plans)

Merges a list of plans into a single plan by combining operations and wires.

Parameters

plans (List[Plan]) – list of Aquarium Plans instances

Return type

Planner

Returns

new Plan

copy()

Return a copy of this planner, with a new anonymous copy of the plan.

Browser cache is copied as well, but model_cache in browser are not anonymous

Return type

Planner

create()

Create the plan on Aquarium.

create_operation_by_name(operation_type_name, category=None)

Adds a new operation to the plan.

Return type

Operation

delete()

Delete the plan on the Aquarium server. Make an annonymized copy of the plan stored in Trident.

New in version 0.1.5a10: Added delete method

distribute_items_of_object_type(object_type)

Distribute items of a particular object_type across non-planning operations across existing plans and these operations in this Planner instance.

E.g. distributing one-shot yeast competent cell aliquots

get_op_by_name(operation_type_name)

Find operations by their operation_type_name.

Parameters

operation_type_name (basestring) – The operation type name

Returns

list of operations

Return type

list

move_operations(ops, to_plan_id, confirm=True)

Move a list of operations from this planner to a different plan.

Parameters

• ops – list of operations

• to_plan_id – destination plan_id

• confirm (bool) – whether this required confirmation from the user.

Returns

None

property operations

Return list of operations in the plan.

Return type

List[Operation]

Returns

list of operations

optimize(merge_missing_samples=False)

Optimize the plan, merging wires and operations that have identical inputs and outputs.

Changed in version 0.1.5a11: Numerous bug fixes.

Parameters

merge_missing_samples – if True, the method will consider FieldValues with missing inputs as identical. By default, this is False, and so the method will not merge any operation with a missing input or output.

Return type

Planner

Returns

the planner (self)

quick_wire(source, destination, strict=False)

Parameters

• source (FieldValue|Operation) – field_value or operation source

• destination (FieldValue|Operation) – field_value or operation destination

• strict (bool) – will raise error if there is is ambiguous wiring between the source and destination

Returns

created wire

Return type

Wire

quick_wire_by_name(otname1, otname2)

Wires together the last added operations.

Return type

Wire

remove_wire(fv1, fv2)

Removes a wire between two field values from a plan.

Parameters

• fv1 (FieldValue) –

• fv2 (FieldValue) –

Return type

Wire

Returns

replan()

Replan the plan, by ‘copying’ the plan using the Aquarium server.

Return type

Planner

reserved_items(items, search_server=False)

Returns a dictionary of item_ids and the array of field_values that use them.

Return type

Dict[int, List[FieldValue]]

roots()

Get field values that have no predecessors (i.e. are ‘roots’)

Return type

List[FieldValue]

save()

Saves the Plan to the Aquarium server.

Returns

None

set_field_value(field_value, sample=None, item=None, object_type=None, value=None, row=None, column=None)

Changed in version 0.1.5a15: Argument container changed to object_type to keep consistency with other code.

Parameters

• field_value (FieldValue) –

• sample (Optional[Sample]) –

• item (Optional[Item]) –

• object_type (Optional[ObjectType]) –

• value (Optional[Any]) –

• row (Optional[int]) –

• column (Optional[int]) –

Returns

set_input_field_value_array(op, field_value_name, sample=None, item=None, container=None, value=None, row=None, column=None)

Finds the first ‘empty’ (no incoming wires and no sample set) field value and set the field value. If there are no empty field values in the array, create a new field value and set that one.

Parameters

• op (Operation) – operation

• field_value_name (basestring) – field value name

• sample (Sample) – the sample to set

• item (Item) – the item to set

• container (ObjectType) – the container type to set

Returns

the set field value

Return type

FieldValue

set_inputs_using_sample_properties(operation, sample, routing=None, setter=None)

Map the sample field values to the operation inputs. Optionally, a routing dictionary may be passed to indicate the mapping between the sample field values and operation inputs.

For example, the following would map the “Integrant” sample field value to the “Template” operation input, and so on…:

routing={
    "Integrant": "Template",
    "QC_Primer1": "Forward Primer",
    "QC_Primer2": "Reverse Primer"
}

set_output_sample(fv, sample=None, routing=None, setter=None)

Sets the output of the field value to the sample. If the field_value names between the Sample and the field_value’s operation inputs, these will be set as well. Optionally, a routing dictionary may be passed to indicate the mapping between the sample field values and the operation field values.

Parameters

• fv (FieldValue) – the output field value

• sample (Optional[Sample]) –

• routing (Optional[dict]) –

Returns

Return type

set_to_available_item(fv, order_preference='LAST', filter_func=None, item_preference='PREFERRED')

Sets the item of the field value to the next available item. Setting recent=False will select the oldest item.

Parameters

• fv (FieldValue) – The field value to set.

• recent (bool) – whether to select the most recent item (recent=True is default)

• filter_func (list) – array of lambda to filter items by. E.g. ‘lambda_arr=[lambda x: x.get(“concentration”) > 10]’

• order_preference (basestring) – The item order preference. Select from “LAST” (default), “FIRST”, or “RANDOM”. Selections also available in Planner.ITEM_ORDER_PREFERENCE. Random will choose a random item from the available items found after all preferences and filters

• item_preference (basestring) – The item selection preference. Select from items in Planner.ITEM_SELECTION_PREFERENCE If “PREFERRED” (default), will select item that matches the allowable_field_value that is already set for the field_value, else select any item that matches the Sample set FieldValue. If “RESTRICT”, will restrict selected item only to those that matches the current allowable_field_value that is set for the FieldValue. If “ANY”, will select any items that matches the Sample.set for the field_value

Returns

The selected item (or None if no item set)

Return type

Item or None

split()

Split the plan into several distinct plans, if possible.

This first convert the plan to an operation graph, find subgraphs that are not connected to each other, and create new plans based on these subgraphs. This will return anonymous copies of all the plans, meaning operations and field_values will be anonymized. Sample and items attached to field values will remain to avoid re-creating samples and items.

Return type

List[Planner]

update()

Update the plan on Aquarium.

validate()

Validates sample routes in the plan.

Returns

dictionary of each sample route and validation errors

Return type

dict