.. _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
``libmine/`` folder. You need to add ``#include "mine.h"`` in your
C source files and link your program with ``mine.c``.

.. c:var:: char *libmine_version
   
   The libmine version in the form X.Y.Z (e.g., 1.0.1).

.. 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 :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.

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

   .. code-block:: c
   
      typedef struct mine_score {
          int n; /* number of rows of M */
          int *m; /* number of cols of M[i] for each i */
	  double **M; /* the approx. characteristic matrix */
      } mine_score;
      
   where M[i][j] contains the score using a grid partitioning x-values
   into i+2 bins and y-values into j+2 bins.
   m and M are of length n and each M[i] is of length m[i].

.. c:function:: mine_score *mine_compute_score(mine_problem *prob, mine_parameter *param)
   
   Computes the maximum normalized mutual information scores and returns
   a :c:type:`mine_score` structure. Returns NULL if an error occurs.

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

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

   Returns the Maximal Information Coefficient (MIC).

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

   Returns the Maximum Asymmetry Score (MAS).

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

   Returns the Maximum Edge Value (MEV).

.. c:function:: double mine_mcn(mine_score *score, double eps)

   Returns the Minimum Cell Number (MCN) with :math:`\epsilon \geq 0`.

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

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

.. 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 -Wall ../libmine/mine.c -I../libmine/ -lm

or 

.. code-block:: sh

   $ gcc c_example.c -O3 -Wall ../libmine/mine.c -I../libmine/ -lm

for an extensive optimization. Run the example by typing:

.. code-block:: sh

   $ ./a.out
   libmine version 100
   
   MINE statistics:

   MIC: 1.000
   MAS: 0.667
   MEV: 1.000
   MCN (eps=0): 4.585
   MCN (eps=1-MIC): 4.585

   Characteristic Matrix:

   0.108 0.146 0.226 0.347 0.434 0.545 0.639 0.740 0.863 0.932 1.000 
   0.199 0.138 0.169 0.256 0.298 0.379 0.427 
   0.237 0.190 0.217 0.286 0.324 
   0.247 0.198 0.191 
   0.262 0.213 0.232 
   0.272 0.225 
   0.286 0.237 
   0.296 
   0.308 
   0.321 
   0.333