Installation and configuration

Prerequisites

Access to Seven Bridges RHEO

Your Seven Bridges Platform account needs to be activated for use of Seven Bridges RHEO. If your account is not activated, installation of ADK libraries will fail at the "pip install" step further below. Please contact Seven Bridges to activate your account.

Python

The Seven Bridges RHEO Automation Development Kit (or just ADK) requires Python version 3.4 or higher. To be able to successfully run all ADK examples in this tutorial, Python 3.6 or higher is required.

To check your version of Python, type:

python -V
>Python 3.6.7

Please refer to Python upgrade instructions of your system should your Python version be too low.

Setting up virtual environment

Virtualenv is a tool to create isolated Python environments. It allows you to avoid installing Python packages globally, which could break system tools or impact Python projects you already have installed on your system.

Installing virtualenv

You can install virtualenv using pip, which is the reference Python package manager for installing and updating Python packages.

On macOS and Linux, if your system default python is already python3, then type:

python -m pip install --user virtualenv

or

python3 -m pip install --user virtualenv

Please note, this installation method doesn't require root permission, "virtualenv" binary will be installed under ~/.local/bin in your user home directory.

After installation, make sure this path is in your PATH environmental variable.

On Windows, type:

py -m pip install --user virtualenv

Creating new virtual environment

After installing virtualenv, you can create a new Python virtual environment. The first step is creating the directory where you want the virtual environments to be stored.

Here, we use a directory named ‘venv’ under your home directory:

mkdir ~/venv

Next let's make sure that the default "python" command on your system points to the correct version of Python. You can get this information by typing:

which python

This displays the full path to the default python binary.

Option 1: Default 'python' command points to the correct version of Python

In case the above command outputs the correct version of Python, you can proceed with the following command to create a new environment under path ~/venv.

The command assumes the new environment is named “adk”. You can choose a different name if you want.

virtualenv ~/venv/adk

Option 2: Default 'python' command points to wrong version of Python

In case the which command above pointed to the wrong Python binary, you need to find out where on your system the correct binary is located that fulfills the version requirement mentioned at the top of this page. For example, you could try "which python3", but ultimately this will depend on your system setup.

Assuming that the Python executable for the correct version of Python is located at /path/to/alternative_python/bin/python, continue with the following command:

virtualenv -p /path/to/alternative_python/bin/python ~/venv/adk

Activating virtual environment

To activate the new virtual environment, type:

source ~/venv/adk/bin/activate

After this step, you should see "(adk)" in front of your command prompt, indicating that you are inside the virtual environment.

📘

