JupyterLab (Watson Studio)

JupyterLab enables you to work with documents and activities such as Jupyter notebooks, Python scripts, text editors, and terminals side by side in a tabbed work area. The JupyterLab IDE, included in IBM Watson Studio, provides all the building blocks for developing interactive, exploratory analytics computations with Python.

Accessing JupyterLab

JupyterLab in IBM Watson Studio includes the extension for accessing a Git repository which allows working in repository branches. To use JupyterLab to work on notebooks or Python scripts for example, you must create a project that is integrated with GIT and enables editing notebooks only with the JupyterLab IDE.

Watch the following video see how to enable Git integration to use the Jupyter Lab IDE.

This video provides a visual method as an alternative to following the written steps in this documentation.

1. Create a project that has Git access and enables editing notebooks only with JupyterLab. See Creating a project with GIT integration.
2. Enable project collaboration in JupyterLab. See Collaboration in JupyterLab.
3. Click JupyterLab from the Launch IDE menu on your project’s action bar.

4. Select the environment in which to launch JupyterLab and your personal Git access token.

   The Git extension is pre-installed, enabling access to the repository that you associated with your project at launch time and adding the Git tab to the left sidebar in JupyterLab.

   The Git repository is cloned at launch time and can be viewed on the Files tab in the left sidebar in the folder called project_git_repo/<your_git_repo>.

   Important: The clone is pulled from the Git repository branch selected at the time the project was created.

5. Work with your files in the main work area of the IDE:

   1. Click the File browser tab from the left sidebar.

   2. Select project_git_repo (the cloned Git folder) and navigate to <your_git_repo>/assets/jupyterlab. All the work that you do on files in JupyterLab, you do in your own clone of the repository.

      Important: To enable sharing the changes you make to files in your clone with others working on their clones of the Git repository, you must work on the files in the <your_git_repo>/assets/jupyterlab folder (or any subfolder inside jupyterlab). Only file changes made in this folder can be pushed to the Git repository and changes made by other users pulled to your clone.

   3. Start working on notebooks by:

      • Selecting the notebook tile in the JupyterLab launcher view. The launcher view is shown after JupyterLab is started and can also be opened by clicking File > New launcher from the JupyterLab File menu.
      • Selecting File > New > Notebook.
      • Uploading a notebook file from your local machine.
      • Creating a notebook from file.

   4. Start working on Python scripts by:

      • Selecting Python file in the JupyterLab launcher view. The launcher view is shown after JupyterLab is started and can also be opened by clicking File > New launcher from the JupyterLab File menu.
      • Selecting File > New > Python File.
      • Uploading a Python script from your local machine.
      • Creating a Python script from file.

      Note: You can only work and collaborate on regular .py Python scripts. You can’t work and collaborate on IPython scripts (.ipy files). These files can’t be pushed or pulled from the Git repository.

6. Save your file changes to your local clone before you commit to the Git repository.
7. Push your file changes to the Git respository by using the Git tab from the left sidebar:
   1. Track the changes to your files.
   2. Add a change description and commit your staged changes to the local clone of your repository in your JupyterLab session.

   3. Click from the toolbar on the Git tab to push your changes to the remote repository where your changes can be seen and accessed by other users. Resolve any merge conflicts that might be caused by competing changes to files you are collaborating on.

      Note that even if a checkpoint file isn’t visible in the JupyterLab UI, it is pushed to the Git repository when changes are pushed. However, this file can’t be used to revert to earlier saved changes of files in JupyterLab.

      From the toolbar on the Git tab, you can also pull file changes made by collaborators to your repository clone.

8. After you have finished working on your notebooks or Python scripts and have pushed your changes, sync the changes made to the Git repository with the assets in your project. See Syncing Git changes with your project.

   By syncing the Git notebook changes with the project, you update the common shared project clone to reflect what was last pushed to the Git repository. Remember that the project clone is pulled from the Git repository branch that was selected at the time the project was created.

Collaboration in JupyterLab

With the Git version control sytem added through the Git extension in JupyterLab, users can share their work on files in JupyterLab. To enable sharing when working on files, users must be added to the project as collaborators and must have an access token for the associated project Git repository, which they need to select when they open JupyterLab.

To enable users in a project to track and share file changes in JuypterLab:

1. Add users as collaborators to the project and assign them either Admin or Editor role. You can invite only users who have an existing IBM Cloud Pak for Data account. See Adding collaborators.
2. Give all collaborators the appropriate access permissions to the project Git repository.

3. Instruct all collaborators to create their own personal access token for the associated project repository. See Creating personal access tokens for Git repositories.

   When collaborabors open JupyterLab, they will see their personal Git access token in the list of available tokens.

Working with files

