Scripts

Listed here are the definitions of the various base classes of scripts.

Derived Sample Automation Script

class s4.clarity.scripts.DerivedSampleAutomation(options)

Bases: s4.clarity.scripts.GenericScript

A script run from the Project Dashboard screen.

Variables:
  • lims (LIMS) – The Clarity object to perform operations against.
  • artifacts (list[Artifact]) – The list of Artifacts that the script applies to, loaded from the provided LIMS Ids.
Parameters:

options (map) – A map of the values of the supplied command line arguments. The default keys available are: username, password, api_uri, and derived_sample_ids.

Usage:

Implement process_derived_samples(), which must return a string to display success status to the user.

Optionally:
add_arguments(argparser) # To add more arguments. Don’t forget to call super.

Add to the end of your file:

if __name__ == ‘__main__’:
YourSubClass.main()

Example Clarity automation string. Contains an example of additional user input that would require an override of add_arguments to add the -x arg. Note that all userinput args are strings:

python <script_name>.py -u {username} -p {password} -a '{baseURI}v2' -d {derivedSampleLuids} -x {userinput:input_x}
classmethod add_arguments(argparser)[source]

Configures the Argument Parser to read command line input and store it in the self.options object.

This method can be overrode in sub classes to provide extra arguments specific to the script being written. When this is done it is important to call the parent class add_arguemnts methods so that all arguments are included.

Parameters:parser (argparse.ArgumentParser) – The ArgumentParser that will be used to process the command line.
process_derived_samples()[source]

Implement this to perform the work required. Method must return a summary success string, as it’s used to display the user-facing message on script completion.

Returns:Message to report success to the user
Return type:str
Raise:Exception to report failure
run()[source]

The run method is called once the arguments are parsed and the logging is started. It will return an exit code indicating the success or failure of the process to run. Exit Codes: http://www.tldp.org/LDP/abs/html/exitcodes.html

Returns:The Exit code

Generic Script

class s4.clarity.scripts.GenericScript(options)

GenericScript is the base abstract class for all of our script classes. The class provides common logging, argument parsing and entry point for all other script types.

The GenericScript provides the main() method as an entry point for all scripts. Because your implementing class will be the main entry point for the program it will need to call the main method.

The following code will make sure that the script is only run _if_ the file is the main python entry point:

if __name__ == ‘__main__’:
YourSubClass.main()

For more information on this see:

Command line arguments can be added by overriding the add_arguments method. Remember to call the parent implementation of add_arguments so that all arguments are included.

Example method adding an extra command line argument:

@classmethod
def add_arguments(cls, argparser):
    super(YourSubClass, cls).add_arguments(argparser)
    argparser.add_argument(
        '-t', '--thisparam', type=str, help='Something helpful', required=True
    )

The values will be available in the self.options object.

An example of printing the value passed in as –thisparam print self.options.thisparam

This class works with the python logging system to gather log information and save it to a file. The files can be stored as html or plain text.

To use this logging system in your own files declare the logging object at the top of each file:

log = logging.getLogger(__name__)

The log object can then be used to log information that the GenericScript will save.

log.info(“Low priority info to log.”) log.warning(“Warnings to log”) log.error(“Error conditions logged”)

To add functionality to a class derived from GenericScript the run() method must be overrode in the child class.

Creates a new instance of this class and saves the command line options

Parameters:options (argparse.Namespace) – The parsed command line options
TEXT_LOG_FORMAT = '%(asctime)s\t%(levelname)s\t%(name)s: %(message)s'
classmethod add_arguments(parser)[source]

Configures the Argument Parser to read command line input and store it in the self.options object.

This method can be overrode in sub classes to provide extra arguments specific to the script being written. When this is done it is important to call the parent class add_arguemnts methods so that all arguments are included.

Parameters:parser (argparse.ArgumentParser) – The ArgumentParser that will be used to process the command line.
final_summary = ''
static loggingpreamble(obfuscated_options)[source]
classmethod main()[source]

The entry point for all scripts. This method will exit() the program upon completion.

open_log_output_stream()[source]

override this for more complicated logging output.

Return type:io.IOBase
run(*args)[source]

The run method is called once the arguments are parsed and the logging is started. It will return an exit code indicating the success or failure of the process to run. Exit Codes: http://www.tldp.org/LDP/abs/html/exitcodes.html

Returns:The Exit code

Shell Script

class s4.clarity.scripts.ShellScript(options)

Bases: s4.clarity.scripts.GenericScript

ShellScript provides the framework for a basic shell script that will communicate with Clarity. It provides all of the functionality of a GenericScript with the addition of a LIMS object.

Creates a new instance of this class and saves the command line options

Parameters:options (argparse.Namespace) – The parsed command line options
classmethod add_arguments(parser)[source]

Add command line arguments to be parsed.

Parameters:parser (argparse.ArgumentParser) – The ArgumentParser that will be used to process the command line.

StepEpp

