Installation and configuration
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.
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.
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:
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:
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
The command assumes the new environment is named “adk”. You can choose a different name if you want.
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:
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
deactivateinside 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_accessoption 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
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
<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
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!
Updated almost 2 years ago