JupyterLab with default Git integration (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 working with the local clone of a Git repository.

1. Create a project that supports default Git if you haven't already created one. See Creating a project with default GIT integration.
2. Optional: Add collaborators to the project if you want to work on the same file with others. See Collaboration.
3. Click JupyterLab from the Launch IDE menu on your project's action bar.

4. Select the environment in which to launch JupyterLab.

   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.

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

   1. Click the File browser tab from the left sidebar to work with files and directories on your system. You add files or create subdirectories in the userfs directory. Note that Python functions are currently not supported in the projects with default Git integration.

   2. 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.

   3. 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.

6. Save your file changes. Don't save the file under userfs/assets as the assets directory is reserved for files related to project assets.

   As all files and assets in the project reflect the current state of your Git clone, you can test your code before committing and pushing your changes by creating a job from your project's Jobs page and running it.

   1. From the project's Jobs page, select New job.
   2. Select your file, enter the job settings, and run it.
   3. Validate the run results by clicking the job run.

7. When your files are ready, push your changes to the Git respository:

   • By using the Git tab from the left sidebar in JuypterLab:

     1. Track the changes to your files.
     2. Add a change description, select the Git repository branch and commit your staged changes.

     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.

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

   • By selecting the Git icon from the project's action bar:

     1. Click Commit from the menu.
     2. Add a description, select the Git repository branch you chose for the project, select the files and commit the changes.
     3. Click Push from the Git menu to push your commits to the repository.

   Note that the notebook and script files in the Git repository that are pushed are not added as assets to the project's Assets page. You can however select those files to run as jobs from the project's Jobs page. Note that although there is no restriction on the file types you can work with, you can only select .py scripts and .ipynb files as entry points when you create a job.

Working with files

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

• Notebook files and Python scripts stored in the userfs directory

• Project data assets

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

• Files in subdirectories under userfs

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

Loading and accessing data

You can load and access data from files or connections 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. These files are listed in the directory called assets/data_asset and added as assets to your project. From your JupyterLab notebook, you can also add 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, no access credentials are exposed. This means that when you commit and push your changes to the Git repository, your credentials will not be visible to Git collaborators.

Merging conflicts

If you are collaborating on the same file, the easiest way to resolve a conflicted file is to open the file in JupyterLab and make any necessary changes.

To resolve a merge conflict directly in JupyterLab:

1. Pull all the current changes from the remote repository to your clone. Doing so will ensure that your local clone is in sync with the remote repository.
2. If someone else pushed changes to a file that you worked on, you will see a message telling you that your changes can't be auto-merged because you weren't working on the latest version of the file. Git is unable to automatically determine which code changes to keep and which to discard.
3. Open the changed (auto-merged) file in the Launcher view where you can compare your local changes with those in the remote repository.
4. After editing the file, stage the newly merged content.
5. Create a new commit and then push your changes to the remote repository.

Adding files as data assets

You should upload data files to use in your notebooks as data assets 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 or downloaded data files in JupyterLab, and want to add these files to the project as a data asset, you can. However, these files must be located in the assets/data_asset directory of your repository 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. Find the files and select them.
3. Navigate to the top entry that indicates the number of selected files, click the Actions icon () on the right, and select Add as data asset. Apply your changes.

Deploying notebooks or scripts in a space

You can use CPDCTL to create a code package (ZIP archive file) that contains your notebooks and scripts, promote it to a deployment space where it is registered as a code package asset and then create a job that runs the files in the code package asset. See Code packages.

Supported extensions

The following JupyterLab extensions are currently supported:

• JupyterLab git extension
• Jupyter nbdime extensions

• These Elyra extensions are available:

  • Elyra code snippet extension which enables you to reuse any snippets of code in your notebooks and scripts
  • Elyra Python editor extension which is an editor for developing and running Python scripts
  • Language Server Protocol (LSP) extension which enhances the development experience with features such as autocompletion, code navigation, hover suggestions, code linting, and renaming. You can open the diagnostics panel in JuypterLab while working on your code to see and jump between the diagnostics provided by the Language Server Protocol.
  • Notebook navigation using an auto-generated table of contents which enhances navigation capabilities in large notebooks. To access the table of contents, select the Table of Contents tab from the sidebar in the opened notebook.
  • Resource usage extension which helps you monitor your resource usage by showing you how much memory you are using while you are coding, and what your memory limit is. Resource usage is displayed at the bottom of the window. Monitoring resource usage is especially useful in situations where you are not sure how much compute power will be consumed, for example when training models.

  • Simple view which allows you to concentrate on just one notebook. To switch to simple view, enable the Table of Contents tab in the sidebar in an opened notebook by setting Simple to on. The content switcher is displayed in the lower left of the window.

    Note that the Language Server Protocol (LSP) and the resource usage extensions are enabled for local kernels only (kernels without Spark and Hadoop).

Debugger mode

When you create and open a notebook in JupyterLab, the debugger mode is enabled by default and can be activated directly in the notebook. The debugger mode is not supported in Spark kernels.

The Elyra Python editor extension supports the debugger mode for local Python kernels. To activate the debugger mode in the Elyra Python editor extension:

1. In the Python editor, right click on the canvas and select Create Console for Editor.

   The debugger mode is activated in the console window.

2. To run code from the Python editor in the console, select the code in the editor with the mouse, or click CMD+A (on Mac OS) or Ctrl+A (on Windows).

3. From the Jupyter menu, click Run > Run All Code.

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 directory called assets/data_asset are read-only.

Learn more

• Projects with default Git integration
• Use the provided JuypterLab environment
• Create your own JupyterLab environment
• Create jobs for code files
• Execute SAS code in Carolina by Dulles Research
• Learn what you can do in JupyterLab: Jupyter Lab: Evolution of the Jupyter Notebook

Parent topic: Analyzing data and building models