@flourish/enhanced-arrays

Flourish enhaced arrays

The purpose of this module is to make working with collections of data of a single type (string, numeric, datetime) simpler. Each "enhanced array" is an immutable object which is created with a fixed set of values. The properties and methods on the array object then give the user easy access to properties, subsets and transformations of the data without the need for them to draw in additional libraries.

How to install

npm install @flourish/enhanced-arrays;

How to create an enhanced array

Import the relevant creater functions from the module...

import {
	createNumericArray, createDatetimeArray, createStringArray
} from @flourish/enhanced-arrays;

then create an enhanced array object by calling them with aregular array of data of the relevant type.

const dates = [new Date(2022-02-02), new Date(2022-02-02), new Date(2023-02-01)];
const numbers = createNumericArray([1, 5, 6, 4, 8, 5]);
const strings = createStringArray('a', "boat", "21", "boat");
const dates = createDatetimeArray(dates);

You can also call supply an accessor function to extract or transform transform the data from the input area:

const things = [{x: "coats", y: 7}, {x: "hats", y: 10}, {x: "boots", y: 6} ];
const more_numbers = createNumericArray(things, d => d.y);

Any element passed to a creater function that is of the wrong type (after the accessor function is applied, if used) will be rejected. These values will not be used in any calculations and there values will not be stored in the enhanced arrays. However, their indexes from the original input array will still be available through a dropped_indexes property that returns a frozen array of these indexes.

const other_things = [{x: "cat", y: 5}, {x: "dog", y: 4}, {x: "mouse", y: "two"} ];
const yet_more_numbers = createNumericArray(other_things, d => d.y);
console.log(yet_more_things.dropped_indexes); // [2];

Properties of enhanced arrays

datetime_array

true for datetime arrays. undefined for numeric and string arrays.

dropped_indexes

The indexes of all values from the input array (or the array created after running the accessor function on the input array) that were dropped because they were of the wrong type.

enhanced_array

true for all enhanced arrays.

length

The number of values in the stored array. This is the length of the input array minus the number of values that were rejected for being of the wrong type.

max

The largest value in a numeric array, the latest timestamp in a datetime array and the last string alphabetically in a string array.

mean

The (arithmetic) mean value in a numeric or datetime array. undefined for a string array.

median

The median value in a numeric or datetime array. undefined for a string array.

min

The smallest value in a numeric array, the earliest timestamp in a datetime array and the first string alphabetically in a string array.

n_empty

The number of empty string ("") in a string array. undefined for numeric and datetime arrays.

numeric_array

true for all numeric arrays. undefined for datetime and string arrrays.

range

The difference between the max and in min values in a numeric array. undefined for datetime and string arrays.

sd

The (sample) standard deviation of the values in a numeric array. undefined for datetime and string arrays.

sorted_values

A frozen array of all values stored in the enhanced array, in ascending order. For numeric arrays this means numeric sorting (eg 2 before 10), for string arrays this means alphabetical/lexical sorting (eg "10" before "2" but after "1") and for datetimes that means the earliest date appears first.

sum

The sum of all entries in a numeric array. undefined for datetime and string arrays.

string_array

true for all string arrays. undefined for all numeric and datetime arrays.

values

A frozen array of all values stored in the enhanced array following the order of the input array.

variance

The (sample) variance of the values in a numeric array. undefined for datetime and string arrays.

Methods of enhanced arrays

ascending()

Returns an array of the stored values, sorted in ascending order. The result of calling this method is different from the sorted_values property in that the array returned is a not frozen and can be altered.

descending()

Returns an array of the stored values, sorted in descending order.

extent()

Returns a two-element array describing the extent of the data, ie [min, max].

rank([lowest_first [, ties_method])

Returns a map of the stored values to their rank as outlined in the arguments to the funciton call. By default values will be ranked largest to smallest (numeric), last to first (datetime) or latest alphabetically to earliest alphabetically (string). If lowest_first is truthy then then this ranking system will be reversed. The ties_method determines the rank in the case of ties. Recognised values are "best" (default), "worst", "dense", "fractional" and "ordinal". In the "best" case tied entries will share the lower-numbered rank (representation 1 2 2 4, assuming a tie for 2nd rank). In the "worst" case tied entries will share the higher-numbered rank (1 3 3 4). In the "dense" case tied entries will share the lower rank with the next highest ranking value taking the rank 1 above that (1 2 2 3). In the "fractional" case the possible ranks are averaged (1 2.5 2.5 4). In the "ordinal" case the tie values are arbitrairily given different ranks despite the tie (1 2 3 4). See also this Wikipedia article.

unique()

Returns an array of the stored values with duplicates removed. For datetimes, timestamps are used to determine if two-different entries are duplicates.

uniqueAscending()

Returns an array of the stored values, sorted in ascending order, with duplicates removed. For datetimes, timestamps are used to determine if two-different entries are duplicates.

uniqueDescending()

Returns an array of the stored values, sorted in ascending order, with duplicates removed. For datetimes, timestamps are used to determine if two-different entries are duplicates.

unsorted()

Returns an array of the stored values. The result of calling this method is different from the values property in that the array returned is a not frozen and can be altered.