Oracle Machine Learning Notebooks

4.1 Oracle Machine Learning Notebooks

Oracle Machine Learning Notebooks is an enhanced web-based notebook platform for data engineers, data analyst, R and Python users, and data scientists. You can write code, text, create visualizations, and perform data analytics including machine learning. Notebooks work with interpreters in the back-end.

In Oracle Machine Learning, notebooks are available in a project within a workspace, where you can create, edit, delete, copy, move, and even save notebooks as templates. A notebook can contain many paragraphs. A paragraph is a notebook component where you can write and run SQL statements, PL/SQL scripts, R and Python code, and conda instructions. You can run paragraphs individually or, run all the paragraphs in a notebook using a single button. A paragraph has an input section and an output section. In the input section, specify the interpreter to run along with the code or text. This information is sent to the interpreter to be run. In the output section, the results of the interpreter are provided.

Note:

There is a single namespace for both the original notebooks and the new notebooks. You cannot have a notebook with the same name in both notebook lists. A notebook copied from the original interface to the new will have _new appended to it.

Figure 4-1 OML Notebook

Description of "Figure 4-1 OML Notebook"

The Oracle Machine Learning Notebooks provides:

Faster notebook loading time.
The Oracle look and feel as it based on the Oracle Redwood theme.
Enriched visualization in its Line chart, Area chart, Bar chart, Pyramid chart, Pie chart, Donut chart, Funnel chart, Tag Cloud, Treemap Diagram, Sunburst Diagram, Scatter Plot, Box Plot.
Option to enter comments in notebook paragraphs.
Option to create Paragraph Dependencies. The Paragraph Dependencies feature allows you to add dependencies between paragraphs. The dependents of a paragraph automatically run after the original paragraph is run.
Simplified service level selection of High, Medium, Low, and GPU through drop-down menu.
Layout of Zeppelin and Jupyter notebook.
On-page versioning, viewing of version history, and version comparison.

Access your Oracle Machine Learning Notebooks
You can access the OML Notebooks page from the Oracle Machine Learning UI home page and the left navigation pane. You can access the GitHub Notebooks page from the Oracle Machine Learning UI home page and from the user profile drop-down menu.
Edit your Oracle Machine Learning Notebook
Upon creating a notebook, it opens automatically, presenting you with a single paragraph using the default %sql interpreter. You can change the interpreter by explicitly specifying one of %script, %python, %sql , %r , %md, or %conda.
Manage Oracle Machine Learning Notebooks
The Notebooks page lists all the notebooks—both Oracle Machine Learning notebooks and GitHub notebooks.

Parent topic: OML Notebooks

4.1.1 Access your Oracle Machine Learning Notebooks

You can access the OML Notebooks page from the Oracle Machine Learning UI home page and the left navigation pane. You can access the GitHub Notebooks page from the Oracle Machine Learning UI home page and from the user profile drop-down menu.

Accessing the Oracle Machine Learning Notebooks page

To access the OML Notebooks page:

Go to the Oracle Machine Learning left navigation pane, expand Projects and then click Notebooks. Alternatively, you can click Notebooks under Quick Link on the home page to open the Notebooks page.

Figure 4-2 Notebooks option on OML UI left navigation menu and OML UI home page

Description of "Figure 4-2 Notebooks option on OML UI left navigation menu and OML UI home page"

Parent topic: Oracle Machine Learning Notebooks

4.1.2 Edit your Oracle Machine Learning Notebook

Upon creating a notebook, it opens automatically, presenting you with a single paragraph using the default %sql interpreter. You can change the interpreter by explicitly specifying one of %script, %python, %sql , %r , %md, or %conda.

Set the context with a project with which your notebook is associated. You can edit an existing notebook in your project. To edit an existing notebook:

On the Oracle Machine Learning home page, select the project in which your notebook is available.

Note:
A project is a logical grouping of notebooks and experiments within a workspace. While you may own many projects, other workspaces and projects may be shared with you.
Click the notebook that you want to open and edit.
The selected notebook opens in edit mode.
In the edit mode, you can use the following Oracle Machine Learning Notebook toolbar options:

