Clarity Elements

Listed here are the definitions for classes that mirror the XML entities used by the Clarity API.

Artifact

class s4.clarity.artifact.Artifact(lims, uri=None, xml_root=None, name=None, limsid=None)[source]

Bases: s4.clarity._internal.FieldsMixin, s4.clarity.ClarityElement

Reference: https://www.genologics.com/files/permanent/API/latest/data_art.html#artifact

container

From “location.container”. For XML value “location.value”, use Python property .location_value.

Type:Container
control_type
Type:ControlType
demux[source]

Provides access to the ‘demux’ endpoint added in Clarity 5.1.

Using this property with an earlier version of Clarity will result in a 404 Not Found error.

Type:ArtifactDemux
file
Type:File
is_control
Type:bool
location_value

The value of the XML property ‘location/value’

Type:str
open_file(mode, only_write_locally=False, name=None)[source]
Parameters:
  • mode (str) – ‘r’, ‘r+’, ‘w’, ‘a’, ‘rb’, ‘r+b’, ‘wb’, ‘ab’. NOTE: ‘r+’ sets initial file position to the beginning, ‘a’ sets it to the end.
  • only_write_locally (bool) – if true, don’t upload this file to Clarity.
  • name (str) – The name that will be used if you are creating a new file.
Return type:

File
output_type

The value of the XML property ‘output-type’

Type:str
parent_process

The linked Process from the ‘parent-process’ subnode

Type:Process
parent_step
Type:Step
qc

Whether QC is marked as PASSED or FAILED on the artifact

Clarity Value Bool Value
PASSED True
FAILED False
UNKNOWN None
Type:bool
qc_failed()[source]
Return type:bool
qc_passed()[source]
Return type:bool
queued_stages
Type:set[Stage]
reagent_label_name
Type:str
reagent_label_names
Type:list[str]
reagent_labels

ReagentLabel items from the ‘reagent-label’ subnodes

Type:list[ReagentLabel]
sample
Type:Sample
samples
Type:list[Sample]
set_qc_flag(value)[source]

The qc property should be used in favor of this method.

Parameters:value (bool) – True if PASSED, False if FAILED, None to unset.
type

The value of the XML property ‘type’

Type:str
workflow_stages

WorkflowStageHistory items from the ‘workflow-stage’ subnodes

Type:list[WorkflowStageHistory]

Artifact Action

class s4.clarity.step.ArtifactAction(lims, step, xml_root)[source]
action

The value of the XML property ‘action’

Type:str
artifact_uri

The value of the XML property ‘artifact-uri’

Type:str
complete_and_repeat(step_uri)[source]

Sets the Next Step property for the artifact specified by artifact_uri to ‘Complete and Repeat’ with the specified next step uri.

mark_protocol_complete()[source]
next_step(step_uri=None)[source]

Set the next step to continue to, or mark the protocol as complete if there is no next step.

If step_uri is not provided, artifact will: - Continue to the first transition defined for this step, if any transitions are defined. - Mark the protocol as complete, if there are no transitions (the protocol is done).

remove_from_workflow()[source]

Sets the Next Step property for the artifact specified by artifact_uri to ‘Remove From Workflow’

repeat()[source]

Sets the Next Step property for the artifact specified by artifact_uri to ‘Repeat Step’

review()[source]

Sets the Next Step property for the artifact specified by artifact_uri to ‘Request Manager Review’

rework(step_uri)[source]

Sets the Next Step property for the artifact specified by artifact_uri to ‘Rework from an earlier step’ with the specified next step uri.

rework_step_uri

The value of the XML property ‘rework-step-uri’

Type:str
step_uri

The value of the XML property ‘step-uri’

Type:str

Artifact Demux

class s4.clarity.artifact.ArtifactDemux(lims, uri=None, xml_root=None, name=None, limsid=None)[source]

Bases: s4.clarity.ClarityElement

Corresponds to the ‘demux’ type in the ‘artifact’ namespace of the Clarity API.

artifact

The linked Artifact from the ‘artifact’ subnode

Type:Artifact
demux

The element DemuxDetails from subnode ‘demux’

Type:DemuxDetails

Automation

class s4.clarity.configuration.Automation(lims, uri=None, xml_root=None, name=None, limsid=None)
channel

The value of the XML property ‘channel’

Type:str
command_string

The value of the XML property ‘string’

Type:str
context

The value of the XML property ‘context’

Type:str
name

The value of the XML property ‘name’

Type:str
process_types

The linked ProcessType objects from the ‘process-type’ subnodes

Type:list[ProcessType]

Available Input

class s4.clarity.step.AvailableInput(lims, xml_root)[source]
input
Type:Artifact
replicates

The value of the XML property ‘replicates’

Type:number

Clarity Element

class s4.clarity.ClarityElement(lims, uri=None, xml_root=None, name=None, limsid=None)
Variables:
  • xml_root (ETree.Element) –
  • uri (str|None) –
  • lims (LIMS) –
commit()[source]

Shorthand for put_and_parse().

invalidate()[source]

Clear the local cache, forcing a reload next time the element is used.

is_fully_retrieved()[source]
Return type:bool
limsid[source]
Type:str
name

The name of the element instance in Clarity.

Type:str
post_and_parse(alternate_uri=None)[source]

POST the current state of this object to a REST endpoint, then parse the response into this object.

Parameters:

alternate_uri (str) – Will be used instead of self.uri if provided.
Raises:
  • requests.exceptions.HTTPError – If there are communication problems.
  • ClarityException – If Clarity returns an exception as XML.
put_and_parse(alternate_uri=None)[source]

PUT the current state of this object to a REST endpoint, then parse the response into this object.

Parameters:

alternate_uri – Will be used instead of self.uri if provided.
Raises:
  • requests.exceptions.HTTPError – If there are communication problems.
  • ClarityException – If Clarity returns an exception as XML.
refresh()[source]

