Running DXJupyterLab

Learn to launch a JupyterLab session on the DNAnexus Platform, via the DXJupyterLab app.

DXJupyterLab is accessible to all users of the UK Biobank Research Analysis Platform and the Our Future Health Trusted Research Environment.

For DNAnexus Platform users, a license is required to access DXJupyterLab. Contact DNAnexus Sales for more information.

Running from the UI

1. In the main menu, navigate to Tools > JupyterLab. If you have used DXJupyterLab before, the page shows your previous sessions across different projects.

2. Click New JupyterLab.

3. Configure your JupyterLab session:

   • Specify the session name and select an instance type.

   • Choose the project where JupyterLab should run.

   • Set the session duration after which the environment automatically shuts down.

   • Optionally, provide a snapshot file to load a previously saved environment.

   • If needed, enable Spark Cluster and set the number of nodes.

4. Select a feature option based on your analysis needs:

   • PYTHON_R (default): Python3 and R kernel and interpreter

   • ML: Python3 with machine learning packages (TensorFlow, PyTorch, CNTK) and image processing (Nipype), but no R

   • IMAGE_PROCESSING: Python3 with image processing packages (Nipype, FreeSurfer, FSL), but no R. FreeSurfer requires a license.

   • STATA: Stata requires a license to run

   • MONAI_ML: Extends the ML feature with specialized medical imaging frameworks, such as MONAI Core, MONAI Label, and 3D Slicer.

5. Review the pricing estimate (if you have billing access) based on your selected duration and instance type.

6. Click Start Environment to launch your session. The JupyterLab shows an "Initializing" state while the worker spins up and the server starts.

7. Open your JupyterLab environment by clicking the session name link once the state changes to "Ready". You can also access it directly via https://job-xxxx.dnanexus.cloud, where job-xxxx is your job ID.

Snapshots created using older versions of DXJupyterLab are incompatible with the current version. If you need to use an older DXJupyterLab snapshot, see environment snapshot guidelines.

For a detailed list of libraries included in each feature option, see the in-product documentation.

Running DXJupyterLab from the CLI

You can start the JupyterLab environment directly from the command line by running the app:

dx run app-dxjupyterlab

Once the app starts, you may check if the JupyterLab server is ready to server connections, which is indicated by the job's property httpsAppState set to running. Once it is running, you can open your browser and go to https://job-xxxx.dnanexus.cloud where job-xxxx is the ID of the job running the app.

To run the Spark version of the app, use the command:

dx run app-dxjupyterlab_spark_cluster

You can check the optional input parameters for the apps on the DNAnexus Platform (platform login required to access the links):

• DXJupyterLab App

• DXJupyterLab Spark Cluster Enabled App

From the CLI, you can learn more about dx run with the following command:

dx run -h APP_NAME

where APP_NAME is either app-dxjupyterlab or app-dxjupyterlab_spark_cluster.

Next Steps

See the Quickstart and References pages for more details on how to use DXJupyterLab.