Transform data

This module exports a collection of functions for transforming data (arrays of objects and arrays of arrays) that may be useful either in the visualisation editor or when using the API.

pivotObjects(input_data, headers_column, values_column)

Takes an array of objects, input_data, and two strings that should refer to properties in the input_data object. The output data is then a pivotted version of input_data with properties from the headers_column and values from the values_column. This is similar to the Excel pivot table operation and will generally turn "long" data into "wide data". It also adds a column_names property to the output array that is useful with the Flourish API.

pivotArrays(input_data, headers_index, values_index)

Takes an array of arrays, input_data, and two numbers that should refer to indexes within each inner array. The first element of input_data should contain the headers. The output data is then a pivotted version of input_data with properties from the headers_index entries and values from the values_index entries. This is similar to the Excel pivot table operation and will generally turn "long" data into "wide data".

meltObjects(input_data, melt_columns, opts)

Takes an array of objects, input_data, and an array of property names, melt_columns. The melt_columns are then used to create multiple rows for each previous row. This is the reverse operation of pivotObjects and will generally turn "wide data" into "long data". It also adds a column_names property to the output array that is useful with the Flourish API. The opts argument, if present, should be an object that can have up to three (useful) properties:
- variable_name: The name applied to the new column based on the melt_columns properties (headers);
- value_name: The name applied to the new column based on the melt_columns values;
- keep_empty_strings: If true, keeps rows that would otherwise by ignored because the associated value is an empty string.

meltArrays(input_data, melt_columns, opts)

Takes an array of arrays, input_data, and an array of indexes, melt_columns. The melt_columns are then used to create multiple rows for each previous row. The first element of input_data should contain the headers. This is the reverse operation of pivotArrays and will generally turn "wide data" into "long data". The opts argument, if present, should be an object that can have up to three (useful) properties:
- variable_name: The name given to the new column based on the melt_columns properties (headers);
- value_name: The name given to the new column based on the melt_columns values;
- keep_empty_strings: If true, keeps rows that would otherwise by ignored because the associated value is an empty string.

flourishifyObjects(input_data, column_bindings, columns_bindings)

Takes an array of objects, input_data, and up to two objects, column_bindings and columns_bindings. These two objects then act as dictionaries to transform the input_data into output data that better matches the structure used in a Flourish template. Each key of the column_bindings object should match a key of type: column in the template and the values should match keys in the input data. Similarly, each key of the columns_bindings should match a key in the template of type: columns while the values should be arrays whose elements match keys in the input data (you can also use a string in place of an array if you only want to map one column to a given key). This function will also add a column_names property to the output array.

flourishifyArrays(input_data, column_bindings, columns_bindings)

Takes an array of _arrays_, input_data, and up to two objects, column_bindings and columns_bindings. These two objects then act as dictionaries to transform the input_data into an array of _objects_ that better matches the structure used in a Flourish template and by the API. Each key of the column_bindings object should match a key of type: column in the template and the values should match indexes in the input data. Similarly, each key of the columns_bindings should match a key in the template of type: columns while the values should be arrays whose elements match indexes in the input data (you can also use a single index in place of an array if you only want to map one column to a given key). This function will also add a column_names property to the output array.

flourishify(input_data, column_bindings, columns_bindings)

Calls and returns the results of either flourishifyArrays or flourishifyObjects (passing in all arguments) based on whether input_data[0] is an array or not.

leftJoin(left_data, right_data, [options])

Expects two arrays of arrays - left_data and right_data - plus options and returns an array of arrays that is the left join of left_data and right_data. options properties are the left_index for the left_data column to join on (defaults to the last column in left_data), right_index for the right_data column to join on (defaults to the first column, index 0, in right_data), left_keep for whether to keep the left_index column in the merged data (defaults to true) and right_keep for whether to keep the right_index column in the merged data (defaults to true).

rightJoin(left_data, right_data, [options])

Expects two arrays of arrays - left_data and right_data - plus options and returns an array of arrays that is the right outer join of left_data and right_data. options properties are the left_index for the left_data column to join on (defaults to the last column in left_data), right_index for the right_data column to join on (defaults to the first column, index 0, in right_data), left_keep for whether to keep the left_index column in the merged data (defaults to true) and right_keep for whether to keep the right_index column in the merged data (defaults to true).

fullJoin(left_data, right_data, [options])

Expects two arrays of arrays - left_data and right_data - plus options and returns an array of arrays that is the full outer join of left_data and right_data. options properties are the left_index for the left_data column to join on (defaults to the last column in left_data), right_index for the right_data column to join on (defaults to the first column, index 0, in right_data), left_keep for whether to keep the left_index column in the merged data (defaults to true) and right_keep for whether to keep the right_index column in the merged data (defaults to true).

innerJoin(left_data, right_data, [options])

Expects two arrays of arrays - left_data and right_data- plus options and returns an array of arrays that is the inner join of left_data and right_data. options properties are the left_index for the left_data column to join on (defaults to the last column in left_data), right_index for the right_data column to join on (defaults to the first column, index 0, in right_data), left_keep for whether to keep the left_index column in the merged data (defaults to true) and right_keep for whether to keep the right_index column in the merged data (defaults to true).

*Join.getLastUnmatched()

The four *Join methods all have an attached getLastUnmatched method. These methods return an unmatched object giving information on rows that had no matches the last time the parent function was invoked. The unmatched object contains two properties: left and right whose values are arrays of objects. Each object in the left or right array represents an unmatched row from the appropriate left_data or right_data dataset. The properties of these objects are input_row (the row index in the input data), output_row (the row index in the output data or null if it does not appear) and the value that had no match.