Retrieve fresh element representation from the API.

xml_root
Type:ETree.Element

Clarity Exception

class s4.clarity.ClarityException(msg)

Bases: Exception

Exceptions that are returned as XML from Clarity LIMS.

static is_authentication_error(response)[source]
static is_redirect(response)[source]
static is_response_exception(response)[source]
classmethod raise_if_present(response, data=None, username=None)[source]
classmethod raise_on_exception(response, data=None)[source]

Container

class s4.clarity.container.Container(lims, uri=None, xml_root=None, name=None, limsid=None)[source]

Bases: s4.clarity._internal.FieldsMixin, s4.clarity.ClarityElement

artifact_at(well)[source]
Parameters:well (str) – String matching “Y:X” where Y is a column index and X is a row index. The string may use letters or numbers depending on the container type.
Return type:Artifact or None
container_type

The linked ContainerType from the ‘type’ subnode

Type:ContainerType
occupied_wells

The value of the XML property ‘occupied-wells’

Type:number
placements

Dict of string “Y:X” -> Artifacts.

Type:dict[str, Artifact]
state

The value of the XML property ‘state’

Type:str
type_name

Read-only shortcut to containertype name, which we know without doing another GET.

Type:str

Container Dimension

class s4.clarity.container.ContainerDimension(lims, xml_root=None)[source]

Bases: s4.clarity._internal.element.WrappedXml

as_index(label)[source]
as_label(index)[source]
dimension_range[source]

List of the labels for the given dimension

Returns:list[int]|list[str]
is_alpha

The value of the XML property ‘is-alpha’

Type:bool
offset

The value of the XML property ‘offset’

Type:number
size

The value of the XML property ‘size’

Type:number

Container Type

class s4.clarity.container.ContainerType(lims, uri=None, xml_root=None, name=None, limsid=None)[source]

A class to handle container types, with helper functions to create and encode well positions For the purposes of this class, the y-dimension is considered the columns, and the x-dimension is considered the rows.

column_major_order_wells()[source]

Returns wells in the container type in column major order. This will return the wells ordered: [“y1:x1”, “y2:x1”, “y3:x1”, […], “yn:x1”, “y1:x2”, “y2:x2”, […]]

Unavailable wells are omitted.

Return type:list[str]
column_order_wells()[source]
Deprecated:use ContainerType.column_major_order_wells() instead.
is_tube

The value of the XML property ‘is-tube’

Type:bool
rc_to_well(rc)[source]

Converts a zero based index of the row and column to a Clarity well position.

Example:

(1, 3) -> 'B:4'
Parameters:rc (tuple[int]) – The zero based index of the row and the column.
Returns:A Clarity formatted well position
Return type:str
row_major_order_wells()[source]

Returns wells in the container type in row major order. This will return the wells ordered: [“y1:x1”, “y1:x2”, “y1:x3”, […], “y1,xn”, “y2:x1”, “y2:x2”, […]]

Unavailable wells are omitted.

Return type:list[str]
row_order_wells()[source]
Deprecated:use ContainerType.row_major_order_wells() instead.
total_capacity[source]
Type:int
unavailable_wells[source]
Type:set[str]
well_to_rc(well)[source]

Converts a Clarity well position to the zero based index of the row and column.

Example:

'B:4' -> (1, 3)
Parameters:well (str) – A Clarity formatted well position
Returns:The zero based index of the row and the column.
Return type:tuple[int]
x_dimension

The element ContainerDimension from subnode ‘x-dimension’

Type:ContainerDimension
x_dimension_range()[source]
Deprecated:use ContainerType.x_dimension.dimension_range instead
y_dimension

The element ContainerDimension from subnode ‘y-dimension’

Type:ContainerDimension
y_dimension_range()[source]
Deprecated:use ContainerType.y_dimension.dimension_range instead

Control Type

class s4.clarity.control_type.ControlType(lims, uri=None, xml_root=None, name=None, limsid=None)[source]

Bases: s4.clarity.ClarityElement

archived

The value of the XML property ‘archived’

Type:bool
catalogue_number

The value of the XML property ‘catalogue-number’

Type:str
concentration

The value of the XML property ‘concentration’

Type:str
single_step

The value of the XML property ‘single-step’

Type:bool
supplier

The value of the XML property ‘supplier’

Type:str
website

The value of the XML property ‘website’

Type:str

Demux Artifact

class s4.clarity.artifact.DemuxArtifact(lims, xml_root=None)[source]

Bases: s4.clarity._internal.element.WrappedXml

Corresponds to the ‘demux-artifact’ type in the ‘artifact’ namespace of the Clarity API.

artifact

The linked Artifact from the ‘.’ subnode

Type:Artifact
demux

The element DemuxDetails from subnode ‘demux’

Some versions of Clarity do not provide this element when the DemuxArtifact is a pool of artifacts that are all from the same submitted sample. In this case, if more than one artifact is labeled, the pool Artifact’s demux will be provided, but if only one artifact is labeled, the pool’s demux will not be provided.

Type:DemuxDetails
reagent_labels

ReagentLabel items from the ‘reagent-label’ subnodes

Type:list[ReagentLabel]
samples

The linked Sample objects from the ‘./samples/sample’ subnodes

Type:list[Sample]

Demux Details

class s4.clarity.artifact.DemuxDetails(lims, xml_root=None)[source]

Bases: s4.clarity._internal.element.WrappedXml

Corresponds to the ‘demux-details’ type in the ‘artifact’ namespace of the Clarity API.

demux_artifacts

DemuxArtifact items from the ‘artifact’ subnodes

Type:list[DemuxArtifact]
pool_step

The linked Step from the ‘./pool-step’ subnode

Type:Step

Element Factory

class s4.clarity.ElementFactory(lims, element_class, batch_flags=None, request_path=None, name_attribute='name')

Provides access to a Clarity API endpoint. Implements conversion between XML and ClarityElement as well as caching and network services.