Notebook level edit options:
- Click to run all paragraphs in the notebook
- Click to invalidate and reset the notebook session.
- Clickto create a new version this notebook, or to view the earlier versions of the notebook.
  - Create Version: Click this option to create a new version of this notebook. You have the option to provide a new name for the version, and a description about it. When you create a new notebook version, the paragraph results of each run session are stored in the versioned notebook. When you restore a notebook, the paragraph results of each run session are also restored. You can also create notebook versions from the editor. For more information, see Work with Notebook Versions in the Notebook Editor
  - View Version History: Click this option to view the earlier versions of the notebook. You have the option to restore any earlier version, compare versions, and delete any earlier version that you created.
  Note:
  You can also create notebook versions, view version history, and delete older versions from the option on the Notebooks page.
- Click to clear paragraph results.
- Click to clear paragraph dependencies.
- Click to export the notebook. You can export the notebook as a .dsnb file, .zpln file (Zeppelin notebook) and .ipynb file (Jupyter notebook). You have these settings while exporting a notebook:
  - Export All
  - Exclude code
  - Exclude results
  - Exclude Timestamp
- Click to print the notebook
- Click to hide the code of all paragraphs in the notebook
- Click to hide the results of all the paragraph in the notebook
- Click to enable read-only mode for this notebook.
  
  Note:
  The read-only mode is available only for the Oracle Machine Learning Notebook.
- Click to show the edit panel. The edit options in the panel are the same edit options available for the paragraph. Clicking the panel icon opens the edit pane on the right, and the edit tool bar in the paragraph is hidden.
- Click to change the notebook service level to either low, medium, high, or GPU.
- Click to switch the OML notebook to either Zeppelin or Jupyter notebook
Paragraph level edit options:
- Click to run the selected paragraph
- Click to enter into Dependency Mode. In Dependency Mode, you must select and deselect paragraphs in order to add or remove them as dependents.
  
  Note:
  The Paragraph Dependencies feature allows you to add dependencies between paragraphs. The dependents of a paragraph automatically run after the original paragraph is run.
- Click to open the Comments dialog. Type in your comments here, and press Enter to add the comment. You can also delete any comments by clicking the corresponding Delete icon. Click the comments icon to close the dialog. You can provide comments for each paragraph in a notebook. Paragraphs with comments are indicated by a green dot on the comments icon.
- Click to view the notebook paragraph in full screen mode. To view the paragraph in the normal mode, click the collapse icon.
- Click to show line numbers in the notebook paragraph.
- Click to view the paragraph title, code, results, and the paragraph settings.
- Click to :
  - Move up: Click to move the paragraph up in the notebook.
  - Move down: Click to move the paragraph down in the notebook.
  - Clear results: Click to clear the results of the commands that you ran in the paragraph.
  - Open as Embedded Window: Click to view the current paragraph separately in your browser.
  - Clone Paragraph: Click to clone the paragraph. The paragraph is cloned in the same notebook.
  - Disable Run: Click to disable running of the paragraph. To enable run, go to Settings and click Enable Run.
  - Delete Paragraph: Click to delete the paragraph.
- Click to view the paragraph in HTML format
- Click to view the paragraph in text format
- Click to adjust settings of the notebook paragraph output. This setting is specifically applicable to visualizations in graphs, charts etc.
- Click to download the paragraph as a text file, or as .png or .svg files, as applicable, for paragraphs that contains graphs or charts as output.

Work with Notebook Versions in the Notebook Editor
By creating versions of your notebook, you can archive your work in a notebook.
Create Paragraph Dependencies
Paragraph Dependencies allow you to add dependencies between paragraphs. The dependent paragraphs automatically run after the original paragraph is run, according to the order of dependency.

Parent topic: Oracle Machine Learning Notebooks

4.1.2.1 Work with Notebook Versions in the Notebook Editor

By creating versions of your notebook, you can archive your work in a notebook.

You can create versions of notebooks in the Notebooks editor, as well as on the Notebooks page. In this example:

The original notebook Notebook Versioning Demo, is edited to add a script to build a machine learning model.
The Notebook Versioning Demo notebook is then versioned as Version 2 to archive the code to build the machine learning model.
The Version 2 and Version 1 of the Notebook Versioning Demo notebook are compared using the Compare Versions feature.

Note:

A versioned notebook is non-editable. If you want to make any changes to a particular version of a notebook, you must restore that version to edit it.

To create a new notebook version and view version history:

On the Notebooks EA page, click on the Notebook Versioning Demo notebook to open it in the notebook editor.

Note:
Version 1 of this notebook is already created as part of the example in Work with Notebook Versions on the Notebooks Page. It contains the archived code to create the view ESM_SH_DATA, count the record, and view the data. Clicking on the notebook opens the original version which is editable.
Now, edit the notebook to add a script to build a machine learning model. On the notebook, hover your cursor over the lower border of the third paragraph, and click the + icon to add a new paragraph.

Copy and paste the following script to the new paragraph. This script builds a machine learning model using the ESM algorithm.

%script

BEGIN DBMS_DATA_MINING.DROP_MODEL('ESM_SALES_FORECAST_1');
EXCEPTION WHEN OTHERS THEN NULL; END;
/
DECLARE
    v_setlst DBMS_DATA_MINING.SETTING_LIST;
BEGIN
    
    v_setlst('ALGO_NAME')            := 'ALGO_EXPONENTIAL_SMOOTHING';
    v_setlst('EXSM_INTERVAL')        := 'EXSM_INTERVAL_QTR'; -- accumulation int'l = quarter
    v_setlst('EXSM_PREDICTION_STEP') := '4';                 -- prediction step = 4 quarters
    v_setlst('EXSM_MODEL')           := 'EXSM_WINTERS';      -- ESM model = Holt-Winters
    v_setlst('EXSM_SEASONALITY')     := '4';                 -- seasonal cycle = 4 quarters    

    DBMS_DATA_MINING.CREATE_MODEL2(
        MODEL_NAME          => 'ESM_SALES_FORECAST_1',
        MINING_FUNCTION     => 'TIME_SERIES',
        DATA_QUERY          => 'select * from ESM_SH_DATA',
        SET_LIST            => v_setlst,
        CASE_ID_COLUMN_NAME => 'TIME_ID',
        TARGET_COLUMN_NAME  =>'AMOUNT_SOLD');
END;

Now, archive this notebook along with the code to build the machine learning model by versioning it. On the top left corner of the notebook editor, click Versioning
The options to Create Version and View Version History opens.

Description of the illustration create-view-nb-versions.eps
Click Create Version. The New Version dialog opens.
In the New Version dialog:
1. Name: Here, the name Version 2 is taken by default. Let's retain this name.
2. Comments: Enter comments, if any.
3. Click Create. A message is displayed confirming the creation of the new version.
Description of the illustration new-version-dialog.eps

Version 2 of this notebook now contains the archived code to create the machine learning model.
To view the version that you just created, click Versioning , and then click View Version History.
On the right pane of the notebook editor, the Version History pane opens. Hover your cursor over any notebook version and click on it to enable the available options.
You can perform the following tasks in the Version History pane:

Description of the illustration view-version-history.eps
- Click to open the selected version.
  
  Note:
  Clicking on any versioned notebook opens the notebook in read-only mode, as versioned notebooks are non-editable. To view the current editable version, click View current version of the notebook.
  
  Description of the illustration view-current-version-option.eps
- Click Delete to delete the selected version.
- Click Compare Versions to compare the selected and current version of the notebook. You can select other available versions from the drop-down list. In this example, Version 2 of the notebook (under Current State) is compared with Version 1. New additions are highlighted in green, as shown in the screenshot here, and deletions are highlighted in red.
  
  Description of the illustration compare-versions.eps
- Click Restore to restore the selected version.
  
  Note:
  Restoring a selected version of the notebook will discard all the unversioned changes, if any.

Parent topic: Edit your Oracle Machine Learning Notebook

