Skip to main content

benchling.benchling

class Benchling​

Benchling object to interact with Benchling API through read and write type methods.

Attributes​

ganymede_context : GanymedeContext
        Ganymede context to get run attributes
benchling_context : BenchlingContext
        Benchling context variable, which stores Benchling connection information
conn : benchling_sdk.benchling.Benchling
        The benchling connection object
run_tag : str
        Tag associated with flow run
custom_entity_service : CustomEntityService
        Benchling custom entity service to create or update custom entities
molecule_service : MoleculeService _ defaults to None, initialized when first used
        Benchling molecule service to create or update molecules

function Benchling.init​

Set up the Benchling object

Parameters​

ganymede_context : GanymedeContext
        Ganymede context to get run attributes
benchling_context : BenchlingContext | None
        Benchling context variable, which stores Benchling connection information

function Benchling.list_schemas​

Lists schemas, filtered by type if provided

Parameters​

type : str | None
        Schema type - potential values are "custom_entity", "assay_result", "molecule", "plate",
        "aa_sequence", "box", "container", "entry", "location", "mixture", "workflow_task", etc.

Returns​

list[dict]
        list of schemas

function Benchling.get_schema_id_by_name​

Get schema by name

Parameters​

schema_name : str
        Schema name
type : str | None
        Subset search by schema type - potential values are "custom_entity", "assay_result", etc.

Returns​

str
        Schema ID for specified schema

function Benchling.is_http_429_error​

Check if the exception is a Benchling HTTP 429 (rate limit) error.

function Benchling.create_or_update_custom_entity​

Creates custom entity in Benchling.    If the entity does not exist, first create it.

Parameters​

entity_name : str
        Name of new entity to be created
folder_id : str | Unset
        Folder ID containing Benchling entity to be created. This should be a string starting
        with "lib_".    If updating a custom entity, specifying the folder ID is optional (if specified,
        moves the custom entity to the specified folder).
schema_id : str | Unset
        Input schema ID Tag. schema associated with Benchling entity to be created. This should
        be a string starting with "ts_"
registry_id : str | Unset
        Project associated with custom entity.    This identifies the registry that your run
        entity will be registered to.    This can be found by clicking on Avatar - Feature
        Settings - Registry Settings, and you will be able to find it in the URL.    This should
        be a string starting with "src_"
naming_strategy : NamingStrategy
        Naming strategy to use when creating new entities. See NamingStrategy for more details.
custom_entity_fields : dict | Unset
        Dictionary of field names and values to associate with custom entity
author_id : str | Unset
        Author ID to associate with custom entity. Should be a string starting with "ent_"
if_exists : str
        Either "fail" or "update". If "fail", will raise an error if the entity already exists.

Returns​

dict[str, str]
        Dictionary with custom entity name as key and custom entity ID as value

function Benchling.create_or_update_custom_entities_bulk​

Bulk creates custom entities in Benchling.    If the entity does not exist, first create it.

Parameters​

custom_entities_dataframe : pd.DataFrame
        Dataframe containing custom entities to be created
        Columns should include name_field and all fields in schema
name_field : str
        Name of column in custom_entities_dataframe containing entity names
folder_id : str | None
        Folder ID containing Benchling entity to be created. This should be a string starting
        with "lib_".    If updating a custom entity, specifying the folder ID is optional (if specified,
        moves the custom entity to the specified folder).
schema_id : str
        Input schema ID Tag. schema associated with Benchling entity to be created. This should
        be a string starting with "ts_"
registry_id : str
        Project associated with custom entity.    This identifies the registry that your run
        entity will be registered to.
naming_strategy : NamingStrategy
        Naming strategy to use when creating new entities. See NamingStrategy for more details.
check_for_existing : bool
        Whether or not to check for the existence of the entities in name_field. This is useful to turn off when you know you'll be creating new entities (for example with many naming strategies) and want to avoid many api calls for checking existence of custom entities,
wait : bool
        Whether to wait for the task to complete before returning
error_on_fail : bool
        Whether to raise an error if the task fails
page_size_limit : int
        Maximum number of entities Benchling will return in a single page. Default is 100

Returns​