Parameters:
  • request_path (str) – for example, ‘/configuration/workflows’. when not specified, uses ‘/<plural of element name>’.
  • name_attribute (str) – if not “name”, provide this to adjust behaviour of ‘get_by_name’.
add(element)[source]

Add an element to the Factory’s internal cache and persist it back to Clarity.

Return type:ClarityElement
all(prefetch=True)[source]

Queries Clarity for all ClarityElements associated with the Factory.

Parameters:prefetch – Force load full content for each element.
Returns:List of ClarityElements returned by Clarity.
batch_create(elements)[source]

Creates new records in Clarity for each element and returns these new records as ClarityElements. If this operation can be performed in a single network operation it will be.

Parameters:elements – A list of new ClarityElements that have not been persisted to Clarity yet.
Returns:New ClarityElement records from Clarity, created with the data supplied to the method.
Raises:ClarityException – if Clarity returns an exception as XML
batch_fetch(elements)[source]

Updates the content of all ClarityElements with the current state from Clarity. Syntactic sugar for batch_get([e.uri for e in elements])

Returns:A list of the elements returned by the query.
batch_get(uris, prefetch=True)[source]

Queries Clarity for a list of uris described by their REST API endpoint. If this query can be made as a single request it will be done that way.

Parameters:
  • uris – A List of uris
  • prefetch – Force load full content for each element.
Returns:

A list of the elements returned by the query.
batch_get_from_limsids(limsids)[source]

Return a list of ClarityElements for a given list of limsids

Parameters:limsids – A list of Clarity limsids
Returns:A list of the elements returned by the query.
batch_invalidate(elements)[source]

Clears the current local state for all elements. :param elements: The ClarityElements that are to have their current state cleared.

batch_refresh(elements)[source]

Loads the current state of the elements from Clarity. Any changes made to these artifacts that has not been pushed to Clarity will be lost. :param elements: All ClarityElements to update from Clarity.

batch_tag
batch_update(elements)[source]

Persists the ClarityElements back to Clarity. Will preform this action as a single query if possible.

Parameters:elements – All ClarityElements to save the state of.
Raises:ClarityException – if Clarity returns an exception as XML
can_batch_create()[source]

Indicates if Clarity will allow batch record creation.

can_batch_get()[source]

Indicates if Clarity will allow batch get requests.

can_batch_update()[source]

Indicates if Clarity will allow batch updates.

can_query()[source]

Indicates if Clarity will allow the user to submit queries.

delete(element)[source]

Delete an element from the Factory’s internal cache and delete it from Clarity.

from_limsid(limsid, force_full_get=False)[source]

Returns the ClarityElement with the specified limsid.

Will return the ClarityElement described by the link node.

Link nodes are any xml element with the following attributes <element uri=’…’ name=’…’ limsid=’…’ />

Will return the ClarityElements described by the link nodes.

Link nodes are any xml element with the following attributes <element uri=’…’ name=’…’ limsid=’…’ />

get(uri, force_full_get=False, name=None, limsid=None)[source]

Returns the cached ClarityElement described by the provide uri. If the element does not exist a new cache entry will be created with the provided name and limsid. If force_full_get is true, and the object is not fully retrieved it will be refreshed.

get_by_name(name)[source]

Queries for a ClarityElement that is described by the unique name. An exception is raised if there is no match or more than one match.

Raises:
  • NoMatchingElement – if no match
  • MultipleMatchingElements – if multiple matches
new(**kwargs)[source]

Create a new ClarityElement pre-populated with the provided values. This object has yet to be persisted to Clarity.

Parameters:kwargs – Key/Value list of attribute name/value pairs to initialize the element with.
Returns:A new ClarityElement, pre-populated with provided values.
post(element)[source]

Posts the current state of the ClarityElement back to Clarity.

query(prefetch=True, **params)[source]

Queries Clarity for ClarityElements associated with the Factory. The query will be made with the provided parameters encoded in the url. For the specific parameters to pass and the expected values please see the Clarity REST API.

Some of the expected parameters contain the ‘-’ character, in which case the dictionary syntax of this call will need to be used.

Inline parameter names:

query(singlevaluename='single value', multivaluename=['A', 'B', 'C'])

Dictionary of parameters:

query(prefetch=True, ** {
    'single-value-name': 'single value',
    'multi-value-name': ['A', 'B', 'C']
})
Parameters:
  • params – Query parameters to pass to clarity.
  • prefetch – Force load full content for each element.
Returns:

A list of the elements returned by the query.
query_uris(**params)[source]

For backwards compatibility, use query() instead. Does a query and returns the URIs of the results.

Parameters:params – Query parameters to pass to clarity.

Fields Mixin

class s4.clarity._internal.FieldsMixin(lims, uri=None, xml_root=None, name=None, limsid=None)
fields[source]
Type:dict[str, object]
get(name, default=None)[source]

Get a UDF, if it exists. (Non-exception version of []).

Parameters:default – returned if the item is not present
Return type:str or int or bool or datetime.datetime or float
get_formatted_number_string(name, default=None)[source]

Get a Numeric UDF formatted to the correct precision, if the UDF exists.

Parameters:default (str) – returned if the item is not present
Return type:str
get_raw(name, default=None)[source]

Get a UDF as a string, if it exists.

Parameters:default – returned if the item is not present
Return type:str
get_udf_config(name)[source]

Get the underlying UDF configuration associated with the field :param name: name of the field :rtype: s4.clarity.configuration.Udf

xml_root
Type:ETree.Element

File

class s4.clarity.file.File(lims, uri=None, xml_root=None, name=None, limsid=None)[source]

Bases: s4.clarity.ClarityElement

This is a file in Clarity. It is also a Python file (more or less). You can read, write, and do everything else you can normally do with a Python file. NOTE: nothing will be committed to Clarity until you call close, or commit.

attached_to

The value of the XML property ‘attached-to’

Type:str
close()[source]

