Win/Loss Chart

Create a Unicode sparkline win/loss chart.

Usage

var WinLossChart = require( '@stdlib/plot/sparklines/unicode/win-loss' );

WinLossChart( [options] )

Returns a chart instance.

var chart = new WinLossChart();

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 WinLossChart();
chart.data = [ 1, 1, 2, 1, -1, -1 ];
chart.data = new Int8Array( [1, 2, -1, 1, 1, -2] );

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

var chart = new WinLossChart();

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

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

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': -1 } ]
];

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

var chart = new WinLossChart();

// 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': -1 } ]

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 WinLossChart();

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( 1 );

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

chart.render()

Renders a sparkline.

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

var opts = {
    'data': data
};

var chart = new WinLossChart( opts );

var str = chart.render();
// returns '┌╵└┴╵╷╷╵┌┬'

Glyphs:

Value Glyph
1
-1
2
-2

If a 2 or -2 is preceded by a 2 or -2,

Value Glyph
2
-2

Based on the win/loss analogy,

  • 1: win away
  • -1: loss away
  • 2: win at home
  • -2: loss at home

If provided any other value other than 1, -1, 2, -2, the value is encoded as a missing value.

chart.toString()

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

var chart = new WinLossChart();

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

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 winloss = require( '@stdlib/plot/sparklines/unicode/win-loss' );

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

// Based on GS Warriors winning percentages for 2015-2016...
function datum() {
    var d = randu();
    if ( d > 0.5 ) {       // home
        d = randu();
        if ( d < 0.057 ) { // loss
            d = -2;
        } else {           // win
            d = 2;
        }
    } else {               // away
        d = randu();
        if ( d < 0.229 ) { // loss
            d = -1;
        } else {           // win
            d = 1;
        }
    }
    return d;
}

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

// Create a new win/loss chart:
chart = winloss();

// 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-winloss [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\n1\n' | sparkline-winloss --split /\r?\n/
    
    # Escaped...
    $ echo -n $'1\n-1\n1\n' | sparkline-winloss --split /\\r?\\n/
    

Examples

$ sparkline-winloss -- -2 1 2 2 1 -1 -1 1 -2 -2
┌╵└┴╵╷╷╵┌┬
$ echo -n $'-2\n1\n2\n2\n1\n-1\n-1\n1\n-2\n-2\n' | sparkline-winloss
┌╵└┴╵╷╷╵┌┬