zcloud.benchling_order module

class zcloud.benchling_order.MetadataTableColumnDispatcher

Bases: object

table2columns = {'binding_site_table': ['binding_site_id', 'benchling_binding_site_id', 'design_binding_site_id', 'target_id'], 'fusion_table': ['fusion_id', 'benchling_fusion_id', 'design_fusion_id'], 'program_table': ['program_id', 'benchling_program_id', 'design_program_id', 'monday_program_id'], 'target_table': ['benchling_target_id', 'design_target_id', 'monday_target_id', 'target_id'], 'user_table': ['user_id', 'user_email', 'user_full_name', 'cluster_id']}

class zcloud.benchling_order.OrderUploaderColumns(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enum for order uploader columns.

DESIGN_NAME = 'design_name'

ENTITY_REGISTRY_ID = 'entity_registry_id'

SEQUENCE = 'sequence'

TAG_LOCATION = 'tag_location'

class zcloud.benchling_order.OrderUploaderInputColumns(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enum for order uploader input columns.

BINDING_SITE_ID = 'binding_site'

DESIGN_NAME = 'design_name'

FUSION_ID = 'fusion_id'

ITERATION_NUMBER = 'iteration'

PROGRAM_ID = 'program'

SEQUENCE = 'sequence'

TAG_LOCATION = 'tag_location'

TARGET_ID = 'target_id'

class zcloud.benchling_order.OrderUploaderIntermediateColumns(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

DESIGN_NUMBER_IMPLIED = 'design_number_implied'

FUSION_ID_IMPLIED = 'fusion_id_implied'

ITERATION_CODE_IMPLIED = 'iteration_code_implied'

SITE_NAME_IMPLIED = 'site_name_implied'

TARGET_ID_IMPLIED = 'target_id_implied'

class zcloud.benchling_order.PossibleBindingSiteColumns(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

BENCHLING_BINDING_SITE_ID = 'benchling_binding_site_id'

BINDING_SITE_ID = 'binding_site_id'

DESIGN_BINDING_SITE_ID = 'design_binding_site_id'

TARGET_ID = 'target_id'

class zcloud.benchling_order.PossibleFusionIDColumns(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

BENCHLING_FUSION_ID = 'benchling_fusion_id'

DESIGN_FUSION_ID = 'design_fusion_id'

FUSION_ID = 'fusion_id'

class zcloud.benchling_order.PossibleProgramIDColumns(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

BENCHLING_PROGRAM_ID = 'benchling_program_id'

DESIGN_PROGRAM_ID = 'design_program_id'

MONDAY_PROGRAM_ID = 'monday_program_id'

PROGRAM_ID = 'program_id'

class zcloud.benchling_order.PossibleTargetIDColumns(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

BENCHLING_TARGET_ID = 'benchling_target_id'

DESIGN_TARGET_ID = 'design_target_id'

MONDAY_TARGET_ID = 'monday_target_id'

TARGET_ID = 'target_id'

class zcloud.benchling_order.PossibleUserColumns(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

CLUSTER_ID = 'cluster_id'

USER_EMAIL = 'user_email'

USER_FULL_NAME = 'user_full_name'

USER_ID = 'user_id'

exception zcloud.benchling_order.UnableToFindMetadataError

Bases: ValueError

zcloud.benchling_order.call_benchling_service(payload)

Call the Benchling updater service with the provided payload.

Parameters:

payload (Dict) – Payload data to send to the Benchling service.

Returns:

Response from the Benchling service, including success status and any error messages.

Return type:

Dict

zcloud.benchling_order.check_allowed_project_metadata(query_dict)

Validate a metadata entity against BigQuery.

Parameters:

query_dict (Dict[str, str]) – Dictionary containing query parameters. For program_id, this is a dict mapping allowed column names to the program_id value. For target_id, this is a list of dicts with benchling_target_id, design_target_id, and monday_target_id. For binding_site_id, this includes binding_site_id and target_id.

Returns:

Dictionary containing matching records from BigQuery.

Return type:

Dict[str, List[Dict[str, str]]]

Raises:

ValueError – If validation fails with non-200 status code.

zcloud.benchling_order.check_binding_site_id(binding_site_query, allowed_other_ids=None, eval_records=None)

Validate binding site ID against metadata oracle.

Parameters:

• binding_site_query (str) – Binding site ID to validate.

• allowed_other_ids (Optional[List[str]], optional) – List of allowed target IDs for cross-validation, by default None.

• eval_records (Optional[List[Dict[str, str]]], optional) – Pre-loaded records to validate against instead of making API call, by default None.

Returns:

Tuple containing (matching_target_id, binding_site_id_benchling, binding_site_id_design).

Return type:

Tuple[str, str, str]

Raises:

UnableToFindMetadataError – If binding site ID cannot be found in the metadata.

zcloud.benchling_order.check_fusion_id(fusion_id_query, eval_records=None)

Validate a fusion ID against the metadata validator.

Parameters:

• fusion_id_query (str) – Fusion ID to validate.

• eval_records (Optional[List[Dict[str, str]]], optional) – Pre-loaded records to validate against instead of making API call, by default None.

Returns:

Tuple containing (fusion_id_internal, fusion_id_benchling, fusion_id_design).

Return type:

Tuple[str, str, str]

Raises:

UnableToFindMetadataError – If fusion ID cannot be found in the metadata.

zcloud.benchling_order.check_generated_design_names(df, generated_design_names, allow_cli_override=False)

Check if generated design names match existing design names in DataFrame.

Parameters:

• df (pd.DataFrame) – Input DataFrame containing existing design names.

• generated_design_names (pd.Series) – Series of generated design names to compare against.

• allow_cli_override (bool, optional) – Whether to allow override and use generated names when there’s a mismatch, by default False.

Raises:

UnableToFindMetadataError – If design names don’t match and override is not allowed.

Return type:

None

zcloud.benchling_order.check_program_id(program_id_query, eval_records=None, try_to_find_monday_id=None)

Validate program ID against metadata oracle.

Parameters:

• program_id_query (str) – Program ID to validate.

• eval_records (Optional[List[Dict[str, str]]], optional) – Pre-loaded records to validate against instead of making API call, by default None.

• try_to_find_monday_id (Optional[str], optional) – Monday ID to try to match against, by default None.

Returns:

Tuple containing (program_id_benchling, program_id_design, program_id_monday).

Return type:

Tuple[str, str, str]

Raises:

ValueError – If program ID cannot be found in the metadata.

zcloud.benchling_order.check_scu_schema(query_dict, all_tables=None)

Check Scientific Compute Unit (SCU) schema against available tables.

Parameters:

• query_dict (Dict[str, str]) – Dictionary containing query parameters with field information.

• all_tables (Optional[Dict[str, List[Dict[str, str]]]], optional) – Pre-loaded table data to avoid API calls. If None, will make API call.

Returns:

Dictionary mapping table IDs to lists of found field names.

Return type:

Dict[str, List[str]]

Raises:

ValueError – If SCU validation fails with non-200 status code.

zcloud.benchling_order.check_target_id(target_id_query, allowed_other_ids=None, eval_records=None, try_to_find_monday_id=None)

Validate target ID against metadata oracle.

Parameters:

• target_id_query (str) – Target ID to validate.

• allowed_other_ids (Optional[List[str]], optional) – List of allowed program IDs for cross-validation, by default None.

• eval_records (Optional[List[Dict[str, str]]], optional) – Pre-loaded records to validate against instead of making API call, by default None.

• try_to_find_monday_id (Optional[str], optional) – Monday ID to try to match against, by default None.

Returns:

Tuple containing (matching_program_id, matching_target_id_benchling, matching_target_id_design, matching_target_id_monday, matching_target_id_internal).

Return type:

Tuple[str, str, str, str, str]

Raises:

UnableToFindMetadataError – If target ID cannot be found in the metadata.

zcloud.benchling_order.check_user_id(user_id)

Check if user ID is valid.

Return type:

Tuple[str, str, str, str]

zcloud.benchling_order.create_benchling_order_folder(program_id, target_id, iteration)

Create a new folder in Benchling for the order.

Parameters:

• program_id (str) – The program ID for the order.

• target_id (str) – The target ID for the order.

• iteration (str) – The iteration number for the order.

Returns:

Response containing folder creation details including registry_folder_id and iteration_folder_id.

Return type:

Dict

zcloud.benchling_order.get_all_indexed_input_columns()

Get all the columns that are indexed in the input CSV.

Returns:

List of all column names that are part of the indexed input schema.

Return type:

List[str]

zcloud.benchling_order.get_all_scu_tables()

Retrieve all Scientific Compute Unit (SCU) tables from the service.

Returns:

Dictionary mapping table IDs to table data, or error information if the call fails.

Return type:

Dict[str, List[Dict[str, str]]]

zcloud.benchling_order.get_binding_site_candidates(df, binding_site_id_specified, allow_cli_override=False)

Get binding site ID candidates from DataFrame and CLI arguments.

Parameters:

• df (pd.DataFrame) – Input DataFrame that may contain binding site ID information.

• binding_site_id_specified (Optional[str]) – Binding site ID specified via CLI arguments.

• allow_cli_override (bool, optional) – Whether to allow CLI arguments to override DataFrame values, by default False.

Returns:

Set of resolved binding site IDs to use.

Return type:

Set[str]

Raises:

ValueError – If multiple conflicting binding site IDs are found and override is not allowed.

zcloud.benchling_order.get_full_metadata_tables(*table_ids)

Get complete metadata tables for the specified table IDs.

Parameters:

*table_ids (str) – Variable number of table IDs to retrieve.

Returns:

Dictionary containing the full metadata tables data.

Return type:

Dict

zcloud.benchling_order.get_fusion_id_candidates(df, fusion_id_specified, allow_cli_override=False)

Get candidate fusion IDs from various sources.

Parameters:

• df (pd.DataFrame) – Input DataFrame that may contain fusion ID information.

• fusion_id_specified (Optional[str]) – Fusion ID specified via CLI arguments.

• allow_cli_override (bool, optional) – Whether to allow CLI arguments to override DataFrame values, by default False.

Returns:

Set of candidate fusion IDs.

Return type:

Set[str]

Raises:

ValueError – If multiple conflicting fusion IDs are found and override is not allowed.

zcloud.benchling_order.get_iteration_id_candidate(df, iteration_number_specified, allow_cli_override=False)

Get iteration ID candidate from DataFrame and CLI arguments.

Parameters:

• df (pd.DataFrame) – Input DataFrame that may contain iteration number information.

• iteration_number_specified (Optional[str]) – Iteration number specified via CLI arguments.

• allow_cli_override (bool, optional) – Whether to allow CLI arguments to override DataFrame values, by default False.

Returns:

The resolved iteration number to use.

Return type:

str

Raises:

UnableToFindMetadataError – If multiple conflicting iteration numbers are found and override is not allowed.

zcloud.benchling_order.get_possible_columns_names_for_metadata_table(metadata_table_id)

Get possible column names for a specific metadata table.

Parameters:

metadata_table_id (str) – The ID of the metadata table to get column names for.

Returns:

List of possible column names for the specified metadata table.

Return type:

List[str]

zcloud.benchling_order.get_program_id_candidate(df, program_id_specified, allow_cli_override=False)

Get program ID candidate from DataFrame and CLI arguments.

Parameters:

• df (pd.DataFrame) – Input DataFrame that may contain program ID information.

• program_id_specified (Optional[str]) – Program ID specified via CLI arguments.

• allow_cli_override (bool, optional) – Whether to allow CLI arguments to override DataFrame values, by default False.

Returns:

The resolved program ID to use.

Return type:

str

Raises:

ValueError – If multiple conflicting program IDs are found and override is not allowed.

zcloud.benchling_order.get_required_columns()

Get the required columns for the order uploader.

Returns:

List of column names that are required for order upload.

Return type:

List[str]

zcloud.benchling_order.get_small_table_fields()

Get the fields for the small table (core sequence information).

Returns:

List of column names that constitute the small table fields.

Return type:

List[str]

zcloud.benchling_order.get_small_table_rename_dict()

Get the mapping dictionary for renaming small table columns.

Returns:

Dictionary mapping input column names to output column names.

Return type:

Dict[str, str]

zcloud.benchling_order.get_target_id_candidate(df, target_id_specified, allow_cli_override=False)

Get target ID candidate from DataFrame and CLI arguments.

Parameters:

• df (pd.DataFrame) – Input DataFrame that may contain target ID information.

• target_id_specified (Optional[str]) – Target ID specified via CLI arguments.

• allow_cli_override (bool, optional) – Whether to allow CLI arguments to override DataFrame values, by default False.

Returns:

The resolved target ID to use.

Return type:

str

Raises:

ValueError – If multiple conflicting target IDs are found and override is not allowed.

zcloud.benchling_order.initialize_df_with_design_name(df_input)

Initialize DataFrame with design name parsing and validation.

Parameters:

df_input (pd.DataFrame) – Input DataFrame containing design names to parse.

Returns:

DataFrame with additional columns for parsed design name components and adjusted index.

Return type:

pd.DataFrame

Raises:

ValueError – If design name numbers don’t match the expected index pattern.

zcloud.benchling_order.oracle_data_is_empty(oracle_data)

Check if the oracle data is empty.

Parameters:

oracle_data (Dict[str, list[dict[str, str]]]) – Dictionary containing oracle data with string keys and list of dictionaries as values.

Returns:

True if the oracle data is empty (no values in any lists), False otherwise.

Return type:

bool

zcloud.benchling_order.pdapply_build_design_names_from_row(row, iteration, target_id, binding_site_id=None, fusion_id=None, override=False)

Build a design name from a row, intended for pandas apply.

Parameters:

• row (pd.Series) – Pandas Series representing a row of data.

• iteration (str) – Iteration code to use in the design name.

• target_id (str) – Target ID to use in the design name.

• binding_site_id (Optional[str], optional) – Binding site ID to use. If None, will try to infer from row data.

• fusion_id (Optional[str], optional) – Fusion ID to use. If None, will try to infer from row data.

• override (bool, optional) – If True, use provided parameters directly. If False, try to infer missing values.

Returns:

Generated design name in the format target_id_binding_site_iteration_fusion_id###.

Return type:

str

zcloud.benchling_order.post_to_monday_service(payload, endpoint)

Call the Monday service with the provided payload.

Parameters:

• payload (Dict) – Payload data to send to the Monday service.

• endpoint (str) – The specific endpoint to call on the Monday service.

Returns:

Response from the Monday service, including success status and any error messages.

Return type:

Dict

zcloud.benchling_order.publish_benchling_entry(benchling_entry_query_dict)

Create a new entry in Benchling.

Parameters:

benchling_entry_query_dict (Dict) – Dictionary containing entry data including sequence records, CSV data, entry name, GCS bucket path, author email, Monday ticket URL, and iteration folder ID.

Returns:

Response from the Benchling service indicating success or failure of entry creation.

Return type:

Dict

zcloud.benchling_order.register_protein_entities(protein_registry_folder_id, small_table_data)

Register protein entities in Benchling.

Parameters:

• protein_registry_folder_id (str) – The folder ID in Benchling where proteins should be registered.

• small_table_data (List[Dict[str, str]]) – List of dictionaries containing protein data to register.

Returns:

Response containing registration details including aaSequences with entity registry IDs.

Return type:

Dict

zcloud.benchling_order.split_design_names(design_name)

Parse a design name following the schema: {target_id}_{site name}_{iteration code}_{design number}.

Parameters:

design_name (str) – Design name to parse in the format target_id_site_name_iteration_code_fusion_combo_number.

Returns:

Series containing parsed components: target_id_implied, site_name_implied, iteration_code_implied, design_number_implied, fusion_id_implied.

Return type:

pd.Series

zcloud.benchling_order.ticket_details_from_monday_service(ticket_url)

Get ticket details from the Monday service.

Parameters:

ticket_url (str) – URL of the Monday ticket to retrieve details for.

Returns:

Dictionary containing ticket details including project, target, and iteration code.

Return type:

Dict

zcloud.benchling_order.update_monday_ticket(ticket_link, benchling_url)

Update the Monday ticket with the Benchling URL.

Parameters:

• ticket_link (str) – Link to the Monday ticket to update.

• benchling_url (str) – URL of the Benchling entry to link to the ticket.

Returns:

Response indicating success or failure of the ticket update.

Return type:

Dict