# 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.