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 exists, 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 uploaded 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
)