JupyterLab with default Git integration (Watson Studio)

You can work on files in JupyterLab with true Git-based version control to increase workflow flexibility and enhance collaboration.

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  the push icon 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 File Browser tab in the left sidebar in JupyterLab, you can work with:

  • Notebook files and Python scripts

    Notebook files and Python scripts are stored in the directory called userfs.

    Note that if you add data files directly under userfs, these files will not show up as Data assets in the project and can't be opened and previewed in JupyterLab. Also, if you want to go on and use these files in a Watson Studio tool, for example in Data Refinery, you need to add the files as Data assets to the project, see Adding files as data assets.

  • 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 the file as a Data asset to the project, see Adding project assets. After you have added the file as a Data asset to the project, it can be used in different tools like Data Preview, Data Refinery, or SPSS Modeler in Watson Studio.

  • 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 add data files or connections to a notebook in JuypterLab the same way you do for notebooks in the notebook editor by clicking the Upload asset to project icon (Shows the Upload asset to project icon) from the toolbar. These files or connections 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 clicking the Code snippets icon (the Code snippets icon) from the toolbar and clicking Read data. See Loading and accessing data in a notebook.

Important: When generated code is created to load data from a database connection, 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 project data assets

You should upload data files to use in your notebooks from the upload asset to project sidebar because these files are automatically added as data assets to your project. The data sidebar opens when you click the Upload asset to project icon (Shows the upload asset to project 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 repository clone.

To add these files as data assets to the project:

  1. On the Assets page of the project, click Import assets.
  2. Select Project files and the file in the project_data_assets folder that you want to add to the project as asset.

Deploying notebooks or scripts in a space

You can move assets from a project with default Git integration to a deployment space by creating a Git archive file (a ZIP file containing the contents of your repository from a particular branch or tag) in your Git provider's user interface and importing this ZIP file to an existing deployment space. A Code Package asset will be created containing all the code files you created using Jupyterlab. See Importing spaces and projects into existing deployment spaces.

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. It supports the debugger mode for local Python kernels.

    • 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).

Enabling the 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. Debugger mode in JuypterLab

  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

Parent topic: JupyterLab