The Miso Project :: Dataset

Miso.Dataset

Miso.Dataset is the main object you will instantiate to create a new dataset. A Miso.Dataset also extends from Miso.Dataset.DataView. All the methods available on a Miso.Dataset.DataView will also be available on the dataset.

new Miso.Dataset( options )

Returns: Miso.Dataset

Returns a new dataset. See the creating datasets guide for detailed information.

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 } 
                ]
              });
              
              var ds2 = new Miso.Dataset({
                url: '/data/simple.json'
              });
              
              log( ds instanceof Miso.Dataset );
              log( ds2 instanceof Miso.Dataset );
              You can edit the code in this block and rerun it.

Parameters

options Object required

Object containing all the initial configuration for the dataset.
- url String || Function optional
  
  The url of a remote file or a function returning a string for a url containing your data, used for remote importers
- sync Boolean optional
  
  When true it enables binding to dataset changes. See the Syncronization & Events guide for detailed information.
- jsonp Boolean optional
  
  Whether a remote request should use jsonp to enable cross-domain requests.
- callback String optional
  
  By default, If making a jsonp request, you can use this parameter to specify an alternate callback function name than the one that would be auto generated for you.
- delimiter String optional
  
  When using the delimited parser this is used to set a custom field delimiter such as
  delimiter: '||' for CSV files such as value1||value2
- strict Boolean optional
  
  Whether the incoming data is in the strict format - shorthand for using the Strict parser
- extract Function optional
  
  Optional function used to pre-process raw data, see the creating a dataset guide for more information.
- ready Function optional
  
  Callback function that will be called once data is fetched. Will be called before success callback on fetch. see the creating a dataset guide for more information.
- columns Object optional
  
  A way to manually override column type detection. Expects an array of objects of the following structure: { name : 'columnname', type: 'columntype', ... (additional params required for type here.)}
- comparator Function optional
  
  A function to sort the data by. It will be sorted on fetch and on any successive addition. See the sort function for more information.
- deferred Object optional
  
  A way to provide your own deferred object. It needs to follow the standard deferred signatures.
- importer Miso.Dataset.Importers optional
  
  The classname of any importer (passes through auto detection based on parameters. For example: Miso.Dataset.Importers.Polling. See the Creating a dataset guide for more information.
- parser Miso.Dataset.Parsers optional
  
  The classname of any parser (passes through auto detection based on parameters. For example: Miso.Dataset.Parsers.Delimited. See the Creating a dataset guide for more information.
- resetOnFetch Boolean optional
  
  Set to true if any subsequent fetches after first one should overwrite the current data.
- uniqueAgainst String optional
  
  Set to a column name to check for duplication on subsequent fetches.
- interval Integer optional
  
  Polling interval. Set to any value in milliseconds to enable polling on a url.
- idAttribute String optional
  
  By default all ids are stored in a column called '_id'. If there is an alternate column in the dataset that already includes a unique identifier, specify its name here. Note that the row objects will no longer have an _id property.

Instance Methods

ds.fetch( options )

Returns: Deferred

Fetches the data and populates the dataset. Even when importing local objects from a var this needs to be called before data can be accessed. Fetch returns a deferred which makes it simple to chain operations off async data requests.

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 }
                ]
              }).fetch({
                success: function() {
                  log( this.column('one').data );
                }
              });
              You can edit the code in this block and rerun it.

Parameters

options Object optional

optional arguments
- success Function optional
  
  Success callback to be called when data is fetched. Context is the dataset.
- error Function optional
  
  Error callback to be called when data fetching fails. Context is the dataset.

ds.addColumn( column )

Returns: Miso.Dataset.Column

Creates a new column and adds it to the dataset.

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 } 
                ]
              });
              ds.fetch({
                success: function() {
                  this.addColumn({
                    type: 'string',
                    name: 'four'
                  });
              
                  log(this.columnNames());
                }
              });You can edit the code in this block and rerun it.

Parameters

column Object required

Column options
- name String required
  
  Column name
- type String required
  
  String name of column type
- format String optional
  
  Only used for columns of the type time. The moment.js format describing the input dates.
- _id String optional
  
  Sets a custom column _id. We assign one by default.
- data Array optional
  
  Optional. An array of column data. By default, set to an empty array.

ds.addComputedColumn( name, type, func )

Returns: Miso.Dataset.Column

Creates a new column that is computationally derived from the rest of the row. See the Computed columns tutorial for more information.

Parameters

name String required

Name of the column to be added. Must not already exist.
type String required

The type of the column to be added. Must match one of the Miso.Dataset.types.
func function required

The way that the new column is derived. It takes a row as a parameter.

ds.add( row, options )

Returns: ds

Adds a row to the dataset. This will fire add and change events on a syncable dataset.

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 } 
                ]
              });
              ds.fetch({
                success: function() {
                  this.add({ one: 44, two: 9 });
                  log( this.column('two').data );
                  log( this.column('three').data );
                }
              });You can edit the code in this block and rerun it.

