Bench
The platform GUI provides tools for performing interactive data analysis using a sandbox workspace running a docker image with access to data and pipelines within a project.
Access
Bench is a module that can be found in a project. It is shown in the menu bar within the project.
❗️Before users can access Bench:
On the domain level, Bench needs to be included in the subscription
On the project level, the project owner needs to enable Bench
On the user level, the project administrator needs to enable workgroups to access the Bench pages
Permission to enable Bench
The access to activate the Bench module is controlled based upon the chosen subscription (full subscription gives access to Bench) when registering the account. This will all happen automatically after the first user logs into the system for that account. So from the moment the account is up and running, the Bench module will also be ready to be enabled.
Enable the Bench module
When a user has created a project, they can go to the Bench pages and click the Enable button. From that moment on, every user who has the correct permissions has access to the Bench module in that project.
Only the project owner can enable Illumina Connected Analytics Bench. Make sure that your subscription for the domain includes Bench.
In the project, select any page under Bench.
Select a bundle. The bundles available depend on your Illumina Connected Analytics subscription.
Select Enable.
Access the Bench pages
Access to the projects and all modules located within the project is provided on a per workgroup basis via the Team page within the project.
Workspaces
The main concept in Bench is the “Workspace”. Multiple workspaces can be created within the project. A workspace is an instance of a Docker image that runs the framework defined in the image, such as JupyterLab, R Studio, etc. It is in this workspace that code can be written and run. Via API calls, data, runs, Base tables and queries in the platform can be accessed and manipulated. Via the command line, R-packages, tools, libraries, IGV browsers, widgets, etc. can be installed. Data can also be graphically presented. At the moment, each workspace runs on an individual node and are available in different resource sizes. In addition, each node will have a local storage capacity as well, where files and results can be stored temporarily, before they are stored permanently in a Project. The size of the storage capacity can range from 10GB – 64TB.
Create new Workspace
To use Bench, a workspace needs to be created. This workspace will define which docker image will be used, which node and storage size will be used, etc.
To create a new workspace:
Click + New Workspace
Complete the following fields:
Name
Required field
Needs to be unique
Docker image
Required field
Dropdown list is filled with all possible docker images - There are a couple of standard docker images we have provided as default docker images, but users are able to expand those docker images with new or updated packages/applications as well.
Field is pre-filled with first option in the dropdown list
Storage size
Required field
Fill out a number
Represents the size of the storage available on the workspace. A storage from 10GB to 64TB can be provided.
Resource model
Required field
Size of the machine on which the workspace will run and whether or not the machine should contain GPU.
Access mode
Required field
Type of access to the internet for this workspace
Open: Internet access is allowed
Restricted: Internet access is restricted to software installations only
Closed: Internet access is restricted in any capacity
Description
Optional field
Provide additional information about the workspace
Click “Save”
The workspace can be edited afterwards on the Details tab within the workspace.
Delete workspace
To delete a workspace, click “Delete”.
The workspace will not be accessible anymore, nor shown in the list of workspaces. The content of it will be deleted so if there is any information that should be kept, you can either put it in a docker image, that you then use as a basis to start from next time, or export it using the API.
Use workspace
The workspace is not always accessible; it needs to be started before it can be used. From the moment a workspace is in the “Running” state, a node with a specific capacity is assigned to this workspace. From that moment on, you can start working in your workspace. As long as the workspace is running, the resources provided for this workspace will be charged.
Start workspace
To start the workspace, follow next steps:
Go to the Details tab of the workspace
Click on Start button
On the top of the details tab, the status changes to “Starting”. When you click on the >_Access tab, the message “The workspace is starting” appears.
Wait until the status is “Running” and the “Access” tab can be opened.
Stop workspace
The workspace will be paused, so content will not be accessible and actions can no longer be performed until started again. There are no resources provided at this moment. Any work that has been saved will stay stored in the meantime. Storage will continue to be charged until the workspace is deleted.
Workspace actions
Access tab
Once the Workspace is running, the Access tab should be loading the default applications. The default applications are defined by the start script part of the docker image. The docker images provided by Illumina will load JupyterLab by default. It also contains Tutorial notebooks that can help you get started. Opening a new terminal can be done via the Launcher, + button above the folder structure.
Build tab
To ensure that packages (and other objects, including data) are permanently installed on a Bench image, a new Bench image needs to be created, using the BUILD option in Bench. A new image can only be derived from an existing one. The build process uses the DOCKERFILE method, where an existing image is the starting point for the new Docker Image (The FROM directive), and any new or updated packages are "additive" (they are added as new layers to the existing Docker file).
NOTE: The Dockerfile commands are all run as ROOT, so it is absolutely possible to delete or otherwise interfere with an image in such a way that the image is no longer running correctly. The image does not have access to any underlying parts of the platform so will not be able to harm the platform in any way, but inoperable Bench images will have to be deleted or fixed. In order to create a derived image, open up the image that you would like to use as the basis and select the Build tab.
Name: By default, the same name as the original image; it is recommended to change the name
Version: Required field, can by any value
Description: The description you want to give your docker image (e.g., indicating which apps it contains)
Code: The Docker file commands must be provided in this section. The first 4 lines of the Docker file should NOT be edited. It is not possible to start a docker file with a different FROM directive. The most important docker file commands are RUN and COPY. More information on them is available in the official Docker documentation.
Once all information is present, click the Build button. The building can take a while. When the building has completed, the docker image will be available on the Data page within the Project. If the build has failed, the log will be displayed here and the log file will be in the Data list.
Tools
From within the workspace it is possible to create a docker image and a tool from it at the same time.
Click the + Create Tool button in the top right corner of the workspace
Give the tool a name
Replace the description of the tool to describe what it does
Add a version number for the tool
Click the Image tab
Here the IMAGE that accompanies the TOOL will be created
Change the name for the image
Change the version
Replace the description to describe what the image does
Below the line where it says “#Add your commands below.” write the code necessary for running this docker image.
Click the General Tool tab This tab and all next tabs will look familiar from Flow. Enter the information required for the tool in each of the tabs. For more detailed instruction check out the Tool creation section in the Flow documentation.
Click the Save button in the upper, right-hand corner to start the build process.
The building can take a while. When it has completed, the tool will be available in the Tool Repository.
New ‘+’ tab
The tab mechanism allows showing a web application running on the same Bench instance to be displayed in a new window.
To create a new tab, click the (+) button next to the Activity tab. This opens a dialog box to indicate
Name: Can be any name, spaces are allowed.
URL: The app URL without the leading forward slash, but with the following slash.
Clicking Save will save the link for the tab and clicking the tab will open the new application. Clicking on the Access tab will open up the default application again.
Activity tab
The last tab of the workspace is the activity tab. On this tab all actions that are performed in the workspace are shown. For example, the creation of the workspace, starting of the workspace, pausing of the workspace,etc. The activities are shown with their date, the user that performed the action and the description of the action. One use of this page is to allow users to check how long the workspace has run.
In the general “Activity” page of the project, there is also a Bench activity tab. This shows all activities performed in all workspaces within the project, even when the workspace has been deleted. The “Activity” tab in the workspace only shows the action performed in that workspace. The information shown is the same as per workspace, except here the workspace the action is performed in is listed as well.
Last updated