Workstation Apps

Workstations are a class of apps on precisionFDA that are "interactive". Most apps on precisionFDA are non-interactive: you provide inputs, the app follows a set script, and creates outputs if it finishes successfully. Workstations are interactive; they create an environment where the user may enter any command they choose.

Workstation Types

There are currently two types of Workstations on precisionFDA:

1) TTYD - this Workstation provides an Ubuntu command-line terminal interface.

2) JupyterLab - this Workstation provides a JupyterLab server graphical interface. The Jupyter interface supports running Python or R notebooks, as well as a built-in terminal.

Access to Workstations

In order to run a Workstation, your account needs additional authorization. You can request Workstations authorization by sending an email to precisionFDA Support (precisionfda-support@dnanexus.com).

If you do not have authorization, you will receive an error message when you click "Run" on a Workstation app.

Launching a Workstation

Workstations may be found in the public Apps repository, similar to other apps.

Here are links to current Workstations:

TTYD Workstation, for command line access

JupyterLab Workstation, for creating and running Jupyter notebooks

When you launch a Workstation, it will take 2-5 minutes for the worker to initialize. Once the Execution page states that the execution is "Running", you may access the Workstation. A link will appear in the middle of the page, labeled "Open."

Running Workstation page

Clicking on this "Open" link will open the Workstation in a new tab, bringing up a terminal interface (TTYD Workstation) or the Jupyter interface (JupyterLab Workstation).

Accessing files and data on Workstations

When you run a Workstation, you have full admin access on the worker, as well as unrestricted internet access.

You may install packages with "sudo pip" or "sudo apt-get".

sudo apt-get install pigz

You may install Python packages with pip.

sudo pip install numpy

You may download any public-facing file with wget.

wget http://www.usadellab.org/cms/uploads/supplementary/Trimmomatic/Trimmomatic-0.36.zip

You can pull GitHub repositories with Git.

git clone https://github.com/lh3/bwa.git

Accessing data on precisionFDA

Workstations have full access to your private files in your precisionFDA cloud environment. You can interact with these files using dx commands:

   dx ls
   dx download
   dx upload
        

dx ls will show all files on your private precisionFDA area.

dx download <$filename> will download a file from precisionFDA to the local worker. You may use an asterisk to indicate multiple files.

dx upload <$filename> will upload a file from the local worker to your precisionFDA private area. You may upload multiple files using an asterisk.

NOTE: your files will not appear on precisionFDA until file synching occurs, which happens only upon termination of the Workstation execution.

Creating snapshots on Workstations

Workstations support the ability to create a snapshot, which takes a picture of all modifications to the Workstation since it was launched and can be seen as a "save point". The snapshot action creates a tarball that contains all modified files, which is placed in a user's precisionFDA private area as a *.snapshot data object.

After a snapshot file is created, a new execution of a Workstation may be launched, with the snapshot data object as an optional input. If a snapshot is provided as input, it will be unpacked on the worker instance and all files will be placed in the locations where they were located when the snapshot was created.

To take a snapshot in the TTYD Workstation, run the command:

dx ls

To take a snapshot with the JupyterLab Workstation, click on the "snapshot" option under the "precisionFDA" menu in the top menu bar.

Once created and synched (via termination of the Workstation), a snapshot file will appear in your private Files area. You can recognize these files, as they will end in ".snapshot". This file may be an optional input to a new Workstation execution.

NOTE: In order to run the snapshot generation command, Python2.7 must be included in the $PYTHONPATH variable. Installing Python managers, such as Conda/BioConda, may alter this path. If you see a failure to generate the snapshot, check to see if this path has been changed by running echo $PYTHONPATH.

Terminating Workstations

TTYD Workstations will terminate after 30 days.

Jupyter Workstations will terminate after 4 hours (240 minutes) by default. This timeout can be adjusted, either by providing a custom duration as an input or by using the "Adjust Duration" option in the Jupyter interface.

You can terminate a Workstation at any time by selecting "Terminate" from the Execution detail page.

Any uploaded files on a Workstation, pushed to the cloud using `dx upload`, will not appear on precisionFDA in your private area until the Workstation Execution is terminated.

Note that after a Workstation is terminated, any files on the worker are no longer accessible! Make sure to upload your work, or take a snapshot of the worker, before terminating.