.. _analyst:

*************************************************
Running Built-in Algorithms Using the Analyst API
*************************************************

The Analyst API provides convenience ways to apply built-in graph analyses. Especially, the API provides a single wrapper method for the analyses that is composed of multiple sub-steps.

Obtaining an Analyst instance
-----------------------------

In order to obtain an ``Analyst`` instance, simply invoke :meth:`create_analyst()` on
your :ref:`Session <session>` object:

.. code-block:: python
    :linenos:

    analyst = session.create_analyst()

Running Algorithms and Browsing Results
---------------------------------------

The Analyst API provides methods for each built-in graph analysis. If the graph analysis requires certain preprocessing steps, all of those preprocessing steps are encapsulated in the Analyst API method.

For instance, the Analyst API provides the following method to count the numbers of triangles in a graph:

.. code-block:: python
    :linenos:

    analyst.count_triangles(graph, sort_vertices_by_degree=True)

The above method is actually composed of the following sub-steps.

  1. Create an undirected copy of the given graph (the count triangles algorithm is only defined on undirected graphs)

  2. Optionally sort the vertices of the undirected copy by degree. This is a speed versus memory consumption trade-off which can be controlled by passing the `sort_vertices_by_degree` parameter

  1. Invoke the built-in count triangles algorithm on the graph copy
  
  2. Return the result
  
  3. Drop the undirected copy of the graph

For detailed information, refer to the :class:`Analyst` class in the API section.

Optional arguments
------------------

The Analyst class has overloaded convenience methods which use default values for optional parameters.
For example,

.. code-block:: python
    :linenos:

    analyst.pagerank(
        graph,
        tol=0.001,
        damping=0.85,
        max_iter=100,
        norm=False,
        rank="pagerank"
    )

will use a max error of ``0.001``, a damping factor of ``0.85`` and a maximum of ``100`` iterations.
For detailed information, refer to the :class:`Analyst` class in the API section.

Reuse existing data structures
------------------------------

By default, the Analyst creates a new in-memory data structure to hold the result of an algorithm invocation.
That data structure gets disposed once the Analyst object gets disposed. However, you can also pass in existing
mutable data structures the algorithm writes its result into. Examples:

.. code-block:: python
    :linenos:

    rank = analyst.pagerank(graph)
    analyst.pagerank(graph, rank=rank)

Disposing an Analyst Instance
-----------------------------

Once the graph analysis is finished, the user can invoke the :meth:`destroy()` method to
deallocate all of the resources used by the Analyst. If there are multiple Analyst
objects, a :meth:`destroy()` invocation of one Analyst instance does not affect the other
instances.