Parameters

row Object required

Object representing a new row
options Object optional

Options object
- silent Boolean optional
  
  Set to true to disable an add event being triggered

ds.remove( filter, options )

Returns: ds

Removes rows matching the passed filter from the dataset. This will fire remove and change events on a syncable dataset.

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 }
                ]
              });
              ds.fetch({ 
                success: function() {
                  log(this.column('two').data);
              
                  this.remove(function(row) {
                    return row.three === 7;
                  });
              
                  log(this.column('two').data);
                }
              });You can edit the code in this block and rerun it.

Parameters

filter Function required

Can be one of two things: A row id, or a filter function that takes a row and returns true if that row should be removed or false otherwise.
options Object optional

Options object
- silent Boolean optional
  
  Set to true to disable event firing

ds.update( rowsOrFunction, options )

Returns: ds

Updates one or more rows in a dataset. You can pass either a row object that contains an the identifying id property and altered property, an array of objects of the same form or a function that will be first applied to all rows. The function should take a `row` object for each row in the dataset. If a row shouldn't be modified, the function can return false for that row. This will fire update and change events on a syncable dataset.

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 }
                ]
              });
              
              ds.fetch({
                success: function() {
              
                  log(this.column('two').data);
              
                  // update just the first row
                  var firstRow = this.rowByPosition(0);
                  this.update({ _id : firstRow._id, one : 100 });
              
                  log(this.rowByPosition(0));
              
                  // update all rows where col three == 7
                  this.update(function(row) {
                    if (row.three === 7) {
                      row.two = 99;
                      return row;
                    } else {
                      return false;
                    }
                  });
              
                  log(this.column('two').data);
                }
              });You can edit the code in this block and rerun it.

Parameters

filter Function required

Can be one of two things: A row id, or a filter function that takes a row and returns true if that row should be removed or false otherwise.
newProperties Object required

An object representing the values that are changing.
options Object optional

Options object
- silent Boolean optional
  
  Set to true to disable event firing

ds.reset()

Returns: undefined

Updates one or more rows in a dataset. This will fire update and change events on a syncable dataset.

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 }
                ]
              });
              
              ds.fetch({
                success: function() {
                  log( this.column('two').data );
                  this.reset();
                  log( this.column('two').data );
                }
              });You can edit the code in this block and rerun it.

Miso.Dataset.DataView

A Miso.DataView is an immutable version of dataset. It is the result of selecting a subset of the data using the ds.where call. If the dataset is syncing, this view will be updated when changes take place in the original dataset. A Miso.Dataset also extends from Miso.DataView. All the methods available on a dataview will also be available on the dataset.

Instance Methods

ds.columnNames()

Returns: Array

Returns an array containing the names of all columns

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 }
                ]
              });
              
              ds.fetch({ 
                success: function() {
                  log(this.columnNames());
                }
              });
              You can edit the code in this block and rerun it.

ds.column( name )

Returns: Array

Returns a reference to a column object

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 }
                ]
              });
              
              ds.fetch({
                success: function() {
                  log(this.column('one').data);
                }
              });
              You can edit the code in this block and rerun it.

Parameters

name String required

Name of Column to be returned

ds.columns( nameArray )

Returns: Miso.Dataset.DataView

Shorthand for ds.where({ columns : nameArray });

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 }
                ]
              });
              
              ds.fetch({ 
                success: function() {
                  var oneTwo = this.columns(['one','two']);
                  log(this.columnNames());
                  log(oneTwo.columnNames());
                }
              });
              You can edit the code in this block and rerun it.

Parameters

nameArray Array required

Array of column names to select for the view

ds.hasColumn( name )

Returns: Boolean

Checks for the existance of a column and returns true/false

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 }
                ]
              });
              ds.fetch({
                success : function() {
                  log(this.hasColumn('three'));
                  log(this.hasColumn('otter'));    
                }
              });You can edit the code in this block and rerun it.

Parameters

name String required

Name of column to check for

ds.eachColumn( iterator, context )

Returns:

Iterate over all columns. Direct column references, not arrays so modifying data may cause internal inconsistencies.

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 }
                ]
              });
              
              ds.fetch({ 
                success: function() {
                  this.eachColumn(function(colName, colObject, index) {
                    log(colName);
                  });
                }
              });You can edit the code in this block and rerun it.

Parameters

iterator Function required

A function with the following signature: function(columnName, columnObject, index)'
context Object optional

The context to be bound to the iterator.

ds.each( iterator, context )

Returns:

Iterate over all rows. Each row is not a direct reference to the data and thus should not be altered in any way.

              var ds = new Miso.Dataset({
                data : [
                  { one : 12,  two : 40},
                  { one : 1,   two : 40},
                  { one : 102, two : 430}
                ]
              });
              ds.fetch({ 
                success : function() {
                  this.each(function(row) {
                    log(JSON.stringify(row));
                  });
                }
              });You can edit the code in this block and rerun it.

