group-into-intervals

v1.1.1

Published

7 months ago

Group data into intervals

0High
0Medium
0Low

mariamair

intervals statistics histogram

group-into-intervals

Scope: This module was developed as a 2-week school project for the course 1DV610.

group-into-intervals is a tool that supports statistical analysis of data by grouping data points into intervals.

Input an array of numbers and get it grouped for a quick and lightweight analysis.
Choose one of four color schemes to go with the intervals and use the result to visualize your data.

Statistical background

The number of intervals (a.k.a. classes or bins) is calculated with Sturges' formula k = 1 + 3.322 * log10(number of data points).
The interval width (or class width) is calculated by dividing the range of the dataset with the number of intervals. In case the interval width multiplied with the number of intervals is too small to cover the range ot the dataset, the interval width is increased by 1 until the range is covered.

For more information about Sturges' rule and criticism of it, see Wikipedia.

Installation

To add the module to your application, run:

npm install group-into-intervals

Usage

The module takes an array of numbers and groups them into intervals. The output is returned as JSON.

Code examples

Requesting ascending intervals with color scheme #1:

import { getAscendingIntervalsWithColors } from 'group-into-intervals'

const colorSchemeId = 1
const input = [1, 3, -5, 17, 3]
const intervals = groupIntoIntervalsWithColorsAscending(input, colorSchemeId)

Will return this object (after JSON.parse):

[
  {
    lowerBoundary: -5,
    upperBoundary: 2,
    data: [ -5, 1 ],
    color: { hexValue: '#be2020', rgbValue: 'rgb(190, 32, 32)' }
  },
  {
    lowerBoundary: 3,
    upperBoundary: 10,
    data: [ 3, 3 ],
    color: { hexValue: '#7532a8', rgbValue: 'rgb(117, 50, 168)' }
  },
  {
    lowerBoundary: 11,
    upperBoundary: 18,
    data: [ 17 ],
    color: { hexValue: '#1a02f0', rgbValue: 'rgb(26, 2, 240)' }
  }
]

Examples for usage of output

Use the output to easily visualize your data, e.g. displaying it as intervals or creating a histogram of your data.

Examples made using the test-group-into-intervals repo and arrays containing random numbers.

Example of using color scheme 3 and displaying the resulting intervals

Example of using color scheme 1 and displaying the result as histogram

API

Fetch color schemes

You can fetch all color schemes or a specific one.

To get all color schemes, use:

getAllColorSchemes()

To fetch information about a specific color scheme, call this function with one of the color scheme ID's:

getColorScheme(colorSchemeId)

Get intervals (without colors)

Get ascending intervals of your input:

getAscendingIntervals(input)  // input = an array of numbers

Get descending intervals of your input:

getDescendingIntervals(input)  // input = an array of numbers

Get intervals (with colors)

Get the intervals together with a color for each interval. Specify the ID of the color scheme you want to use. Based on that scheme, the function will add as much colors as needed to give each interval its own color.
Please note: If your data results in more than 9 intervals, the created colors might be hard to distinguish visually.

Get ascending intervals with colors:

getAscendingIntervalsWithColors(input, colorSchemeId)  // input = an array of numbers

Get descending intervals with colors:

getDescendingIntervalsWithColors(input, colorSchemeId)  // input = an array of numbers

Get interval metadata

Returns the metadata that will be used when your input is grouped into intervals, e.g. range, number of intervals and interval width.

Set isAscending = true if the data should be sorted ascending
Set isAscending = false if the data should be sorted descending

getIntervalMetadata(input, isAscending)  // input = an array of numbers

Color schemes

| ID | Name | Color 1 | Color 2 | Color 3 | |----|------|---------|---------|---------| | 1 | red, violet, blue | red (190, 32, 32) | violet (117, 50, 168) | blue (26, 2, 240) | | 2 | red, yellow, blue | red (190, 32, 32) | yellow (214, 219, 66) | blue (26, 2, 240) | | 3 | violet, yellow, blue | violet (117, 50, 168) | yellow (214, 219, 66) | blue (26, 2, 240) | | 4 | white, light green, dark green | white (255, 255, 255) | (94, 193, 56) | (58, 109, 37) |