dict[str, list[str]]
        Dictionary with keys "created" and "updated" and values of lists of custom entity IDs

function Benchling.create_or_update_molecule​

Creates molecule in Benchling.    If the entity does not exist, first create it.

Parameters​

entity_name : str
        Name of new entity to be created
folder_id : str
        Folder ID containing Benchling entity to be created. This should be a string starting
        with "lib_"
schema_id : str
        Input schema ID Tag. schema associated with Benchling entity to be created. This should
        be a string starting with "ts_"
registry_id : str
        Project associated with custom entity.    This identifies the registry that your run
        entity will be registered to.    This can be found by clicking on Avatar - Feature
        Settings - Registry Settings, and you will be able to find it in the URL.    This should
        be a string starting with "src_"
naming_strategy : NamingStrategy
        Naming strategy to use when creating new entities. See NamingStrategy for more details.
custom_entity_fields : dict | None
        Dictionary of field names and values to associate with custom entity
author_id : str | None
        Author ID to associate with custom entity. Should be a string starting with "ent_"
molecule_fields : dict | None
        Dictionary of field names and values to associate with molecule
if_exists : str
        Either "fail" or "update". If "fail", will raise an error if the entity already exists.

Returns​

molecule : Molecule
        Created molecule object

function Benchling.create_or_update_molecules_bulk​

Bulk creates molecules in Benchling.    If the entity does not exist, first create it.

Parameters​

molecules_dataframe : pd.DataFrame
        Dataframe containing molecules to be created
        Columns should include name_field and all fields in schema
name_field : str
        Name of column in molecules_dataframe containing entity names
folder_id : str
        Folder ID containing Benchling entity to be created. This should be a string starting
        with "lib_"
schema_id : str
        Input schema ID Tag. schema associated with Benchling entity to be created. This should
        be a string starting with "ts_"
registry_id : str
        Project associated with custom entity.    This identifies the registry that your run
        entity will be registered to.
naming_strategy : NamingStrategy
        Naming strategy to use when creating new entities. See NamingStrategy for more details.
wait : bool
        Whether to wait for the task to complete before returning
error_on_fail : bool
        Whether to raise an error if the task fails
molecular_structure_field : str | None
        Name of column in molecules_dataframe containing molecular structure
molecular_structure_format : str | None
        Format of molecular structure.    This should be one of ["smiles", "mol-v3000"]
check_for_existing : bool
        Whether or not to check for the existence of the entities in name_field. This is useful to turn off when you know you'll be creating new entities (for example with many naming strategies) and want to avoid many api calls for checking existence of molecules,
page_size_limit : int
        Maximum number of entities Benchling will return in a single page. Default is 100

Returns​

dict[str, list[str]]
        Dictionary with keys "created" and "updated" and values of lists of molecule IDs

function Benchling.create_benchling_ids_from_files​

Upload blob files to Benchling and return a dictionary of
{blob name: blob ID from Benchling}

Parameters​

files : dict[str, bytes]
        Files to upload to Benchling
process_file_names : bool
        Use to process file_name for benchling by converting string to lowercase and removing
        periods. Default is False.

Returns​

dict[str, Unset | str]
        Returns a dictionary of IDs from benchling_sdk.models.Blob where the keys are the blob
        names and the benchling IDs are the values

Example​

from ganymede_sdk.api.benchling import Benchling  
from ganymede_sdk import Ganymede  
import pandas as pd  
  
g = Ganymede()  
b = Benchling(g.ganymede_context)  
  
# Get the IDs for two files that are uploaded to Benchling  
  
file_ids = b.create_benchling_ids_from_files(  
    \{"Filename1.csv": file1, "Filename2.csv": file2\}, process_file_names=True  
) # where file_ids.keys() = ['filename1csv', 'filename2csv']"  
  
file_ids = b.create_benchling_ids_from_files(  
    \{"Filename1.csv": file1, "Filename2.csv": file2\}  
) # where file_ids.keys() = ['Filename1.csv', 'Filename2.csv']"

function Benchling.create_assay_results_from_dataframe​

Process input DataFrame into assay results for upload to Benchling.

Parameters​

data : pd.DataFrame
        Tabular results of data to send to Benchling. Converted to list of dictionaries for
        each row.
