.. _cpp_api:

C++ API
=======

This chapter describes the mine C++ wrapper. The class is declared in
the header file ``cppmine.h``, located in the ``minepy/libmine/``
folder. You need to add ``#include "cppmine.h"`` in your C++ source files
and link your program with ``core.c``, ``mine.c`` and ``cppmine.c``.

.. cpp:class:: MINE
   
   .. cpp:function:: MINE::MINE(double alpha=0.6, double c=15)
      
      MINE constructor.

      `alpha` is the exponent in B(n) = n^alpha and must be in (0,1],
      and `c` determines how many more clumps there will be than
      columns in every partition. `c` = 15 meaning that when trying to
      draw Gx grid lines on the x-axis, the algorithm will start with
      at most 15*Gx clumps. `c` must be > 0.

      The constructor throws an exception when the parameters are
      invalid.					

   .. cpp:function:: MINE::~MINE()
 
      MINE destructor.

   .. cpp:function:: void MINE::compute_score(double *x, double *y, int n)

      Computes the maximum normalized mutual information scores the between
      variables `x` and `y` of length `n`.
      
   .. cpp:function:: void MINE::get_mic()

      Returns the Maximal Information Coefficient (MIC).

   .. cpp:function:: void MINE::get_mas()
   
      Returns the Maximum Asymmetry Score (MAS).

   .. cpp:function:: void MINE::get_mev()

      Returns the Maximum Edge Value (MEV).

   .. cpp:function:: void MINE::get_mcn()
    
      Returns the Minimum Cell Number (MCN).


Example
-------

The example is located in ``examples/cpp_example.cpp``.

.. literalinclude:: ../../examples/cpp_example.cpp
   :language: cpp

To compile the example, open a terminal, go into the example
(``examples/``) folder and run:

.. code-block:: sh

   $ g++ -O3 -Wall -Wno-write-strings cpp_example.cpp ../minepy/libmine/cppmine.cpp \
   ../minepy/libmine/core.c ../minepy/libmine/mine.c -I../minepy/libmine/

Run the example by typing:

.. code-block:: sh

   $ ./a.out
   MIC: 0.999999
   MAS: 0.728144
   MEV: 0.999999
   MCN: 4.584963

A more simple example
---------------------

The example is located in ``examples/cpp_example2.cpp``.

.. literalinclude:: ../../examples/cpp_example2.cpp
   :language: cpp

To compile the example, open a terminal, go into the example
(``examples/``) folder and run:

.. code-block:: sh

   $ g++ -O3 -Wall -Wno-write-strings cpp_example2.cpp ../minepy/libmine/cppmine.cpp \
   ../minepy/libmine/core.c ../minepy/libmine/mine.c -I../minepy/libmine/

Run the example by typing:

.. code-block:: sh

   $ ./a.out
   MIC: 0.291692