JavaScript API

class DataStore(size, config)

Creates an empty data structure

Arguments:

size (integer) – the number of rows(items) of the data structure
config (Object) – setup information for the datastore.
config.columns (Array.<Object>) – an array of column objects, specifying the metadata for data structure, see {@link DataStore#addColumn}
config.columnGroups (Array.<Object>) – an array of objetcs each has name, and a list of columns in that group
config.links (Object) – an object describing how this DataStore links with other DataStore
config.images (Object) – an object describing thumbnails which are associated with each item/row in the DataStore
config.large_iamges (Object) – an object describing large images which are associated with each item/row in the DataStore
config.offsets (Object) – an object specofying which columns can have values that can be transformed and rotated and any transformations/ rotations appplied to them

DataStore.addColumn(column, data, dirty=false)

Adds a column’s metadata and optionally it’s data to the DataStore

Arguments:

column (Object) – An object describing the column
column.field (string) – the id of the column - used internally
column.name (string) – the human readable column label
column.datatype (string) – the datatype- can be one of <ul> <li> double - any floating point data </li> <li> integer - any integer data </li> <li> text - data containing strings but with no more than 256 categories </li> <li> unique - data contianing strings but with many categories </li> <li> multitext - </ul>
column.editable (boolean) – whether the column’s data can be changed
column.is_url (boolean) – the column’s values will be displayed as links (text and unique columns only)
column.values (Array.<string>) – Only required for text columns, where the index of the array should match the value in the data
column.colors (Array.<string>) – An array of rgb hex colors. In the case of a text column the colors should match the values. For number columns, the list represents colors that will be interpolated. If not suplied default color pallettes will be supplied
column.minMax (Array.<number>) – the min max values in the column’s values (integer/double only)
column.quantiles (object) – an object describing the 0.05,0.01 and 0,001 qunatile ranges (integer/double only)
column.colorLogScale (boolean) – if true then the colors will be displayed on a log scale- useful if the dataset contains outliers. Because a symlog scale is used the data can contain 0 and negative values
data (SharedArrayBuffer|Array) – In the case of a double/integer (number) column, the array buffer should be the appropriate size to contain float32s. For text it should be Uint8 and contain numbers corresponding to the indexes in the values parameter. For a column of type unique it should be a JavaScript array. This parameter is optional as the data can be added later see {@link DataStore#setColumnData}
dirty (boolean) – if true then the store will keep a record that this column has been added and is not permanently stored in the backend

DataStore.addListener(id, listener)

Adds a listener to the datastore that will be called when an event occurs, passing the event type and any data. There are the following different types of event:- <ul>

<li> filtered - called when a filter is applied. The dimension doing the the filtering is passed as data </li> <li> data_highlighted - called when certain indexes have been highlighted </li> <li> column_removed - called just before a column is removed </li> <li> data_changed- called when data has changed giving a list of columns where the data has changed </li>

</ul>

Arguments:

id (string) – a unique id identifying the listener
listener (function) – a function that accepts two paramaters, the type of event and the data associated with it.

DataStore.dataChanged(columns, is_dirty=true)

This method should be called if the any data has been modified, specifiying the columns involved. Any dimensions will re-filter if necessary i.e. if the modified columns are involved in the filter and single filtered event will be broadcast. All ‘data_changed’ listeners will be informed with the columns changed and whether filtering has already occurred (in which case updating may have already occurred if the object listening to data changes also listens to filtered events)

Arguments:

columns (Array.<string>) – a list of column/fields whose data has been modified
is_dirty (boolean) – if false (default is true) then the column will not be tagged as dirty. This my be the case if the change was pulled from the backend for example

DataStore.dataHighlighted(indexes, source)

This method calls any listeners to ‘highlight’ any rows specified e.g rows in a table or points in a scatter plot

Arguments:

indexes (array) – an array of indexes to items that should be highlighted
source (object) – the obect doing the highlighting

DataStore.getColorForCategory(column, cat)

For a given column will returns the given color for that category

Arguments:

column (string) – the coloumn’s field/id
cat (string) – the category

Returns:

string – - the hex value of the color

DataStore.getColorFunction(column, config)

Returns a function which gives the appropriate color for the value of the specified column, when supplied with the index of a row/item in the datastore,

Arguments:

column (string) – The column id(field) to use for the function . Can be null, if useValue = true i.e. the functions will be supplied with a value rather than an index
config (object) – An optional config with extra parameters
config.bins (integer) – For columns with continuous data (doubles/integers), bins are calculated across the data range so that only a limited number of color values need to be calculated. The default is 100, although it can be altered here.
config.asArray (boolean) – By default the, function will return a JavaScript compatible string specifying the color. If asArray is true then an array of length 3 containing RGB values will be returned.
config.overideValues (object) – an object containing values to use, instead of the columns default values - can include <ul> <li> min - the minumum value </li> <li> max - the maximum value </li> <li> colors - the color scheme to use </li> <li> colorLogScale- whether to use a log scale </li> </ul
config.useValue (boolean) – The returned function will require the columns value, not index
config.datatype (string) – Only required if a column is not supplied

Returns:

function – The function, which when given a row index (or value if this was specified) will return a color.

DataStore.getColorLegend(column, config)

Makes a color bar/legend based on the give column

Arguments:

column (string) – the field/id of the column
config (object) – see [here]{@link DataStore#getColorFunction}

Returns:

HMTLElemnt – - a color bar or color legend

DataStore.getColumnColors(column, config)

Returns the colors that the column uses or default ones if none have been set

Arguments:

column (string) – the column’s field or id
config (object) – see see [here]{@link DataStore#getColorFunction}

Returns:

Array.<string> – An array of colors. For text/multitext, the colors will correspond to the column’s values. For double/integers it will contain binned values fron the min to max value

DataStore.getColumnIndex(column)

Gets an object whose keys contains the supplied column’s values pointing to the row’s index. Only for text and unique columns. Will give unpredictable results if a value is present more than once in the column. The index is cached, so calling multiple times will not affect performance.

Arguments:

column (Array.<string>) – The column’s field/id

Returns:

object – An object whose keys are the columns values which point to the row’s index

DataStore.getColumnList(filter=null, addNone=false)

returns a list of column name and fields (which have data) sorted by name

Arguments:

filter (Array|string) – can be either be a string -‘number’, ‘all’ or a column type. Or an array of column types
addNone (boolean) – if true then an extra object will be added to the list with name ‘None’ and field ‘__none__’

Returns:

Array.<Object> – An array of objects containing name,field and datatype properties. The columns are ordered by main columns followed by subgroups. Each group is ordered alphabetically

DataStore.getColumnQuantile(column, per)

Returns the n and 1-n qauntile values where n is the given percentile If no percentile is passed or is ‘all’ than the column’s max/min value will be returned

Arguments:

column (string) – the column’s field/id
per (string) – the percentile - either 0.001.0.01 or 0.05

Returns:

Array.<number> – - the n and 1-n percentiles

DataStore.getDataAsBlob(columns, rows="all", delimiter="'\\t'")

Gets a text file blob of the data which can be downloaded

Arguments:

columns (Array.<string>) – A list of column fields/ids to create the file with
rows (string|Array.<int>) – a value of ‘filtered’ will only add filtered rows, alternatively a list of row indexes can be given. Any other value will result
delimiter (string) – The column delimiter to use
delimiter – The newline delimiter default ‘n’

Returns:

Blob – A data blob which can be downloaded

DataStore.getDimension(type)

Creates and returns a dimension that it used to filter and group the data

Arguments:

type (string) – the dimension type , the built in dimensions are ‘category_dimension’ for text columns and ‘range_dimension’ for number columns

Returns:

Dimension – A dimension that can be used for grouping/filtering

DataStore.getFilter()

Returns the current filter, which is just an array corresponding to the index of the row, which contains 0 if it is present or greater than 0 if it has been filtrered out. Do not modify the array. To check if an row is filtered use {@link DataStore#isRowFiltered}

Returns:: Uint8Array –

DataStore.getFilteredValues(column)

Return an array of containing all the filterd values for the specified column - inefficent for large data sets

Arguments:

column (string) – the column’s field.id

Returns:

Array.<string>|Array.<number> – An array pf filtered valaues

DataStore.getFirstFilteredIndex()

Returns the index of the first filtered item - slow

Returns:: the index of the first filtered iten

DataStore.getHighlightedData()

Returns:: array – The indexes of items that have been highligted

DataStore.getMinMaxForColumn(column)

Returns the min/max values for a given column

Arguments:

column (string) – The column id(field)

Returns:

Array.<number> – An array - the first value being the min value and the second the max value

DataStore.getRowAsObject(index)

Returns an object, representing the row/item containing key/value pairs for all columns. As an object is created, this method is slow, so it is advisable not to use it for many rows at once.

Arguments:

index (integer) – The index of the row

Returns:

Object – An object containg key(field)/value pairs. An extra variable ‘index’ contianing the row index is also added to the object

DataStore.getRowText(index, column)

Returns the value for the given row index and column

Arguments:

index (integer) – the index of the row,
column (string) – the columns’s field/id

Returns:

string|number – - the vaule for the given index and field

DataStore.getSuggestedValues(text, column, number=10)

This method will return (case insensitive) any values in the column which contain the specified text (unique/text/multitext columns only)

Arguments:

text (*) – the query value
column (*) – the column to query
number (*) – the maximum number of results to return

Returns:

Array.<object> – An array of objects with <ul> <li>value- the actual text match </li> <li>index - for unique columns, the row index and for text/multitext its index in the column’s values array</li> </ul>

DataStore.getValueToColor(column)

This method returns an object whose keys are categories and values are the colors of the categories

Arguments:

column (string) – The column id(field) (only text/multitext columns)

Returns:

object – an object of values to colors

DataStore.isFiltered()

Returns:: boolean – - true if the DataStore has been filtered

DataStore.isRowFiltered(index)

Returns true if the row is in the filter and false if it has been filtered out

Arguments:

index (integer) – The index of the row

Returns:

boolean – whether the row has been filtered out

DataStore.removeAllFilters(): Removes all filters from the datastore, More efficient than removing each filter individuallu Filters oo dimnensions with a noclear property will not be removed

DataStore.removeColumn(column, dirty=false, notify=false)

Removes the column and all its data

Arguments:

column (string) – the columns id/field
dirty (boolean) – if true, tags that the column should also be removed from the backend
notify (boolean) – if true notifies any listeners that the column has been removed

DataStore.removeListener(id)

Removes the specified listener from the datastore

Arguments:

id (string) – The id of the listener to remove

DataStore.resetColumnOffsets(filter, group, update)

resets the columns offsets to default values

Arguments:

filter (sring) – the filter value - or null if no filter
group (string) – The group/category to reset
update (boolean) – whether to inform listeners data has changed

DataStore.setAllColumnsClean(): Specify that all data (and metadata) has beem synched with the backend

DataStore.setColumnColors(column, colors, notify=false)

Changes the columns current colors

Arguments:

column (string) – the column’s field or id
colors (Array.<string>) – the column’s new colors
notify (booles) – notify any listeners that the data has changed

DataStore.setColumnData(column, data)

Adds data to the store for the specified column. If the data is a JavaScript array, then it will be converted to the correct internal data structures and the only previously supplied metadata required are field, name and datatype. If the data is a shared array buffer then, the data should be in the correct format see [columns]{@tutorial datasource}

Arguments:

column (string) – The field/id of the column.
data (SharedArrayBuffer|Array) – either a javascript array or shared array buffer

DataStore.setColumnIsDirty(col): Tag that the colunm’s data has changed and is not synched with the backend

DataStore.setColumnOffset(data, update)

Sets the columns offsets

Arguments:

data (object) – information about offset/rotation (should only contain offsets or rotation)
data.filter (string) – if the offsets have a background filter - the value for this filter
data.group (string) – the group (category) to offset
data.rotation (number) – The amount to rotate (in degrees)
data.offset (Array.<number>) – The x, y offset values
update (boolean) – update all dependants - default is false

DataStore.triggerFilter(): Broadcast a filter event to all listeners