To deactivate a virtual environment, simply type deactivate inside the virtual environment (but don't do this right now).

Upgrading pip inside virtual environment

First, make sure you are inside the correct virtual environment by looking for "(adk)" in front of your command prompt.

To upgrade pip on MacOS and Linux to the latest version, type:

pip install --upgrade pip

Python installers on Windows already include pip. You should be able to access pip using:

py -m pip --version
>pip 9.0.1 from c:\python36\lib\site-packages(Python 3.6.7)

Installing ADK libraries

The ADK consists of two Python libraries: Freyja and Hephaestus. Freyja provides a backend-agnostic parallelization framework, while Hephaestus provides SB-specific bindings on top of Freyja. We need both to write automations for the Seven Bridges Platform.

In addition, we need the Python client for the Seven Bridges public API (sevenbridges-python) that Hephaestus uses to communicate with the Seven Bridges Platform.

Issue the following command to install the ADK libraries. You need to provide your authentication token, which you can obtain here.

Please make sure your Platform account is activated for Seven Bridges RHEO use, otherwise "pip install" will fail (see the note at the beginning of this section).

pip install --extra-index-url https://<YOUR-TOKEN-HERE>@pypi.sbgenomics.com hephaestus

Freyja and sevenbridges-python are both dependencies of Hephaestus, so their most recent version is installed automatically with the above command.

📘

When issuing the above 'pip install' command, you should not be prompted for username and password. If you are, it means that the token-based authentication was not successful.

The most likely reason for this is that the user account associated with the provided token is not activated for use of Seven Bridges RHEO. Please get in touch with Seven Bridges support to resolve this issue.

Upgrading ADK libraries

If at any point you need to upgrade to a newer version of the ADK, you can use the following command:

pip install --extra-index-url https://<YOUR-TOKEN-HERE>@pypi.sbgenomics.com --upgrade freyja hephaestus

Installing ADK examples

Example automations written with the ADK are available in our SB GitHub repo.

To install them on your computer, change into the directory where you want the repo to be created and use git clone:

git clone https://github.com/sbg/adk-examples

Configuring access to Seven Bridges Public API

When you installed the ADK with the commands above, it also installed sevenbridges-python, which is a Python library the ADK depends on. Authentication for sevenbridges-python needs to be set up in case you have not used this library before.

To setup API authentication, you need to provide your authentication token. Several methods are available and we recommend using the configuration file option. Learn more about API authentication via configuration files.

Briefly, include the lines below in config file ~/.sevenbridges/credentials. If this file does not yet exist on your computer, simply create it with a text editor of your choice.

[default]
api_endpoint = https://api.sbgenomics.com/v2
auth_token   = <YOUR_AUTH_TOKEN_HERE>
advance_access = true

📘

Make sure to include advance_access option in your profile inside ~/.sevenbridges/credentials, which is required by the SB CLI (see below)

Automation is currently advance access (think early access or beta), which means the Automation API might still be subject to change.

In addition, we want to activate advance_access in the SB API-specific configuration file as well.
Again, if this file does not exist yet on your computer, simply create it at above location with a text editor of your choice.

$ cat ~/.sevenbridges/sevenbridges-python/config
[mode]
advance_access=True

Verifying installation

Before we use the ADK, let's quickly verify that installation and configuration was successful on your system. We strongly recommend to not skip this step as it may lead to errors downstream that are hard to debug otherwise.

At the Virtualenv prompt (adk), type python. This will open the Python console. In the console at the command prompt ">>>", type:

>>>import sevenbridges as sbg
>>>sbg.__version__
'0.18.3'
 
>>> import freyja
>>> freyja.__version__
'0.8.0'
 
>>> import hephaestus
>>> hephaestus.__version__
'0.11.0'
 
>>> api = sbg.Api(config=sbg.Config(profile="default"))
>>> api.users.me()
<User: username=[USER_NAME]>
 
>>> api.aa
True
 
>>> quit()

If you see messages like the ones above without errors, and api.aa comes back with True, your automation libraries and the SB API have been successfully installed and configured. Note that your library versions might differ from those shown above.

ADK library documentation

Starting with Freyja version 0.17.3 and Hephaestus version 0.14.7, both ADK libraries ship with their own library documentation.

Although the automation tutorial you are currently reading contains enough information to get you started with writing your first automation, we recommend that you also go through the ADK library documentation for a more in-depth understanding on how to configure and use those libraries.

ADK library documentation is distributed in HTML format and can be found under <freyja-library-path>/freyja/docs/html/index.html and <hephaestus-library-path>/hephaestus/docs/html/index.html, respectively. Simply open those files using a web browser of your choice.

If you don't know where ADK libraries are installed on your computer, you can find out using 'pip show' like this:

$ pip show freyja hephaestus
Name: freyja
Version: 0.17.3
Summary: SBG API python client bindings
Home-page: UNKNOWN
Author: None
Author-email: None
License: Copyright 2020 Seven Bridges Genomics Inc. All rights reserved. This software may not be accessed, used, copied or distributed without a separate written license from or agreement with Seven Bridges Genomics Inc.
Location: /home/rosalind/venv/docs/lib/python3.6/site-packages
Requires: requests, pyyaml, zipp, inject, typing
Required-by: hephaestus
---
Name: hephaestus
Version: 0.14.7
Summary: SB API python automation steps
Home-page: UNKNOWN
Author: None
Author-email: None
License: Copyright 2020 Seven Bridges Genomics Inc. All rights reserved. This software may not be accessed, used, copied or distributed without a separate written license from or agreement with Seven Bridges Genomics Inc.
Location: /home/rosalind/venv/docs/lib/python3.6/site-packages
Requires: sevenbridges-python, inject, freyja
Required-by:

The library paths you are looking for can be found under Location.

Installing SB CLI

Automations on the Seven Bridges Platform are managed via the SB Command Line Interface (CLI).
To install SB CLI on your computer, please follow the installation instructions.

Even if you installed the SB CLI before it is strongly recommended that you run the installation command again to make sure you have the latest version (some automation commands may not work in older versions).

To verify that installation and authentication of the SB CLI is correct, you can use the command below. This should print your username and e-mail address.

$ sb version
sb version 0.16.2
 
$ sb whoami
Username: rosalind_franklin
Email:    [email protected]

NEXT: Hello world!