Column Chart

Create a Unicode sparkline column chart.

Usage

var ColumnChart = require( '@stdlib/plot/sparklines/unicode/column' );

ColumnChart( [options] )

Returns a chart instance.

var chart = new ColumnChart();

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 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 Float32Array = require( '@stdlib/array/float32' );

var chart = new ColumnChart();
chart.data = [ 5, 4, 3, 2, 1 ];
chart.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.

var chart = new ColumnChart();

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

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

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

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

var chart = new ColumnChart();

// 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': 3 }, { 'y': 2 }, { 'y': 6 } ]

chart.yMin

Minimum value of the y-axis domain. If this value is set, the y-axis lower bound is fixed; otherwise, the minimum value is computed based on the chart data.

var chart = new ColumnChart();

chart.yMin = 0.0;

chart.data = [ -1.0, 5.0, -3.0, 2.0, -4.0, 4.0, 3.0 ];

var str = chart.render();
// returns '▁█▁▄▁▇▅'

chart.yMax

Maximum value of the y-axis domain. If this value is set, the y-axis upper bound is fixed; otherwise, the maximum value is computed based on the chart data.

var chart = new ColumnChart();

chart.yMax = 10.0;

chart.data = [ -1.0, 5.0, -3.0, 2.0, -4.0, 4.0, 3.0 ];

var str = chart.render();
// returns '▃▆▂▄▁▅▅'

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

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

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

chart.push( 4 );

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

Setting a window size is useful when rendering data streams.

chart.infinities

Boolean flag indicating whether to render infinite values. When set to false, infinite values are considered missing values. When set to true, both positive and negative infinity are encoded as .

var chart = new ColumnChart();

chart.infinities = true;

chart.data = [
    1.0,
    5.0,
    NaN,
    Infinity,
    4.0,
    -Infinity,
    3.0
];

var str = chart.render();
// returns '▁█ ∞▆∞▅'

Methods

A chart instance has the following methods...

chart.push( datum )

Append data to a sparkline.

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

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

chart.push( 4 );

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

chart.render()

Renders a sparkline.

var data = [ 1.0, 5.0, 3.0, 2.0, 4.0, 4.0, 3.0 ];

var opts = {
    'data': data
};

var chart = new ColumnChart( opts );

var str = chart.render();
// returns '▁█▅▃▆▆▅'

chart.toString()

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

var chart = new ColumnChart();

chart.data = [ 1.0, 5.0, 3.0, 2.0, 4.0, 4.0, 3.0 ];

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 Float64Array = require( '@stdlib/array/float64' );
var columnChart = require( '@stdlib/plot/sparklines/unicode/column' );

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

// Generate some random data...
data = new Float64Array( 50 );
for ( i = 0; i < data.length; i++ ) {
    data[ i ] = randu() * 100.0;
}

// Create a new column chart:
chart = columnChart();

// 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;
chart.yMin = 0.0;
chart.yMax = 100.0;

// 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( randu() * 100.0 );

    // 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-column [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/'.
         --ymin min            Minimum value of y-axis domain.
         --ymax max            Maximum value of y-axis domain.
         --infinities          Encode infinite values.

Notes

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

    # Not escaped...
    $ echo -n $'1\n2\n3\n' | sparkline-column --split /\r?\n/
    
    # Escaped...
    $ echo -n $'1\n2\n3\n' | sparkline-column --split /\\r?\\n/
    

Examples

$ sparkline-column -- 1 2 3 4 5 6
▁▂▄▅▇█
$ echo -n $'1\n2\n3\n4\n5\n6\n' | sparkline-column --ymax 3
▁▅████