compute-tversky-index v1.0.0

Tversky Index

Computes the Tversky index between two sequences.

The Tversky index is an asymmetric similarity measure between two sets, one defined the prototype and the other the variant. The measure has two parameters: alpha and beta, which correspond to weights associated with the prototype and variant, respectively. For alpha = beta = 1, the index is equal to the Tanimoto coefficient. For alpha = beta = 0.5, the index is equal to Dice's coefficient.

Installation

$ npm install compute-tversky-index

For use in the browser, use browserify.

Usage

var tversky = require( 'compute-tversky-index' );

tversky( a, b, opts )

Computes the Tversky index between two sequences a and b. a and b must be either both arrays or both strings.

var a, b, idx;

// Arrays:
a = [ 2, 5, 7, 9 ];
b = [ 3, 5, 7, 11 ];

idx = tversky( a, b );
// returns 0.333...

// Strings:
a = 'Harry';
b = 'Hans';

idx = tversky( a, b );
// returns 0.5

The method accepts the following options:

• alpha: weight of the prototype sequence. Must be greater than or equal to 0. Default: 1.
• beta: weight of the variant sequence. Must be greater than or equal to 0. Default: 1.
• symmetric: boolean flag indicating whether to compute a symmetric variant of the Tversky index. Default: false.

To specify options, provide an options object:

var a, b, idx;

a = 'Harry';
b = 'hans';

idx = tversky( a, b, {
	'alpha': 0.8,
	'beta': 2,
	'symmetric': true
});
// returns 0.142857...

Notes

The module defines a and b as sequences, rather than sets, to facilitate more general application. Internally, unique sets are extracted from the sequences, and, from these sets, the index is computed.

Examples

var tversky = require( 'compute-tversky-index' ),
	shuffle = require( 'compute-shuffle' ),
	nanmean = require( 'compute-nanmean' );

// Adjustable variables...

// How big should the population be from which random samples will be drawn? (the larger the population, the more likely that the population will explore all possible random variates)
var numData = 20;

// How many random samples should be drawn from the population?
var numSeq = 100;

// How big should the random samples be? (the smaller the sequence, the more likely individual sequences will vary from one another; for a sample size equal to the population, variation between samples will be zero => index = 1)
var seqLen = 10;

// How much should the random variates be allowed to vary? (the larger the value, the less likely a value will be repeated in the population data set, and thus, the more likely that sequences will vary)
var max = 20;


// Other variables...
var data,
	seq,
	len,
	indices,
	opts,
	means,
	idx,
	i,
	j;

// Simulate some data...
data = new Array( numData );
for ( i = 0; i < numData; i++ ) {
	data[ i ] = Math.round( Math.random()*max );
}

// Generate random sequences...
seq = new Array( numSeq );
len = seqLen;
for ( j = 0; j < numSeq; j++ ) {
	// Randomly shuffle the data...
	shuffle( data );

	// Pick the first X elements...
	seq[ j ] = data.slice( 0, len+1 );
}

// Compute the modified (symmetric) Tversky index for each sequence pair...
len = numSeq;
indices = new Array( len );
for ( i = 0; i < len; i++ ) {
	indices[ i ] = new Array( len );
	// Exclude indices between each sequence and itself...
	indices[ i ][ i ] = NaN;
}
opts = {
	'symmetric': true
};
for ( i = 0; i < len-1; i++ ) {
	for ( j = i+1; j < len; j++ ) {
		idx = tversky( seq[ i ], seq[ j ], opts );
		indices[ i ][ j ] = idx;
		indices[ j ][ i ] = idx;
	}
}

// Compute the mean index between all sequences...
means = new Array( len );
for ( i = 0; i < len; i++ ) {
	means[ i ] = nanmean( indices[ i ] );
}
console.log( nanmean( means ) );

To run the example code from the top-level application directory,

$ node ./examples/index.js

Tests

Unit

Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ make view-cov

License

MIT license.

Copyright

Copyright © 2015. Philipp Burckhardt.