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.

char *libmine_version

The libmine version in the form X.Y.Z (e.g., 1.0.1).

mine_problem

The mine_problem structure describes the problem.

typedef struct mine_problem {
   int n;
   double *x;
   double *y;
} mine_problem;

where of x and y are the two variables of length n.

mine_parameter

The mine_parameter structure describes the MINE parameters.

typedef struct mine_parameter {
   double alpha;
   double c;
} mine_parameter;

where alpha is the exponent in and must be in , 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 clumps. c must be > 0.

mine_score

The mine_score structure contains the maximum normalized mutual information scores.

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

mine_score *mine_compute_score(mine_problem *prob, mine_parameter *param)

Computes the maximum normalized mutual information scores and returns a mine_score structure. Returns NULL if an error occurs.

char *mine_check_parameter(mine_parameter *param)

This function checks the parameters. It should be called before using mine_compute_score(). It returns NULL if the parameters are feasible, otherwise an error message is returned.

double mine_mic(mine_score *score)

Returns the Maximal Information Coefficient (MIC).

double mine_mas(mine_score *score)

Returns the Maximum Asymmetry Score (MAS).

double mine_mev(mine_score *score)

Returns the Maximum Edge Value (MEV).

double mine_mcn(mine_score *score, double eps)

Returns the Minimum Cell Number (MCN) with .

double mine_mcn_general(mine_score *score)

Returns the Minimum Cell Number (MCN) with .

void mine_free_score(mine_score **score)

This function frees the memory used by a mine_score and destroys the score structure.

Example

The example is located in examples/c_example.c.

#include <stdlib.h>
#include <stdio.h>
#include <math.h>
#include "mine.h"


int main (int argc, char **argv)
{
  mine_problem prob;
  mine_parameter param;
  mine_score *score;

  double PI = 3.14159265;
  int i, j;
  char *ret;
  
  //printf("libmine version %d\n\n", libmine_version);
 
  /* set the parameters */
  param.alpha = 0.6;
  param.c = 15;
  
  /* check the parameters */ 
  ret = mine_check_parameter(&param);
  if (ret)
    {
      printf("ERROR: %s\n", ret);
      return 1;
    }

  /* build the problem */
  prob.n = 201;
  prob.x = (double *) malloc (prob.n * sizeof (double));
  prob.y = (double *) malloc (prob.n * sizeof (double));
  for (i=0; i<prob.n; i++)
    {
      /* build x = [0, 0.005, ..., 1] */
      prob.x[i] = (double) i / (double) (prob.n-1);

      /* build y = sin(10 * pi * x) + x */
      prob.y[i] = sin(10 * PI * prob.x[i]) + prob.x[i]; 
    }
  
  /* compute score */
  score = mine_compute_score(&prob, &param);
  if (score == NULL)
    {
      printf("ERROR: mine_compute_score()\n");
      return 1;
    }
  
  /* print the MINE statistics */
  printf ("MINE statistics:\n\n");
  printf ("MIC: %.3lf\n", mine_mic(score));
  printf ("MAS: %.3lf\n", mine_mas(score));
  printf ("MEV: %.3lf\n", mine_mev(score));
  printf ("MCN (eps=0): %.3lf\n", mine_mcn(score, 0));
  printf ("MCN (eps=1-MIC): %.3lf\n", mine_mcn_general(score));

  /* print the characteristic matrix M */
  printf ("\nCharacteristic Matrix:\n\n");
  
  for (i=0; i<score->n; i++)
    {
      for (j=0; j<score->m[i]; j++)
  	printf ("%.3lf ", score->M[i][j]);
      printf ("\n");
    }
  
  /* free score */
  mine_free_score(&score);
  
  /* free prob */
  free(prob.x);
  free(prob.y);
  
  return 0;
}

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

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

or

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

for an extensive optimization. Run the example by typing:

$ ./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