Step Utils

Actions

s4.clarity.steputils.actions.get_artifact_workflow_stages_for_current_step(step, artifact)

s4.clarity.steputils.actions.get_current_workflow_stages(step, artifacts)

Given artifacts in a currently running step, finds their current workflow stages.

Returns:a dict mapping workflow stages to lists of artifacts which are currently in them. Return type:dict[Stage, list[Artifact]]

s4.clarity.steputils.actions.route_to_next_protocol(step, artifacts_to_route)

Queues the given artifacts directly to the first step of the next protocol. NOTE: Artifacts must be in-progress in the current step, or an exception will be thrown.

s4.clarity.steputils.actions.route_to_stage_by_name(step, artifacts_to_route, target_stage_name, name_matches_base_name=<function <lambda>>)

Queues the given artifacts to the first stage in the artifact’s workflow with the given name. NOTE: Artifacts must be in-progress in the current step, or an exception will be thrown. Optionally takes a name comparison function to use. Defaults to exact name matching.

s4.clarity.steputils.actions.set_next_actions(epp, default_action=None, controls_action=None, failed_qc_action=None, action_func=None)

Parameters:

• failed_qc_action – applied to any sample or control that has failed qc.
• controls_action – applied to controls. if this is a qc step, only controls which have passed.
• action_func ((s4.clarity.Artifact) -> str) – called with each artifact; must return an action (string). if either failed_qc_action or controls_action are set, and also action_func is set, action_func will only be called for artifacts which are not caught by those actions. if action_func is None, or returns None for an artifact, the default is used.
• default_action – if None, an appropriate action is calculated (e.g. next step, or complete protocol.)

Copy UDFs

s4.clarity.steputils.copyudfs.copy_from_input_to_output(step, udf_names)

Copies a set of UDFs from the inputs of a step to its outputs. - Supply a list of UDFs if the source and destination names are the same. - Supply a dictionary (source name to destination name) if they differ.

If the UDF is not present on the source, it is skipped.

Will throw an exception if there are more than one input per output.

s4.clarity.steputils.copyudfs.copy_from_input_to_sample(step, udf_names)

Copies a set of UDFs from the inputs of a step to each input’s sample. - Supply a list of UDFs if the source and destination names are the same. - Supply a dictionary (source name to destination name) if they differ.

If the UDF is not present on the source, it is skipped.

s4.clarity.steputils.copyudfs.copy_from_output_to_input(step, udf_names)

Copies a set of UDFs from the outputs of a step to its inputs, one to one. - Supply a list of UDFs if the source and destination names are the same. - Supply a dictionary (source name to destination name) if they differ.

If the UDF is not present on the source, it is skipped.

Will throw an exception if there are more than one input per output or more than one output per input.

s4.clarity.steputils.copyudfs.copy_from_output_to_sample(step, udf_names)

Copies a set of UDFs from the outputs of a step to each output’s sample. - Supply a list of UDFs if the source and destination names are the same. - Supply a dictionary (source name to destination name) if they differ.

If the UDF is not present on the source, it is skipped.

s4.clarity.steputils.copyudfs.copy_from_sample_to_input(step, udf_names)

Copies a set of UDFs to the inputs of a step from each input’s sample. - Supply a list of UDFs if the source and destination names are the same. - Supply a dictionary (source name to destination name) if they differ.

If the UDF is not present on the source, it is skipped.

s4.clarity.steputils.copyudfs.copy_from_sample_to_output(step, udf_names)

Copies a set of UDFs to the outputs of a step from each output’s sample. - Supply a list of UDFs if the source and destination names are the same. - Supply a dictionary (source name to destination name) if they differ.

If the UDF is not present on the source, it is skipped.

Files

s4.clarity.steputils.file_utils.save_file_to_path(step, target_directory, limsid, file_name=None)

Saves step output files to the specified directory.

Parameters:

• step – The step which contains the files to save.
• target_directory – The directory path to save files to.
• limsid – The lims id of the file to save.
• file_name – Optional file name to use when saving the file to disk. It allows renaming on save.

Placements

s4.clarity.steputils.placement_utils.auto_place_artifacts(step, artifacts, order='row')

Places the artifacts provided, in the order provided, to selected_containers in the step.

s4.clarity.steputils.placement_utils.column_order_sort_keys(artifact)

Provide container position sort-keys for the sorted function based on column-major order

Usage example:

sorted_outputs = sorted(self.outputs, key=row_order_sort_keys)

Return type:tuple(str|int, str|int)

s4.clarity.steputils.placement_utils.place_plate_to_plate_match_wells(step, input_container, output_container)

Places samples in the input_container in the output_container at the same well location. Plates do not have to be the same dimensions, but artifacts placed at invalid wells will not be accepted by Clarity.

To submit these changes you will need to call step.placements.post_and_parse() after. :param step: The step that the placement is being done for :param input_container: Container with artifacts to place in the output container :param output_container: Container that will be populated with artifacts.

s4.clarity.steputils.placement_utils.row_order_sort_keys(artifact)

Provide container position sort-keys for the sorted function based on row-major order

