Projects

Projects enable you to organize assets, such as notebooks and data sets, to achieve your data analysis goal.

Projects can contain the following assets:
  • Notebooks
  • RStudio files
  • Models
  • Data sets
  • Scripts
Tip: IBM® Watson™ Studio provides a sample project named dsx-samples, which is available to all users. The project includes sample notebooks to help get you started. Within the dsx-samples project, you can create new notebooks, models, scripts, and data sets. However, you cannot add jobs or collaborators.

You can complete the following tasks:

Create a project

The type of project that you create determines how collaboration privileges are manged, where the master repository exists, and how local copies of the repository are created:

Project type Collaboration privileges Master repository Repository copy
Standard Managed in IBM Watson Studio Master repository exists in the IBM Watson Studio cluster file system Each collaborator gets a copy
GitHub Managed outside of IBM Watson Studio Master repository exists in GitHub Each user gets a copy when the project is imported from GitHub
Bitbucket Managed outside of IBM Watson Studio Master repository exists in Bitbucket Each user gets a copy when the project is imported from Bitbucket
Library Managed in IBM Watson Studio No master repository No repository copy

To create a project:

  1. From the IBM Watson Studio Home page, click Add Project
  2. Select the type of project that you want to create:
    Project type Notes
    New Use this option to create a standard project without any assets or data sources.
    From file Use this option to import a preexisting project from your local device. You can import a ZIP file or TAR.GZ file.
    Restriction: Data source credentials are not imported. For any data sources with credentials, you will need to open the imported project and specify the credentials for the data source again.
    From Git repository Use this option to import a local copy of a GitHub, GitHub Enterprise, Bitbucket, or Bitbucket Server repository.

    To set up the connection to the repository, you must have a GitHub personal access token associated with your account. For more information, see Enable your account to access the Git repository.
  3. Name the project.
    Restriction: A project name cannot contain spaces. If your project connects to a Git repository, then use the Git repository guidelines for project names and notebook names.
  4. Click Create. Your new project opens and you can start adding collaborators and assets to it.

Manage collaborators

If you have admin permissions for a project, you can add collaborators, modify collaborator permissions, or remove collaborators on the Collaborators page.

Collaborators can have the following permissions:
Viewer
Can view the project, accept changes, and commit changes to their own local copy of the project.
Editor
Can control project assets. Can accept, commit, and push changes.
Admin
Can control project assets, collaborators, and settings. Can accept, commit, and push changes.
If you want to remove yourself from a project, click Leave.
Important: If you are the only collaborator with admin permissions, you must give another collaborator admin permissions before you can leave the project.

Manage assets

Assets include files such as notebooks, data sets, models, and RStudio files.

You can add assets to a project from the Assets page.

By default, any changes you make to a project are only in your local copy of the project. However, your changes aren't saved unless you commit your changes to the local copy.

Action Details
Commit Save your changes to the local copy of the project. For example, you might need to commit changes to the project if you edit a notebook or add a new data set to the project.
Push After you save your changes to your local copy, push your changes to the master repository.

Only project admins and editors can make changes to the master repository.
Pull Get the latest version of the project from the master repository. If you have locally committed changes, you must resolve the merge conflicts that occur with the files from the master repository.
Reset If you decide that you don't want to keep your local changes, you can reset the project to overwrite your local copy with the latest version of the project from the master repository.

You can access the Reset option from actions menu on the Projects home page.

Project admins can also delete an asset by clicking Delete next to the asset.

Add data sources

A data source enables you to access remote data, such as a database table or data stream. After you create a data source, you can add remote data sets from the data source to the project as assets.

A data source enables you to securely store information about your database and credentials.

Restriction: Unless you share the data source credentials with other collaborators, collaborators must supply their own credentials to work with data sets from the data source. For example, if a collaborator selects a remote data set from the data source that you created and clicks Insert to code, the collaborator needs to edit the generated code to use their own credentials. If they do not edit the code, they cannot connect to the remote data set.

Project admins and editors can create data source connections from the Data Sources page.

Publish an asset

A project editor or admin can share a read-only copy of the following types of project assets:
  • Static content, such as HTML files
  • Jupyter notebook content
  • Local data sets
  • R Shiny web apps

You can share the assets with other users or with external users who do not have access to the application.

To share an asset, go to the Assets page and select the type of asset that you wan to publish. Then, click Publish next to the asset that you want to share. The publish action creates a read-only snapshot of the current version of the asset, copies the asset to a published content directory in the user-home file system, and automatically generates a URL where the asset can be viewed.

