Protocol

class labstep.entities.protocol.model.Protocol(data, user)

Represents a Protocol on Labstep.

To see all attributes of a protocol run

print(my_protocol)

Specific attributes can be accessed via dot notation like so…

print(my_protocol.name)
print(my_protocol.id)

edit(name=OPTIONAL, body=OPTIONAL, extraParams={})

Edit an existing Protocol.

Parameters:

name (str) – The name of the Protocol.
body (dict) – JSON representing the the protocol document.

Returns:

An object representing the edited Protocol.

Return type:

Protocol

Example

my_protocol = user.getProtocol(17000)
my_protocol.edit(name='A New Protocol Name')

delete()

Delete an existing Protocol.

Example

my_protocol = user.getProtocol(17000)
my_protocol.delete()

newVersion()

Start a new version of the Protocol.

Example

my_protocol = user.getProtocol(17000)
new_version = my_protocol.newVersion()

getBody()

Returns the body of the protocol as a JSON document

Example

my_protocol = user.newProtocol('My API Protocol')

my_protocol.edit(body={
    "type": "doc",
    "content": [
        {
            "type": "paragraph",
            "attrs": {"align": None},
            "content": [
                {
                    "type": "text",
                    "text": "This is the the body of my protocol"
                }
            ]
        },
        {
            "type": "paragraph",
            "attrs": {"align": None}
        }
    ]
})

my_protocol.getBody()

addSteps(N)

Add steps to the protocol

Parameters:: N (int) – The number of steps to add.

Example

my_protocol = user.newProtocol('My API Protocol')
my_protocol.addSteps(5)

getSteps()

Returns a list of the steps in a Protocol.

Returns:: List of the steps in Protocol.
Return type:: List[ProtocolStep]

Example

protocol = user.getProtocol(17000)
protocol_steps = protocol.getSteps()
protocol_steps[0].attributes()

getDataFields()

Retrieve the Data Fields of a Protocol.

Returns:: An array of objects representing the Labstep Data Fields on a Protocol.
Return type:: Metadata

Example

protocol = user.getProtocol(17000)
metadata = protocol.getDataFields()

addDataField(fieldName, fieldType='default', value=OPTIONAL, date=OPTIONAL, number=OPTIONAL, unit=OPTIONAL, filepath=OPTIONAL, extraParams={})

Add a Data Field to a Protocol.

Parameters:

fieldName (str) – The name of the field.
fieldType (str) – The field type. Options are: “default”, “date”, “quantity”, or “number”. The “default” type is “Text”.
value (str) – The value accompanying the fieldName entry.
date (str) – The date and time accompanying the fieldName entry. Must be in the format of “YYYY-MM-DD HH:MM”.
number (float) – The quantity.
unit (str) – The unit accompanying the number entry.

Returns:

An object representing the new Labstep Data Field.

Return type:

Metadata

Example

protocol = user.getProtocol(17000)
dataField = protocol.addDataField("Refractive Index",
                                   value="1.73")

addInventoryField(name=OPTIONAL, amount=OPTIONAL, units=OPTIONAL, resource_id=OPTIONAL, extraParams={})

Add a new inventory field to the Protocol.

Parameters:

name (str) – The name of the inventory field to add.
amount (str) – The amount required by the protocol.
units (str) – The units for the amount.
resource_id (int) – The id of the Resource recommended for use with the protocol.

Returns:

The newly added inventory field entity.

Return type:

ProtocolInventoryField

Example

protocol = user.getProtocol(17000)
resource = user.getResources(search_query='Sample A')[0]
protocol.addInventoryField(name='Sample A', amount='2', units='ml',
                     resource_id=resource.id)

getInventoryFields(count=100, extraParams={})

Returns a list of the inventory fields in a Protocol.

Returns:: List of the inventory fields in a Protocol.
Return type:: List[ProtocolInventoryField]

Example

protocol = user.getProtocol(17000)
protocol_inventoryFields = protocol.getInventoryFields()
protocol_inventory_fields[0]

addTimer(name=OPTIONAL, hours=OPTIONAL, minutes=OPTIONAL, seconds=OPTIONAL)

Add a new timer to the Protocol.

