Data source

You can think of Taucharts API as a mapping between data variable set (data dimensions) and visual encoding parameters (X, Y, color and size).

var plot = new Taucharts.Chart({
    // data dimensions
    data: [
        { name: "John", age: 30, gender: 'Male',   hasChild: true  },
        ...
        { name: "Mary", age: 22, gender: 'Female', hasChild: false }
    ],
    type:  "scatterplot",
    ...
    // visual encoding
    x:     "gender",
    y:     "age",
    size:  "age",
    color: "hasChild"
});

example jsFiddle

Taucharts requires the source data to be provided in a form of structured table which can be expressed in javascript as an array of same-typed objects (e.g. in example above: name, age, gender, hasChild).

By default Taucharts try to detect a dimension type which can be a category, order or measure.

• Category: Represents data that can't be compared. Let's say, list of countries or names.
• Order: As you might guess, represents data that can be ordered, but you can't say how bigger one value from the other. For example, you can say that Must Have is more important than Nice to Have, but you can't say that Must Have is twice as important.
• Measure: That is easy. You can compare these variables, add them, multiply them, etc.

Using dimension type Taucharts tries to find the most appropriate scale for a dimension. Here is a list of default scales for corresponding dimension types:

You can explicitly specify dimension type / scale in dimensions section:

var plot = new Taucharts.Chart({
    data: [
        { name: "John", age: 30, gender: 'Male',   hasChild: true  },
        ...
        { name: "Mary", age: 22, gender: 'Female', hasChild: false }
    ],
    dimensions: {
        name    : { type: 'category', scale: 'ordinal' },
        age     : { type: 'measure' },
        gender  : { type: 'category' },
        hasChild: { type: 'category' }
    },
    type:  "scatterplot",
    ...
    x:     "gender",
    y:     "age",
    size:  "age",
    color: "hasChild"
});

Ordered dimension

You should pass data property as a primitive type (string, boolean) and define an order array that provides the order of categories.

For example, we have priority property in the data. It can be ordered, but Taucharts don't have a clue how to do that. In dimensions section you describe priority as order and set ['Low', 'Medium', 'High'] order.

{
    data: [
        { featureID: 1, priority: 'High'},
        { featureID: 2, priority: 'Low'},
        ...
        { featureID: 5, priority: 'So-so'},
        ...
        { featureID: 9, priority: 'to be done yesterday'},

        { featureID: 99, priority: 'Medium'},
    ],
    dimensions: {
        ...
        priority: {
            type: 'order',
            order: ['Low', 'Medium', 'High'] // ["So-so", "to be done yesterday"]
                                             // will be added to the end of order
        }
        ...
    },
    ...
});

Time-based dimensions

In Taucharts time-based data is expressed as order or measure dimension type on period or time scale.

{
    data: [
        { createDate: "2014-10-02", ... },                  // short ISO
        { createDate: "2014-10-02T22:17:59+03:00", ... },   // full ISO
        { createDate: 1412208000000, ... },                 // tick (from 1970-01-01Z)
        { createDate: new Date(), ... },                    // javascript Date object
        ...
    ],
    dimensions: {
        // if you want to split timeline to some specific periods (day, week, quarter...)
        createDate: {
            type : 'order',
            scale: 'period'
        }
        // guide property sets 
        guide: {
            x:{ tickPeriod: 'quarter', tickFormat: 'day' }
            // tickPeriod indicates that every tick is a quarter, while tickFormat sets how tick value will be displayed
            // In this example we will have quarters with first day of the quarter: 01-Jan-2014, 01-Apr-2014, 01-Jul-2014, 01-Oct-2014...
        }

        ...
        // or
        ...
        // if you want to draw continuous timeline
        createDate: {
            type : 'measure',
            scale: 'time'
        }
        ...
    }
}

Accepted time data source values:

• javascript Date object
• javascript tick (amount of milliseconds from 1970-01-01Z)
• string date in ISO 8601 format (e.g. "2014-10-02T22:17:59+03:00")

The period size for periodical scale is specified using tickPeriod propert. There is a set of pre-defined periods:

• day
• week (split timeline by sundays)
• month
• quarter
• year

Also you can define custom periods.

NOTE: the periodic scale operates with JavaScript Date objects in a LOCAL timezone. Make sure your data meets this requirement otherwise Taucharts automatically cast data values to browser timezone which can be a source of unobvious errors.

The time scale doesn't require special customization, you can use d3-based time format specifiers for tickFormat in scale guide.