JupyterLab with deprecated Git integration (Watson Studio)

You can work on files in JupyterLab in a project configured for Git.

Accessing JupyterLab

JupyterLab in IBM Watson Studio includes the extension for accessing a Git repository to work 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 that enables editing notebooks only with the JupyterLab IDE. JupyterLab is the only editing tool available for Python scripts in Watson Studio.

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

This video provides a visual method to learn the concepts and tasks in this documentation.

  1. Create a project with deprecated Git integration. To learn how to create a project, refer to Creating a project with deprecated GIT integration.

  2. From your project's action bar, go to the Launch IDE menu, and click JupyterLab.

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

    The Git extension is preinstalled and the Git tab is added to the left sidebar in JupyterLab. The Git repository is cloned at launch time. To view the repository, go to the Files tab in the left sidebar and click the project_git_repo/<your_git_repo> folder.

    Important: The clone is pulled from the Git repository branch selected at the time the project was created.
  4. To work with your files in the IDE's main work area:

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

    2. Click the project_git_repo folder, and then click <your_git_repo>/assets/jupyterlab. All the work that you do on files in JupyterLab, you do in your clone repository.

      Important: To share the changes to your clone with others working on their clones of the same Git repository, work on the files in the **` /assets/jupyterlab`** folder or any of its subfolders. 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. To start working on notebooks, open the launcher view. From the Editor menu, click File, and then click New launcher. Then complete the required steps.

    4. To start working on Python scripts, open the launcher view. From the Editor menu, click File, and then click New launcher. Then complete the required steps.

      Note: You can work and collaborate only on regular `.py` Python scripts. You can't work and collaborate on IPython scripts (`.ipy` files). `.ipy` files can't be pushed or pulled from the Git repository.
    5. Save your file changes to your local clone before you commit to the Git repository.

    6. Push your file changes to the Git respository:

      1. Click the Git tab from the left sidebar.

      2. Track the changes to your files.

      3. Add a change description, select the Git repository branch, and commit your staged changes.

      4. Click the Push icon 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.

        If a checkpoint file isn't visible in the JupyterLab UI, it is still 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.

    7. After pushing 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

You can share your work with others with the Git version control system that is added through the Git extension in JupyterLab.

To enable users to track and share file changes in your project in JupyterLab:

  1. Add users as collaborators to the project and assign them the 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 stored in project_git_repo/<name_of_your_repo>/assets/jupyterlab. The Git repository associated with the project is cloned to this folder when you open JupyterLab.

    To push your commits to the Git repository and pull changes, you must create, edit, and delete files only in the jupyterlab folder. 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 project_git_repo/<name_of_your_repo>/assets/data_asset. You can open, view, and work with these assets in JupyterLab.

    If you add a regular file to the data_asset 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, you will see all the files from your previous sessions.

  • Debugging

    You can use the JupyterLab terminal to debug files by 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.

Uploading and accessing data

To add data files or connections to a notebook in JuypterLab, click the Upload asset to project icon Upload asset to project icon from the toolbar. The files or connections are uploaded to the assets/data_asset directory and added as assets to your project.

You can add generated code from your JupyterLab notebook to access the data. From the toolbar, click the Code snippets icon Code snippets icon and then click Read data. For more information, 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.

Adding or deleting project data assets

If you use code to create data files outside of JupyterLab, you can import the data files and use them as data assets in your project. Click the Upload asset to project icon Upload asset to project icon on the JupyterLab action bar and upload the data files from the project sidebar.

If you created data files in JupyterLab, you can add them to the project as a data asset by adding them to the project_data_assets folder of your repository clone.

To add the data files as data assets to the project:

  1. On the Assets page of the project, click Import assets.
  2. Click Project files, go to the project_data_assets folder, and select the file you want you add as an asset.

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. On the Assets page of the project, select the data asset you want to delete.
  2. Click Delete from the options list.

Using notebooks outside JupyterLab

The notebooks that you create in JupyterLab, push to the repository, and then sync with the project can only be edited in JupyterLab. When you finish working on a notebook, you can open it in the project outside of JupyterLab from the project's Assets page but only in view mode and as read-only.

When you open a notebook in the project's notebook viewer, you can:

Using Python scripts outside JupyterLab

Python scripts you create in JupyterLab, push to the repository, and then sync with the project are added as scripts to the project's Assets page.

If you are using Python scripts inside JupyterLab, 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 supported:

  • JupyterLab git extension: Allows you to interact with git through a User Interface with which you can perform operations like staging files, committing files, pushing and pulling files, and many more.

  • Jupyter nbdime extensions: Provides a visual tool to compare the latest modifications of a file with the committed versions in git.

  • Python Script editor extension: An editor for developing and running Python scripts.

  • Language Server Protocol (LSP) extension: Enhances the development experience with features such as autocompletion, code navigation, hover suggestions, code linting, and renaming. You can open the diagnostics panel in JupyterLab 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: 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: 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: 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.

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

Limitations

The following limitations exist:

  • You can't export a notebook file to PDF from JupyterLab. But you can select other export file formats from the list.
  • The project data assets that are listed in the data_asset folder are read-only.

Learn more

Parent topic: JupyterLab