Jupyter Notebook Application
============================

The Jupyter Notebook Application allows the creation and editing of
documents that display the input and output of a Python or R language script.
Once saved, these files may easily be shared with others.

NOTE: Python and R language are included by default, and with customization the 
notebooks can run many other kernel/languages.

Anaconda Enterprise Notebooks 4.1 uses Jupyter notebook 4.2.3,
plus some extensions to make them even more useful. This includes one-click 
integration with Anaconda Cloud, easy management of conda environments 
and packages from a conda tab within the notebook, easy notebook presentations and more.

**Official Jupyter Notebook user instructions** are located in the `Jupyter documentation
<http://jupyter.readthedocs.org/en/latest/>`_. 

This page includes a brief introduction to Jupyter Notebooks for AEN users, and information 
on using the notebook extensions included in AEN.

|image1|

To open the Jupyter Notebook application, from your user home page, select the project you want to manage. On the project's home page, click the Jupyter Notebooks icon.

This brings you to the Jupyter Notebooks Files tab:

|image0|

TIP: You can see and manage the same file list in the Terminal, Workbench, and Viewer apps. 

* **Test a sample notebook**. The examples folder contains several types of notebook examples in Python and one in R language. Open any example notebook to play with it and see how it works. 

* **Create a new notebook**. From the Files tab, create a new notebook by clicking the top right New button, then select the kernel you want to use. When you create the project, customizable Python and R Language kernel environments are automatically created for you. 

Which kernel should I select for my new notebook? 

|image14|

* Your project's default "conda env" kernels are a cloned copy of the root environment. You can customize them, install and delete additional packages. 
* Root is managed by your Administrator. You cannot make any changes to it.
* You will be able to switch between Python, R language and any other custom kernels in the notebook as you work in your notebook. See "Synchronize Environments" below.

NOTE: By default, your new Jupyter Notebook is saved in the related project directory.


Notebook Extensions
~~~~~~~~~~~~~~~~~~~

Extensions included in Anaconda Enterprise Jupyter Notebooks include: 

* **Synchronize Environments** with Jupyter from top Kernel menu
* **Locking** multi-user capability from top menu Lock button
* **Revision Control Mechanism (RCM)** adds top menu buttons Status, Checkout and Commit 
* **Conda** environment and package management tab
* **Conda notebook** conda management inside notebook from Kernel - Conda Packages menu
* **Anaconda Cloud** integration from top menu Publish to cloud button
* **Notebook Present** Turns your notebook into a PowerPoint-style presentation. 

These extensions are all detailed below.

Synchronize environments
^^^^^^^^^^^^^^^^^^^^^^^^

You can change Python, R language and any other custom language environments inside a unique notebook session, without the need to start up several instances using each of your selected environments. To change environments, from the top menu bar, select Kernel, then Change kernel, and select Python [default] or R [default]. 

|image6|

NOTE: In Anaconda Enterprise Notebooks 4.1, the default kernel for projects is ``default``. In versions prior to 4.0, the default kernel for projects was root Python. 


Locking
^^^^^^^

The multi-user capability in the Anaconda Enterprise Notebooks Enterprise experience is engaged when multiple users work in the same notebook file. The notebook is "locked" on opening. If other users later open and try to save the notebook with their own changes, their save capability will be disabled, and they can not overwrite the locked notebook. To override this, they must actively take the lock by clicking the "lock" icon in the notebook toolbar:

|image7|

NOTE: This is a "soft locking model" so a team member can choose to override a lock to save their work. If you have given team members write access to your files, they should unlock your file only to perform only meaningful (non-destructive) team contributions.

.. _revision-control-mechanism:

Revision Control Mechanism (RCM)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The RCM Notebook Extension is simple version control for Jupyter notebook files. It is a notebook extension that uses the internal Jupyter machinery to perform its tasks.

On the surface it is a simple "linear" model, but under the hood is a more complex git-based branched model. It is a model with "the latest wins" as its main "merging" strategy, so by design there are no merge conflicts.

The RCM Notebook Extension adds four buttons:

|image8|

* **Status button**: See what revision you are on.
* **Checkout button**: View a list of the previous revision points, check out a previous revision or compare differences between revisions.
* **Commit button**: Commit the current changes.
* **Configure git**: Allow user to configure Git user name and email values.


-  STATUS: After clicking the Status button, the following window appears:

   |image9|