Commit the file and close the data stream.

commit()[source]

Shorthand for put_and_parse().

content_location

The value of the XML property ‘content-location’

Type:str
data
Returns:The file data IO stream.
Return type:io.IOBase
flush()[source]
getvalue()[source]
is_binary_mode
Type:bool
is_published

The value of the XML property ‘is-published’

Type:bool
isatty()[source]
name

The value of the XML property ‘original-location’

Type:str
classmethod new_empty(attachment_point_element, name=None)[source]

Create a new empty File.

Parameters:
  • attachment_point_element (ClarityElement) – An element to attach the file to.
  • name (str) – A name for the file.
Return type:

File
classmethod new_from_local(attachment_point_element, local_file_path, mode='r+b')[source]

Create a new File from a local file.

Parameters:
  • attachment_point_element (ClarityElement) – An element to attach the file to.
  • local_file_path (str) – Path to the local file.
  • mode (str) – Mode to open the file with.
Return type:

File
pipe_to(target_file_object)[source]
Raises:FileNotFoundException – if the file does not exist in Clarity.
read(n=-1)[source]
readable()[source]
readline(length=None)[source]
readlines(sizehint=0)[source]
replace_and_commit(stream, name, content_type='text/plain')[source]
replace_and_commit_from_local(local_file_path, content_type='text/plain', mode='r+b')[source]
seek(pos, mode=0)[source]
seek_to_end()[source]
seekable()[source]
tell()[source]
truncate(size=None)[source]
writable()[source]
write(s)[source]
writelines(iterable)[source]

Instrument

class s4.clarity.instrument.Instrument(lims, uri=None, xml_root=None, name=None, limsid=None)[source]

Bases: s4.clarity.ClarityElement

Reference: https://d10e8rzir0haj8.cloudfront.net/5.3/rest.version.instruments.html Note: See example xml_root below –

<inst:instrument xmlns:inst=”http://genologics.com/ri/instrument” limsid=”55-6” uri=”https://clarityhost/api/v2/instruments/6”> We use uri id for Instrument object limsid i.e. “6” instead of “55-6”

Cautionary Notes: In most cases, a Step UDF or Reagent Kit/Reagent Lot is a better option to track instrument use in the LIMS. Consider – 1. Instrument API endpoint only permits GET 2. You may configure multiple Instruments to step. However, you can only assign 1 Instrument per step 3. If Instrument is configured to step, Step UDFs CAN NOT be set via the API,

until the Instrument field is set via UX/UI
  1. Instruments are not part of the ETL that supports the Illumina Reporting Module
archived

The value of the XML property ‘archived’

Type:bool
expiry_date

The value of the XML property ‘expiry-date’

Type:datetime.date
instrument_type

The value of the XML property ‘type’

Type:str
name

The value of the XML property ‘name’

Type:str
related_instruments[source]
Returns:List of instruments of the same instrument type
Type:List[Instrument]
serial_number

The value of the XML property ‘serial-number’

Type:str

IO Map

class s4.clarity.iomaps.IOMap(inputs, outputs)[source]
Variables:
  • inputs – list[Artifact]
  • outputs – list[Artifact]
input
Type:Artifact
Raises:Exception – If there are multiple input artifacts
output
Type:Artifact
Raises:Exception – If there are multiple output artifacts

Lab

class s4.clarity.lab.Lab(lims, uri=None, xml_root=None, name=None, limsid=None)[source]

Bases: s4.clarity._internal.FieldsMixin, s4.clarity.ClarityElement

LIMS

