==================
Running a function
==================

Viewing function documentation
==============================

The data scientist who creates a function may provide documentation to help
business analysts understand that function, including: how it works, how to
specify input parameters and how to configure options.

NOTE: Automatic User Interface UI generation is a powerful feature of
Fusion. It allows Excel users to view high-level functions that have been
created in notebooks.

This feature represents a huge step torward lowering the barriers against Excel
users who want to use advanced functions, written in languages like Python, that
otherwise would have only been accessible to those comfortable writing code.

To see the documentation available for a function:

#. In the function list at the top of the Fusion pane, select the function.

#. Click the Information icon to the right of the function name.

.. figure:: /img/fusion_view_documentation.png
    :width: 50%

|

Any available documentation for the selected function is displayed.

Running a function
==================

To run a function:

#. In the functions list at the top of the Fusion pane, select the function.
#. :ref:`Configure the run options <fusion_conf_run_opts>`.
#. :ref:`Select the inputs <fusion_select_inputs>`.
#. :ref:`Configure the output <fusion_conf_outputs>`.
#. In the Fusion pane, click the Run button.

When the function finishes running, the output is loaded into the Excel
spreadsheet, or into the Fusion pane output area.

.. _fusion_conf_run_opts:

Configuring run options
-----------------------

There are two run configuration options in the main Fusion screen:

* Excel sync

  * When sync is on, Fusion automatically adds changes made in Excel into the Fusion input data and writes the Fusion output data into Excel.
  * When sync is off, Fusion does not automatically add data from Excel or write data to Excel. Clicking the Run button runs the Fusion code on data that was previously added from Excel.

* Auto run

  * When auto run is on, users do not need to click the Run button every time they change input data and want to re-run the Fusion code. Fusion re-runs the Fusion code whenever:

    * You select a different input from the Fusion list.
    * Excel Sync is enabled and you change the input data in Excel.

  * When auto run is off, Fusion will only re-run changed Fusion code when the user clicks the Run button.

NOTE: Data accessed from Excel using the Range and Cell option will be kept in
sync but data accessed using the Selection option will not.:

.. figure:: /img/fusion_run_options.png
    :width: 15%

|

.. _fusion_select_inputs:

Selecting inputs
----------------

After selecting a function, you will see all of the inputs necessary to execute
the function:

.. A screen showing the example inputs from the clustering notebook would be helpful here, i.e. the Fusion pane from fusion_clustering_params.png, as it shows the inputs and sample selections discussed in the EXAMPLE below.

.. figure:: /img/fusion_view_documentation.png
    :width: 50%

|

The input and the data you can select for each vary depending on how the
function was defined by the data scientist who created it. For some inputs,
you must select from a predefined list of options, while in others you can
enter data directly in the field or select a named dataset that you created
previously. For more information on using Excel data in an input, see
:doc:`access-data`.

EXAMPLE: In the sample ``clustering`` notebook, which is installed with Fusion,
the clustering function includes the following inputs:

* The ``data`` input displays a list of the data defined in the Excel spreadsheet.

* The ``algorithm`` input displays a list of possible algorithm names that can be used.

* The ``n_clusters`` input displays a list of numbers that can be used to define the number of clusters to find.

After all the input parameters have been filled, execute the function by
clicking on the Run button. After it finishes running, the output is loaded
into the Excel spreadsheet, or into the Fusion output area--if it is a plot,
image or has been configured to do so.

.. _fusion_conf_outputs:

Configuring outputs
-------------------

There are three output options for Fusion:

.. screenshots need to be updated.

* Selection--Use the currently selected cell(s) as the output.

* Range or Cell--Define an Excel range, or cell, to use as the output.

  NOTE: This may be a Named Range--a pre-defined Excel variable.

* Python--Use a Python expression as the output.

You can customize the execution output mechanism back to Excel, as well as
export the output to a defined Excel location:

* Options--Define the default output option when a user clicks the Run button.

* Export--Define the selection for the one time export mechanism. Click Export to export the data:

.. figure:: /img/fusion_export.png
    :width: 50%

|
