Sparkline

Base class for Unicode sparklines.

Usage

var Sparkline = require( '@stdlib/plot/sparklines/unicode/base' );

Sparkline( [options] )

Returns a sparkline instance.

var sparkline = new Sparkline();

The constructor accepts the following options:

  • data: sparkline data.
  • yValue: y-value accessor. Default: identity function.
  • yMin: minimum value of the y-axis domain.
  • yMax: maximum value of the y-axis domain.
  • 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.
  • infinities: boolean flag indicating whether to encode infinite values. Default: false.

Properties

A sparkline instance has the following properties...

sparkline.data

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

var Float32Array = require( '@stdlib/array/float32' );

sparkline.data = [ 5, 4, 3, 2, 1 ];
sparkline.data = new Float32Array( [ 3.14, 5.0, -3.14, -1.0 ] );

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

sparkline.data = [ 3, 1, 2 ];

var data = sparkline.data;
// returns [ { 'y': 3 }, { 'y': 1 }, { 'y': 2 } ]

sparkline.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': 3 } ],
    [ { 'value': 1 } ],
    [ { 'value': 2 } ]
];

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

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

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

var arr = sparkline.data;
// returns [ { 'y': 3 }, { 'y': 2 }, { 'y': 6 } ]

sparkline.yMin

Minimum value of the y-axis domain. For certain sparkline implementations, setting this value will fix the minimum value.

sparkline.yMin = -100.0;

sparkline.yMax

Maximum value of the y-axis domain. For certain sparkline implementations, setting this value will fix the maximum value.

sparkline.yMax = 100.0;

sparkline.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.

sparkline.data = [ 1, 2, 3 ];
sparkline.window = 3;

var data = sparkline.data;
// returns [ { 'y': 1 }, { 'y': 2 }, { 'y': 3 } ]

sparkline.push( 4 );

data = sparkline.data;
// returns [ { 'y': 2 }, { 'y': 3 }, { 'y': 4 } ]

Setting a window size is useful when rendering data streams.

sparkline.infinities

Boolean flag indicating whether to render infinite values. Depending on the sparkline implementation, when set to false, infinite values may be considered missing values. When set to true, an implementation may support special rendering modes.

// Instruct a sparkline implementation to render infinite values:
sparkline.infinities = true;

Methods

A sparkline instance has the following methods...

sparkline.push( datum )

Append data to a sparkline.

sparkline.data = [ 1, 2, 3 ];

var data = sparkline.data;
// returns [ { 'y': 1 }, { 'y': 2 }, { 'y': 3 } ]

sparkline.push( 4 );

data = sparkline.data;
// returns [ { 'y': 1 }, { 'y': 2 }, { 'y': 3 }, { 'y': 4 } ]

sparkline.render()

Renders a sparkline. This method should be implemented by Sparkline descendants.

sparkline.toString()

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

var str = sparkline.toString();
// returns '...'

Examples

var Sparkline = require( '@stdlib/plot/sparklines/unicode/base' );

function Chart( opts ) {
    if ( opts === void 0 ) {
        opts = {};
    }
    // Call the Sparkline constructor:
    Sparkline.call( this, opts );

    return this;
}

// Inherit from the Sparkline class:
Chart.prototype = Object.create( Sparkline.prototype );
Chart.prototype.constructor = Chart;

// Implement a custom render method:
Chart.prototype.render = function render() {
    var str;
    var d;
    var i;

    str = '';
    for ( i = 0; i < this._data.length; i++ ) {
        d = this._data[ i ];
        if ( d.y > 0 ) {
            str += '↑';
        } else {
            str += '↓';
        }
    }
    return str;
};

var chart = new Chart();
chart.data = [ 1, 0, 0, 1, 0, 1, 1, 1, 0, 1, 1, 0, 0 ];
console.log( chart.render() );
// => '↑↓↓↑↓↑↑↑↓↑↑↓↓'