Parameters

iterator Function required

A function with the following signature: function(row, rowIndex)'
context Object optional

The context to be bound to the iterator.

ds.reverseEach( iterator, context )

Returns:

Iterate over all rows in reverse. Each row is not a direct reference to the data and thus should not be altered in any way.

              var ds = new Miso.Dataset({
                data : [
                  { one : 12,  two : 4},
                  { one : 1,   two : 40},
                  { one : 102, two : 430}
                ]
              });
              ds.fetch({ 
                success : function() {
                  this.reverseEach(function(row) {
                    log(JSON.stringify(row));
                  });
                }
              });You can edit the code in this block and rerun it.

Parameters

iterator Function required

A function with the following signature: function(row, rowIndex)'
context Object optional

The context to be bound to the iterator.

ds.rowByPosition( position )

Returns: Object

Fetches a row object at a specified position. Note that the returned row object is NOT a direct reference to the data and thus any changes to it will not alter the original data.

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 }
                ]
              });
              ds.fetch({ 
                success : function() {
                  log(ds.rowByPosition(1));  
                }
              });You can edit the code in this block and rerun it.

Parameters

position Integer required

Position of row

ds.rowById( id )

Returns: Object

Fetches a row object with a specific _id. Note that the returned row object is NOT a direct reference to the data and thus any changes to it will not alter the original data.

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 }
                ]
              });
              
              ds.fetch({ 
                success: function() {
                  var rowOneID = this.column('_id').data[1];
                  log(ds.rowById(rowOneID));
                }
              });
              
              You can edit the code in this block and rerun it.

Parameters

id Integer required

id of row to be returned

ds.rows( rowFilter )

Returns: Miso.Dataset.DataView

Shorthand for ds.where({ rows : rowFilter }); If run with no filter will return all rows.

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 }
                ]
              });
              
              ds.fetch({ 
                success: function() {
              
                  var rowTwo = ds.rows(function(row) {
                    return row.one === 2;
                  });
              
                  log(rowTwo.columnNames());
                  log(rowTwo.length);
                }
              });You can edit the code in this block and rerun it.

Parameters

rowFilter Array || Function optional

An array of rowIds or a filter function that takes in a row and returns true if that row should return, false otherwise.

ds.sort( args )

Returns: Miso.Dataset.DataView

Sorts the dataset according to the comparator. A comparator can either be passed in as part of the options object or have been defined on the dataset already, for example as part of the initialization block.

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 },
                  { one : 9, two : 10, three : 11 }
                ]
              });
              
              ds.fetch({ success: function() {
                log("Before Sort", this.toJSON());
              
                this.sort(function(rowA, rowB) {
                  if (rowA.three > rowB.three) { 
                    return -1; 
                  }
                  if (rowA.three < rowB.three) { 
                    return 1;  
                  }
                  return 0;
                });
              
                log("After Sort", this.toJSON());
              }});You can edit the code in this block and rerun it.

Parameters

args Object optional

Comparator Function OR Options object
- comparator Function optional
  
  Function used to sort the dataset, uses the same return structure as a standard javascript sort
- silent Boolean optional
  
  Default false, set true to supress the firing of a sort event.

ds.where( filters, options)

Returns: Miso.Dataset.DataView

Where is used to create Dataviews, subsets of data based on a set of filters. Filtration can be applied to both rows & columns and for syncing datasets changes in the parent dataset from which the dataview was created will be reflected in the dataview.

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 }
                ]
              });
              
              ds.fetch({ 
                success: function() {
                  var oneTwo = this.where({
                    // copy over the one column
                    columns: ['one'],
                    // and only where the values are > 1
                    rows: function(row) {
                      return row.one > 1;
                    }
                  });
              
                  log(oneTwo.length, oneTwo.toJSON());
                }
              });
              You can edit the code in this block and rerun it.

Parameters

filters Object optional

Could be a function that takes in a row or an options object that can contain the following parameters.
- columns String || Array optional
  
  A filter for columns. A single or multiple column names.
- rows Array || Function optional
  
  A filter for rows. A rowId or a filter function that takes in a row and returns true if it passes the criteria.

ds.groupBy(byColumn, columns, options)

Returns: Miso.Dataset.Derived

Groups rows by the values in a given column

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 },
                  { one : 6, two : 8, three : 55 }
                ]
              });
              
              ds.fetch({ 
                success: function() {
                  log(this.groupBy('one', ['two']));
                }
              });You can edit the code in this block and rerun it.

Parameters

byColumn String required

Name of the column by which to group
columns Array required

A string of a column column or an array of column names to be groups
options Object optional

