Documentation>C API
Data Structures | Functions
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
VlAIB * | vl_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_uint * | vl_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

  aib | data structure to delete.

## ◆ vl_aib_get_costs()

double * vl_aib_get_costs | ( | VlAIB const * | aib | ) |

inline

Parameters

  aib | AIB filter.

Returns
  An array of costs

## ◆ vl_aib_get_parents()

vl_uint * vl_aib_get_parents | ( | VlAIB const * | aib | ) |

inline

Parameters

  aib | AIB filter.

Returns
  An array of parents

## ◆ vl_aib_get_verbosity()

int vl_aib_get_verbosity | ( | VlAIB const * | self | ) |

inline

Parameters

  self | AIB object.

Returns
  the verbosity level.

## ◆ vl_aib_new()

VlAIB* vl_aib_new | ( | double * | Pcx,
|  | vl_uint | nvalues,
|  | vl_uint | nlabels
| ) |  |

Parameters

  Pcx | A pointer to a 2D array of probabilities
  nvalues | The number of rows in the array
  nlabels | The 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

  aib | AIB 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

  self | AIB object.
  verbosity | a non-negative integer.