.. _c_api:

C API
=====

This chapter describes the mine C library. These functions and
structures are declared in the header file ``mine.h``, located in the
``minepy/libmine/`` folder. You need to add ``#include "mine.h"`` in your
C source files and link your program with ``core.c`` and ``mine.c``.

.. c:type:: mine_problem
   
   The :c:type:`mine_problem` structure describes the problem.

   .. code-block:: c

      typedef struct mine_problem {
         int n;
  	 double *x;
  	 double *y;
      } mine_problem;
      
   where  of `x` and `y` are the two variables of length `n`.
      
.. c:type:: mine_parameter

   The :c:type:`mine_parameter` structure describes the MINE parameters.

   .. code-block:: c
      
      typedef struct mine_parameter {
         double alpha;
         double c;
      } mine_parameter;
 
   where `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.

.. c:type:: mine_score
   
   The :c:type:`mine_score` structure describes the maximum normalized 
   mutual information scores.

   .. code-block:: c
   
      typedef struct mine_score {
         int m;
  	 int *p;
  	 double **I;
      } mine_score;

   where `I[i][j]` contains the score using a grid partitioning x-values
   into i+2 bins and y-values into j+2 bins. `p` and `I` are of length 
   `m` and each I[i] is of length `p[i]`.

.. c:function:: mine_score *mine_compute_score(mine_problem *prob, mine_parameter *param)
   
   This function computes the maximum normalized mutual information scores and returns a
   :c:type:`mine_score` structure.

.. c:function:: char *check_parameter(mine_parameter *param)
   
   This function checks the parameters. It should be called before calling 
   :c:func:`mine_compute_score`. It returns NULL if the parameters are
   feasible, otherwise an error message is returned.

.. c:function:: double mic(mine_score *score)

   Returns the Maximal Information Coefficient (MIC).

.. c:function:: double mas(mine_score *score)

   Returns the Maximum Asymmetry Score (MAS).

.. c:function:: double mev(mine_score *score)

   Returns the Maximum Edge Value (MEV).

.. c:function:: double mcn(mine_score *score)

   Returns the Minimum Cell Number (MCN).

.. c:function:: void mine_free_score(mine_score **score)

   This function frees the memory used by a :c:type:`mine_score`
   and destroys the score structure.

Example
-------

The example is located in ``examples/c_example.c``.

.. literalinclude:: ../../examples/c_example.c
   :language: c

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

.. code-block:: sh

   $ gcc c_example.c ../minepy/libmine/core.c \
   ../minepy/libmine/mine.c -I../minepy/libmine/ -lm

or 

.. code-block:: sh

   $ gcc c_example.c -O3 ../minepy/libmine/core.c \
   ../minepy/libmine/mine.c -I../minepy/libmine/ -lm

for an extensive optimization. Run the example by typing:

.. code-block:: sh

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