Parameters:

name (str) – The name of the timer.
hours (int) – The hours of the timer.
minutes (int) – The minutes of the timer.
seconds (int) – The seconds of the timer.

Returns:

The newly added timer entity.

Return type:

ProtocolTimer

Example

protocol = user.getProtocol(17000)
protocol.addTimer(name='Refluxing', hours='4', minutes='30')

getTimers()

Returns a list of the timers in a Protocol.

Returns:: List of the timers in a Protocol.
Return type:: List[ProtocolTimer]

Example

protocol = user.getProtocol(17000)
protocol_timers = protocol.getTimers()
protocol_timers[0].attributes()

addTable(name=OPTIONAL, data=OPTIONAL)

Add a new table to the Protocol.

Parameters:

name (str) – The name of the table.
data (json) – The data of the table in json format.

Returns:

The newly added table entity.

Return type:

ProtocolTable

Example

data = {
    "rowCount": 12,
    "columnCount": 12,
    "colHeaderData": {},
    "data": {
        "dataTable": {
            0: {
                0: {
                    "value": 'Cell A1'
                },
                1: {
                    "value": 'Cell B1'
                }
            }
        }
    }
}

protocol = user.getProtocol(17000)
protocol.addTable(name='Calibration', data=data)

getTables()

Returns a list of the tables in a Protocol.

Returns:: List of the tables in a Protocol.
Return type:: List[ProtocolTable]

Example

protocol = user.getProtocol(17000)
protocol_tables = protocol.getTables()
protocol_tables[0].attributes()

addToCollection(collection_id)

Add the protocol to a collection.

Parameters:: collection_id (int) – The id of the collection to add to
Return type:: None

getCollections(): Returns the list of collections the protocol is in.

removeFromCollection(collection_id)

Remove the protocol from a collection.

Parameters:: collection_id (int) – The id of the collection to remove from

addFile(filepath=OPTIONAL, rawData=OPTIONAL)

Add a file to a Protocol.

Parameters:: filepath (str) – The path to the file to upload.
Returns:: The newly added file entity.
Return type:: File

Example

protocol = user.getProtocol(17000)
protocol.addFile(filepath='./my_file.csv')

getFiles()

Returns a list of the files in a Protocol.

Returns:: List of the files in a Protocol.
Return type:: List[File]

Example

protocol = user.getProtocol(17000)
protocol_files = protocol.getFiles()

export(path)

Export the protocol to the directory specified.

Parameters:: path (str) – The path to the directory to save the protocol.

Example

experiment = user.getProtocol(17000)
experiment.export('/my_folder')

getJupyterNotebooks(count=100)

Retrieve the Jupyter Notebooks attached to this Labstep Entity.

Returns:: List of the Jupyter Notebooks attached.
Return type:: List[JupyterNotebook]

Example

protocol = user.getProtocol(17000)
jupyter_notebooks = protocol.getJupyterNotebooks()
print(jupyter_notebooks[0])

addJupyterNotebook(name=OPTIONAL, data=OPTIONAL)

Add a Jupyter Notebook to an protocol entry.

Parameters:

name (str) – Name of Jupyter Notebook
data (JSON) – JSON Jupyter Notebook structure

Returns:

The newly added file entity.

Return type:

JupyterNotebook

Example

protocol = user.getProtocol(17000)
protocol.addJupyterNotebook()

addConditions(number_of_conditions)

Add conditions to the protocol :Parameters: number_of_conditions (int) – The number of conditions to add

Returns:: A list of the protocol conditions added to the protocol.
Return type:: List[ProtocolCondition]

Example

protocol = user.getProtocol(17000)
conditions = protocol.addConditions(5)

getConditions()

Retrieve a list of the different conditions associated with this protocol. :returns: A list of the protocol conditions associated with the protocol. :rtype: List[ProtocolCondition]

Example

protocol = user.getProtocol(17000)
conditions = protocol.getConditions()

addComment(body, filepath=OPTIONAL, extraParams={})

Add a comment and/or file to a Labstep Entity.

Parameters:

body (str) – The body of the comment.
filepath (str) – A Labstep File entity to attach to the comment, including the filepath.