Options object
- method Function optional
  
  Function that specifies the way in which the columns are aggregated. The default is sum. The function signature is function(arr). It should return a single result.
- rejectNA boolean optional
  
  Set to true to remove nulls, undefined and empty values before computing group by. Set to true by default. Set to false to turn this off.

ds.countBy(byColumn, options)

Returns: Miso.Dataset.Derived

Returns a new derived dataset that contains the original byColumn and a count column that returns the number of occurances each unique value in the byColumn contained.

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 },
                  { one : 1, two : 5, three : 8 }
                ]
              });
              
              ds.fetch({ 
                success: function() {
                  log(this.countBy('one').toJSON());
                }
              });You can edit the code in this block and rerun it.

Parameters

byColumn String required

The column to count instances again.
options Object optional

Options object

ds.movingAverage(columns, size, options)

Returns: Miso.Dataset.Derived

Returns a derived dataset in which the specified columns have a moving average computed over them of a specified size.

Parameters

columns Array optional

The columns to compute a moving average over.
size Integer optional

The size of your moving average window (the number of rows to average per row.)
options Object optional

Options object
- method Function optional
  
  The method by which the moving average will be computed. The default is mean.

ds.min( column )

Returns: Number || Miso.Dataset.Product

If the dataset has sync enabled this will return a Miso.Dataset.Product that can be used to bind events to and access the current value. Otherwise it will return the current value - the lowest numeric value in that column

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 },
                  { one : 6, two : 8, three : 55 }
                ]
              });
              
              ds.fetch({ 
                success: function() {
                  log( "Column 'one' min: " + this.min('one') );
                  log( "Column 'two' min: " + this.min('two') );
                }
              });
              You can edit the code in this block and rerun it.

Parameters

column String required

Name of the column on which to find the min

ds.max( column )

Returns: Number || Miso.Dataset.Product

If the dataset has sync enabled this will return a Miso.Dataset.Product that can be used to bind events to and access the current value. Otherwise it will return the current value - the highest numeric value in that column

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 },
                  { one : 6, two : 8, three : 55 }
                ]
              });
              
              ds.fetch({ 
                success: function() {
                  log( "Column 'one' max: " + this.max('one') );
                  log( "Column 'two' max: " + this.max('two') );
                }
              });
              You can edit the code in this block and rerun it.

Parameters

column String required

Name of the column on which to find the max

ds.sum( column )

Returns: Number || Miso.Dataset.Product

If the dataset has sync enabled this will return a Miso.Dataset.Product that can be used to bind events to and access the current value. Otherwise it will return the current value - the sum of the numeric form of the values in the column.

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 },
                  { one : 6, two : 8, three : 55 }
                ]
              });
              
              ds.fetch({ 
                success: function() {
                  log( "Column 'one' sum: " + this.sum('one') );
                  log( "Column 'two' sum: " + this.sum('two') );
                }
              });
              
              You can edit the code in this block and rerun it.

Parameters

column String required

Name of the column on which to add up the sum

ds.mean( column )

Returns: Number || Miso.Dataset.Product

If the dataset has sync enabled this will return a Miso.Dataset.Product that can be used to bind events to and access the current value. Otherwise it will return the current value - the mean or average of the numeric form of the values in the column.

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 },
                  { one : 6, two : 8, three : 55 }
                ]
              });
              
              ds.fetch({ 
                success: function() {
                  log( "Column 'one' mean: " + this.mean('one') );
                  log( "Column 'three' mean: " + this.mean('three') );
                }
              });
              
              
              You can edit the code in this block and rerun it.

Parameters

column String required

Name of the column on which to find the mean

Miso.Dataset.Derived

A Miso.Dataset.Derived is what you will be returned from derivative operations such as groupBy or movingAverage, it is essetially a Miso.Dataset but with a syncronisation link back to its parent dataset.

Miso.Dataset.Product

A Miso.Dataset.Product is what you will be returned if you run a method such as max on a dataset that has sync set to true. The product object allows you to bind events to it, meaning you can automatically update anything using the product when the underlying dataset changes in a way which affects the current value of the product.

Miso.Dataset.Product.define(func)

Returns: Function

Use this method to define a new product. For example:

              // initialize a new dataset
              var ds = new Miso.Dataset({
                data: { 
                  columns : [ 
                    { name : "one", data : [10, 2, 3] },
                    { name : "two", data : [1, 20, 3] }
                  ] 
                },
                strict: true
              });
              
              Miso.Dataset.prototype.random = Miso.Dataset.Product.define(function(columns) {
                  
                  // assemble all the data 
                  // values into a single array temporarily
                  var values = [];
                  _.each(columns, function(column) {
                    values.push(column.data);
                  }, this);
              
                  // flatten the values
                  values = _.flatten(values);
              
                  // get a random value from the total array of values
                  // we gathered.
                  return values[Math.floor(Math.random() * values.length)];
                }
              );
              
              ds.fetch({
                success : function() {
                  log(this.random(["one", "two"]));    
                }
              });You can edit the code in this block and rerun it.

