Tristate Chart

Create a Unicode sparkline tristate chart.

Usage

var TristateChart = require( '@stdlib/plot/sparklines/unicode/tristate' );

TristateChart( [options] )

Returns a chart instance.

var chart = new TristateChart();

The constructor accepts the following options:

  • data: sparkline data.
  • yValue: y-value accessor. Default: identity function.
  • window: sliding window size. If provided, data is kept in a first-in first-out (FIFO) buffer which cannot exceed the window size. Default: +infinity.

Properties

A chart instance has the following properties...

chart.data

Sparkline data. When set, the value must be either an array or typed array and cannot exceed the window size.

var Int8Array = require( '@stdlib/array/int8' );

var chart = new TristateChart();
chart.data = [ 1, 1, 0, 1, -1, -1 ];
chart.data = new Int8Array( [ 1, 0, -1, 1, 1, 0 ] );

When set, data is converted to a standard representation. The returned data is a copy of this representation.

var chart = new TristateChart();

chart.data = [ -1, 1, 0 ];

var data = chart.data;
// returns [ { 'y': -1 }, { 'y': 1 }, { 'y': 0 } ]

chart.yValue

y-value accessor function. By default, the accessor is an identity function. The accessor is invoked when converting provided data to a standard representation. The function is provided two arguments: d, a datum, and i, the datum index.

var data = [
    [ { 'value': -1 } ],
    [ { 'value': 1 } ],
    [ { 'value': 0 } ]
];

function yValue( d, i ) {
    return d[ 0 ].value;
}

var chart = new TristateChart();

// Set the accessor prior to setting the data:
chart.yValue = yValue;

// Accessor will be used during standardization:
chart.data = data;

var arr = chart.data;
// returns [ { 'y': -1 }, { 'y': 1 }, { 'y': 0 } ]

chart.window

Sliding window size. If set, this specifies the maximum number of data elements which can be rendered. Once the window buffer is full, each new datum results in the oldest datum being removed.

var chart = new TristateChart();

chart.data = [ 1, -1, -1 ];
chart.window = 3;

var data = chart.data;
// returns [ { 'y': 1 }, { 'y': -1 }, { 'y': -1 } ]

chart.push( -1 );

data = chart.data;
// returns [ { 'y': -1 }, { 'y': -1 }, { 'y': -1 } ]

Setting a window size is useful when rendering data streams.

Methods

A chart instance has the following methods...

chart.push( datum )

Append data to a sparkline.

chart.data = [ 1, -1, -1 ];

var data = chart.data;
// returns [ { 'y': 1 }, { 'y': -1 }, { 'y': -1 } ]

chart.push( 0 );

data = chart.data;
// returns [ { 'y': 1 }, { 'y': -1 }, { 'y': -1 }, { 'y': 0 } ]

chart.render()

Renders a sparkline. By default, negative values are encoded as lower blocks, positive values are encoded as upper blocks, and values equal to zero are encoded as middle lines.

var data = [ -1, 1, 0, 0, 1, -1, -1, 1 ];

var opts = {
    'data': data
};

var chart = new TristateChart( opts );

var str = chart.render();
// returns '▄▀──▀▄▄▀'

chart.toString()

Serializes a sparkline as a string by calling the render() method.

var chart = new TristateChart();

chart.data = [ -1, 1, 0, 0, 1, -1, -1, 1 ];

var str = chart.toString();
// returns '▄▀──▀▄▄▀'

Notes

  • The new operator is not required when instantiating a chart instance.
  • NaN values are always encoded as missing values.

Examples

var randu = require( '@stdlib/random/base/randu' );
var Int8Array = require( '@stdlib/array/int8' );
var tristate = require( '@stdlib/plot/sparklines/unicode/tristate' );

var chart;
var data;
var id;
var i;

function datum() {
    var d = randu();
    if ( d > 0.67 ) {
        return 1;
    }
    if ( d < 0.33 ) {
        return -1;
    }
    return 0;
}

// Generate some random data...
data = new Int8Array( 50 );
for ( i = 0; i < data.length; i++ ) {
    data[ i ] = datum();
}

// Create a new tristate chart:
chart = tristate();

// Set the chart data:
chart.data = data;

// Hide the terminal cursor:
process.stdout.write( '\u001b[?25l' );

// Render the chart in the terminal:
process.stdout.write( chart.render() );

// Configure the chart to support streaming data:
chart.window = data.length;

// Update the terminal chart with new data every second:
id = setInterval( update, 1000 );

// After some time, stop updating and close:
setTimeout( stop, 20000 );

function update() {
    // Update the chart with new data:
    chart.push( datum() );

    // Clear the terminal line and render the chart:
    process.stdout.write( '\r\u001b[2K' + chart.render() );
}

function stop() {
    clearInterval( id );

    // Restore the terminal cursor:
    process.stdout.write( '\u001b[?25h' );

    process.stdout.write( '\n' );
}

CLI

Usage

Usage: sparkline-tristate [options] [<number> <number> ...]

Options:

  -h,    --help                Print this message.
  -V,    --version             Print the package version.
         --split sep           Separator for standard input data. Default: '/\r?\n/'.

Notes

  • If the split separator is a regular expression, ensure that the split option is properly escaped.

    # Not escaped...
    $ echo -n $'1\n-1\n0\n' | sparkline-tristate --split /\r?\n/
    
    # Escaped...
    $ echo -n $'1\n-1\n0\n' | sparkline-tristate --split /\\r?\\n/
    

Examples

$ sparkline-tristate -- -1 1 0 0 1 -1 -1 1
▄▀──▀▄▄▀
$ echo -n $'-1\n1\n0\n0\n1\n-1\n-1\n1\n' | sparkline-tristate
▄▀──▀▄▄▀