Usage example:

sorted_outputs = sorted(self.outputs, key=row_order_sort_keys)

Return type:tuple(str|int, str|int)

Step Average

s4.clarity.steputils.step_average_utils.calculatecv(lst)

s4.clarity.steputils.step_average_utils.compute_average(epp, sourceudf, averageudf, excludeudf, cvudf, outputdilutionudf=None, inputdilutionudf=None)

s4.clarity.steputils.step_average_utils.discard_outliers(epp, sourceudf, excludeudf, cvthreshold, madthreshold)

s4.clarity.steputils.step_average_utils.find_dilution_factor(iomap, outputdilutionudf, inputdilutionudf)

s4.clarity.steputils.step_average_utils.median(lst)

Step Runner

class s4.clarity.steputils.step_runner.StepRunner(lims, protocolname, stepconfigname, usequeuedinputs=True, numberofinputs=4)

StepRunner is the abstract class that provides base functionality to automatically execute a step in Clarity. Sub classes can implement ‘virtual’ methods to take custom action at each screen in the step.

add_default_reagents()

For every required reagent kit in the step, the first active lot will be selected. If there are no active lots it will be omitted.

add_reagents_step()

arranging()

fire_script(script_name)

get_controls_from_control_names(candidate_control_names)

get control els controls from array of control_names :raise Exception: If any control names not permitted or non-existent

get_previous_steps_outputs(previous_step, get_all=False)

By default, filters previous step’s actioned artifacts which either continued to this step, or ended a protocol. If get_all=True, doesn’t filter.

Returns:list of artifact URIs that match the conditions Return type:list[str]

get_started_step(previous_step, project_name)

load_existing_step(step_limsid)

Loads an existing step from Clarity into the StepRunner. :param step_limsid: The LIMS ID of an existing, but not completed step.

load_new_step(input_uri_list=None, previous_step=None, controls=None, container_type=None, reagent_type=None, control_names=None)

Starts a new step to be used by the StepRunner.

Parameters:

• input_uri_list – A list of artifacts that will be use to run the step
• previous_step – A step that has already run, the outputs of which will be used as the inputuris
• controls – The list of controls that will be included in this step
• container_type – The container that output artifacts will be placed in. If none is supplied the default will be used.
• reagent_type – The name of the reagent category to use for the step. If none is supplied the default will be used.
• control_names – If no controls are provided, this list of control names will be used to look up controls and include them in the step

next_steps()

placement()

pooling()

post_tube_to_tube(container_type_name='Tube')

Create single-well (tube) containers, and place the outputs in them.

This works around a ‘bug’ in Clarity where, when a step is run through the API, Clarity will not automatically move artifacts from input tubes to output tubes.

It is necessary if you are automating a step that has tube inputs and tube outputs. Override the record_details() method in your sub class and call this method as the first action in it.

@param container_type_name: the name of the container type. Must be single-well, but not necessarily “Tube”

prefetch_artifacts()

Loads the current state in Clarity of all inputs and outputs.

record_details()

replicates_for_control(control)

replicates_for_inputuri(input_uri)

run(inputuris=None, previousstep=None, controls=None, containertype=None, reagenttype=None, steplimsid=None, control_names=None)

Runs a step from its current state to completion.

Parameters:

• inputuris – A list of artifacts that will be use to run the step
• previousstep – A step that has already run, the outputs of which will be used as the inputuris
• controls – The list of controls that will be included in this step
• containertype – The container that output artifacts will be placed in. If none is supplied the default will be used.
• reagenttype – The name of the reagent category to use for the step. If none is supplied the default will be used.
• steplimsid – The LIMS ID of an existing, but not completed step. If this is provided all other arguments will be ignored
• control_names – If no controls are provided, this list of control names will be used to look up controls and include them in the step

run_to_state(goal_state_name)

Execute sequential stages in the step until the goal state is reached.

Parameters:goal_state_name – The name of the state to run to, name must be in the list ALL_STEP_STATES list

set_artifact_udf_as_user(artifact, udf_name, value, stop_on_error=True)

Set an Artifact UDF after first validating that it’s both visible on the step, and editable.

Parameters:

• artifact (s4.clarity.Artifact) – An Artifact (Analyte or ResultFile) in a running step.
• udf_name – Name of the udf
• value – Value to set
• stop_on_error – Whether to raise an Exception if the user couldn’t set the value. Otherwise, the method will log an error and continue

Raises:

Exception – If stop_on_error is True, and there is any reason that would prevent the user from setting the UDF in the Clarity UI

set_step_udf_as_user(udf_name, value, stop_on_error=True)

Set a Step UDF after first validating that it’s both visible on the step, and editable.

Parameters:

• udf_name – Name of the udf
• value – Value to set
• stop_on_error – Whether to raise an Exception if the user couldn’t set the value. Otherwise, the method will log an error and continue

Raises:

Exception – If stop_on_error is True, and there is any reason that would prevent the user from setting the UDF in the Clarity UI

setup()

step_config

Type:StepConfiguration

exception s4.clarity.steputils.step_runner.StepRunnerException