Skip to main content

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

VariableMethodsBenchling PrefixDescription
schema_idcreate_assay_results_from_dataframeassaysch_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_idcreate_assay_results_from_dataframesrc_Project ID. Locate project folder in projects. Right click folder and click copy API ID.
schema_idcreate_or_update_custom_entityts_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_idcreate_or_update_custom_entitylib_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_idcreate_or_update_custom_entitysrc_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_idcreate_or_update_custom_entityent_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, ...) - get

This 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 - get_assay_result_schema_table

This method will retrieve 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 dataframea 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

Get 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
)