Parameters

func Function required

The function which will be wrapped to create a product. Function signature is function(columns, options)

Instance Methods

product.val()

Returns: Any

Returns the current value of the product.

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 },
                  { one : 6, two : 8, three : 55 }
                ],
                sync: true
              });
              
              ds.fetch({ 
                success: function() {
                  this.min('three').bind('change', function() {
                    log("Column 'three' min is: " + this.val());
                  });
              
                  this.add({ one: 2, two: 2, three: 2 });
                  this.add({ one: 2, two: 2, three: 1 });
                  //doesn't trigger as min didn't change
                  this.add({ one: 2, two: 2, three: 99 });
              
                }
              });
              You can edit the code in this block and rerun it.

Miso.Events

Miso.Events is a simple set of pub/sub methods that can be added to any object. Miso Events support not just simple subscriptions but also make identifiying individual subscriptions easier through a token system and support callback priority.

object.publish( eventName )

Returns: this

Publish an event on the object the events have been mixed in to.

Parameters

name String required

Name of the event to publish

object.subscribe( eventName, callback, options )

Returns: token

Subscribe to an event by passing in a name and a callback function. The token option allows you to supply the token that you can use to uniquely identify the subscription. The priority subscription allows you to specify the running order of event subscriptions with higher numbers being run earlier.

Parameters

name String required

Name of the event to subscribe to
callback Function required

Callback function to be run
options Object optional

Optional configuration parameters
- token String optional
  
  String token to uniquely identify the subscription, will be generated if not passed in
- priority Number optional
  
  Priority number, a higher number will mean the callback will be run earlier

object.subscribeOnce( eventName, callback )

Returns: token

Create a subscription that will only be run once.

Parameters

name String required

Name of the event to subscribe to
callback Function required

Callback function to be run

object.unsubscribe( eventName, identifier )

Returns: this

Destroy a subscription. If no identifier is provided all subscriptions to the event will be destroyed.

Parameters

name String required

Name of the event to subscribe to
identifier String || Function optional

Either a subscription token or a callback function.

Miso.Dataset.Event

Miso.Dataset.Events are objects that will be passed to event callbacks bound to dataset objects that contain information about the event and what has changed. See the Events tutorial for more information.

event.isRemove(delta)

Returns: Boolean

Returns whether or not a given delta is for a remove event

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 }
                ],
                sync: true
              });
              
              ds.fetch({
                success: function() {
                  this.bind('change', function( event ) {
                    log( 'Remove ?: ' + Miso.Dataset.Event.isRemove(event.deltas[0]) );
                  });
                }
              });
              
              //false
              ds.add({ one: 3 });
              
              //true
              ds.remove(function(row) { return true; });
              You can edit the code in this block and rerun it.

Parameters

delta Object required

a delta object from the event

event.isAdd(delta)

Returns: Boolean

Returns whether or not a given delta is for an add event

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 }
                ],
                sync: true
              });
              
              ds.fetch({
                success: function() {
                  this.bind('change', function( event ) {
                    log( 'Add ?: ' + Miso.Dataset.Event.isAdd(event.deltas[0]) );
                  });
                }
              });
              
              //true
              ds.add({ one: 3 });
              
              //false
              ds.remove(function(row) { return true; });
              
              You can edit the code in this block and rerun it.

Parameters

delta Object required

a delta object from the event

event.isUpdate(delta)

Returns: Boolean

Returns whether or not a given delta is for an update event

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 }
                ],
                sync: true
              });
              
              ds.fetch({
                success: function() {
                  this.bind('change', function( event ) {
                    log( 'Update ?: ' + Miso.Dataset.Event.isUpdate(event.deltas[0]) );
                  });
                }
              });
              
              //false
              ds.add({ one: 3 });
              
              //true
              var firstRowID = ds.column('_id').data[0];
              ds.update(firstRowID, { one: 9 });
              
              You can edit the code in this block and rerun it.

Parameters

delta Object required

a delta object from the event

Instance Methods

event.affectedColumns()

Returns: Array

Returns an array of columns affected by the event

              var ds = new Miso.Dataset({
                data: [ 
                  { one : 1, two : 4, three : 7 },
                  { one : 2, two : 5, three : 8 }
                ],
                sync: true
              });
              
              ds.fetch({
                success: function() {
                  this.bind('change', function( event ) {
                    log( event.affectedColumns() );
                  });
                }
              });
              
              ds.add({ one: 3, two: 9 });
              You can edit the code in this block and rerun it.

Miso.Dataset.Importers

To specify a custom importer during dataset instantiation, just set the importer property to the class name of the importer you want. Some importers require custom properties. This section will document the properties you can set that will either cause this importer to be selected or will be required by it to continue.

