# Running JupyterLab

{% hint style="info" %}
JupyterLab 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 JupyterLab. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information.
{% endhint %}

## Running from the UI

1. In the main menu, navigate to **Tools** > **JupyterLab**. If you have used JupyterLab 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](https://documentation.dnanexus.com/user/jupyter-notebooks/running-dxjupyterlab/freesurfer-in-dxjupyterlab) requires a license. GUI viewers such as `fsleyes` and `freeview` cannot be launched in the headless environment.
   * `STATA`: Stata requires a [license to run](https://documentation.dnanexus.com/user/jupyter-notebooks/stata-in-dxjupyterlab)
   * `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.

{% hint style="info" %}
Snapshots created using older versions of JupyterLab are incompatible with the current version. If you need to use an older JupyterLab snapshot, see [environment snapshot guidelines](https://documentation.dnanexus.com/user/jupyter-notebooks/..#environment-snapshots).
{% endhint %}

For a detailed list of libraries included in each feature option, see the [in-product documentation](https://platform.dnanexus.com/app/app-dxjupyterlab).

## Running JupyterLab from the CLI

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

```shell
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:

```shell
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):

* [JupyterLab App](https://platform.dnanexus.com/app/app-dxjupyterlab)
* [JupyterLab Spark Cluster App](https://platform.dnanexus.com/app/app-dxjupyterlab_spark_cluster)

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

```shell
dx run -h APP_NAME
```

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

## Next Steps

See the [Quickstart](https://documentation.dnanexus.com/user/jupyter-notebooks/quickstart) and [References](https://documentation.dnanexus.com/user/jupyter-notebooks/references) pages for more details on how to use JupyterLab.