-  CHECKOUT: After clicking the Checkout button, the following window appears:

   |image10|

   -  **Checkout a previous revision point**. Check the checkbox of the 
      desired revision point and press the "OK" button. This will open 
      a copy of the notebook at the selected revision point. If you have 
      not saved your current window, checking out a previous revision 
      will destroy it. If in doubt, click Cancel, save your work, then 
      revert to a previous revision point. 
   -  **Make a diff comparison**. Compare two previous revision points
      by checking the checkboxes and clicking the "View Diff" button.
   -  **Cancel** to close the current modal window.


-  COMMIT: Save or persist the changes. This keeps a permanent record of
   the changes introduced so you don't have to worry about losing data
   or information. You can "roll back" at any time by checking out a
   previous version you have committed. After clicking the Commit button,
   the following window appears:

|image11|

Enter a description of this commit to remind you if you need to revert
back to it later. Click the OK button when finished.
If Git user name and user email are not set, the following window appears:

|image21|

Configure Git and then try to commit again.

-  CONFIGURE GIT: Save or persist Git configuration. After clicking the
   Configure Git button, the following window appears:

Enter user name and e-mail address. Click the OK button when finished.

|image22|

.. _aen-conda-integration:

Conda integration
~~~~~~~~~~~~~~~~~

The NBConda extension adds a Conda tab to the notebook for easy
environment and package management from within the notebook:

|image12|


Click the Conda tab in a notebook to display:

-  **Conda environments list**. Also export, clone or delete an environment  
   in the action column, or create a new environment by clicking the "+" icon. 
   Switch to an environment by clicking it; packages for that 
   environment are displayed below in the installed packages list.
-  **Conda available packages list** for the selected environment 
   in currently configured channels, search for packages and click a package 
   name to install it.
-  **Installed packages list** in the selected environment, check for updates, update 
   or delete selected packages.

TIP: While you are in any notebook, you can jump to this same conda extension for 
the current environment by selecting Kernel -> Conda Packages: 

|image13|

Conda in Notebook view
^^^^^^^^^^^^^^^^^^^^^^^

This extension adds a Conda Packages item to the Kernel menu. Selecting
this item displays the list of Conda packages in the environment
associated with the running kernel, and the list of available packages.
You can perform the same actions as in the Conda tab, but only against
the current environment.

Anaconda Cloud integration
~~~~~~~~~~~~~~~~~~~~~~~~~~

You can now easily upload your notebook to Anaconda Cloud with a simple
button at the notebook UI:

|image13|

Notebook Present
~~~~~~~~~~~~~~~~

Turns your notebook into a PowerPoint-style presentation. 

1. Notebook Present
===================

Turns your notebook into a PowerPoint-style presentation. Two new 
buttons are visible in your top menu bar: Edit Presentation, and Show 
Presentation: 

.. image:: /img/nb-ext-present1.png

To begin using Notebook Present, click the Edit Presentation button. 
A black bar with several menu items appears on the right side of your 
browser. As you click each icon, the menu and layout of your screen 
changes. 

.. image:: /img/nb-ext-present2.png

Click the Help icon to view three quick tours of the main features of 
Notebook Present. The tours are: Intro Tour, Slides Tour, and Editor 
Tour.


**Intro tour** 

Click Help - Intro to see a 2-minute presentation on how to use all 
of the main features. Every button is explained, and you can pause, 
go back to the previous slide, or the next slide. Here is a summary 
of the presentation.

App Bar: When Authoring, you control the content and style of your 
presentation. It also activates several special editing keyboard 
shortcuts:

.. image:: /img/nb-ext-shortcuts.png

Stop Authoring: Clicking the Edit Presentation button again stops 
Authoring, and removes all keyboard shortcuts.

Show Presentation: If you just want to run your presentation without 
using any Authoring tools, just click the Show Presentation button.

Presenting/Authoring: Once you've made some slides, start Presenting, 
where you can use most Notebook functions with the Theme we have defined, 
as well as customize slides on the fly.

Slides button: Slides, made of Regions linked to Cell Parts are the bread 
and butter of any presentation, and can be imported, created, linked, 
reordered, and edited here.

.. image:: /img/nb-ext-slides1.png

Theming: Theming lets you select from existing colors, typography, and 
backgrounds to make distinctive presentations. The first theme you 
select will become the default, while you can choose custom themes for 
a particular slide, like a title.

.. image:: /img/nb-ext-themes.png

Saving: Whenever you save your Notebook, all your presentation data will 
be stored right in the Notebook .ipynb file.

Downloading: After you've made a presentation, you can download it as an 
HTML page by choosing Download → Download As: Presentation (.html) in the 
menu.

Help: Activate Help at any time to try other tours, connect with the 
Present developers and community, and other information. 

**Using slides**

