perspective
The main API module for Perspective.
-
perspective
-
~view
- new view()
-
.get_config() ⇒
object
- .delete()
-
.schema() ⇒
Promise.<Object>
-
.to_columns([options]) ⇒
Promise.<Array>
-
.to_json([options]) ⇒
Promise.<Array>
-
.to_csv([options]) ⇒
Promise.<string>
-
.col_to_js_typed_array(column_name) ⇒
Promise.<TypedArray>
-
.to_arrow([options]) ⇒
Promise.<TypedArray>
-
.num_rows() ⇒
Promise.<number>
-
.num_columns() ⇒
Promise.<number>
-
.get_row_expanded() ⇒
Promise.<bool>
-
.expand() ⇒
Promise.<void>
-
.collapse() ⇒
Promise.<void>
- .set_depth()
- .on_update(callback)
- .on_delete(callback)
-
~table
- new table()
- .clear()
- .replace()
- .delete()
- .on_delete(callback)
-
.size() ⇒
Promise.<number>
-
.schema(computed) ⇒
Promise.<Object>
-
.computed_schema() ⇒
Promise.<Object>
-
.is_valid_filter([filter]) ⇒
boolean
-
.view([config]) ⇒
view
- .update(data)
- .remove(data)
- .add_computed(computed)
-
.columns(computed) ⇒
Array.<string>
-
.column_metadata() ⇒
Array.<object>
-
~view
perspective~view
Kind: inner class of perspective
-
~view
- new view()
-
.get_config() ⇒
object
- .delete()
-
.schema() ⇒
Promise.<Object>
-
.to_columns([options]) ⇒
Promise.<Array>
-
.to_json([options]) ⇒
Promise.<Array>
-
.to_csv([options]) ⇒
Promise.<string>
-
.col_to_js_typed_array(column_name) ⇒
Promise.<TypedArray>
-
.to_arrow([options]) ⇒
Promise.<TypedArray>
-
.num_rows() ⇒
Promise.<number>
-
.num_columns() ⇒
Promise.<number>
-
.get_row_expanded() ⇒
Promise.<bool>
-
.expand() ⇒
Promise.<void>
-
.collapse() ⇒
Promise.<void>
- .set_depth()
- .on_update(callback)
- .on_delete(callback)
new view()
A View object represents a specific transform (configuration or pivot, filter, sort, etc) configuration on an underlying table. A View receives all updates from the table from which it is derived, and can be serialized to JSON or trigger a callback when it is updated. View objects are immutable, and will remain in memory and actively process updates until its delete method is called.
Note This constructor is not public - Views are created by invoking the view method.
Example
// Returns a new View, pivoted in the row space by the "name" column.
table.view({row_pivots: ["name"]});
object
view.get_config() ⇒ A copy of the config object passed to the table#view method which created this view.
Kind: instance method of view
Returns: object
- Shared the same key/values properties as view
view.delete()
Delete this view and clean up all resources associated with it. View objects do not stop consuming resources or processing updates when they are garbage collected - you must call this method to reclaim these.
Kind: instance method of view
Promise.<Object>
view.schema() ⇒ The schema of this view. A schema is an Object, the keys of which are the columns of this view, and the values are their string type names. If this view is aggregated, theses will be the aggregated types; otherwise these types will be the same as the columns in the underlying table
Kind: instance method of view
Returns: Promise.<Object>
- A Promise of this view's schema.
Promise.<Array>
view.to_columns([options]) ⇒ Serializes this view to JSON data in a column-oriented format.
Kind: instance method of view
Returns: Promise.<Array>
- A Promise resolving to An array of Objects
representing the rows of this view. If this view had a
"row_pivots" config parameter supplied when constructed, each row Object
will have a "ROW_PATH" key, whose value specifies this row's
aggregated path. If this view had a "column_pivots" config
parameter supplied, the keys of this object will be comma-prepended with
their comma-separated column paths.
Params
- [options]
Object
- An optional configuration object.- .start_row
number
- The starting row index from which to serialize. - .end_row
number
- The ending row index from which to serialize. - .start_col
number
- The starting column index from which to serialize. - .end_col
number
- The ending column index from which to serialize.
- .start_row
Promise.<Array>
view.to_json([options]) ⇒ Serializes this view to JSON data in a row-oriented format.
Kind: instance method of view
Returns: Promise.<Array>
- A Promise resolving to An array of Objects
representing the rows of this view. If this view had a
"row_pivots" config parameter supplied when constructed, each row Object
will have a "ROW_PATH" key, whose value specifies this row's
aggregated path. If this view had a "column_pivots" config
parameter supplied, the keys of this object will be comma-prepended with
their comma-separated column paths.
Params
- [options]
Object
- An optional configuration object.- .start_row
number
- The starting row index from which to serialize. - .end_row
number
- The ending row index from which to serialize. - .start_col
number
- The starting column index from which to serialize. - .end_col
number
- The ending column index from which to serialize.
- .start_row
Promise.<string>
view.to_csv([options]) ⇒ Serializes this view to CSV data in a standard format.
Kind: instance method of view
Returns: Promise.<string>
- A Promise resolving to a string in CSV format
representing the rows of this view. If this view had a
"row_pivots" config parameter supplied when constructed, each row
will have prepended those values specified by this row's
aggregated path. If this view had a "column_pivots" config
parameter supplied, the keys of this object will be comma-prepended with
their comma-separated column paths.
Params
- [options]
Object
- An optional configuration object.- .start_row
number
- The starting row index from which to serialize. - .end_row
number
- The ending row index from which to serialize. - .start_col
number
- The starting column index from which to serialize. - .end_col
number
- The ending column index from which to serialize. - .config
Object
- A config object for the Papaparse https://www.papaparse.com/docs#json-to-csv config object.
- .start_row
Promise.<TypedArray>
view.col_to_js_typed_array(column_name) ⇒ Serializes a view column into a TypedArray.
Kind: instance method of view
Returns: Promise.<TypedArray>
- A promise resolving to a TypedArray
representing the data of the column as retrieved from the view - all
pivots, aggregates, sorts, and filters have been applied onto the values
inside the TypedArray. The TypedArray will be constructed based on data type -
integers will resolve to Int8Array, Int16Array, or Int32Array. Floats resolve to
Float32Array or Float64Array. If the column cannot be found, or is not of an
integer/float type, the Promise returns undefined.
Params
- column_name
string
- The name of the column to serialize.
Promise.<TypedArray>
view.to_arrow([options]) ⇒ Serializes a view to arrow.
Kind: instance method of view
Returns: Promise.<TypedArray>
- A Table in the Apache Arrow format containing
data from the view.
Params
- [options]
Object
- An optional configuration object.- .start_row
number
- The starting row index from which to serialize. - .end_row
number
- The ending row index from which to serialize. - .start_col
number
- The starting column index from which to serialize. - .end_col
number
- The ending column index from which to serialize.
- .start_row
Promise.<number>
view.num_rows() ⇒ The number of aggregated rows in this view. This is affected by the "row_pivots" configuration parameter supplied to this view's contructor.
Kind: instance method of view
Returns: Promise.<number>
- The number of aggregated rows.
Promise.<number>
view.num_columns() ⇒ The number of aggregated columns in this view. This is affected by the "column_pivots" configuration parameter supplied to this view's contructor.
Kind: instance method of view
Returns: Promise.<number>
- The number of aggregated columns.
Promise.<bool>
view.get_row_expanded() ⇒ Whether this row at index idx
is in an expanded or collapsed state.
Kind: instance method of view
Returns: Promise.<bool>
- Whether this row is expanded.
Promise.<void>
view.expand() ⇒ Expands the row at index idx
.
Kind: instance method of view
Promise.<void>
view.collapse() ⇒ Collapses the row at index idx
.
Kind: instance method of view
view.set_depth()
Set expansion depth
of the pivot tree.
Kind: instance method of view
view.on_update(callback)
Register a callback with this view. Whenever the view's underlying table emits an update, this callback will be invoked with the aggregated row deltas.
Kind: instance method of view
Params
- callback
function
- A callback function invoked on update. The parameter to this callback is dependent on themode
parameter:- "none" (default): The callback is invoked without an argument.
- "rows": The callback is invoked with the changed rows.
view.on_delete(callback)
Register a callback with this view. Whenever the view is deleted, this callback will be invoked.
Kind: instance method of view
Params
- callback
function
- A callback function invoked on update. The parameter to this callback shares a structure with the return type of to_json.
perspective~table
Kind: inner class of perspective
-
~table
- new table()
- .clear()
- .replace()
- .delete()
- .on_delete(callback)
-
.size() ⇒
Promise.<number>
-
.schema(computed) ⇒
Promise.<Object>
-
.computed_schema() ⇒
Promise.<Object>
-
.is_valid_filter([filter]) ⇒
boolean
-
.view([config]) ⇒
view
- .update(data)
- .remove(data)
- .add_computed(computed)
-
.columns(computed) ⇒
Array.<string>
-
.column_metadata() ⇒
Array.<object>
new table()
A Table object is the basic data container in Perspective. Tables are typed - they have an immutable set of column names, and a known type for each.
Note This constructor is not public - Tables are created by invoking the table factory method, either on the perspective module object, or an a module:perspective~worker instance.
table.clear()
Remove all rows in this table while preserving the schema and construction options.
Kind: instance method of table
table.replace()
Replace all rows in this table the input data.
Kind: instance method of table
table.delete()
Delete this table and clean up all resources associated with it. Table objects do not stop consuming resources or processing updates when they are garbage collected - you must call this method to reclaim these.
Kind: instance method of table
table.on_delete(callback)
Register a callback with this table. Whenever the view is deleted, this callback will be invoked.
Kind: instance method of table
Params
- callback
function
- A callback function invoked on update. The parameter to this callback shares a structure with the return type of module:perspective~table#to_json.
Promise.<number>
table.size() ⇒ The number of accumulated rows in this table. This is affected by the "index" configuration parameter supplied to this view's contructor - as rows will be overwritten when they share an idnex column.
Kind: instance method of table
Returns: Promise.<number>
- The number of accumulated rows.
Promise.<Object>
table.schema(computed) ⇒ The schema of this table. A schema is an Object whose keys are the columns of this table, and whose values are their string type names.
Kind: instance method of table
Returns: Promise.<Object>
- A Promise of this table's schema.
Params
- computed
boolean
- Should computed columns be included? (default false)
Promise.<Object>
table.computed_schema() ⇒ The computed schema of this table. Returns a schema of only computed columns added by the user, the keys of which are computed columns and the values an Object containing the associated column_name, column_type, and computation.
Kind: instance method of table
Returns: Promise.<Object>
- A Promise of this table's computed schema.
boolean
table.is_valid_filter([filter]) ⇒ Determines whether a given filter is valid.
Kind: instance method of table
Returns: boolean
- Whether the filter is valid
Params
- [filter]
Array.<string>
- A filter configuration array to test
view
table.view([config]) ⇒ Create a new view from this table with a specified configuration.
Kind: instance method of table
Returns: view
- A new view object for the supplied configuration,
bound to this table
Params
- [config]
Object
- The configuration object for this view.- [.row_pivots]
Array.<string>
- An array of column names to use as Row Pivots. - [.column_pivots]
Array.<string>
- An array of column names to use as Column Pivots. - [.columns]
Array.<Object>
- An array of column names for the output columns. If none are provided, all columns are output. - [.aggregates]
Object
- An object, the keys of which are column names, and their respective values ar ethe aggregates calculations to use when this view hasrow_pivots
. A column provided toconfig.columns
without an aggregate in this object, will use the default aggregate calculation for its type. - [.filter]
Array.<Array.<string>>
- An Array of Filter configurations to apply. A filter configuration is an array of 3 elements: A column name, a supported filter comparison string (e.g. '===', '>'), and a value to compare. - [.sort]
Array.<string>
- An Array of Sort configurations to apply. A sort configuration is an array of 2 elements: A column name, and a sort direction, which are: "none", "asc", "desc", "col asc", "col desc", "asc abs", "desc abs", "col asc abs", "col desc abs".
- [.row_pivots]
Example
var view = table.view({
row_pivots: ['region'],
columns: ["region"],
aggregates: {"region": "dominant"},
filter: [['client', 'contains', 'fred']],
sort: [['value', 'asc']]
});
table.update(data)
Updates the rows of a table. Updated rows are pushed down to any derived view objects.
Kind: instance method of table
See: table
Params
- data
Object.<string, Array>
|Array.<Object>
|string
- The input data for this table. The supported input types mirror the constructor options, minus the ability to pass a schema (Object<string, string>) as this table has already been constructed, thus its types are set in stone.
table.remove(data)
Removes the rows of a table. Removed rows are pushed down to any derived view objects.
Kind: instance method of table
See: table
Params
- data
Array.<Object>
- An array of primary keys to remove.
table.add_computed(computed)
Create a new table with the addition of new computed columns (defined as javascript functions)
Kind: instance method of table
Params
- computed
Computation
- A computation specification object
Array.<string>
table.columns(computed) ⇒ The column names of this table.
Kind: instance method of table
Returns: Array.<string>
- An array of column names for this table.
Params
- computed
boolean
- Should computed columns be included? (default false)
Array.<object>
table.column_metadata() ⇒ Column metadata for this table.
If the column is computed, the computed
property is an Object containing:
- Array
input_columns
- String
input_type
- Object
computation
.
Otherwise, computed
is undefined
.
Kind: instance method of table
Returns: Array.<object>
- An array of Objects containing metadata for each column.