## perspective The main API module for Perspective. * [perspective](#module_perspective) * [~view](#module_perspective..view) * [new view()](#new_module_perspective..view_new) * [.get_config()](#module_perspective..view+get_config) ⇒ object * [.delete()](#module_perspective..view+delete) * [.schema()](#module_perspective..view+schema) ⇒ Promise.<Object> * [.to_columns([options])](#module_perspective..view+to_columns) ⇒ Promise.<Array> * [.to_json([options])](#module_perspective..view+to_json) ⇒ Promise.<Array> * [.to_csv([options])](#module_perspective..view+to_csv) ⇒ Promise.<string> * [.col_to_js_typed_array(column_name)](#module_perspective..view+col_to_js_typed_array) ⇒ Promise.<TypedArray> * [.to_arrow([options])](#module_perspective..view+to_arrow) ⇒ Promise.<TypedArray> * [.num_rows()](#module_perspective..view+num_rows) ⇒ Promise.<number> * [.num_columns()](#module_perspective..view+num_columns) ⇒ Promise.<number> * [.get_row_expanded()](#module_perspective..view+get_row_expanded) ⇒ Promise.<bool> * [.expand()](#module_perspective..view+expand) ⇒ Promise.<void> * [.collapse()](#module_perspective..view+collapse) ⇒ Promise.<void> * [.set_depth()](#module_perspective..view+set_depth) * [.on_update(callback)](#module_perspective..view+on_update) * [.on_delete(callback)](#module_perspective..view+on_delete) * [~table](#module_perspective..table) * [new table()](#new_module_perspective..table_new) * [.clear()](#module_perspective..table+clear) * [.replace()](#module_perspective..table+replace) * [.delete()](#module_perspective..table+delete) * [.on_delete(callback)](#module_perspective..table+on_delete) * [.size()](#module_perspective..table+size) ⇒ Promise.<number> * [.schema(computed)](#module_perspective..table+schema) ⇒ Promise.<Object> * [.computed_schema()](#module_perspective..table+computed_schema) ⇒ Promise.<Object> * [.is_valid_filter([filter])](#module_perspective..table+is_valid_filter) ⇒ boolean * [.view([config])](#module_perspective..table+view) ⇒ view * [.update(data)](#module_perspective..table+update) * [.remove(data)](#module_perspective..table+remove) * [.add_computed(computed)](#module_perspective..table+add_computed) * [.columns(computed)](#module_perspective..table+columns) ⇒ Array.<string> * [.column_metadata()](#module_perspective..table+column_metadata) ⇒ Array.<object> * * * ### perspective~view **Kind**: inner class of [perspective](#module_perspective) * [~view](#module_perspective..view) * [new view()](#new_module_perspective..view_new) * [.get_config()](#module_perspective..view+get_config) ⇒ object * [.delete()](#module_perspective..view+delete) * [.schema()](#module_perspective..view+schema) ⇒ Promise.<Object> * [.to_columns([options])](#module_perspective..view+to_columns) ⇒ Promise.<Array> * [.to_json([options])](#module_perspective..view+to_json) ⇒ Promise.<Array> * [.to_csv([options])](#module_perspective..view+to_csv) ⇒ Promise.<string> * [.col_to_js_typed_array(column_name)](#module_perspective..view+col_to_js_typed_array) ⇒ Promise.<TypedArray> * [.to_arrow([options])](#module_perspective..view+to_arrow) ⇒ Promise.<TypedArray> * [.num_rows()](#module_perspective..view+num_rows) ⇒ Promise.<number> * [.num_columns()](#module_perspective..view+num_columns) ⇒ Promise.<number> * [.get_row_expanded()](#module_perspective..view+get_row_expanded) ⇒ Promise.<bool> * [.expand()](#module_perspective..view+expand) ⇒ Promise.<void> * [.collapse()](#module_perspective..view+collapse) ⇒ Promise.<void> * [.set_depth()](#module_perspective..view+set_depth) * [.on_update(callback)](#module_perspective..view+on_update) * [.on_delete(callback)](#module_perspective..view+on_delete) * * * #### new view() A View object represents a specific transform (configuration or pivot, filter, sort, etc) configuration on an underlying [table](#module_perspective..table). A View receives all updates from the [table](#module_perspective..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](#module_perspective..view+delete) method is called. Note This constructor is not public - Views are created by invoking the [view](#module_perspective..table+view) method. **Example** ```js // Returns a new View, pivoted in the row space by the "name" column. table.view({row_pivots: ["name"]}); ``` * * * #### view.get\_config() ⇒ object A copy of the config object passed to the [table#view](table#view) method which created this [view](#module_perspective..view). **Kind**: instance method of [view](#module_perspective..view) **Returns**: object - Shared the same key/values properties as [view](#module_perspective..view) * * * #### view.delete() Delete this [view](#module_perspective..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](#module_perspective..view) * * * #### view.schema() ⇒ Promise.<Object> The schema of this [view](#module_perspective..view). A schema is an Object, the keys of which are the columns of this [view](#module_perspective..view), and the values are their string type names. If this [view](#module_perspective..view) is aggregated, theses will be the aggregated types; otherwise these types will be the same as the columns in the underlying [table](#module_perspective..table) **Kind**: instance method of [view](#module_perspective..view) **Returns**: Promise.<Object> - A Promise of this [view](#module_perspective..view)'s schema. * * * #### view.to\_columns([options]) ⇒ Promise.<Array> Serializes this view to JSON data in a column-oriented format. **Kind**: instance method of [view](#module_perspective..view) **Returns**: Promise.<Array> - A Promise resolving to An array of Objects representing the rows of this [view](#module_perspective..view). If this [view](#module_perspective..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](#module_perspective..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. * * * #### view.to\_json([options]) ⇒ Promise.<Array> Serializes this view to JSON data in a row-oriented format. **Kind**: instance method of [view](#module_perspective..view) **Returns**: Promise.<Array> - A Promise resolving to An array of Objects representing the rows of this [view](#module_perspective..view). If this [view](#module_perspective..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](#module_perspective..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. * * * #### view.to\_csv([options]) ⇒ Promise.<string> Serializes this view to CSV data in a standard format. **Kind**: instance method of [view](#module_perspective..view) **Returns**: Promise.<string> - A Promise resolving to a string in CSV format representing the rows of this [view](#module_perspective..view). If this [view](#module_perspective..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](#module_perspective..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](https://www.papaparse.com/docs#json-to-csv) config object. * * * #### view.col\_to\_js\_typed\_array(column_name) ⇒ Promise.<TypedArray> Serializes a view column into a TypedArray. **Kind**: instance method of [view](#module_perspective..view) **Returns**: Promise.<TypedArray> - A promise resolving to a TypedArray representing the data of the column as retrieved from the [view](#module_perspective..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. * * * #### view.to\_arrow([options]) ⇒ Promise.<TypedArray> Serializes a view to arrow. **Kind**: instance method of [view](#module_perspective..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. * * * #### view.num\_rows() ⇒ Promise.<number> The number of aggregated rows in this [view](#module_perspective..view). This is affected by the "row_pivots" configuration parameter supplied to this [view](#module_perspective..view)'s contructor. **Kind**: instance method of [view](#module_perspective..view) **Returns**: Promise.<number> - The number of aggregated rows. * * * #### view.num\_columns() ⇒ Promise.<number> The number of aggregated columns in this [view](view). This is affected by the "column_pivots" configuration parameter supplied to this [view](view)'s contructor. **Kind**: instance method of [view](#module_perspective..view) **Returns**: Promise.<number> - The number of aggregated columns. * * * #### view.get\_row\_expanded() ⇒ Promise.<bool> Whether this row at index `idx` is in an expanded or collapsed state. **Kind**: instance method of [view](#module_perspective..view) **Returns**: Promise.<bool> - Whether this row is expanded. * * * #### view.expand() ⇒ Promise.<void> Expands the row at index `idx`. **Kind**: instance method of [view](#module_perspective..view) * * * #### view.collapse() ⇒ Promise.<void> Collapses the row at index `idx`. **Kind**: instance method of [view](#module_perspective..view) * * * #### view.set\_depth() Set expansion `depth` of the pivot tree. **Kind**: instance method of [view](#module_perspective..view) * * * #### view.on\_update(callback) Register a callback with this [view](#module_perspective..view). Whenever the [view](#module_perspective..view)'s underlying table emits an update, this callback will be invoked with the aggregated row deltas. **Kind**: instance method of [view](#module_perspective..view) **Params** - callback function - A callback function invoked on update. The parameter to this callback is dependent on the `mode` 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](#module_perspective..view). Whenever the [view](#module_perspective..view) is deleted, this callback will be invoked. **Kind**: instance method of [view](#module_perspective..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](#module_perspective..view+to_json). * * * ### perspective~table **Kind**: inner class of [perspective](#module_perspective) * [~table](#module_perspective..table) * [new table()](#new_module_perspective..table_new) * [.clear()](#module_perspective..table+clear) * [.replace()](#module_perspective..table+replace) * [.delete()](#module_perspective..table+delete) * [.on_delete(callback)](#module_perspective..table+on_delete) * [.size()](#module_perspective..table+size) ⇒ Promise.<number> * [.schema(computed)](#module_perspective..table+schema) ⇒ Promise.<Object> * [.computed_schema()](#module_perspective..table+computed_schema) ⇒ Promise.<Object> * [.is_valid_filter([filter])](#module_perspective..table+is_valid_filter) ⇒ boolean * [.view([config])](#module_perspective..table+view) ⇒ view * [.update(data)](#module_perspective..table+update) * [.remove(data)](#module_perspective..table+remove) * [.add_computed(computed)](#module_perspective..table+add_computed) * [.columns(computed)](#module_perspective..table+columns) ⇒ Array.<string> * [.column_metadata()](#module_perspective..table+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](#module_perspective..table) factory method, either on the perspective module object, or an a [module:perspective~worker](module:perspective~worker) instance. * * * #### table.clear() Remove all rows in this [table](#module_perspective..table) while preserving the schema and construction options. **Kind**: instance method of [table](#module_perspective..table) * * * #### table.replace() Replace all rows in this [table](#module_perspective..table) the input data. **Kind**: instance method of [table](#module_perspective..table) * * * #### table.delete() Delete this [table](#module_perspective..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](#module_perspective..table) * * * #### table.on\_delete(callback) Register a callback with this [table](#module_perspective..table). Whenever the [view](#module_perspective..view) is deleted, this callback will be invoked. **Kind**: instance method of [table](#module_perspective..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](module:perspective~table#to_json). * * * #### table.size() ⇒ Promise.<number> The number of accumulated rows in this [table](#module_perspective..table). This is affected by the "index" configuration parameter supplied to this [view](#module_perspective..view)'s contructor - as rows will be overwritten when they share an idnex column. **Kind**: instance method of [table](#module_perspective..table) **Returns**: Promise.<number> - The number of accumulated rows. * * * #### table.schema(computed) ⇒ Promise.<Object> The schema of this [table](#module_perspective..table). A schema is an Object whose keys are the columns of this [table](#module_perspective..table), and whose values are their string type names. **Kind**: instance method of [table](#module_perspective..table) **Returns**: Promise.<Object> - A Promise of this [table](#module_perspective..table)'s schema. **Params** - computed boolean - Should computed columns be included? (default false) * * * #### table.computed\_schema() ⇒ Promise.<Object> The computed schema of this [table](#module_perspective..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](#module_perspective..table) **Returns**: Promise.<Object> - A Promise of this [table](#module_perspective..table)'s computed schema. * * * #### table.is\_valid\_filter([filter]) ⇒ boolean Determines whether a given filter is valid. **Kind**: instance method of [table](#module_perspective..table) **Returns**: boolean - Whether the filter is valid **Params** - [filter] Array.<string> - A filter configuration array to test * * * #### table.view([config]) ⇒ view Create a new [view](#module_perspective..view) from this table with a specified configuration. **Kind**: instance method of [table](#module_perspective..table) **Returns**: view - A new [view](#module_perspective..view) object for the supplied configuration, bound to this table **Params** - [config] Object - The configuration object for this [view](#module_perspective..view). - [.row_pivots] Array.<string> - An array of column names to use as [Row Pivots](https://en.wikipedia.org/wiki/Pivot_table#Row_labels). - [.column_pivots] Array.<string> - An array of column names to use as [Column Pivots](https://en.wikipedia.org/wiki/Pivot_table#Column_labels). - [.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 has `row_pivots`. A column provided to `config.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". **Example** ```js 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](#module_perspective..table). Updated rows are pushed down to any derived [view](#module_perspective..view) objects. **Kind**: instance method of [table](#module_perspective..table) **See**: [table](#module_perspective..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) as this table has already been constructed, thus its types are set in stone. * * * #### table.remove(data) Removes the rows of a [table](#module_perspective..table). Removed rows are pushed down to any derived [view](#module_perspective..view) objects. **Kind**: instance method of [table](#module_perspective..table) **See**: [table](#module_perspective..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](#module_perspective..table) **Params** - computed Computation - A computation specification object * * * #### table.columns(computed) ⇒ Array.<string> The column names of this table. **Kind**: instance method of [table](#module_perspective..table) **Returns**: Array.<string> - An array of column names for this table. **Params** - computed boolean - Should computed columns be included? (default false) * * * #### table.column\_metadata() ⇒ Array.<object> 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](#module_perspective..table) **Returns**: Array.<object> - An array of Objects containing metadata for each column. * * *