schema_id : str
        ID should contain the Benchling schema ID to write to.    This should be a string starting
        with "assaysch_"
project_id : str
        ID that results will be recorded against.    This should be a string starting with "src_".

        The members of your organization that have access to this project will also have
        visibility to the results that this integration generates.    You can find this ID by
        right clicking on the Project that you have selected, and click on "Copy API ID".
        If you don't see "Copy API ID" as an option, click on your avatar, click Settings,
        and scroll to the bottom and verify that
        "Enable Copy API ID button" is checked.
replace_special_characters : bool
        Replace special characters in column names with underscores to mimic Benchling behavior.
        Default is True.
ignore_na : bool
        If True, drop columns with only nulls prior to upload. Default is True.
error_on_empty_result : bool
        If True, raise an error if the DataFrame is empty. Default is True.
upload : bool
        Whether to upload list[AssayResults] to Benchling
**kwargs
        Keyword args to pass to create_assay_result_from_dict
        drop_na (bool | None)

Returns​

list[AssayResultCreate]
        List of AssayResultCreate's to be uploaded to Benchling

Example​

from ganymede_sdk.api.benchling import Benchling  
from ganymede_sdk import Ganymede  
  
g = Ganymede()  
b = Benchling(g.ganymede_context)  
  
# Create or update the entity  
custom_entity_id = b.create_or_update_custom_entity(  
    entity_name, folder_id, schema_id, registry_id,  
    author_id=None, custom_entity_fields=None, if_exists="fail",  
)  
  
# Create file IDs and get dropdown IDs  
file_ids = b.create_benchling_ids_from_files(\{"filename1": file1, "filename2": file2\})  
dropdown_ids = \{dropdown["name"]: dropdown["id"] for dropdown in b.get("dropdowns")\}  
  
# Use pandas.DataFrame.replace to link entries in your dataframe with Benchling IDs  
# or manually add IDs to the dataframe.  
dataframe = dataframe.replace(\{**custom_entity_id, **file_ids, **dropdown_ids\})  
  
# Upload dataframe to Benchling as Assay Results  
assay_results = b.create_assay_results_from_dataframe(  
    dataframe, schema_id, project_id, drop_na=True, upload=True  
)

function Benchling.transfer_entities_to_plate​

Transfer entities to a plate in Benchling.

Parameters​

plate : Plate
        Plate to transfer entities to. E.g.
                plate_dict = b.get("plates", ids=["plt_efVi6kBw"])[0]         plate = Plate.from_dict(plate_dict)        
        or
                plate_create = PlateCreate(PLATE_96_WELL_SCHEMA_ID, plate_barcode, PROJECT_ID, parent_storage_id=FRIDGE_ID)         plate = b.conn.plates.create(plate_create)        
transfer_df : pd.DataFrame
        DataFrame with the following columns:
        - entity_id: str
                ID of the entity to transfer
        - well: str
                Well to transfer entity to. Should be in the format "rowcolumn" (e.g. "A1")
        - volume: float
                Volume of the entity
        - volume_units: str
                Units of the volume. See benchling_sdk.models.ContainerQuantityUnits for options
        - concentration: float | None
                Concentration of the entity
        - concentration_units: str | None
                Units of the concentration
                Valid units are molar (M), mass (g/L), and count (cells/L) concentration units. Otherwise, use U/L units. See ContainerQuantityUnits for options to use in the form f"\{mass or count unit\}/\{volume unit\}"

function Benchling.write_dataframe_to_benchling_table​

Uploads Pandas DataFrame to Benchling assay results with specified Benchling table. Please
see https://docs.benchling.com/docs/example-creating-results for more information. Make sure
there are appropriate permissions to write to the notebook entry.

Parameters​

data : pd.DataFrame
        Tabular results of data to send to Benchling. Converted to list of dictionaries for
        each row.
schema_id : str
        ID should contain the Benchling schema ID to write to.    This should be a string starting
        with "assaysch_"