From the Files tab in the left sidebar in JupyterLab, you can work with:

• Notebook files and Python scripts

  Notebook files and Python scripts are located in the folder called /assets/jupyterlab (under project_git_repo/<name_of_your_repo>). The Git repository associated with the project is cloned to this folder when you open JupyterLab. You must create, edit, or delete files in this folder only if you want to publish your commits to the Git repository and pull changes. Only Git changes made to the jupyterlab folder or any subfolder in the repository can be synced with notebook assets in the project.

• Project data assets

  The project data assets are listed in the folder called assets/data_asset (under project_git_repo/<name_of_your_repo>). You can open, view and work with these assets in JuypterLab. Note that if you add a regular file to this folder, the file is not automatically added as a data asset to the project. To add files as project data assets, see Adding project assets.

• Documents in folders

  The files that you created in the local file system of your JupyterLab session are persisted. If you stop JupyterLab, and restart again on another day for example, you will see all your files from previous sessions.

• Debugging

  As of now, the only editing tool available for Python scripts in Watson Studio is JupyterLab. Users can use the terminal for accessing a runtime (for local kernels only) or debugging. It can be useful for checking log files, container’s memory or CPU usage for running processes, and installation of additional Conda packages. Terminal access to Spark kernels are disabled for security reasons.

Support and limitations for Python scripts

See the table of supported configurations for Python scripts.

Environment variables whether customization of environment variables is a feature.

Arguments whether arguments are allowed to be passed for the job.

Command line arguments are for R scripts only, and not yet supported for Python scripts.

Loading and accessing data

You can load and access data in notebooks in JuypterLab the same way you do for Jupyter notebooks in the notebook editor by clicking the Find and Add Data icon () on the JupyterLab action bar. Any files that you upload or connections that configure are added as assets to your project. From your JupyterLab notebook, you can also add automatically generated code to access the data by using the Insert to code function. See Loading and accessing data in a notebook.

Important: When you use the Insert to code function to access a database connection in a notebook in JupyterLab, all clear text credentials are masked. The only exception is if you have an IBM Cloud Object Storage connection and you inserted the access credentials by using the Credentials option at the time you added the connection in your project. The credentials option expects a JSON structure with the credentials obtained from the IBM Cloud Object Storage instance. However, when you use this option, the API key and resource ID are not masked because the JSON structure is analysed before the code is inserted. You can avoid this by entering the access and secret keys directly when adding the connection instead of pasting the JSON structure into the Credentials field.

Adding or deleting project data assets

You should upload data files to use in your notebooks from the find and add data notebook sidebar because these files are automatically added as data assets to your project. The data sidebar opens when you click the Find and Add Data icon () on the JupyterLab action bar.

If you created data files in JupyterLab, and want to add these files to the project as a data asset, you can. Note however, that these files must be located in the project_data_assets folder of your repostoty clone. To add these files as data assets to the project:

1. On the Assets page of the project, click the Find and Add Data icon () and select the Files tab.
2. Select the files you want to add to the project as assets.
3. From the Actions list, select Add as data asset and apply your changes.

If you delete a data asset from the project_data_assets folder in JupyterLab, you must indicate this on the Assets page of your project by:

1. Selecting the data asset on the Files tab in the find and add data sidebar.
2. From the Actions list, selecting Delete and applying your changes.

Using notebooks outside JuypterLab

Notebooks that are created in JupyterLab and are pushed to the repository and then synced with the project can only be edited in JupyterLab. Outside JupyterLab, these notebooks can only be opened from the project’s Assets page in view (read-only) mode.

When you open the notebook in the notebook viewer, you can:

• Share the link to the notebook with other users.
• Download the notebook.
• Create jobs in which to run the notebook. See Scheduling notebook jobs.

Using Python scripts outside JupyterLab

Python scripts that are created in JupyterLab and are pushed to the repository and then synced with the project are added as Scripts to the project Assets page.

You can:

• Create jobs in which to run the scripts. You can do this from the project’s Assets or Jobs page.
• Promote the script to a deployment space. See Deploying a Python script.

Supported extensions

The following JupyterLab extensions are currently supported:

• JupyterLab git extension
• Jupyter nbdime extensions

Limitations

The following limitations exist:

• You can’t export a notebook file to PDF from JupyterLab. You can however select the other export file formats from the list.
• The project data assets that are listed in the folder called assets/data_asset (under project_git_repo/<name_of_your_repo>) are read-only.

Learn more

• Use the provided JuypterLab environment
• Create your own JupyterLab environment
• Create a job to run a notebooks or Python script
• Execute SAS code in Carolina by Dulles Research
• Learn what you can do in JupyterLab: Jupyter Lab: Evolution of the Jupyter Notebook