Returns:

The comment added.

Return type:

Comment

Example

my_experiment = user.getExperiment(17000)
my_experiment.addComment(body='I am commenting!',
                         filepath='pwd/file_to_upload.dat')

addTag(name)

Add a tag to the Entity (creates a new tag if none exists).

Parameters:: name (str) – The name of the tag to create.
Returns:: The Experiment that was tagged.
Return type:: Experiment

Example

my_experiment = user.getExperiment(17000)
my_experiment.addTag(name='My Tag')

assign(user_id, extraParams={})

Assign a user to a Labstep Entity as a Collaborator.

Parameters:: user_id (int) – User to be assigned.
Returns:: The collaborator added.
Return type:: Collaborator

Example

::: user_id = 120 experiment= getExperiment(10000) collaborator = experiment.assign(user_id)

getCollaborators(count=OPTIONAL, extraParams={})

Get Collaborators assigned into a Labstep Entity.

Parameters:: count (int) – Number of collaborators to fetch.
Returns:: List of the collaborators assigned.
Return type:: List[Collaborator]

Example

::: experiment= getExperiment(10000) collaborators = experiment.getCollaborators()

getComments(count=OPTIONAL)

Retrieve the Comments attached to this Labstep Entity.

Returns:: List of the comments attached.
Return type:: List[Comment]

Example

entity = user.getExperiment(17000)
comments = entity.getComments()
comments[0].attributes()

getPermissions()

Returns the sharing permissions for the Entity.

Return type:: List[Permission]

getSharelink()

Returns a sharelink for the Entity.

Returns:: The sharelink for the entity
Return type:: Sharelink

getTags()

Retrieve the Tags attached to a this Labstep Entity.

Returns:: List of the tags attached.
Return type:: List[Tag]

Example

entity = user.getExperiment(17000)
tags = entity.getTags()
tags[0].attributes()

shareWith(workspace_id, permission='view')

Shares the Entity with another Workspace.

Parameters:

workspace_id (int) – The id of the workspace to share with
permission (str) – Permission to share with. Can be ‘view’ or ‘edit’

Return type:

None

transferOwnership(workspace_id)

Transfer ownership of the Entity to a different Workspace

Parameters:: workspace_id (int) – The id of the workspace to transfer ownership to

update(): Fetches the most up-to-date version of the entity from Labstep.

Protocol Inventory Field

class labstep.entities.protocolInventoryField.model.ProtocolInventoryField(data, user)

edit(name=OPTIONAL, amount=OPTIONAL, units=OPTIONAL, resource_id=OPTIONAL, extraParams={})

Edit an existing Protocol Inventory Field.

Parameters:

name (str) – The name of the Protocol Inventory Field.
amount (str) – The amount of the Protocol Inventory Field.
units (str) – The units of the amount.
resource_id (Resource) – The id of the Resource of the Protocol InventoryField.

Returns:

An object representing the edited Protocol Inventory Field.

Return type:

ProtocolInventoryField

Example

protocol = user.getProtocol(17000)
protocol_inventory_fields = exp_protocol.getInventoryFields()
protocol_inventory_fields[0].edit(value=1.7, units='ml')

Protocol Data Field

class labstep.entities.protocolDataField.model.ProtocolDataField(data, user)

Represents a data field on a Labstep Protocol.

To see the attributes of the data field run

print(my_data_field)

Specific attributes can be accessed via dot notation like so…

print(my_data_field.value)
print(my_data_field.id)

edit(fieldName=OPTIONAL, value=OPTIONAL, extraParams={})

Edit the value of an existing data field.

Parameters:

fieldName (str) – The new name of the field.
value (str) – The new value of the data.

Returns:

An object representing the edited data field.

Return type:

ProtocolDataField

Example

data.edit(value='2.50')

delete()

Delete an existing Data field.

Example

data.delete()

linkToInventoryField(inventoryField)

Link a data field to an inventory field.

Parameters:: inventoryField :class:`~labstep.entities.protocolInventoryField.model.ProtocolInventoryField` – The inventory field to link the data field to.

Example

inventoryField = protocol.addinventoryField('Sample')
data = protocol.addDataField('Concentration')
data.linkToInventoryField(inventoryfield)