From the Help menu, clicking Slides brings up the following 2-minute 
presentation on how to create and manage slides:

.. image:: /img/nb-ext-slides2.png

Slides make up a presentation. Clicking Slides toggles the sorter 
view and the Slide Toolbar.

Slide Toolbar: Let's create a new slide. Clicking the + Slide will 
offer some choices for creating your new slide.

Import: The quickest way to a presentation is to just import every 
complete cell as a slide. If you've already created slides with the 
official slideshow cell toolbar or RISE, you can import most of the 
content. 

Template Library: You can also pick from some existing templates...

Reuse Slide as Template: Or copy an existing slide.

Simple Template: A common template is the Quad Chart, with four pieces 
of content arranged in a grid.

Region: The Quad Chart has four Regions. Select a region by clicking 
it.

Linking a Region to a Cell Part: Each Region can be linked to a single 
Cell Part

Link Overlay: The Link Overlay shows all of the parts available

Cell Part: Source (blue): Source, such as code and Markdown text

Cell Part: Outputs (red): Outputs, such as rich figures and script 
results

Cell Part: Widgets (purple): Jupyter widgets, interactive widgets 
that provide both visualization and user input.

Cell Part: Whole (orange): Finally, a Whole Cell (including its 
Source, Widgets, and Outputs) can be linked to a single region

Part Thumbnail: We'll try to draw a part thumbnail. It can only 
be reliably updated when a linked Cell Part is on-screen when you 
mouse over it, but you should usually be able to get an idea of what 
you're seeing. The colors of the regions correspond to the cell types.

Cell Part: Unlinking: Unlinking removes the connection between a 
region and a cell part, without deleting either one.

Region: Trashing: Trashing a Region permanently deletes it, without 
affecting any linked Cell Part

Presenting: Clicking the Present button while editing brings up the 
Presenter with editing mode still enabled:

It's still a Notebook: Linked inputs and widgets are still interactive. 

Go forward: Click to go to the next slide

Go back: Click to go back to the previous slide

Go back to the beginning: Click here to go back to the first slide

My work is done here: Click to go back to the Notebook.

**Using the editor**

When you click Help - Editor, you see the following 2-minute presentation 
on editing your notebook:

So You Made Some Slides: Once you've made a few slides, you'll likely need 
to customize them

Editing Slides: Once you have selected a slide, you can activate the Slide 
Editor by double-clicking the slide, or clicking Edit Slide.

Region Editor: This is the Region editor. You can click and drag Regions 
around and resize them.

Region Tree: This is the Region tree. It lets you reorder Regions and see 
the details of how your Regions will show their linked Parts.

Add Region: You can add new regions

Attribute Editor: All of the properties of a region can be edited here

Data Layouts: In addition to manually moving regions around, you can use 
other Layouts, like this Treemap, which will fill the slide:

More Regions: More regions will be added with a weight of 1

Tree Weight: This new value lets you make a Region bigger or smaller 
based on relative Weight

12 Grid: The Grid is a compromise between Free layout and Treemap layout, 
and rounds all the values to a factor of 12.



.. |image0| image:: /img/aen-user-jupyter_main41.png
.. |image1| image:: /img/aen-user-finding-jupyter.png
.. |image2| image:: /img/aen-user-sample_notebook.png
.. |image3| image:: /img/aen-user-dashboard.png
.. |image4| image:: /img/aen-user-terminal_notebook.png
.. |image5| image:: /img/aen-user-workbench_notebook.png
.. |image6| image:: /img/aen-user-extensions_kernels41.png
.. |image7| image:: /img/aen-user-extensions_locker.png
.. |image8| image:: /img/aen-user-extensions_rcm.png
.. |image9| image:: /img/aen-user-extensions_rcm_status.png
.. |image10| image:: /img/aen-user-extensions_rcm_checkout.png
.. |image11| image:: /img/aen-user-extensions_rcm_commit.png
.. |image12| image:: /img/aen-user-extensions_conda.png
.. |image13| image:: /img/aen-user-extensions_anacondacloud.png
.. |image14| image:: /img/aen-user-kernel-menu41.png
.. |image15| image:: /img/nb-ext-present1.png
.. |image16| image:: /img/nb-ext-present2.png
.. |image17| image:: /img/nb-ext-shortcuts.png
.. |image18| image:: /img/nb-ext-slides1.png
.. |image19| image:: /img/nb-ext-themes.png
.. |image20| image:: /img/nb-ext-slides2.png
.. |image21| image:: /img/aen-user-extensions_rcm_commit_error.png
.. |image22| image:: /img/aen-user-extensions_rcm_git_config.png