4.1.2.2 Create Paragraph Dependencies

Paragraph Dependencies allow you to add dependencies between paragraphs. The dependent paragraphs automatically run after the original paragraph is run, according to the order of dependency.

To create paragraph dependencies:

On the Notebooks page, click Create Notebooks.
In the Create Notebooks dialog, enter the name Paragraph Dependencies Demo in the Name field and click OK.
The notebook is created and it opens in the notebook editor.
On the notebook, hover your cursor over the lower border of the paragraph and click the + icon to add a paragraph. Add two more paragraphs to this notebook, and paste the following PL/SQL script in the paragraphs:
1. In the first paragraph, copy and paste the following PL/SQL script. This script creates the view ESM_SH_DATA from the SALES table present in the SH schema.
```
%script

CREATE OR REPLACE VIEW ESM_SH_DATA AS 
  SELECT TIME_ID, AMOUNT_SOLD FROM SH.SALES;
```
2. In the second paragraph, copy and paste the following SQL script. This script gives a count of the record present in the view ESM_SH_DATA.
```
%script
SELECT COUNT(*) FROM ESM_SH_DATA;
```
3. In the third paragraph, copy and paste the following SQL script to review the data in a tabular format.
```
%sql
SELECT * FROM ESM_SH_DATA
FETCH FIRST 10 ROWS ONLY;
```
Go to the first paragraph and click on the Enter Dependency Mode icon.

Description of the illustration enter-dp-mode.eps

The message appears: You are selecting dependents for this paragraph
Click on the second and third paragraph to add them as dependents of paragraph one.

Note:
The order of paragraph dependency is based on the order of your click.

Description of the illustration select-dep-para.eps
Click Save. Once the dependent paragraphs are defined and saved, it is indicated by the numbers as shown in the screenshot here:

Description of the illustration nb-dp-definition.eps
Now, go to the first paragraph and click Run. After the first paragraph starts successfully, the subsequent dependent paragraphs start to run according to the order of dependency.

Parent topic: Edit your Oracle Machine Learning Notebook

4.1.3 Manage Oracle Machine Learning Notebooks

The Notebooks page lists all the notebooks—both Oracle Machine Learning notebooks and GitHub notebooks.

This is the Oracle Machine Learning Notebooks page. Selecting a notebook enables all the options on this page.

Note:

The Version and Edit options are not enabled for GitHub notebooks. For GitHub notebooks, open and edit the notebook in the editor, and use the

(Version Control) option to commit the changes to the GitHub repository.

Figure 4-3 Notebooks page

Description of "Figure 4-3 Notebooks page"

Note:

Some notebooks have the icon

against it. It indicates that the notebook is imported from a GitHub repository.

You can perform the following tasks:

Create: Click Create to create a new notebook.
Edit: Click on a notebook row to select it and click Edit. You can edit the notebook name, and add comments in the Edit Notebook dialog box.

Note:
The Edit option here is not enabled for GitHub notebooks. To edit a GitHub notebook, update repository path or credentials, see Manage GitHub Notebooks.
Delete: Click on a notebook row to select it and click Delete.
Duplicate: Click on a notebook row to select it , and click Duplicate. This creates a copy of a notebook, and the duplicate copy of the is listed on the Notebooks page with the suffix _1 in the notebook name.
Move: To move notebooks from one project to another project in the same or different workspace.
Copy: To copy notebooks to another project in the same or different workspace. When you copy notebooks, the a copy of the notebook remains in the original project.
Save as Template: To save a notebook as a template, select the notebook and click Save as Template. In the Save as Template dialog, you can define the location of the template to save it in Personal or Shared under Templates.
Import: To import a notebook, click Import. one of the following options:
- File: To import a notebook as a .json file
- Git: To import a notebook from a remote GitHub repository. This clones the notebook.
Export: To export a notebook, click Export. You can export Notebooks in the .dsnb format, Zeppelin format (.json ) file and in Jupyter format ( .ipynb), and later import them in to the same or a different environment.
Version: To create versions of a notebook, select it and click Version. The Versions page for that particular notebook opens. Here, you can create a new version of the notebook by clicking +Version. The Create Version dialog opens. Enter a name of the notebook version, a description, and click OK. The new version of the notebook gets created by the same name with a suffix _2 for the second version. For subsequent versions, suffix (number) increments by one. To revert to an older version by clicking Revert Version. You also have the option to delete any version of the notebook. Click Back to Notebooks to go to the OML Notebooks page.