Built in Importers include:

Miso.Dataset.Importers.Local
Miso.Dataset.Importers.Remote
Miso.Dataset.Importers.Polling
Miso.Dataset.Importers.GoogleSpreadsheet

An importer must implement the following interface:

              Miso.Dataset.Importers.MyCustomImporter = function(options) {
                // save your options
                // overwrite 'extract' function if you want
                // but don't forget users can overwrite that when
                // instantiating a new Dataset.
              };
              
              _.extend(
                Miso.Dataset.Importers.MyCustomImporter.prototype, 
                Miso.Dataset.Importers.prototype, 
                {
                  
                  // required method fetch must be defined.
                  // options should have a success and error callback.
                  // On successful data retrieval, the fetch should call
                  // the success callback with the returned data.
                  fetch : function(options) {
                    
                    // retrieve data
                    //    ....
              
                    // if data is successfully returned, pass it to
                    //    options.success like so:
                    options.success( this.extract(data) );
                  }
                }
              );

Miso.Dataset.Importers.Local

Import local data already in the environment

            var ds = new Miso.Dataset({
              data: [ 
                { one : 1, two : 4, three : 7 },
                { one : 2, two : 5, three : 8 }
              ]
            });
            
            ds.fetch({
              success: function() {
                log( this.column('two').data );
              }
            });
            
            You can edit the code in this block and rerun it.

new Miso.Dataset.Importers.Local( options )

Returns: Miso.Dataset.Importers

Parameters

options Object optional

Options object
- data Array optional
  
  local object containing your data

Miso.Dataset.Importers.Remote

Import data from remote files via an AJAX request

            var ds = new Miso.Dataset({
              url: '/data/simple.json'
            });
            
            ds.fetch({
              success: function() {
                log( this.column('two').data );
              }
            });
            You can edit the code in this block and rerun it.

new Miso.Dataset.Importers.Remote( options )

Returns: Miso.Dataset.Importers

Parameters

options Object optional

Options object
- url string optional
  
  url from which to fetch data
- jsonp Boolean optional
  
  Set to true for jsonp requests

Miso.Dataset.Importers.Polling

Pull data from a remote source on a regular interval

            var requests = 5, 
                madeRequests = 0;
            
            // query twitter for tweets containing the term "javascript"
            // and get 5 per page. Note that twitter uses jsonp requests, 
            // so we toggle that flag too.
            var ds = new Miso.Dataset({
              url : "http://search.twitter.com/search.json?q=javascript&rpp=5&callback=",
              interval : 1000,
              jsonp : true,
              // Because of the structure of tweets:
              // https://dev.twitter.com/docs/api/1/get/search
              // we actually extract the rows from the returned data first.
              extract : function(data) {
                return data.results;
              }
            });
            
            ds.fetch({
              success : function() {
                // track how many requests we've made
                madeRequests++;
                // If we reached our max
                if (madeRequests >= requests) {
                  // stop the importer.
                  this.importer.stop();
                  // output our current collection of tweets
                  log(ds.column("text").data);
                }
                // update the number of rows we now have.
                log(madeRequests, ds.length);
              }
            });
            You can edit the code in this block and rerun it.

new Miso.Dataset.Importers.Polling( options )

Returns: Miso.Dataset.Importers

Parameters

options Object optional

Options object
- interval Integer optional
  
  Frequency (in milliseconds) with which to fetch data

Miso.Dataset.Importers.GoogleSpreadsheet

Import directly from google spreadsheets, see the Google Spreadsheets guide.

new Miso.Dataset.Importers.GoogleSpreadsheet( options )

Returns: Miso.Dataset.Importers

Parameters

options Object optional

Options object
- key string required
  
  The google spreadsheet key
- worksheet String optional
  
  An optional worksheet id. Default is always first worksheet.
- fast boolean optional
  
  An optional flag to enable faster parsing. See the Google Spreadsheets guide for more information about this flag.
- sheetName String optional
  
  If enabling faster parsing with fast flag, instead of using worksheet to designate the sheet index, you can use sheetName to access spreadsheet by name. Default is "Sheet1".

Miso.Dataset.Parsers

To specify a custom parser, during dataset instantiation set the parser property to the class name of the parser you want. Some parsers require some custom properties. This section will document the properties you can set that will either cause this parser to be selected or will be required by it to continue.

Built in Parsers include:

Miso.Dataset.Parsers.Strict
Miso.Dataset.Parsers.Object
Miso.Dataset.Parsers.Delimited
Miso.Dataset.Parsers.GoogleSpreadsheet

