JupyterLab with default Git integration (Watson Studio)

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. To learn how to create a project, refer to Creating a project with default 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.

   The Git extension is preinstalled and the Git tab is added to the left sidebar in JupyterLab. You have access to the repository that you associated with your project at launch time.

4. To work with your files in the IDE's main work area:

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

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

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

5. Save your file changes. Don't save the file under userfs/assets because the assets directory is reserved for files that are related to project assets.

   All files and assets in the project reflect the current state of your Git clone.

   You can test your code before you commit and push your changes. See Creating jobs in the Notebook editor.

6. When your files are ready, push your changes to the Git repository:

   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 from the toolbar on the Git tab to push your changes to the remote repository where other users can see and access your changes. 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 that are made by collaborators to your repository clone.

   The notebook and script files you push to the Git repository are not added as assets to the project's Assets page. But you can select those files to run as jobs from the project's Jobs page. There is no restriction on the file types that you can work with, but you can select only .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 userfs directory.

  If you add data files directly under userfs, the files are not automatically added as data assets in the project. To 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. To learn more, see Adding files as data assets.

• Project data assets

  The project data assets are listed in the assets/data_asset directory under userfs. You can open, view, and work with the data assets in JuypterLab.

  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. After you add the file as a data asset to the project, you can use the file in different tools like Data Preview, Data Refinery, or SPSS Modeler in Watson Studio.

• Files in subdirectories under userfs

  You can access the files that you create in the local file system of your JupyterLab session under userfs in future sessions. If you stop JupyterLab and restart it on another day, you can see all your files from the previous sessions.

Uploading and accessing data

To add data files or connections to a notebook in JuypterLab, click the 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 and then click Read data. For more information, see Loading and accessing data in a notebook.

Merging conflicts

If you are collaborating with others on the same file and need to resolve a merge conflict, open the file in JupyterLab and make the necessary changes.

To resolve a merge conflict directly in JupyterLab:

1. Pull all the current changes from the remote repository to your clone. Pulling the changes updates your local clone so it's in sync with the remote repository.
   Note: If someone else pushed changes to a file that you worked on, 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.
2. Open the changed (auto-merged) file in the launcher view to compare your local changes with the changes in the remote repository.
3. Edit the file and add your changes.
4. Stage the newly merged content.
5. Create a new commit and push your changes to the remote repository.

Adding files as 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 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.

Deploying notebooks or scripts in a space

You can move assets from a project with default Git integration to a deployment space. To make a Git archive file, create a compressed file that contains the contents of your repository from a particular branch or tag. Then import the compressed file to an existing deployment space. A Code Package asset will be created containing all the code files that you created in Jupyterlab. For more information, see Importing spaces and projects into existing deployment spaces.

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

• 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 JuypterLab while you are 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 how much memory that 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 your project will use, 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 the other export file formats from the list.
• The project data assets that are listed in the data_asset directory 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
• Learn what you can do in JupyterLab: Jupyter Lab: Evolution of the Jupyter Notebook

Parent topic: JupyterLab