Note:
The Version option here is not enabled for GitHub notebooks. For versioning, see Edit and Sync your GitHub Notebook.

Note:
You can also version a notebook by opening it, and then clicking on the option. By using this option, you can create new versions, view version history, restore older versions, and delete any older versions of the notebook that you have opened.

For each notebook listed on this page, the following information is displayed:

Name: This is the name of the notebook.
Comment: This is the comment you entered when creating the notebook.
Created on: This is the date on which the notebook was first created.
Created by: This is the name of the user who created the notebook.
Last Update: This is the date on which the notebook was last updated.
Last Updated By: This is the name of the user who last updated the notebook.

Work with Notebook Versions on the Notebooks Page
By creating versions of your notebook, you can archive your work in a notebook.

Parent topic: Oracle Machine Learning Notebooks

4.1.3.1 Work with Notebook Versions on the Notebooks Page

By creating versions of your notebook, you can archive your work in a notebook.

You can create versions of notebooks on the Notebooks page, as well as in the Notebook editor. In this example, the Notebook Versioning Demo notebook is created and versioned as Version 1.

Note:

A versioned notebook is non-editable. If you want to make any changes to a particular version of a notebook, you must restore that version to edit it.

Prerequisites: The Notebook Versioning Demo notebook. This notebook is created as part of the example here.

To create a new notebook version and view version history:

On the Notebooks page, click Create Notebooks.
In the Create Notebooks dialog, enter the name Notebook Versioning Demo in the Name field and click OK. The notebook is created and it opens in the notebook editor.
On the notebook, hover your cursor over the lower border of the paragraph and click the + icon to add a paragraph. Add two more paragraphs to this notebook, and paste the following PL/SQL script in the paragraphs:
1. In the first paragraph, copy and paste the following PL/SQL script. This script creates the view ESM_SH_DATA from the SALES table present in the SH schema.
```
%script

CREATE OR REPLACE VIEW ESM_SH_DATA AS 
  SELECT TIME_ID, AMOUNT_SOLD FROM SH.SALES;
```
2. In the second paragraph, copy and paste the following SQL script. This script gives a count of the record present in the view ESM_SH_DATA.
```
%script
SELECT count(*) from ESM_SH_DATA;
```
3. In the third paragraph, copy and paste the following SQL script to review the data in a tabular format.
```
SELECT * FROM ESM_SH_DATA
FETCH FIRST 10 ROWS ONLY;
```
Run all the paragraphs, and go back to the Notebooks page after all the paragraphs run successfully.
On the Notebooks page, select the Notebook Versioning Demo notebook to enable all the edit options, and click Versions to go to the versions page for this notebook.
The Versions - Notebook Versioning Demo page opens.
On the Versions - Notebook Versioning Demo page, click Version to create a new version of the notebook. This opens the Create Version dialog.

Figure 4-4 Versions page

Description of "Figure 4-4 Versions page"
In the Create Versions dialog:
1. Name: Enter Version 1 for the new version of this notebook
2. Comments: Enter comments, if any.
3. Click OK. Once the notebook version is created, it is listed on the Versions - Notebook Versioning Demo page.
Description of the illustration versions-page2.eps
On the Versions - Notebook Versioning Demo page, select Version 1 of the notebook version that you just created to enable all the available options.

Description of the illustration select-verison1-nb.eps
- Click Delete to delete the selected version of the notebook.
- Click Restore to restore the selected version of the notebook.
  
  Note:
  Restoring a selected version of the notebook will discard all the unversioned changes, if any.
- Click Back to Notebooks to go back to the Notebooks page.

Parent topic: Manage Oracle Machine Learning Notebooks