project_id : str
        ID that results will be recorded against.    This should be a string starting with "src_".

        The members of your organization that have access to this project will also have
        visibility to the results that this integration generates.    You can find this ID by
        right clicking on the Project that you have selected, and click on "Copy API ID".
        If you don't see "Copy API ID" as an option, click on your avatar, click Settings,
        and scroll to the bottom and verify that
        "Enable Copy API ID button" is checked.
table_id : str | None
        ID of the table to write to.    This should be a string starting with "strtbl_". You can
        find this using b.get("entries", id="etr_") or b.get("entries", name="EXP12345678") in
        the apiId field. The default is None.
replace_special_characters : bool
        Replace special characters in column names with underscores to mimic Benchling behavior.
        Default is True.
ignore_na : bool
        If True, drop columns with only nulls prior to upload. Default is True.
error_on_empty_result : bool
        If True, raise an error if the DataFrame is empty. Default is True.
wait : bool
        Whether to wait for the task to complete before returning
**kwargs
        Keyword args to pass to create_assay_result_from_dict
        drop_na (bool | None)

Returns​

list
        List of task ids for the results uploaded to Benchling.

Example​

from ganymede_sdk.api.benchling import Benchling  
from ganymede_sdk import Ganymede  
  
g = Ganymede()  
b = Benchling(g.ganymede_context)  
  
# Create or update the entity  
custom_entity_id = b.create_or_update_custom_entity(  
    entity_name, folder_id, schema_id, registry_id,  
    author_id=None, custom_entity_fields=None, if_exists="fail",  
)  
  
# Create file IDs and get dropdown IDs  
file_ids = b.create_benchling_ids_from_files(\{"filename1": file1, "filename2": file2\})  
dropdown_ids = \{dropdown["name"]: dropdown["id"] for dropdown in b.get("dropdowns")\}  
  
# Use pandas.DataFrame.replace to link entries in your dataframe with Benchling IDs  
# or manually add IDs to the dataframe.  
dataframe = dataframe.replace(\{**custom_entity_id, **file_ids, **dropdown_ids\})  
  
# Upload dataframe to Benchling as Assay Results  
task_ids = b.write_dataframe_to_benchling_table(  
    dataframe,  
    schema_id,  
    project_id,  
    table_id = "strtbl_",  
    replace_special_characters = True,  
    ignore_na = True,  
    error_on_empty_result = True,  
    wait = True  
)

function Benchling.create_entry​

Create a benchling notebook entry in a given folder. Entries can be created from templates
if passed the entry_template_id.

Parameters​

folder_id : str
        The ID of the folder where the entry will be created.
name : str
        The name of the new entry.
author_ids : str | list[str] | Unset
        The IDs of the authors of the entry.
custom_fields : CustomFields | Unset
        Any custom fields to include in the entry.
entry_template_id : str | Unset
        The ID of the template to use for the entry. The API ID can be copied from Template
        Collections in Feature Settings.
fields : Fields | Unset
        The fields to include in the entry.
initial_tables : InitialTable | list[InitialTable] | Unset
        The initial tables to include in the entry.
schema_id : str | Unset
        The ID of the schema to use for the entry.

Returns​

EntryCreate
        The object of the created entry

Example​

b = Benchling(ganymede_context)  
  
entry = b.create_entry(  
    folder_id="lib_",  
    name="My Entry from Template",  
    entry_template_id="tmpl_",  
)

function Benchling.create_lab_auto_result_from_dataframe​

Creates lab auto result from DataFrame.

Parameters​

df : pd.DataFrame
        DataFrame to create lab auto assay result from.    A typical use case is to upload a DataFrame with 1 row,
        consisting of IDs associated with uploaded images and raw files to associate.
assay_run_id : str
        Assay Run ID to associate with assay result.    This should be a UUID of the form "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        and exists in the event payload for the v2.assayRun.created and v2.assayRun.updated.fields Benchling events.
result_table_name : str
        Name of result table associated with lab auto processor of interest.

Returns​

AsyncTaskLink
        Link to async task result for assay result creation related to lab auto

function Benchling.is_automated_test​

Checks if the current test is an automated test.

Returns​

bool
        True if the test is automated, False otherwise.

function Benchling.get_id_from_dropdown_name​

Get a dictionary of dropdown name - dropdown id from dropdown summary info identified by
name. Can pass a dropdown id to look up the id of an option of a dropdown

