Get Started with Oracle Machine Learning Notebooks for Data Analysis and Data Visualization

4 Get Started with Oracle Machine Learning Notebooks for Data Analysis and Data Visualization

Oracle Machine Learning Notebooks is an enhanced web-based notebook platform for data analyst 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 user interface, notebooks are available in a project, where you can create, edit, delete, copy, move, and even save notebooks as templates.

About 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.
Access your Oracle Machine Learning Notebooks Page
You can access the OML Notebooks page from the left navigation pane of Oracle Machine Learning Notebooks, or from the Notebooks page.
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.
Export a Notebook
You can export a Notebook in Native format (.dsnb) file, Zeppelin format ( .json ) file, in Jupyter format ( .ipynb ), and later import them in to the same or a different environment.
Import a Notebook
You can import notebooks across Pluggable Databases (PDBs) into your workspace. Oracle Machine Learning UI supports the import of notebooks in the native format (.dsnb), Zeppelin (.json) and Jupyter (.ipynb) notebooks.

4.1 About 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

The Oracle Machine Learning Notebook 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 through drop-down menu.
Layout of Zeppelin and Jupyter notebook.
On-page versioning, viewing of version history, and version comparison.

Parent topic: Get Started with Oracle Machine Learning Notebooks for Data Analysis and Data Visualization

4.2 Access your Oracle Machine Learning Notebooks Page

You can access the OML Notebooks page from the left navigation pane of Oracle Machine Learning Notebooks, or from the Notebooks page.

To access the Notebooks page:
- Go to the Oracle Machine Learning left navigation pane, expand Projects and then click Notebooks.
  
  Figure 4-2 Left navigation pane
- Alternatively, you can click Notebooks under Quick Link on the home page to open the Notebooks page.
This opens the OML Notebooks page.
- Figure 4-3 OML Notebooks page
  Here, you have the option to:
- 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.
- 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.
- 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 as .json files, click Import. Select the project and workspace in which to import 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:
  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.

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

Parent topic: Get Started with Oracle Machine Learning Notebooks for Data Analysis and Data Visualization

4.2.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.
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.
On the Versions - Notebook Versioning Demo page, select Version 1 of the notebook version that you just created to enable all the available options.
- 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: Access your Oracle Machine Learning Notebooks Page

4.3 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 interpreter binding to either low, medium, or high
- 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: Get Started with Oracle Machine Learning Notebooks for Data Analysis and Data Visualization

4.3.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.
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.
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 panel 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 panel:
- 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.
- 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.
- 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.3.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.

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.
Click Save. Once the dependent paragraphs are defined and saved, it is indicated by the numbers as shown in the screenshot here:
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.4 Export a Notebook

You can export a Notebook in Native format (.dsnb) file, Zeppelin format ( .json ) file, in Jupyter format ( .ipynb ), and later import them in to the same or a different environment.

To export a Notebook:

On the Notebooks page, select the notebooks that you want to export. You have the option to export one or more or all the notebooks.
On the top panel of the notebook editor, click Export and then click any one of the following options:
- Notebooks to Export — To export notebooks, click:
  - All — To export all the notebooks listed on the Notebooks page.
  - Selected — To export the selected notebooks.
- Format — Click the format in which you want to export your notebook:
  - Native— Exports the notebook as a .dsnb (Data Studio Notebook) file.
  - Jupyter — Exports the notebook as a .ipynb file.
  - Zeppelin — Exports the notebook as a .json (JavaScript Object Notation) file.
The exported notebooks are saved either as .dsnb files, .json files or .ipynb files in a zipped folder.

Related Topics

About Interpreter Bindings and Notebooks

Parent topic: Get Started with Oracle Machine Learning Notebooks for Data Analysis and Data Visualization

4.5 Import a Notebook

You can import notebooks across Pluggable Databases (PDBs) into your workspace. Oracle Machine Learning UI supports the import of notebooks in the native format (.dsnb), Zeppelin (.json) and Jupyter (.ipynb) notebooks.

Oracle Machine Learning UI supports the import of both Zeppelin (.json) and Jupyter (.ipynb) notebooks.

Note:

Starting in Oracle Database 20c,"database" refers specifically to the data files of a multitenant container database (CDB), pluggable database (PDB), or application container.

To import a notebook:

On Oracle Machine Learning UI home page, click Notebooks.
On the Notebooks page, click Import.
This opens the File Upload dialog. Browse and select the notebook that you want to import.

Note:
You must have the notebook saved as a .json file or .dsnb file to import it. You can import notebooks exported from non-Oracle Apache Zeppelin environments, but only paragraphs types that are supported may be run.
In the File Upload dialog, browse and select the notebook and click Open.
This imports the notebook file into your workspace.
Click the imported notebook to open it. On the Notebooks page, click the gear icon to view the interpreter bindings.