Benchling Class

Overview

The Benchling object can be used within editor notebooks and operators to

Upload files to Benchling
Upload assay results to Benchling
Create or update custom entities in Benchling.

The object can be setup with

from ganymede_sdk import Ganymede
from ganymede_sdk.api.benchling import Benchling

g = Ganymede()
b = Benchling(g.ganymede_context)

Displaying the Benchling Object

print(b)

Setting up Benchling

Environment configuration requires setting the following variables in Ganymede. More details can be found at the following link (https://docs.benchling.com/docs/getting-started-benchling-apps)

benchling_url: URL of Benchling instance https://<instance>.benchling.com
benchling_app_client_id: Client ID of Benchling app (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
benchling_client_secret: Client secret of Benchling app (cs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx)

Benchling Variables

Variable	Methods	Benchling Prefix	Description
schema_id	create_assay_results_from_dataframe	assaysch_	Assay result schema ID. This can be found by clicking Avatar -> Feature Settings -> Registry Settings -> Result Schemas. Highlight result schema with mouse and click </>(Copy API ID)
project_id	create_assay_results_from_dataframe	src_	Project ID. Locate project folder in projects. Right click folder and click copy API ID.
schema_id	create_or_update_custom_entity	ts_	Custom entity schema_id. This can be found by clicking Avatar -> Feature Settings -> Registry Settings -> Entity Schemas. Highlight entity schema with mouse and click </> (Copy API ID)
folder_id	create_or_update_custom_entity	lib_	Folder ID. Locate your project folder. Click the Gear object next to Project/Your project/. Click copy project link. The link will look like https://tenant.benchling.com/bio/f_/FolderID-FolderName/. The folder_id is lib_FolderID
registry_id	create_or_update_custom_entity	src_	Registry ID. 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_'
author_id	create_or_update_custom_entity	ent_	Author ID. For Ganymede user, click on the Avatar -> tenant admin console -> users tab -> search for ganymede -> click three dots -> Copy user API ID

The avatar can be found at the lower right corner of benchling.

Creating and Updating Custom Entities

Custom entities can be created and updated with

create_or_update_custom_entity(self, entity_name: str, folder_id: str, schema_id: str, registry_id: str, author_id=None, custom_entity_fields=None, if_exists="fail")

Here is an example of creating a custom entity from the columns of a dataframe. If the entity already exsits, the method will update it if if_exists = "update".

from ganymede_sdk.api.benchling import Benchling
from ganymede_sdk import Ganymede


REGISTRY_ID = "src_"
FOLDER_ID = "lib_"
ENTITY_SCHEMA_ID = "ts_"
AUTHOR_ID = "ent_"

g = Ganymede()
b = Benchling(g.ganymede_context)


for entity_name, entity_var in df[["entity_name", "entity_var"]].itertuples(
    index=False
):
    entity_dict = b.get_models_to_map(
        b.get("custom_entities", benchling_filter={"name": entity_var})
    )

    custom_entity = b.create_or_update_custom_entity(
        entity_name,
        FOLDER_ID,
        ENTITY_SCHEMA_ID,
        REGISTRY_ID,
        author_id=AUTHOR_ID
        if_exists="update",
        custom_entity_fields={
            "Some Other Entity": entity_dict.get(entity_var, None),
        },
    )

    custom_entities.update({**entity_dict, **custom_entity})

df[["entity_name", "entity_var"]] = df[["entity_name", "cell_entity_var"]].replace(custom_entities)

Data Retrieval from Benchling

The Benchling object contains methods to retrieve data from Benchling. The methods are

get(self, service: str, *args, as_dict: bool = True, benchling_filter: Optional[Dict] = None, **kwargs)
get_assay_result_schema_table(self, assay_result_id: str)
get_fields_data(self, service: str, *args, benchling_filter: Optional[Dict] = None, **kwargs)

Retrieve data (IDs, names, ...)

The get method is used to retrieve data from Benchling such as custom_entities, assay_results, schemas, plates, etc. To see available services, use

from ganymede_sdk.api.benchling import Benchling
from ganymede_sdk import Ganymede

g = Ganymede()
b = Benchling(g.ganymede_context)
b.list_available_services()

Example of using this method to get custom entities and plates information

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 custom entities with names "ent1" and "ent2"
custom_entities = b.get('custom_entities', names_any_of=['ent1', 'ent2'])

# retrieve custom entities by Benchling IDs
custom_entities = b.get('custom_entities', ids=['bfi_1234', 'bfi_5678'])

# retrieve plate named "my_plate_name"
test_plate = b.get('plates', benchling_filter={'name': 'my_plate_name'})[0]

Retrieve Schema Table

The get_assay_result_schema_table method retrieves the schema table for an assay result using its ID. This method can be used to see which columns to keep in your dataframe or how to name them.

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)

You can validate your dataframe against the schema using

validate_assay_result_schema_names(self, df: pd.DataFrame, assay_result_id: str)

Retrieve Data in Entities and Results

get_fields_data gets a Pandas DataFrame of Benchling service field results such as custom_entity and assay results data. For assay results, you must pass the schema ID starting with assaysch_.

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_entity")
df_assay_result_fields = b.get_fields_data("assay_results", "assaysch_1234")

Data Upload to Benchling

The Benchling object contains methods to upload to Benchling. The methods are

create_assay_results_from_dataframe(self, data: Union[pd.DataFrame, List[pd.DataFrame]], schema_id: str, project_id: str, replace_special_characters: bool = True, ignore_na: bool = True, upload: bool = True, **kwargs)
create_benchling_ids_from_files(self, files: Dict[str, bytes], process_file_names: bool = False)

Uploading Files - create_benchling_ids_from_files

This method can be used to upload files to Benchling and return the IDs of the files. The returned object is a dictionary mapping the file name to the ID. You can use this dictionary to link / associate values in your data to the created files.

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']"

Uploading Assay Results - create_assay_results_from_dataframe

This method can be used to upload assay results to Benchling. You can use create_ids_from_files to associate rows in your dataframe with uplaoded benchling files.

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
)

Overview​

Displaying the Benchling Object​

Setting up Benchling​

Benchling Variables​

Creating and Updating Custom Entities​

Data Retrieval from Benchling​

Retrieve data (IDs, names, ...)​

Retrieve Schema Table​

Retrieve Data in Entities and Results​

Data Upload to Benchling​

Uploading Files - create_benchling_ids_from_files​

Uploading Assay Results - create_assay_results_from_dataframe​