Parameters​

dropdown_name : str
        Dropdown name to identify id for
*args
        Optional positional arguments to pass to list method of benchling_sdk dropdown service
dropdown_id : str | None
        If supplied, get the ID of an option in the dropdown specified by the dropdown_name. The
        default is None.
**kwargs
        Optional keyword arguments to pass to list method of benchling_sdk dropdown service

Returns​

dict[str, str]
        Dictionary of dropdown name - dropdown id for a specified dropdown name. Raises an
        error if dropdown id is not found

Example​

from ganymede_sdk.api.benchling import Benchling  
from ganymede_sdk import Ganymede  
  
g = Ganymede()  
b = Benchling(g.ganymede_context)  
  
dropdown_id = get_id_from_dropdown_name(  
    "option_name",  
    b.benchling_context,  
    dropdown_id=get_id_from_dropdown_name("Dropdown Name", b.benchling_context),  
)

function Benchling.list_available_services​

List available Benchling services

Returns​

list[str]
        List of available Benchling services

function Benchling.get_fields_data​

Get a pandas dataframe of benchling service field results such as custom_entity and assay
results data.

Parameters​

service : str
        Benchling object service (e.g. - 'custom_entities', 'assay_results')
*args
        Optional arguments to pass to list methods of the benchling service
benchling_filter : dict | None
        Filter to apply to the list of Benchling objects
**kwargs
        Optional keyword arguments to pass to list methods of the benchling service

Raises​

ValueError
        Raise an error if the service argument is not a valid method of benchling_context.conn
ValueError
        Raise an error if fields is not an attribute of of the service results.

Returns​

pd.DataFrame
        A dataframe of records returned benchling_context.conn.service.list(_...)

Example​

from ganymede_sdk.api.benchling import Benchling  
from ganymede_sdk import Ganymede  
  
g = Ganymede()  
b = Benchling(g.ganymede_context)  
  
# Get data frame of fields returned from custom entities and assay_results  
df_custom_entity_fields = b.get_fields_data(  
    "custom_entities", ids=['bfi_1234', 'bfi_5678']  
)  
df_assay_result_fields = b.get_fields_data("assay_results", "assaysch_1234")

function Benchling.get​

Get all Benchling objects of a specific type, optionally filtered by object attributes

Parameters​

service : str
        Benchling object service (e.g. - 'custom_entities', 'plates', 'entries')
*args
        Optional arguments to pass to list methods of the benchling service
as_dict : bool
        Whether to return each Benchling object as a dictionary. Default is True.
benchling_filter : dict | None
        Filter to apply to the list of Benchling objects
**kwargs
        Optional keyword arguments to pass to list methods of the benchling service

Raises​

ValueError
        Raise an error if the service argument is not a valid method of benchling_context.conn

Example​

from ganymede_sdk.api.benchling import Benchling  
from ganymede_sdk import Ganymede  
  
g = Ganymede()  
b = Benchling(g.ganymede_context)  
  
# retrieve all custom entities  
custom_entities = b.get('custom_entities')  
  
# retrieve all custom entities with specific entity schema  
custom_entities = b.get('custom_entities', schema_id='ts_1234')  
  
# retrieve custom entities with names "ent1" and "ent2" (with alternatives)  
custom_entities = b.get('custom_entities', names_any_of=['ent1', 'ent2'])  
custom_entities = b.get('custom_entities', names_any_of_case_sensitive=['eNt1', 'eNt2'])  
custom_entities = b.get('custom_entities', name_includes='ent')  
  
# retrieve custom entities by Benchling IDs  
custom_entities = b.get('custom_entities', ids=['bfi_1234', 'bfi_5678'])  
  
# retrieve all custom entities with specific entity schema  
# note that author IDs also start with "ent_", like other custom entities  
custom_entities = b.get('custom_entities', author_idsany_of=['ent_1234'])  
  
# get a list of entities filtered by schema fields (in this case, a lab instrument)  
b.get(  
    "custom_entities",  
    schema_id=INSTRUMENT_SCHEMA_ID,  
    schema_fields=\{"Serial #": instrument_serial_number\},  
)  
  
