===============
Getting started
===============


Overview
========

This getting started guide walks you through opening and using Anaconda Fusion 
for the first time. 

**When you complete this guide, you will be able to:**

* Open a demo data file and run a clustering algorithm in Excel.
* Execute a plot of the clustering results in the Anaconda Fusion pane, and
* Create a Jupyter Notebook to export functions to Excel.

If you have not yet installed Anaconda Fusion, follow the :doc:`Install 
instructions <install>`.


Starting Anaconda Fusion
========================

- Run Anaconda Fusion from the start menu. You will see a terminal window 
  showing the server log.
- Download the `demo spreadsheet <https://drive.google.com/file/d/0B55gVlhhvKkNcFJ0dWJIa2JQLU0/view?usp=sharing>`_ 
  to your Downloads folder. 
- Open the demo spreadsheet in Excel 2016.
- In Excel, click Insert > Add-ins > My Add-ins > Shared Folder > Anaconda 
  Fusion > OK.
- A new right pane appears. Click Codesheets to see the list of example 
  notebooks. Click on the one named ``clustering.ipynb``. 

TIP: If you don't see the list of example notebooks in the pane, you might have 
a different Jupyter kernel running on port http://localhost:8888. Stop that 
kernel and then restart Anaconda Fusion by closing the terminal and clicking the 
Anaconda Fusion icon again.


Execute a clustering algorithm in Excel
=======================================

To see how to execute code from other developers directly from Excel, you will run 
a clustering demonstration. When you complete this section, you will have 
executed Python code to run a machine learning algorithm on your data and visualize 
its output.

**Select some data in the spreadsheet to make it visible to Anaconda Fusion** 

Under the table ``NOISY_CIRCLES`` in your demo spreadsheet, find the
columns ``x`` and ``y``. Highlight to select at least 100 rows of those two columns. 
In the Anaconda Fusion pane, click on Data > Current Selection.

.. figure:: /img/fusion_add_data.png

A small form pops up. In the ``name`` field type the name for the dataset you 
selected, ``noisy_circles_small``. Click ``Confirm`` to save and click the
"clustering.ipynb" tab at the bottom of the pane.

.. figure:: /img/fusion_confirm_add_data.png

**Run the clustering algorithm** 

In the Anaconda Fusion pane, from the drop-down menu  
select ``clustering``. You will see three additional drop-down input menus for  
selecting the parameters of the algorithm. Set them as follows:

- **Select Data** Select your dataset ``noisy_small_circles``.
- **Select Algorithm** Select ``MiniBatchKMeans``.
- **n_clusters** Leave the selection as ``---``.

.. figure:: /img/fusion_clustering_params.png

Now click the ``Run`` button to produce a plot of the clustering results in the 
Anaconda Fusion pane.

.. figure:: /img/fusion_clustering_plot.png

You just executed Python code from within Excel to run a machine 
learning algorithm on your data and visualize its output!


Creating a notebook to export functions to Excel
================================================

If you already use Python for data analysis and want to make your code
available for your coworkers using Excel, this section is for you. It
demonstrates writing Python code that others can open and use within Excel.
This script will calculate and display the sum of the even numbers 
in the Excel list.

* **Open Anaconda Fusion.** If the Anaconda Fusion server is not running, open 
  it from the Start menu. Anaconda Fusion will show a black window with white 
  text displaying the Fusion server log.

* **Open Jupyter Notebook in your browser.** Open your browser and enter the 
  address of the Jupyter kernel that was installed with Anaconda Fusion. By 
  default, the address is ``https://localhost:8888``.

TIP: If you did not use the default address, you may find the address by opening 
the Anaconda Fusion window and using the ``localhost:...`` string you find there 
as the address. You should see a screen like the following:

.. figure:: /img/fusion_jupyter_opening.png

* **Open a new Python 3 notebook.** In your Jupyter Notebooks browser window, 
  in the top tab named Files, click on the folder named ``notebooks``, click 
  the ``New`` button, and select ``Python [default]`` to create a new Jupyter 
  Notebook with a Python 3 kernel. 

* **Create the Python script.** In the new notebook's single cell, copy and 
  paste or type this code:

.. code-block:: python

    from anacondafusion.fusion import fusion

    @fusion.register()
    def add_evens(data):
        total = 0
        for item in *data:
            if item % 2 == 0:
                total = total + item
        return total

TIP: This function ``add_evens`` is exposed to Excel with the 
``@fusion.register`` decorator.

Your notebook should now look like this:

.. figure:: /img/fusion_jupyter_function.png

* **Save the new notebook.** To save the Jupyter notebook, click 
  on File > Save and Checkpoint. 

NOTE: At the top left next to the Jupyter symbol is the notebook name 
followed by "Last Checkpoint: ...". By default the notebook name is "Untitled".
Now that you've saved it, the Last Checkpoint function can be used. 

The Jupyter Notebooks interface in your browser is the best way to create, edit, 
and delete the notebooks used with Anaconda Fusion.

* **Open a new blank Excel worksheet and Anaconda Fusion.** Open Excel, then 
  open the Anaconda Fusion pane by clicking Insert > Add-Ins > My Add-Ins > 
  Shared Folder > Anaconda Fusion. Click Codesheets and select the new 
  notebook you just saved named ``Untitled.ipynb``. Note the drop-down menu with 
  the ``add_evens`` function from the Jupyter notebook. Make sure ``add_evens`` 
  is selected in this drop-down.

* **Enter your data in the worksheet.** On the blank Excel worksheet, in the 
  cells ``B2:E2`` enter 1, 2, 3, and 4. Highlight to select cells ``B2:E2``. In 
  Anaconda Fusion we will name this dataset ``mydata``.

* **Define** ``mydata``. In the Anaconda Fusion pane, click Data and Current 
  Selection, enter "mydata" in the "Name" field, and click Confirm to define 
  ``mydata`` as the dataset you selected in Excel. This creates an object 
  accessible to Jupyter that points to your Excel dataset.

* **Calculate result.** In Excel, click on cell ``C4``. This cell will contain 
  the result.

* **Run script.** We can now call the ``add_evens`` function on ``mydata``. In 
  Anaconda Fusion's Inputs drop-down menu, select ``mydata``. Click ``Run``. In 
  Excel, in the blank cell ``C4`` that you selected, you should see the sum 
  ``6``.


More practice
=============

At this point you may want to go back to your browser and look at the first 
example to see how we wrote the ``clustering.ipynb`` notebook.


Other options
=============

In the Output section Anaconda Fusion displays a link "Options". This shows the 
"Select Default Output" drop-down menu which sets the default way for Fusion to 
output data to Excel: "Selection", "Cell/Range", or "Named Range".

The Output section also shows the link "Export" which can export the most recent 
result from Fusion to Excel. The "Select Export Destination" drop-down menu also 
offers a choice of "Selection", "Cell/Range", or "Named Range".
