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.

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

mine_score

The mine_score structure describes the maximum normalized mutual information scores.

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

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

This function computes the maximum normalized mutual information scores and returns a mine_score structure.

char *check_parameter(mine_parameter *param)

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

double mic(mine_score *score)

Returns the Maximal Information Coefficient (MIC).

double mas(mine_score *score)

Returns the Maximum Asymmetry Score (MAS).

double mev(mine_score *score)

Returns the Maximum Edge Value (MEV).

double mcn(mine_score *score)

Returns the Minimum Cell Number (MCN).

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)
{
  double PI;
  int i;
  mine_problem prob;
  mine_parameter param;
  mine_score *score;
  char *ret;
  
  PI = 3.14159265;
 
  /* set the parameters */
  param.alpha = 0.6;
  param.c = 15;
  
  /* check the parameters */ 
  if ((ret=check_parameter(&param)))
    {
      printf("ERROR: %s\n", ret);
      return 1;
    }

  /* build the problem */
  prob.n = 1001;
  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.001, ..., 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);

  /* print mine statistics */
  printf ("MIC: %lf\n", mic(score));
  printf ("MAS: %lf\n", mas(score));
  printf ("MEV: %lf\n", mev(score));
  printf ("MCN: %lf\n", mcn(score));

  /* 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 ../minepy/libmine/core.c \
../minepy/libmine/mine.c -I../minepy/libmine/ -lm

or

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

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