class s4.clarity.scripts.StepEPP(options)

Bases: s4.clarity.scripts.GenericScript

This class forms the base of the scripting for Step EPP scripts run from Clarity. It will provide access to a LIMS object as well as the Step data for the currently running step.

If the log file name that gets passed in over the command line is the limsId clarity assigned to an file it will be automatically uploaded at the end of the step.

Variables:
  • step (s4.clarity.step.Step) – The Clarity Step to execute the script against.
  • lims (LIMS) – The Clarity LIMS object to use for API operations.

Creates a new StepEPP object and initializes the local LIMS and Step objects.

Parameters:options – Parsed command line options
PREFETCH_INPUTS = 'inputs'
PREFETCH_OUTPUTS = 'outputs'
PREFETCH_SAMPLES = 'samples'
classmethod add_arguments(argparser)[source]

Configures the Argument Parser to read command line input and store it in the self.options object.

This method can be overrode in sub classes to provide extra arguments specific to the script being written. When this is done it is important to call the parent class add_arguemnts methods so that all arguments are included.

Parameters:parser (argparse.ArgumentParser) – The ArgumentParser that will be used to process the command line.
static display(*args)[source]
inputs

Shortcut for self.step.details.inputs.

Return type:list[Artifact]
iomaps

Shortcut for self.step.details.iomaps.

Return type:list[IOMap]
open_log_output_stream()[source]

Use step’s logfile.

outputs

Shortcut for self.step.details.outputs.

Return type:list[Artifact]
prefetch(*categories)[source]

Fetch values for input artifacts, output artifacts, or samples in a batch.

Input and output samples are always an identical set, so ‘samples’ will fetch both.

Note: when only samples are selected, input artifacts will also be fetched. To change this behaviour, supply both ‘outputs’ and ‘samples’ in the categories list.

Parameters:categories (str|list[str]) – List of any number of the strings: ‘inputs’, ‘outputs’, ‘samples’.
Returns:a list of all fetched objects
Return type:list[ClarityElement]

TriggeredStepEpp

class s4.clarity.scripts.TriggeredStepEPP(options)

Bases: s4.clarity.scripts.StepEPP

TriggeredStepEPP acts as an EPP with multiple entry points, to allow the developer to group all scripts associated with a step together in a single file. A script implementing this class is intended to be called multiple times in the same step at different stages, with the Action parameter determining which method is called.

Choices for the Action parameter are automatically generated from all class methods starting with on_. The Action value is generated by taking the method name, trimming the on_, and transforming the rest of the name to Pascal-case. For example, an EPP String containing -a TestThing would attempt to execute a method named on_test_thing.

Usage:
python <script.py> -u {username} -p {password} --step-uri {stepURI:v2} -l {compoundOutputFileLuid#} -a <Action>

Our suggested implementation when creating method names is to mirror Clarity’s language for scripts triggered on step transitions, and having button-triggered scripts follow the button label, as shown here:

Action Parameter EPP Method Name
BeginningOfStep on_beginning_of_step
EndOfStep on_end_of_step
PlacementEnter on_placement_enter
PlacementExit on_placement_exit
PoolingEnter on_pooling_enter
PoolingExit on_pooling_exit
AddReagentsEnter on_add_reagents_enter
AddReagentsExit on_add_reagents_exit
RecordDetailsEnter on_record_details_enter
RecordDetailsExit on_record_details_exit
CalculateQc on_calculate_qc (Record Details buttons example)

Ultimately, though, as long as the on_ rules for method naming is followed, the pattern used in your implementation is up to you.

Creates a new StepEPP object and initializes the local LIMS and Step objects.

Parameters:options – Parsed command line options
classmethod add_arguments(argparser)[source]

Configures the Argument Parser to read command line input and store it in the self.options object.

This method can be overrode in sub classes to provide extra arguments specific to the script being written. When this is done it is important to call the parent class add_arguemnts methods so that all arguments are included.

Parameters:parser (argparse.ArgumentParser) – The ArgumentParser that will be used to process the command line.
classmethod add_triggered_step_actions()[source]
run()[source]

The run method is called once the arguments are parsed and the logging is started. It will return an exit code indicating the success or failure of the process to run. Exit Codes: http://www.tldp.org/LDP/abs/html/exitcodes.html

Returns:The Exit code
triggered_step_actions = {}

UserMessageException

class s4.clarity.scripts.UserMessageException

Bases: Exception

Stops the currently running EPP and displays a message box to the user. The message box is like other exceptions but will not display a stack trace.

Workflow Test

class s4.clarity.scripts.WorkflowTest(options)

Bases: s4.clarity.scripts.ShellScript

Creates a new instance of this class and saves the command line options

Parameters:options (argparse.Namespace) – The parsed command line options
classmethod add_arguments(argparser)[source]

Add command line arguments to be parsed.

Parameters:parser (argparse.ArgumentParser) – The ArgumentParser that will be used to process the command line.