.. _cpp_api:

C++ API
=======

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

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

      alpha is the exponent in :math:`B(n) = n^\alpha` and must be in 
      :math:`(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 x grid lines on the x-axis, the algorithm will start with at 
      most :math:`15 x` 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`. It rhrows an exception if an error
      occurs.
      
   .. cpp:function:: void MINE::mic()

      Returns the Maximal Information Coefficient (MIC).

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

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

      Returns the Maximum Edge Value (MEV).

   .. cpp:function:: void MINE::mcn(double eps)
    
      Returns the Minimum Cell Number (MCN) with :math:`\epsilon \geq 0`.

   .. cpp:function:: void MINE::mcn_general()
    
      Returns the Minimum Cell Number (MCN) with :math:`\epsilon=1 - \mathrm{MIC}`.
   


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 ../libmine/cppmine.cpp \
   ../libmine/mine.c -I../libmine/

Run the example by typing:

.. code-block:: sh

   $ ./a.out
   MIC: 0.999999
   MAS: 0.728144
   MEV: 0.999999
   MCN (eps=0): 4.58496
   MCN (eps=1-MIC): 4.58496

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 ../libmine/cppmine.cpp \
   ../libmine/mine.c -I../libmine/

Run the example by typing:

.. code-block:: sh

   $ ./a.out
   MIC: 0.291692