class s4.clarity.LIMS(root_uri, username, password, dry_run=False, insecure=False, log_requests=False, timeout=None)
Parameters:
  • root_uri (str) – Location of the clarity server e.g. (https://<clarity server>/api/v2/)
  • username (str) – Clarity User Name
  • password (str) – Clarity Password
  • dry_run (bool) – If true, no destructive requests will be made to the Clarity API. Default false.
  • insecure (bool) – Disables SSL validation. Default false.
  • timeout (int) – Number of seconds to wait for connections and for reads from the Clarity API. Default None, which is no timeout.
Variables:
DEFAULT_TIMEOUT = None
artifact(limsid)[source]
Return type:Artifact
artifact_from_uri(uri)[source]
Return type:Artifact
factory_for(element_type)[source]
Return type:ElementFactory
properties[source]
Type:dict
raw_request(method, uri, **kwargs)[source]
Raises:ClarityException – if Clarity returns an exception as XML
Return type:requests.Response
request(method, uri, xml_root=None)[source]
Return type:ETree.Element
Raises:ClarityException – if Clarity returns an exception as XML
sample(limsid)[source]
Return type:Sample
stage_from_uri(uri)[source]
Return type:Stage
step(limsid)[source]
Return type:Step
step_from_uri(uri)[source]
Return type:Step
stepconfiguration_from_uri(uri)[source]
Return type:StepConfiguration

Output Reagent

class s4.clarity.step.OutputReagent(step, node)[source]
reagent_label
Type:str

Permission

class s4.clarity.permission.Permission(lims, uri=None, xml_root=None, name=None, limsid=None)[source]

Bases: s4.clarity.ClarityElement

action

The value of the XML property ‘action’

Type:str
description

The value of the XML property ‘description’

Type:str

Placement

class s4.clarity.step.Placement(lims, xml_root=None)[source]
artifact

The linked Artifact from the ‘.’ subnode

Type:Artifact
container

The linked Container from the ‘location/container’ subnode

Type:Container
location_value

The value of the XML property ‘location/value’

Type:str

Pool

class s4.clarity.step.Pool(lims, xml_root=None)[source]
inputs[source]
Type:list[Artifact]
name
Type:str
output[source]
Type:Artifact

Process

class s4.clarity.process.Process(*args, **kwargs)[source]

Bases: s4.clarity.iomaps.IOMapsMixin, s4.clarity._internal.FieldsMixin, s4.clarity.ClarityElement

Variables:
commit()

Shorthand for put_and_parse().

get(name, default=None)

Get a UDF, if it exists. (Non-exception version of []).

Parameters:default – returned if the item is not present
Return type:str or int or bool or datetime.datetime or float
get_formatted_number_string(name, default=None)

Get a Numeric UDF formatted to the correct precision, if the UDF exists.

Parameters:default (str) – returned if the item is not present
Return type:str
get_raw(name, default=None)

Get a UDF as a string, if it exists.

Parameters:default – returned if the item is not present
Return type:str
get_udf_config(name)

Get the underlying UDF configuration associated with the field :param name: name of the field :rtype: s4.clarity.configuration.Udf

invalidate()

Clear the local cache, forcing a reload next time the element is used.

iomaps_input_keyed()
Returns:a mapping of input -> outputs.
Return type:dict[Artifact, list[Artifact]]
iomaps_output_keyed()
Returns:a mapping of output -> inputs.
Return type:dict[Artifact, list[Artifact]]
refresh()

Retrieve fresh element representation from the API.

fields
Type:dict[str, object]
limsid
Type:str
process_type
Type:ProcessType
technician

The linked Researcher from the ‘technician’ subnode

Type:Researcher

Process Template

class s4.clarity.configuration.ProcessTemplate(lims, uri=None, xml_root=None, name=None, limsid=None)

Bases: s4.clarity._internal.FieldsMixin, s4.clarity.ClarityElement

is_default

The value of the XML property ‘is-default’

Type:bool
type

The linked ProcessType from the ‘type’ subnode

Type:ProcessType

Process Type

class s4.clarity.configuration.ProcessType(lims, uri=None, xml_root=None, name=None, limsid=None)

Bases: s4.clarity.ClarityElement

get_parameter(parameter_name)[source]
Parameters:parameter_name (str) – the name of the parameter to retrieve
Return type:dict
inputs

Retrieves the value of the property ‘process-input’

Type:list[dict]
outputs

Retrieves the value of the property ‘process-output’

Type:list[dict]
parameters

Retrieves the value of the property ‘parameter’

Type:list[dict]

Project

class s4.clarity.project.Project(lims, uri=None, xml_root=None, name=None, limsid=None)[source]

Bases: s4.clarity._internal.FieldsMixin, s4.clarity.ClarityElement

Reference: https://d10e8rzir0haj8.cloudfront.net/5.3/rest.version.projects.html

close_date

The value of the XML property ‘close-date’

Type:datetime.date
files

The linked File objects from the ‘{http://genologics.com/ri/file}file’ subnodes

Type:list[File]
invoice_date

The value of the XML property ‘invoice-date’

Type:datetime.date
open_date

The value of the XML property ‘open-date’

Type:datetime.date
researcher

The linked Researcher from the ‘researcher’ subnode

Type:Researcher

Protocol

class s4.clarity.configuration.Protocol(lims, uri=None, xml_root=None, name=None, limsid=None)

Bases: s4.clarity.ClarityElement

index

The value of the XML property ‘index’

Type:number
number_of_steps
Type:int
properties

The value of the XML property ‘protocol-properties’

Type:str
step(name)[source]
Return type:StepConfiguration or None
step_from_id(stepid)[source]
Return type:StepConfiguration or None
steps[source]
Type:list[StepConfiguration]

Protocol Step Field

class s4.clarity.configuration.ProtocolStepField(lims, xml_root=None)
attach_to

The value of the XML property ‘attach-to’

Type:str
name

The value of the XML property ‘name’

Type:str
style

The value of the XML property ‘style’

Type:str

Queue

class s4.clarity.queue.Queue(lims, uri=None, xml_root=None, name=None, limsid=None)[source]

Bases: s4.clarity.ClarityElement

query(prefetch=True, **params)[source]
queued_artifacts

Reagent Kit

class s4.clarity.reagent_kit.ReagentKit(lims, uri=None, xml_root=None, name=None, limsid=None)[source]

Bases: s4.clarity.ClarityElement

archived

The value of the XML property ‘archived’

Type:bool
catalogue_number

The value of the XML property ‘catalogue-number’

Type:str
name

The value of the XML property ‘name’

Type:str
related_reagent_lots[source]
supplier

The value of the XML property ‘supplier’

Type:str
website

The value of the XML property ‘website’

Type:str

Reagent Lot

class s4.clarity.reagent_lot.ReagentLot(lims, uri=None, xml_root=None, name=None, limsid=None)[source]

Bases: s4.clarity.ClarityElement

created_date

The value of the XML property ‘created-date’

Type:datetime.date
expiry_date

The value of the XML property ‘expiry-date’

Type:datetime.date
last_modified_date

The value of the XML property ‘last-modified-date’

Type:datetime.date
lot_number

The value of the XML property ‘lot-number’

Type:str
name

The value of the XML property ‘name’

Type:str
notes

The value of the XML property ‘notes’

Type:str
reagent_kit

The linked ReagentKit from the ‘reagent-kit’ subnode

Type:ReagentKit
status

The value of the XML property ‘status’

Type:str
storage_location

The value of the XML property ‘storage-location’

Type:str
usage_count

The value of the XML property ‘usage-count’

Type:number

Reagent Type

class s4.clarity.reagent_type.ReagentType(lims, uri=None, xml_root=None, name=None, limsid=None)[source]

Bases: s4.clarity.ClarityElement

attributes

The value of the XML property ‘special-type’

Type:str
name

The name of the element instance in Clarity.

Type:str
reagent_category

The value of the XML property ‘reagent-category’

Type:str
special_type
Type:str

Researcher

class s4.clarity.researcher.Researcher(lims, uri=None, xml_root=None, name=None, limsid=None)[source]

Bases: s4.clarity._internal.FieldsMixin, s4.clarity.ClarityElement

add_role(new_role)[source]
email

The value of the XML property ‘email’

Type:str
first_name

The value of the XML property ‘first-name’

Type:str
initials

The value of the XML property ‘initials’

Type:str
lab

The linked Lab from the ‘lab’ subnode

Type:Lab
last_name

The value of the XML property ‘last-name’

Type:str
password

The value of the XML property ‘credentials/password’

Type:str
remove_role(role)[source]
roles

The linked Role objects from the ‘credentials/role’ subnodes

Type:list[Role]
username

The value of the XML property ‘credentials/username’

Type:str

Role

class s4.clarity.role.Role(lims, uri=None, xml_root=None, name=None, limsid=None)[source]

Bases: s4.clarity.ClarityElement

permissions

The linked Permission objects from the ‘permissions/permission’ subnodes

Type:list[Permission]
researchers[source]
Type:list[Researcher]

Router

class s4.clarity.routing.Router(lims)[source]

Class allowing routing of multiple artifacts to a given workflow or stage

assign(workflow_or_stage_uri, artifact_or_artifacts)[source]

Stages an artifact or multiple artifacts to be assigned to a workflow_or_stage_uri.

Parameters:workflow_or_stage_uri (str) – The uri of either a workflow or workflow-stage. If a workflow uri is provided, the artifacts will be queued to the first stage. Otherwise, they will be queued to the specific workflow-stage.
clear()[source]

Clears the routing node and the routing dict.

commit()[source]

Generates the routing XML for workflow/stage assignment/unassignment and posts it.

remove(artifact_or_artifacts)[source]

Remove given artifact or artifacts from the routing dict. No error is raised if the artifact is not found.

unassign(workflow_or_stage_uri, artifact_or_artifacts)[source]

Stages an artifact or multiple artifacts to be unassigned from a workflow_or_stage_uri.

Parameters:workflow_or_stage_uri (str) – The uri of either a workflow or workflow-stage. If a workflow uri is provided, the artifacts will be removed from any stages of that workflow. Otherwise, they will be removed from the specified workflow stage.

Sample

class s4.clarity.sample.Sample(lims, uri=None, xml_root=None, name=None, limsid=None)[source]

Bases: s4.clarity._internal.FieldsMixin, s4.clarity.ClarityElement

artifact

The linked Artifact from the ‘artifact’ subnode

Type:Artifact
date_completed

The value of the XML property ‘date-completed’

Type:datetime.date
date_received

The value of the XML property ‘date-received’

Type:datetime.date
is_control
Type:bool
project

The linked Project from the ‘project’ subnode

Type:Project
set_location(container, row, col)[source]

Sets this artifact’s location (usually for sample creation) with the given row and column, in the given container.

Parameters:
  • container (s4.clarity.Container) – The Sample’s container
  • row (str or int) – The well position row.
  • col (str or int) – The well position column
Deprecated:

Use set_location_coords or set_location_well
set_location_coords(container, row, col)[source]

Sets this artifact’s location (usually for sample creation) with the given row and column, in the given container.

Equivalent to set_location_well with the string “<row>:<col>”.

Parameters:
  • container (s4.clarity.Container) – The Sample’s container
  • row (str or int) – The well position row.
  • col (str or int) – The well position column
set_location_well(container, well)[source]

” Sets this artifact’s location (usually for sample creation) with the given well location, in the given container.

Parameters:
  • container (s4.clarity.Container) – The Sample’s container
  • well (str) – The well position in the form “<row>:<col>”

Stage

class s4.clarity.configuration.Stage(lims, uri=None, xml_root=None, name=None, limsid=None)

Bases: s4.clarity.ClarityElement

enqueue(artifact_or_artifacts)[source]

Add one or more artifacts to the stage’s queue

Parameters:artifact_or_artifacts (s4.clarity.Artifact | list[s4.clarity.Artifact]) – The artifact(s) to enqueue
index

The value of the XML property ‘index’

Type:str
protocol[source]
Type:Protocol
remove(artifact_or_artifacts)[source]

Remove one or more sample artifacts from the stage

Parameters:artifact_or_artifacts (s4.clarity.Artifact | list[s4.clarity.Artifact]) – The artifact(s) to enqueue
step[source]
Type:StepConfiguration
workflow[source]
Type:Workflow

Step

class s4.clarity.step.Step(lims, uri=None, xml_root=None, name=None, limsid=None)[source]

Bases: s4.clarity.ClarityElement

actions[source]
Type:StepActions
advance()[source]

Advances the current step to the next screen.

automatic_next_step
Type:Step
available_programs[source]
Type:StepTrigger
configuration[source]
Type:StepConfiguration
current_state
Type:str
date_completed

The value of the XML property ‘date-completed’

Type:datetime
date_started

The value of the XML property ‘date-started’

Type:datetime
details[source]
Type:StepDetails
fields
Raises:NotImplementedError – Steps don’t have fields. Use step.details.
name

The value of the XML property ‘configuration’

Type:str
open_resultfile(name, mode, only_write_locally=False, limsid=None)[source]
Return type:s4.clarity.File
placements[source]
Type:StepPlacements
pooling[source]
Type:StepPools
process
Type:Process
program_status[source]
Type:StepProgramStatus
reagent_lots[source]
Type:StepReagentLots
reagents[source]
Type:StepReagents
wait_for_epp()[source]

Polls Clarity, blocking until the currently running EPP is done.

Raises:EppException – When EPP execution fails.
Returns:Zero
Return type:int

Step Actions

class s4.clarity.step.StepActions(lims, uri=None, xml_root=None, name=None, limsid=None)[source]

Bases: s4.clarity.ClarityElement

all_next_step(step_uri=None)[source]

Set all artifacts actions to either next step, or mark protocol as complete.

If step_uri is not provided, artifacts will:
  • Continue to the first transition defined for this step, if any transitions are defined.
  • Mark the protocol as complete, if there are no transitions.
artifact_actions[source]

A dictionary of ArtifactActions for this step, keyed by artifact.

Return type:dict[Artifact, ArtifactAction]
escalated_artifacts

The linked Artifact objects from the ‘./escalation/escalated-artifacts/escalated-artifact’ subnodes

Type:list[Artifact]
escalation_author

The linked Researcher from the ‘./escalation/request/author’ subnode

Type:Researcher
escalation_date

The value of the XML property ‘./escalation/request/date’

Type:datetime
escalation_reviewer

The linked Researcher from the ‘./escalation/request/reviewer’ subnode

Type:Researcher
next_actions

Retrieves the value of the property ‘next-actions/next-action’

Type:list[dict]
step

The linked Step from the ‘step’ subnode

Type:Step

Step Configuration

class s4.clarity.configuration.StepConfiguration(protocol, node)

Bases: s4.clarity.ClarityElement

permitted_containers[source]
Type:ContainerType
permitted_control_types[source]
Type:ControlType
permitted_instrument_types[source]
Type:List[str]
post_and_parse(alternate_uri=None)[source]

POST the current state of this object to a REST endpoint, then parse the response into this object.

Parameters:

alternate_uri (str) – Will be used instead of self.uri if provided.
Raises:
  • requests.exceptions.HTTPError – If there are communication problems.
  • ClarityException – If Clarity returns an exception as XML.
process_type[source]
Type:ProcessType
properties

The value of the XML property ‘step-properties’

Type:str
protocol_step_index

The value of the XML property ‘protocol-step-index’

Type:number
put_and_parse(alternate_uri=None)[source]

PUT the current state of this object to a REST endpoint, then parse the response into this object.

Parameters:

alternate_uri – Will be used instead of self.uri if provided.
Raises:
  • requests.exceptions.HTTPError – If there are communication problems.
  • ClarityException – If Clarity returns an exception as XML.
queue[source]
Type:Queue
queue_fields

ProtocolStepField items from the ‘queue-field’ subnodes

Type:list[ProtocolStepField]
refresh()[source]
Raises:Exception – Unable to refresh step directly, use protocol
required_reagent_kits[source]
Type:ReagentKit
sample_fields

ProtocolStepField items from the ‘sample-field’ subnodes

Type:list[ProtocolStepField]
step_fields

ProtocolStepField items from the ‘step-field’ subnodes

Type:list[ProtocolStepField]
transitions

Retrieves the value of the property ‘transitions/transition’

Type:list[dict]
triggers

Retrieves the value of the property ‘epp-triggers/epp-trigger’

Type:list[dict]

Step Details

class s4.clarity.step.StepDetails(step, *args, **kwargs)[source]

Bases: s4.clarity.iomaps.IOMapsMixin, s4.clarity._internal.FieldsMixin, s4.clarity.ClarityElement

Variables:
commit()

Shorthand for put_and_parse().

get(name, default=None)

Get a UDF, if it exists. (Non-exception version of []).

Parameters:default – returned if the item is not present
Return type:str or int or bool or datetime.datetime or float
get_formatted_number_string(name, default=None)

Get a Numeric UDF formatted to the correct precision, if the UDF exists.

Parameters:default (str) – returned if the item is not present
Return type:str
get_raw(name, default=None)

Get a UDF as a string, if it exists.

Parameters:default – returned if the item is not present
Return type:str
get_udf_config(name)

Get the underlying UDF configuration associated with the field :param name: name of the field :rtype: s4.clarity.configuration.Udf

invalidate()

Clear the local cache, forcing a reload next time the element is used.

iomaps_input_keyed()
Returns:a mapping of input -> outputs.
Return type:dict[Artifact, list[Artifact]]
iomaps_output_keyed()
Returns:a mapping of output -> inputs.
Return type:dict[Artifact, list[Artifact]]
refresh()

Retrieve fresh element representation from the API.

fields
Type:dict[str, object]
limsid
Type:str
instrument_used

The linked Instrument from the ‘instrument’ subnode

Type:Instrument
name

The value of the XML property ‘configuration’

Type:str
sorted_input_sample_iomaps()[source]

return list of sample iomaps sorted by sample name

Step Factory

class s4.clarity.StepFactory(lims, element_class, batch_flags=None, request_path=None, name_attribute='name')

Bases: s4.clarity.ElementFactory

Parameters:
  • request_path (str) – for example, ‘/configuration/workflows’. when not specified, uses ‘/<plural of element name>’.
  • name_attribute (str) – if not “name”, provide this to adjust behaviour of ‘get_by_name’.

Override so that we can accept a process link or a step link. Requires that node include a limsid

Return type:ClarityElement
get_by_name(protocol_name, step_name)[source]

Queries for a ClarityElement that is described by the unique name. An exception is raised if there is no match or more than one match.

Raises:
  • NoMatchingElement – if no match
  • MultipleMatchingElements – if multiple matches

Step Placements

class s4.clarity.step.StepPlacements(lims, uri=None, xml_root=None, name=None, limsid=None)[source]

Bases: s4.clarity.ClarityElement

add_selected_container(new_container)[source]

Adds a new container to the step placement’s list of selected containers.

clear_placements()[source]

Clears all previous artifact placements recorded to this step. This is often called before starting automated placement to ensure that artifacts are not placed twice.

clear_selected_containers()[source]

Clears the list of selected containers associated with the step. This can be used to remove containers that are automatically created for the step when they are not used.

commit()[source]

Push placement changes back to Clarity.

create_placement(artifact, container, well_string)[source]

Place the provided artifact, in the provided container at the location described by the well_string.

Parameters:
  • artifact – The artifact to place.
  • container – The container that will hold the artifact.
  • well_string – The location on the plate to place the artifact
create_placement_with_no_location(artifact)[source]

Samples that are part of a process, but have been removed need to be included with out a location in some cases because Clarity will hold the old spot, which may now be used by another sample.

placements

Placement items from the ‘output-placement’ subnodes

Type:list[Placement]
selected_containers
Type:list[Container]
step

The linked Step from the ‘step’ subnode

Type:Step

Step Pools

class s4.clarity.step.StepPools(step, lims, uri)[source]

Bases: s4.clarity.ClarityElement

available_inputs
Type:list[AvailableInput]
create_pool(name, samples)[source]
pools
Type:list[Pool]

Step Program Status

class s4.clarity.step.StepProgramStatus(lims, uri=None, xml_root=None, name=None, limsid=None)[source]

Bases: s4.clarity.ClarityElement

Manage the status of the currently executing step. By setting a message to the step status, a message box will be displayed to the user.

The AI node will set the status to RUNNING, but does not allow the API to set this value.

NOTE: A user has to action Step transition, upon message box display. i.e. There is no API request to get past the message box. In practise, using the ‘program-status’ endpoint conflicts with using StepRunner to develop automated workflow tests

message

The value of the XML property ‘message’

Type:str
report_error(message)[source]
report_ok(message)[source]
report_warning(message)[source]
status

The value of the XML property ‘status’

Type:str
step

The linked Step from the ‘step’ subnode

Type:Step

Step Reagents

class s4.clarity.step.StepReagents(step, lims, uri)[source]

Bases: s4.clarity.ClarityElement

output_reagents
Type:list(OutputReagent)
reagent_category

The value of the XML property ‘reagent-category’

Type:str

Step Reagent Lots

class s4.clarity.step.StepReagentLots(step, lims, uri)[source]

Bases: s4.clarity.ClarityElement

add_reagent_lots(elements)[source]
Parameters:elements (list[ReagentLot]) – Add reagent lots to the step
reagent_lots
Type:list(ReagentLot)

Step Trigger

class s4.clarity.step.StepTrigger(step, uri)[source]
fire()[source]
name
Type:str

UDF

class s4.clarity.configuration.Udf(lims, uri=None, xml_root=None, name=None, limsid=None)

Bases: s4.clarity.ClarityElement

add_preset(new_preset_value)[source]

Add a new preset value to the end of the list. Ignores values that are already present.

Parameters:new_preset_value (str|unicode|int|float|datetime.date|bool) – the preset value to add, with a type appropriate to the UDF. The value is not validated to be the correct type.
allow_non_preset_values

The value of the XML property ‘allow-non-preset-values’

Type:bool
attach_to_category

The value of the XML property ‘attach-to-category’

Type:str
attach_to_name

The value of the XML property ‘attach-to-name’

Type:str
field_type

The value of the XML property ‘type’

Type:str
first_preset_is_default_value

The value of the XML property ‘first-preset-is-default-value’

Type:bool
is_controlled_vocabulary

The value of the XML property ‘is-controlled-vocabulary’

Type:bool
is_deviation

The value of the XML property ‘is-deviation’

Type:bool
is_editable

The value of the XML property ‘is-editable’

Type:bool
is_required

The value of the XML property ‘is-required’

Type:bool
max_value

The value of the XML property ‘max-value’

Type:number
min_value

The value of the XML property ‘min-value’

Type:number
precision

The value of the XML property ‘precision’

Type:number
presets
Type:list
remove_preset(preset_value)[source]

Remove a preset value from the list.

Parameters:preset_value (str|unicode|int|float|datetime.date|bool) – the preset value to remove, with a type appropriate to the UDF. The value is not validated to be the correct type.
set_default_preset(default_preset_value)[source]

Sets a preset value as the default (puts first in the list). Adds value if it isn’t already preset.

Parameters:default_preset_value (str|unicode|int|float|datetime.date|bool) – the new default preset value, with a type appropriate to the UDF. The value is not validated to be the correct type.
Raises:Exception – if the udf’s first-preset-is-default property is currently false

The value of the XML property ‘show-in-lablink’

Type:bool
show_in_tables

The value of the XML property ‘show-in-tables’

Type:bool

UDF Factory

class s4.clarity.UdfFactory(lims, element_class, batch_flags=None, request_path=None, name_attribute='name')

Bases: s4.clarity.ElementFactory

Parameters:
  • request_path (str) – for example, ‘/configuration/workflows’. when not specified, uses ‘/<plural of element name>’.
  • name_attribute (str) – if not “name”, provide this to adjust behaviour of ‘get_by_name’.
get_by_name(udf_name, attach_to_key)[source]
Parameters:attach_to_key ((str, str)) – tuple comprising the element’s attach-to-name and attach-to-category properties
Returns:s4.clarity.configuration.Udf
Raises:NoMatchingElement – if no match

Workflow

class s4.clarity.configuration.Workflow(lims, uri=None, xml_root=None, name=None, limsid=None)

Bases: s4.clarity.ClarityElement

ACTIVE_STATUS = 'ACTIVE'
ARCHIVED_STATUS = 'ARCHIVED'
PENDING_STATUS = 'PENDING'
enqueue(artifact_or_artifacts)[source]

Add one or more artifacts to the start of the workflow

Type:artifact_or_artifacts: Artifact | list[Artifact]
is_active
Type:bool
is_archived
Type:bool
is_pending
Type:bool
protocols[source]
Param:prefetch: set to False if you don’t want an automatic batch_get.
Type:prefetch: bool
Return type:list[Protocol]
remove(artifact_or_artifacts)[source]

Remove one or more artifacts from the workflow

Type:artifact_or_artifacts: Artifact | list[Artifact]
stage_from_id(stageid)[source]
Return type:Stage or None
stages
Return type:list[Stage]
status

The value of the XML property ‘status’

Type:str

Workflow Stage History

class s4.clarity.artifact.WorkflowStageHistory(lims, xml_root=None)[source]
name

The value of the XML property ‘name’

Type:str
stage

The linked Stage from the ‘.’ subnode

Type:Stage
status

The value of the XML property ‘status’

Type:str
uri

The value of the XML property ‘uri’

Type:str