getLinkedInventoryFields()

Returns the inventory fields linked to this data field.

Example

inventoryField = protocol.addInventoryField('Sample')
data = protocol.addDataField('Concentration')
data.linkToInventoryField(inventoryField)
data.getLinkedInventoryFields()

getNotificationAlert()

Retrieve the Notification Alert of a date type metadata field.

Returns:: An object representing the notification alert of a metadata field of type Date or Date / Time.
Return type:: notificationAlert

Example

::: protocol = user.getProtocol(49574) dataField = protocol.getDataFields()[0] notification_alert = dataField.getNotificationAlert()

setNotificationAlert(message, minutes_before)

Set the Notification Alert of a date type metadata field.

Returns:: An object representing the notification alert of a metadata field of type Date or Date / Time.
Return type:: notificationAlert

Example

::: protocol = user.getProtocol(49574) dataField = protocol.getDataFields()[0] dataField.setNotificationAlert(message=’Overdue’, minutes_before=0)

Protocol Step

class labstep.entities.protocolStep.model.ProtocolStep(data, user)

Protocol Table

class labstep.entities.protocolTable.model.ProtocolTable(data, user)

edit(name=OPTIONAL, data=OPTIONAL, extraParams={})

Edit an existing Protocol Table.

Parameters:

name (str) – The name of the Protocol Table.
data (str) – The data of the table in json format.

Returns:

An object representing the edited Protocol Table.

Return type:

ProtocolTable

Example

data = {
    "rowCount": 6,
    "columnCount": 6,
    "colHeaderData": {},
    "data": {
        "dataTable": {
            0: {
                0: {
                    "value": 'Cell A1'
                },
                1: {
                    "value": 'Cell B1'
                }
            }
        }
    }
}

protocol = user.getProtocol(17000)
protocol_tables = protocol.getTables()
protocol_tables[0].edit(name='New Table Name', data=data)

getDataFrame()

Converts a Labstep Table to a Pandas DataFrame.

The first row of the Labstep Table is used as the column names for the DataFrame.

Returns:: A pandas dataframe.
Return type:: DataFrame

Example

data = {
    "rowCount": 2,
    "columnCount": 2,
    "data": {
        "dataTable": {
            0: {
                0: {
                    "value": 'Column A'
                },
                1: {
                    "value": 'Column B'
                }
            },
            1: {
                0: {
                    "value": "A1"
                },
                1: {
                    "value": "B1"
                }
            }
        }
    }
}

protocol = user.getProtocol(17000)
protocol_table = protocol.addTable(name='Test Table', data=data)
dataFrame = protocol_table.getDataFrame()
print(dataFrame['Column A'][0])

Protocol Timer

class labstep.entities.protocolTimer.model.ProtocolTimer(data, user)

edit(name=OPTIONAL, hours=OPTIONAL, minutes=OPTIONAL, seconds=OPTIONAL, extraParams={})

Edit an existing Protocol Timer.

Parameters:

name (str) – The name of the timer.
hours (int) – The hours of the timer.
minutes (int) – The minutes of the timer.
seconds (int) – The seconds of the timer.

Returns:

An object representing the edited Protocol Timer.

Return type:

ProtocolTimer

Example

protocol = user.getProtocol(17000)
protocol_timers = protocol.getTimers()
protocol_timers[0].edit(name='New Timer Name',
                        minutes=1, seconds=17)

Protocol Condition

class labstep.entities.protocolCondition.model.ProtocolCondition(data, user)

getDataFields()

Returns the variable data fields associated with this condition. :returns: An array of objects representing the Labstep Data Fields on an Protocol. :rtype: List[ProtocolDataField]

Example

protocol = user.getProtocol(17000)
condition = protocol.getConditions()[0]
dataFields = condition.getDataFields()

getInventoryFields()

Returns the variable inventory fields associated with this condition. :returns: An array of objects representing the Labstep Inventory Fields on an Protocol. :rtype: List[ProtocolInventoryField]

Example

protocol = user.getProtocol(17000)
condition = protocol.getConditions()[0]
inventoryFields = condition.getInventoryFields()