Documentation>C API
aib.h File Reference

AIB (Agglomerative Information Bottleneck (AIB)) More...

#include "generic.h"
#include "mathop.h"

Data Structures

struct  VlAIB
 AIB algorithm data. More...
 

Functions

void vl_aib_set_verbosity (VlAIB *self, int verbosity)
 Set the verbosity. More...
 
int vl_aib_get_verbosity (VlAIB const *self)
 Get the verbosity. More...
 
Create and destroy
VlAIBvl_aib_new (double *Pcx, vl_uint nvalues, vl_uint nlabels)
 Allocates and initializes the internal data structure. More...
 
void vl_aib_delete (VlAIB *aib)
 Deletes AIB data structure. More...
 
Process data
void vl_aib_process (VlAIB *aib)
 Runs AIB on Pcx. More...
 
Retrieve results
vl_uintvl_aib_get_parents (VlAIB const *aib)
 Get resulting list of parents. More...
 
double * vl_aib_get_costs (VlAIB const *aib)
 Get a list of merge costs. More...
 

Detailed Description

Author
Brian Fulkerson
Andrea Vedaldi

Function Documentation

◆ vl_aib_delete()

void vl_aib_delete ( VlAIB aib)
Parameters
aibdata structure to delete.

◆ vl_aib_get_costs()

double * vl_aib_get_costs ( VlAIB const *  aib)
inline
Parameters
aibAIB filter.
Returns
An array of costs

◆ vl_aib_get_parents()

vl_uint * vl_aib_get_parents ( VlAIB const *  aib)
inline
Parameters
aibAIB filter.
Returns
An array of parents

◆ vl_aib_get_verbosity()

int vl_aib_get_verbosity ( VlAIB const *  self)
inline
Parameters
selfAIB object.
Returns
the verbosity level.

◆ vl_aib_new()

VlAIB* vl_aib_new ( double *  Pcx,
vl_uint  nvalues,
vl_uint  nlabels 
)
Parameters
PcxA pointer to a 2D array of probabilities
nvaluesThe number of rows in the array
nlabelsThe number of columns in the array

Creates a new VlAIB struct containing pointers to all the data that will be used during the AIB process.

Allocates memory for the following:

  • Px (nvalues*sizeof(double))
  • Pc (nlabels*sizeof(double))
  • nodelist (nvalues*sizeof(vl_uint))
  • which (nvalues*sizeof(vl_uint))
  • beta (nvalues*sizeof(double))
  • bidx (nvalues*sizeof(vl_uint))
  • parents ((2*nvalues-1)*sizeof(vl_uint))
  • costs (nvalues*sizeof(double))

Since it simply copies to pointer to Pcx, the total additional memory requirement is:

(3*nvalues+nlabels)*sizeof(double) + 4*nvalues*sizeof(vl_uint)

Returns
An allocated and initialized VlAIB pointer

◆ vl_aib_process()

void vl_aib_process ( VlAIB aib)
Parameters
aibAIB object to process

The function runs Agglomerative Information Bottleneck (AIB) on the joint probability table aib->Pcx which has labels along the columns and feature values along the rows. AIB iteratively merges the two values of the feature x that causes the smallest decrease in mutual information between the random variables x and c.

Merge operations are arranged in a binary tree. The nodes of the tree correspond to the original feature values and any other value obtained as a result of a merge operation. The nodes are indexed in breadth-first order, starting from the leaves. The first index is zero. In this way, the leaves correspond directly to the original feature values. In total there are 2*nvalues-1 nodes.

The results may be accessed through vl_aib_get_parents which returns an array with one element per tree node. Each element is the index the parent node. The root parent is equal to zero. The array has 2*nvalues-1 elements.

Feature values with null probability are ignored by the algorithm and their nodes have parents indexing a non-existent tree node (a value bigger than 2*nvalues-1).

Then the function will also compute the information level after each merge. vl_get_costs will return a vector with the information level after each merge. cost has nvalues entries: The first is the value of the cost functional before any merge, and the others are the cost after the nvalues-1 merges.

◆ vl_aib_set_verbosity()

void vl_aib_set_verbosity ( VlAIB self,
int  verbosity 
)
inline
Parameters
selfAIB object.
verbositya non-negative integer.