When you publish an asset, you can specify who can view the published asset:
  • Anyone with the link - This means that even users who don't have access to the application can see the asset as long as they have the URL.
  • Any authenticated user - This means that only users who are logged in to the application can see the asset.
  • Restricted to collaborators in the selected project - This means that only users who are collaborators on the specified project can view it.
    This option has the following restrictions:
    • You must have admin access to the project where you want to publish the asset.
    • You can publish an asset to only a standard project or library project. You cannot publish an asset to a Git project.
    Security recommendation: If you need to publish assets that contain sensitive content, you can create or select a target project to publish the assets to. For example, your department can create a special private project for collecting sensitive assets, models, and reports from other projects. This enables you to add only specific users as collaborators.

    Anyone with admin access to the project can add other collaborators to the project and publish content to the project. If you need to control exactly who can see the project or publish content to the project, add collaborators as editors or viewers.

If you publish a Jupyter notebook, the published copy is automatically converted to HTML. You can publish the notebook with the following options:
  • You can rerun the entire notebook, which might take a while, or you can publish the notebeook as-is.
  • You can include code cells in the published copy, or you can hide the code cells so that only the output is displayed.

If you publish an R Shiny app, the URL displays the app as an interactive interface where users can dynamically input their own variables to explore trends.

When you publish an asset, the application generates a permalink to the published asset that you can copy (except for models, which already have a URL for online scoring). Depending on the permissions you specified when you published the asset, users can access the asset from one or more of the following locations:
Location Notes
The URL If the asset is available to anyone with the URL, they can automatically access the asset by open the URL in their web browser. Otherwise, the user must authenticate before they can access the asset.
The Published Assets page If the signed in user has access to the asset, it is displayed in the Published Assets page, which is available from the menu.

This list includes assets that are published for all users and that are published to a specific project to which the authenticated user has access.
The Published Assets page for a specific project If the asset is published to a specific project that the authenticated user has access to, it is displayed in the Published Assets page for the project.

Remove a published asset

If you previously published an asset, you can go to the Published Assets page and click Unpublish next to it.

Restriction: If the asset is published to a specific project, any project admin can remove the published asset from the project. However, if the asset is published for anyone with the URL or any authenticated user, only the person who originally published the asset can remove it.

Export a project

You can download a project as a ZIP file or a TAR.GZ file by clicking Export as next it.

Restriction: Some information is not included when you import or export a project:
  • When you export a project, the environments in the project are not exported.
  • When you import a project, data source credentials are not imported. You must reenter the credentials to connect to the data source.

Rename a project

If you are a project admin, you can rename a standard project or library project by clicking Rename next to it. (You cannot rename projects that are managed in an external GitHub repository.)

Recommendation: Before you rename a project, complete the following tasks:
  • Review all of the assets in the project to ensure that they use the DSX_PROJECT_DIR environment variable rather than relative paths or absolute paths that include hard-coded project names.
  • Let your collaborators know that you plan to rename the project so that they can terminate any of their own runtime environments before the project is renamed.
When you rename a project:
  • The project is renamed for all of the collaborators, and
  • Your active environments for the project are automatically stopped

If you access a notebook or RStudio file after you rename a project, the environments are automatically restarted in the updated project. Alternatively, you can manually restart the environments from the project's Environments page.

The existing runtime environments for other project collaborators are not stopped. Each collaborator must manually stop the environments that are associated with the old project name. (Collaborators can access a complete list of environments from All Active Environments page, which is accessible from the application menu.)

After a collaborator stops the environments that are associated with the old project, opening a notebook or RStudio file in the updated project automatically restarts the environment in the updated project. Alternatively, the collaborator can manually restart the environments from the project's Environments page.

Delete a project

If you are a project admin, you can delete a project by clicking Delete next to the project name.

Recommendation: Before you delete a project, complete the following tasks:
  • Let your application administrator know that you plan to delete the project so that they can handle any issues that might arise.
  • Let project collaborators know that you plan to delete the project and ask them to:
    • Stop any active environments so that they release system resources. If the environments are not stopped before the project is deleted, an application administrator must delete the pods that correspond to the environments.
    • Save their work
    • Export a copy of the project if they need it for reference.
The content that is deleted depends on the type of project that you are deleting:
Library projects
When you delete a library project, the project is deleted for all users and all assets (and the storage directories) that are associated with the project are deleted.
GitHub projects
When you delete a GitHub project, only the copy of the project in IBM Watson Studio is deleted. The project still exists on the remote GitHub repository.
Standard projects
When you delete a standard project, the project is deleted for all of the collaborators and all assets (and the storage directories) that are associated with the project are deleted.
Tip: Did you delete something you didn't mean to? An application administrator can recover deleted projects from the recycle bin (/user-home/.recycleBin).

Preview project contents

To preview the contents of a project without opening the project, open the application menu and click Projects > View all Projects. Click the Tree View icon (Screen capture of the tree view icon) to open the preview pane and expand the project that you are interested in.

Select a folder to see the contents of the folder or select a Jupyter notebook or CSV file to preview it.