The base Miso.Parser structure is:

              // Pass in the data you'll be parsing
              // Take in any potential options you might need for your parser
              Miso.Dataset.Parsers.MyCustomParser = function(data, options) {};
              
              _.extend(
                Miso.Dataset.Parsers.MyCustomParser.prototype, 
                Miso.Dataset.Parsers.prototype, 
                {
                  // required method parse must be defined:
                  parse : function(data) {
              
                    // parse the data here
                    // ...
              
                    // return the following structure:
                    return {
                      // an array of column names in the order they are in
                      // for example: ["state", "population", "amount"]
                      columns : arrayOfColumnNames,
              
                      // an object conainint the data, keyed by column names
                      // for example:
                      // {
                      //  state : [ "AZ", "AL", "MA" ],
                      //  population : [ 1000, 2000, 3000],
                      //  amount : [12,45,34]
                      // }
                      data : dataObject
                    };
                  }
                }
              );

Miso.Dataset.Parsers.Strict

strict - Set this to true when initializing a dataset to indicate the default internal format should be used.

Miso.Dataset.Parsers.Object

The object parser expects an array of objects where each key is the column name.

data - The local var containing the data to be parsed.

Miso.Dataset.Parsers.Delimited

delimiter - The string that is delimiting the column values.

Note: The delimited parser will assign custom column names in case the header row exists, but has missing values. They will be of the form XN where N starts at 0.

Miso.Dataset.Column

Miso.Dataset.Column objects make up the columns contained in a dataset and are returned by some methods such as .column on Miso.Dataset and Miso.Dataset.DataView

new Miso.Dataset.Column( options )

Returns: Miso.Dataset.Column

Returns a new column.

              var col = new Miso.Dataset.Column({ 
                name: 'inoculated', 
                type: 'boolean', 
                data: [true, false, false, true] 
              });
              
              log(col.data);You can edit the code in this block and rerun it.

Parameters

options Object required

Options object
- name String required
  
  Column name
- type String optional
  
  Column type
- before Function optional
  
  A function to pre-process a column's value before it is coerced. Signature is function(value)
- format String optional
  
  Optional. Only set if time type. The moment.js format describing the input dates.
- id Integer optional
  
  Sets a custom column _id. We assign one by default.
- data Object optional
  
  A set of data. By default, set to an empty array.

Instance Methods

col.numericAt( index )

Returns: Number

Internal function used to return the numeric value of a given input in a column. Index is used as this is currently the return value for numeric coercion of string values.

              var col = new Miso.Dataset.Column({ 
                name: 'inoculated', 
                type: 'boolean', 
                data: [true, false, false, true] 
              });
              
              log (col.numericAt(0));
              log (col.numericAt(1));You can edit the code in this block and rerun it.

Parameters

index Integer optional

index position of the row you want the numeric value for

col.coerce()

Returns: undefined

Coerces all the data in the column's data array to the appropriate type.

              var col = new Miso.Dataset.Column({ 
                name: 'amount', 
                type: 'number', 
                data: [2, 3, '4'] 
              });
              
              log (col.data);
              col.coerce();
              log (col.data);You can edit the code in this block and rerun it.

Miso.Dataset.types

Miso types are used to set and manage the data types on columns. These sets of functions handle testing what type data is and coercing it into the correct format for a given type. The type system is completely extensible, making it easy to create rich custom types for your data when it would be helpful to do so. All types must have the following interface.

            // all types live under the Miso.types namespace.
            // Beware of overriding existing types. 
            // Nothing is stopping you from doing that.
            Miso.Dataset.types.yourCustomType = {
            
              // provide a name for your type.
              name : 'yourCustomTypeName',
            
              // provide a method to test any incoming value for whether it
              // fits within the scope of this type.
              // return true if value is of this type. False otherwise.
              test : function(value) {},
            
              // provide a way to compare two values. This will be used by
              // the sorting algorithm, so be sure to return the correct values:
              // -1 if value1 < value2
              // 1 if value1 > value2
              // 0 if they are equal.
              compare : function(value1, value2) {},
            
              // how would this value be represented numerically? For example
              // the numeric value of a timestamp is its unix millisecond value.
              // This is used by the various computational functions of columns
              // (like min/max.)
              numeric : function(value) {},
            
              // convert an incoming value into this specific type.
              // should return the value as would be represented by this type.
              coerce : function(value) {}
            };

Miso.Dataset.typeOf( value, options )

Returns: String

Typeof tests the type of a given input against the registered Miso types and returns the closest match.

              log(Miso.Dataset.typeOf('foo'));
              log(Miso.Dataset.typeOf(true));
              log(Miso.Dataset.typeOf(4.3453));You can edit the code in this block and rerun it.

Parameters

value Any optional

The value to test
options Object optional

Options object
- format String optional
  
  For time type only. Describes the format.

Miso.Dataset.types.mixed

Miso types are used to set and manage the data types on columns. These sets of functions handle testing what type data is and coercing it into the correct format for a given type. The type system is completely extensible, making it easy to create rich custom types for your data when it would be helpful to do so.

Miso.Dataset.types.mixed.name()

