signals.signals
class Signals
Signals object to interact with Signals API through read and write type methods.
Attributes
ganymede_context : GanymedeContext
Ganymede context to get run attributes
signals_url : str
Signals URL to send requests to
signals_api_key : str
Signals API key to pass in request headers
run_tag : str
Tag associated with flow run
function Signals.init
Set up the Signals object
Parameters
ganymede_context : GanymedeContext
Ganymede context to get run attributes
signals_url : str
Signals URL, retrieved from secrets
signals_api_key : str
Signals API key, retrieved from secrets
function Signals.convert_container_position
Convert string container position to grid coordinates
Parameters
container_position : str
Container position in string format (e.g. - "A1")
Returns
list[int, int]
Container position in grid coordinates (e.g. - [0, 0])
function Signals.create_container
Create a container in Signals
Parameters
container_type_id : str
ID of the container type to create
description : str
Description of the container
amount : float
Amount of the batch to put in the container
amount_unit : str
Unit of the container to create
Must be one of ["g", "ml", "kg", "mg", "l", "mug", "ng", "mul", "nl", "kl", "item"]
location_id : str
ID of the plate location to create the container in
batch_id : str
ID of the batch to add to the container
x_coord : int | None
X coordinate of the container inside a matrix plate
y_coord : str | None
Y coordinate of the container inside a matrix plate
barcode : str
Barcode of the container
container_id : str, optional
ID to use to create container, if not provided, one will be generated
container_name : str, optional
Name of the container to create, if not provided, one will be generated
container_fields : list, optional
List of dictionaries containing fields to add to the container, by default []
Returns
str
ID of the created container
Notes
Container contents cannot be modified once created, except for adjusting amount.
function Signals.create_location
Create a location in Signals, including matrix plates
Notes
Locations cannot be moved in Signals once created.
Parameters
location_name : str
Name of the location to create
location_type_id : str
ID of the location type to create
description : str
Description of the location
barcode : str
Barcode of the location
parent_location_id : str
ID of the parent location, e.g. a freezer or shelf
isGrid : bool
Whether the location is a matrix plate/has coordinates
rows : int
Number of rows in the matrix plate, only required if isGrid is True
columns : int
Number of columns in the matrix plate, only required if isGrid is True
location_fields : list, optional
List of dictionaries containing fields to add to the location, by default []
Returns
str
ID of the created location
function Signals.get_assets_or_batches
Retrieves assets or batches from the Signals API based on the specified asset type ID
(library ID).
Parameters
asset_type_id (str)
The ID of the asset type to retrieve (library ID).
asset_or_batch (str)
Either "asset" or "batch", specifying which to retrieve.
time_start (datetime, optional)
The start time for the time range to filter by. Defaults to None.
time_end (datetime, optional)
The end time for the time range to filter by. Defaults to None.
time_filter (str, optional)
The field to filter by. Defaults to "modifiedAt"
Can also be "createdAt", can add "-" in front to sort descending
page_offset (int, optional)
The page offset to start querying from. Defaults to 0. Max is 5000.
page_limit (int, optional)
The page limit to retrieve. Defaults to 100, max is 100.
sort_by (str, optional)
The field to sort by. Defaults to "createdAt".
drawing (bool, optional)
Whether to retrieve chemical drawing for the assets. Defaults to True. Adds an extra API call per asset if true.
drawing_format (str, optional)
What format to retrieve. Defaults to mol-v3000. Options are ["cdxml", "svg", "mol", "mol-v3000", "smiles", "inchi"]
validate_drawing (bool, optional)
Whether to validate the drawing using rdkit.Chem.MolFromMolBlock. Defaults to False.
Only used if drawing_format is "mol-v3000", will retrieve molfile if drawing is invalid.
Returns
dict: A dictionary containing the retrieved data and metadata.
function Signals.get_all_assets_or_batches
Retrieves all assets or batches of a given type from the Signals API, including any
additional data that may be available beyond the initial query limit of 5000 results.
Args:
asset_type_id (str)
- The ID of the asset type to retrieve.
asset_or_batch (str)
- Either "assets" or "batches", indicating which to retrieve.
drawing (bool, optional)
- Whether to retrieve chemical drawing for the assets. Defaults to False.
- Adds an extra API call per asset if true.
drawing_format (str, optional)
- What format to retrieve. Defaults to mol-v3000.
- Options are ["cdxml", "svg", "mol", "mol-v3000", "smiles", "inchi"]
time_start (datetime, optional)
- The start time for the time range to filter by. Defaults to None.
time_end (datetime, optional)
- The end time for the time range to filter by. Defaults to None.
time_filter (str, optional)
- The field to filter by. Defaults to "modifiedAt"
- Can also be "createdAt", can add "-" in front to sort descending
load_all_data (bool, optional):
- Whether to add extra API call for each asset/batch to load full data.
- Defaults to True.
validate_drawing (bool, optional)
- Whether to validate the drawing using rdkit.Chem.MolFromMolBlock. Defaults to False.
- Only used if drawing_format is "mol-v3000", will retrieve molfile if drawing is invalid.
max_page_offset (int, optional)
- The maximum page offset defined by Signals where the query needs to be adjusted to account for the next start times.
- Defaults to 1000. Check Signals' API documentation for the /entities/search endpoint to find the max page offset.
sleep_time (int, optional)
- Amount of time in seconds to pause when the page offset exceeds the max_page_offset.
- Pause is needed to avoid rate limiting.
- Defaults to 5.
Returns:
pd.DataFrame: A pandas DataFrame containing all retrieved assets or batches, along with
any additional data that was available beyond the initial query limit.
function Signals.get_all_batches_per_asset
Retrieves all assets or batches of a given type from the Signals API, including any
additional data that may be available beyond the initial query limit of 5000 results.
Parameters
asset_type_id (str)
- The ID of the asset type to retrieve.
asset_id (str)
- The eid of the asset to retrieve associated batches for.
drawing (bool, optional)
- Whether to retrieve chemical drawing for the assets. Defaults to False.
- Adds an extra API call per asset if true.
drawing_format (str, optional)
- What format to retrieve. Defaults to mol-v3000.
- Options are ["cdxml", "svg", "mol", "mol-v3000", "smiles", "inchi"]
max_page_offset (int, optional)
- The maximum page offset defined by Signals where the query needs to be adjusted to account for the next start times.
- Defaults to 1000. Check Signals' API documentation for the /entities/search endpoint to find the max page offset.
sleep_time (int, optional)
- Amount of time in seconds to pause when the page offset exceeds the max_page_offset.
- Pause is needed to avoid rate limiting.
- Defaults to 5.
Returns
pd.DataFrame
- A pandas DataFrame containing all retrieved assets or batches, along with any
additional data that was available beyond the initial query limit.
function Signals.get_batches_per_asset
Retrieves batches from the Signals API based on the specified asset ID
Parameters
asset_type_id : str
ID of the asset type to retrieve (library ID).
asset_id : str
ID of the asset to retrieve associated batches for.
time_start : datetime, optional
The start time for the time range to filter by. Defaults to None.
time_end : datetime, optional
The end time for the time range to filter by. Defaults to None.
time_filter : str, optional
The field to filter by. Defaults to "modifiedAt"
Can also be "createdAt", can add "-" in front to sort descending
page_offset : int, optional
The page offset to start querying from. Defaults to 0. Max is 5000.
page_limit : int, optional
The page limit to retrieve. Defaults to 100, max is 100.
sort_by : str, optional
The field to sort by. Defaults to "createdAt".
drawing : bool, optional
Whether to retrieve chemical drawing for the assets. Defaults to True. Adds an extra API call per asset if true.
drawing_format : str, optional
What format to retrieve. Defaults to mol-v3000. Options are ["cdxml", "svg", "mol", "mol-v3000", "smiles", "inchi"]
Returns
dict
A dictionary containing the retrieved data and metadata.
data: pd.DataFrame
A pandas DataFrame containing the retrieved batches.
function Signals.get_materials
Get Materials
Parameters
library_name : str
Name of library (e.g. - Compounds or Building Blocks)
Notes
/materials/{libraryName}/bulkExport is an asynchronous API.
If the request is accepted, server will start a job to export the materials batch by batch
asynchronously. And server will return a report with file ID and report ID to client.
Client can use one of below APIs to check the status of current export.
HEAD "/materials/bulkExport/download/{fileId}"
GET "/materials/bulkExport/reports/{reportId}"
Example usage:
Start an export job by POSTing "/materials/{libraryName}/bulkExport".
Query the status with HEADing "/materials/bulkExport/download/{fileId}" every 5 seconds till
content-length is not 0 in response header.
Or, query the status with GETing "/materials/bulkExport/reports/{reportId}" every 5 seconds
till the status is "COMPLETED" in the response body.
Download the file with GETing "/materials/bulkExport/download/{fileId}".
The maximum file size is 100MB. The maximum count is 25000 assets.
If the count limit or file size limit is reached, the user can continue the export job using
the "nextExport" link in the report.
function Signals.query_for_inventory_item
Query to see if inventory item exists in Signals
Parameters
entity_type_str : str
Type of entity to query for (e.g. - "container" or "location")
entity_property : str
Property of the entity to query for, needs to be prefaced by "fields."
e.g. "fields.Barcode"
entity_value : str
Value of the entity_property to query for
location_type_field_name : str
Name of the location type field
For containers, this is "container.Container Type"
For locations, this is "location.Location Type"
Can leave as None if not querying for a specific location type
location_type_value : str
name to query for in the location_type_field_name field
e.g. "96 well Matrix Plate" or "Matrix Tube"
Can leave as None if not querying for a specific location type
stop_after_items : int, optional
Number of items to stop after, by default 1000000
Returns
dict
JSON response from Signals
function Signals.query_for_batch
Query for batch in Signals
Parameters
libraryName : str
Name of library (e.g. - Compounds or Building Blocks)
batch_id : str
ID of batch to query for
Returns
dict
JSON response from Signals