Creating and Using Loading Configurations#

With Labs and Assistants, Artificial is able to dynamically render models in Digital Twins to match the exact requirements of a workflow or job. This way, when users are setting up instruments or loading samples, they are able to see a visual representation of the exact model and location. This is done through a loading configuration. To do this, you will need to:

  1. Create an Assistant parameter

  2. Define a loading configuration

  3. Define the parameter within the Workflow

Create an Assistant Parameter#

The first thing you will need to do is define an Assistant parameter that will represent the loading configuration. This parameter type will be [Asset Reference]. This parameter is then used to define the material’s destination field.

Learn more about parameters and material destinations here.

Define the Loading Configuration#

Then, for each loading configuration parameter, you will need to define the model and loading locations. This is done through the Lab Editor.

Start this by:

  1. Opening the lab in the Lab Editor

  2. Clicking the “Edit Loading Config” button in the Labs toolbar. This will open the Loading Config Editor.

Then, add a loading config for each parameter by:

  1. Clicking “Add Loading Config”

  2. Rename the Loading Config to a more specific name, if desired

  3. Open the asset library

  4. Drag and drop the relevant labware models into the desired locations. A couple of things to note:

    1. The loading config should represent the maximum loading scenario. For example, if there is a maximum of 10 plates then you should add 10 plates to the loading config.

    2. Add the models in the loading config in the same order you would want them rendered for the user. For example, if you want users to load plates in a hotel from top to bottom, then you should add models in your loading config starting from the top.

  5. If the labware should have a generic name and does not need to be dynamically updated (i.e., show a specific barcode), then you can edit the name of each asset in the Loading Config.

    1. If the name of the assets changes with each job, you can define this in the Workflow.

Define the parameter within the Workflow#

Now, you will link the loading config to the Assistant. To do this, open the workflow in your CodeSpace or Local Dev Container. The implementation in your Workflow will depend on whether your loading config is static or dynamic.

Static Loading Configs#

If your loading configuration is static (the quantity and labels of the labware will never change from how it is defined in the Lab Editor), then you will use the below approach:

Example code:

from artificial.workflows.decorators import parameter, workflow
from artificial.workflows.util import fetch_and_create_load_config_v1
from stubs.stubs_assistants import BaymaxNgsAssistants

@workflow('Example Workflow', 'wf_example', 'lab_b72c042e-dffb-4c7d-9497-ce0e964f609b', interactive=True, quick=True)
@parameter('num_samples', {'required:': True, 'uiTitle': 'Number of Samples'})
async def wf_example(num_samples: int) -> None:

    # Create assets in the digital twin based on the loading config
    # To get the loading config ID, use the Artificial extension.
    # See the video above for more information.
    sample_plate_loading_location = await fetch_and_create_load_config_v1('9b95d22a-9acb-4549-be37-5d5198f6c251')

    # Pass those assets to the Assistant
    await BaymaxNgsAssistants.set_up_assistant(
        num_samples=num_samples,
        sample_plate_load_location=sample_plate_loading_location,
    )

Dynamic Loading Configs#

If your loading configuration is dynamic (the quantity or the labels of the labware changes depending on the run), then you will use the below approach:

  1. Create an adapter action. For more information on adapter actions and the asset API, visit here.

    @action()
async def create_assets(self, actx: ActionExecutionContext, loading_config_id: str, num_assets: int = -1, name_overrides: t.List[str] = []) -> t.List[str]:
    assets = await self.artificial_api.asset_api_v2.fetch_loading_config(actx=actx, load_config_id=loading_config_id)
    if num_assets > 0:
        assets = assets[:num_assets]
    if len(name_overrides) > 0:
        for i, name_override in enumerate(name_overrides):
            assets[i].display_name = name_overridew
    return await self.artificial_api.asset_api_v2.create(actx=actx, assets=assets, cleanup_with_job=True)

  2. Generate action stubs in the Artificial Extension

  3. Import the action into your workflow.

from stubs.stubs_actions import create_assets

  1. Add the function before the Assistant that will use it

  2. Fill in the function arguments:

    1. The first argument is the loading config ID. Use the Artificial extension to set this. Instructions here.

    2. The second argument is the number of assets to render. Define this as needed.

    3. The third argument is the name overrides for the assets. Define this as needed.

  3. Define the output of the function. This is now the input you feed into the associated Assistant parameter.

Below is an example implementation

from typing import List

from artificial.workflows.decorators import parameter, workflow
from stubs.stubs_actions import create_assets
from stubs.stubs_assistants import BaymaxNgsAssistants

@workflow('Example Workflow_2', 'wf_example_2', 'lab_b72c042e-dffb-4c7d-9497-ce0e964f609b', interactive=True, quick=True)
@parameter('num_samples', {'required:': True, 'uiTitle': 'Number of Samples'})
@parameter('barcodes', {'required': True, 'uiTitle': 'Plate Barcodes'})
async def wf_example_2(num_samples: int, barcodes: List[str]) -> None:
    sample_plate_loading_location = await create_assets('9b95d22a-9acb-4549-be37-5d5198f6c251', round(num_samples / 96), barcodes)
    await BaymaxNgsAssistants.set_up_assistant(
        num_samples=num_samples,
        sample_plate_load_location=sample_plate_loading_location,
    )

How to use the Artificial extension to add a Loading config ID#

  1. Go to the Artificial Extension section “Loading Configs.”

  2. Find your lab and expand the list

  3. Select the loading config you defined and drag it into the function

  4. Press Shift on your keyboard and release the mouse

  5. Add quotes around the ID