Returns: string

Returns the name of the mixed type, ie 'mixed'. Used internally.

Miso.Dataset.types.mixed.coerce( value )

Returns: Any

Coerces the value, given the is the mixed type it's a passthrough.

Parameters

value Any optional

Value to be coerced

Miso.Dataset.types.mixed.test( value )

Returns: true

Tests whether the value is of the given type. Given this is the mixed type it will always be true

Parameters

value Any optional

Value to be tested

Miso.Dataset.types.mixed.compare( value1, value2 )

Returns: Integer

Compares two mixed type values

Parameters

value1 Any optional

First value to be compared
value2 Any optional

Second value to be compared

Miso.Dataset.types.mixed.numeric( value )

Returns: Integer

Returns the numeric representation of a mixed value. If it's an integer, then it coerces it. Otherwise it returns 0.

Parameters

value Any optional

Value to be coerced to numeric

Miso.Dataset.types.string

The string type is used for columns of strings (shocking, I know).

Miso.Dataset.types.string.name()

Returns: string

Returns the name of the string type, ie 'string'. Used internally.

Miso.Dataset.types.string.coerce( value )

Returns: Any

Coerces the value to a string.

Parameters

value Any optional

Value to be coerced

Miso.Dataset.types.string.test( value )

Returns: true

Tests whether the value is a string.

Parameters

value Any optional

Value to be tested

Miso.Dataset.types.string.compare( value1, value2 )

Returns: Integer

Compares two string type values

Parameters

value1 Any optional

First value to be compared
value2 Any optional

Second value to be compared

Miso.Dataset.types.string.numeric( value, indexPosition )

Returns: Integer

Returns the numeric representation of a string value - returns the indexPosition HACKHACKHACK.

Parameters

value Any optional

Value to be coerced to numeric
indexPosition Integer optional

Column position of string value, is the value that will be returned.

Miso.Dataset.types.number

The number type is used for columns of numbers.

Miso.Dataset.types.number.name()

Returns: number

Returns the name of the number type, ie 'number'. Used internally.

Miso.Dataset.types.number.coerce( value )

Returns: Any

Coerces the value to a number, a passthrough.

Parameters

value Any optional

Value to be coerced

Miso.Dataset.types.number.test( value )

Returns: true

Tests whether the value is a number.

Parameters

value Any optional

Value to be tested

Miso.Dataset.types.number.compare( value1, value2 )

Returns: Integer

Compares two number type values

Parameters

value1 Any optional

First value to be compared
value2 Any optional

Second value to be compared

Miso.Dataset.types.number.numeric( value, indexPosition )

Returns: Integer

Returns the numeric representation of a number which will be..the number.

Parameters

value Any optional

Value to be coerced to numeric

Miso.Dataset.types.boolean

The boolean type is used for columns of true/false booleans.

Miso.Dataset.types.boolean.name()

Returns: boolean

Returns the name of the boolean type, ie 'boolean'. Used internally.

Miso.Dataset.types.boolean.coerce( value )

Returns: Any

Coerces the value to a boolean, uses javascript truthy/falsy.

Parameters

value Any optional

Value to be coerced

Miso.Dataset.types.boolean.test( value )

Returns: true

Tests whether the value is a boolean.

Parameters

value Any optional

Value to be tested

Miso.Dataset.types.boolean.compare( value1, value2 )

Returns: Integer

Compares two boolean type values

Parameters

value1 Any optional

First value to be compared
value2 Any optional

Second value to be compared

Miso.Dataset.types.boolean.numeric( value, indexPosition )

Returns: Integer

Returns the numeric representation of a boolean value - false is 0, true 1.

Parameters

value Any optional

Value to be coerced to numeric
indexPosition Integer optional

Column position of boolean value, is the value that will be returned.

Miso.Dataset.types.time

The time type is used for columns of dates & timestamps, this uses %a{ :href => 'http://momentjs.com/'} moment.js internally and returns moment objects.

Miso.Dataset.types.time.name()

Returns: time

Returns the name of the time type, ie 'time'. Used internally.

Miso.Dataset.types.time.coerce( value, options )

Returns: Any

Coerces the value to a time.

Parameters

value Any optional

Value to be coerced
options Object optional

Options object
- format String optional
  
  Time format. See %a{ :href => 'http://momentjs.com/'}Moment.js documentation.

Miso.Dataset.types.time.test( value )

Returns: Boolean

Tests whether the value is a time.

Parameters

value Any optional

Value to be tested

Miso.Dataset.types.time.compare( value1, value2 )

Returns: Integer

Compares two time type values

Parameters

value1 Any optional

First value to be compared
value2 Any optional

Second value to be compared

Miso.Dataset.types.time.numeric( value, indexPosition )

Returns: Integer

Returns the numeric representation of a time which will be an epoch time.

Parameters

value Any optional

Value to be coerced to numeric