# get specific notebook entry by ID  
b.get('entries', id='etr_1234')  
  
# retrieve plate named "my_plate_name"  
test_plate = b.get('plates', benchling_filter=\{'name': 'my_plate_name'\})[0]  
  
# to get a list of available services (e.g. - plates, custom_entities, etc.)  
b.list_available_services()

function Benchling.get_models_to_map​

Get a dictionary mapping names to Benchling IDs from a list of dictionaries. This can be
used in conjunction with Benchling.get()

Parameters​

benchling_service_results : str
        Results of the form list[dict] returned from get() where "id" and "name" are common keys
        in the dict.
keys : str
        The key name of the inner dictionaries in the list used to set the key in the returned
        dictionary.
values : str
        The key name of the inner dictionaries Used to set the values in the returned dictionary
        Optional keyword arguments to pass to list methods of the benchling service

Returns​

dict
        Dictionary mapping names to the benchling IDs

Example​

from ganymede_sdk.api.benchling import Benchling  
from ganymede_sdk import Ganymede  
  
g = Ganymede()  
b = Benchling(g.ganymede_context)  
  
# Get the dropdowns of the form [\{"id": id, "name": name\}]  
results = b.get("dropdowns")  
  
# Convert list of dictionaries to dictionary where name is the key and id are the values  
# of the form \{name: value\}  
dropdown_names_to_ids = b.get_model_to_map(results, keys='name', values='id')

function Benchling.validate_assay_result_schema_names​

Validate column names in a DataFrame against an assay result schema.

Parameters​

df : pd.DataFrame
        The DataFrame containing data to be validated against the assay result schema.
assay_result_id : str
        The unique identifier of the assay result schema in Benchling.

Returns​

set
        A set of matched field names between the DataFrame and the assay result schema.

Raises​

SchemaError
        If there are unmatched fields between the DataFrame and the assay result schema.

function Benchling.get_assay_result_schema_table​

Retrieve the schema table for an assay result using its ID.

Parameters​

assay_result_id : str
        The unique identifier of the assay result.

Returns​

pd.DataFrame
        A DataFrame containing the field definitions of the assay result schema.

Examples​

from ganymede_sdk import Ganymede  
from ganymede_sdk.api.benchling import Benchling  
  
g = Ganymede()  
b = Benchling(g.ganymede_context)  
  
result_id = "example_result_id"  
schema_table = b.get_assay_result_schema_table(result_id)

function Benchling.archive_custom_entity​

Unregisters and Archives a custom entity that has been registered in Benchling Registry.

Parameters​

custom_entity_name : str
        Name of custom entity to archive
reason : EntityArchiveReason, optional
        Reason to archive custom entity, by default "Other"

Raises​

ValueError
        Error if method is called in pipeline execution.    The method is only supported
        in editor and analysis notebooks.

function Benchling.archive_assay_result​

Archives assay results based on assay result schema and condition.

Parameters​

assay_result_schema_id : str
        Assay result schema ID to archive; should start with 'assaysch_'
app_name : str, optional
        Creator of assay result to filter by, by default "Ganymede App"
filter_fields : dict[str, str], optional
        Fields on assay result to filter by, specified as a dictionary of field name to field display value
execute : bool
        Whether to execute the archive.    If False, will return assay results to archive.

Raises​

ValueError
        Error if method is called in pipeline execution.    The method is only supported
        in editor and analysis notebooks.

Returns​

list[dict]
        List of assay results to archive

function Benchling.get_notebook_entry_as_pdf​

Fetch a notebook entry as a PDF by making a series of requests to the server.

This function initiates an export task, then polls the task status until it succeeds.
It then downloads the resulting PDF and returns its contents.

Parameters​

entry_id : str
        The ID of the notebook entry to export. Has the form 'etr_...'
sleep_time_seconds : int, optional
        The number of seconds to wait between each attempt to check the task status, by default 5.
max_attempts : int, optional
        The maximum number of attempts to check the task status, by default 10.

Returns​

bytes
        The contents of the exported PDF.

Raises​

HTTPError
        If any of the requests fail.

class SchemaError​

Raised when the assay result trying to be created does not match the table schema in Benchling