Cilantro provides user interfaces components for interacting with data. This requires being able to fetch, temporarily store, and manipulate many frames of data. Conveniently most data is represented in a record/row based structure with supplementary descriptive metadata such as rows of data with column header labels.

To generalize the terms a bit more focusing on dimensionality, there are three core structures: Datum, Series, and Frame. Each is composed of the previous with the Datum composed of some arbitrary value.

To assign labels to the data as well as understand its dimension, indexes are used. A Datum will have a single Index associated with it, while a Series has multiple. The dimension of the index array must match the width (M) or size (N) of the data. In the case of a Series, M or N is fixed at 1, thus the dimension is either 1 x N or N x 1. If the index array contains only one index, the series dimension is 1 x N (a column). If the index array contains an equal number of indexes to the size of the series, the series dimension is N x 1 (a row).

The same logic works with a Frame, either the index array must be of size M or of size N.

Note, at any time the number of indexes does not match dimension M or N, that is an error. The isValid() can be called to check if the structure is _stable.

Datum

A single instance/point of data. The contents can be arbitrarily complex, but will be assumed to be self-contained and structure-less.

var datum = new Datum(54, [
    {name: 'age', label: 'Age'}
]);

datum.size() == datum.width() == 1; // true

Series

1-dimensional array of datums either of the same type of different types.

// 1 x 3 'column'
var series1 = new Series([54, 42, 10], [
    {name: 'age', label: 'Age'}
]);

series1.width(); // 1
series1.size(); // 3
series1.isColumn(); // true

// 3 x 1 'row'
var series2 = new Series(['John', 'Smith', 54], [
    {name: 'firstName', label: 'First Name'},
    {name: 'lastName', label: 'Last Name'},
    {name: 'age', label: 'Age'}
]);

series2.width(); // 3
series2.size(); // 1
series2.isRow(); // true

Frame

2-dimensional array of series.

// 3 x 4
var frame = new Frame([
    ['John', 'Smith', 54],
    ['Jane', 'Lee', 42],
    ['Sue', 'Anne', 10],
    ['Billy', 'Anne', 7]
], [
    {name: 'firstName', label: 'First Name'},
    {name: 'lastName', label: 'Last Name'},
    {name: 'age', label: 'Age'}
]);

frame.width(); // 3
frame.size(); // 4

Data Format

Data supplied as arrays of values, arrays of Datum instances, or arrays of objects keyed by the index name property. For instance, this example is equivalent to the above frame instance:

var frame2 = new Frame([
    {firstName: 'John', lastName: 'Smith', age: 54},
    {firstName: 'Jane', lastName: 'Lee', age: 42},
    {firstName: 'Sue', lastName: 'Anne', age: 10},
    {firstName: 'Billy', lastName: 'Anne', age: 7}
], [
    {name: 'firstName', label: 'First Name'},
    {name: 'lastName', label: 'Last Name'},
    {name: 'age', label: 'Age'}
]);

Indexes & Dimensionality

TBA