statsbreaks is a javascript package whose objective is to split (to classify/to discretize) a quantitative dataset into a (k) number of classes or thematic categories. The general aim is to create a choropleth map, for example with bertin.js.
1. Installation
In browser
Last version
<script src="https://cdn.jsdelivr.net/npm/statsbreaks@1" charset="utf-8"></script>Pinned version
<script src="https://cdn.jsdelivr.net/npm/statsbreaks@1" charset="utf-8"></script>In Observable
Last version
stat = require("statsbreaks")Pinned version
stat = require("statsbreaks@1")2. Methods
The breaks() function allows to compute breaks according to several discretization methods. Source
Parameters
-
method: method of discretization. "quantile", "q6", "equal", "msd", "jenks", "geometric", "headtail" or "pretty" (default: "quantile") -
nb: number of classes (default: 5) -
precision: rounding of values. 2 transform 35667.877876 to 35667.87 -2 transform 35667.877876 to 35600. Set it tonullto indicate breaks shouldn't be rounded (default: 2) -
minmax: a boolean to keep or remove min and max values (default: true) -
middle: a boolean to have the average as a class center. Available with "msd" method only (default: false) -
k: Number of standard deviations taken into account. Available with "msd" method only (default: 1)
quantile
- The
quantilemethod (or equal numbers) constructs classes in which there are the same number of statistical units. When there are 4 classes, the term used is quartiles (one quarter of the total number in each classes), when there are 10 classes, they are known as deciles, and for 100 classes, they will be centiles. This classification method can be used with any type of distribution, and it enables the comparison of maps one to another.
breaks(data, {method: "quantile", nb: 5, precision: 2 })q6
The q6 method is a variation of the quantile method with 6 classes and isolation of extremes classes (5%).
breaks(data, {method: "q6", nb: 5, precision: 2 })jenks
The Jenks method is an automatic classification method based on the principle of resemblance or non-resemblance among values. The method works via iterations. It groups values that most resemble one another and those that least resemble one another. In statistical terms, the method aims to minimize intra-class variance and to maximize inter-class variance.
breaks(data, {method: "jenks", nb: 5, precision: 2 })equal
The equal method is constructed by dividing up the extent of a statistical series (max - min) into the desired number of classes. This method is used even or symmetrical distributions. It should be avoided for strongly skewed distributions. This method does not enable the comparisons of several maps.
breaks(data, {method: "equal", nb: 5, precision: 2 })geometric
The geometric progression is suited to highly skewed distributions. It consists in constructing classes whose extent increases with each class, which enables close follow-up of the statistical series.
breaks(data, {method: "geometric", nb: 5, precision: 2 })arithmetic
The arithmetic progression is suited to right-skewed distributions (i.e. with many low values and few high ones). It consists in constructing classes whose amplitude increases in an arithmetical progression.
breaks(data, {method: "arithmetic", nb: 5, precision: 2 })msd
The mean standard deviation method (msd) is based on significant values (mean and standard deviation). This type of classification is ideal for symmetrical (normal, Gaussian) distributions and should be solely in the instance. When the distribution is skewed, it is preferable tu use another method.
breaks(data, {method: "msd", k: 0.5, middle: true, precision: 2 })headtail
The headtail method is a data classification method in which the number of classes and the class intervals are both naturally determined by the very property of the heavy-tailed distributions of the data. It works with up to 7 classes.
breaks(data, {method: "headtail", nb: 5, precision: 2 })pretty
The pretty method generates breaks that are equally spaced round values which cover the range of values in the input array. The breaks are chosen so that they are 1, 2, or 5 times a power of 10.
breaks(data, {method: "pretty", nb: 5, precision: 2 })nested
The nested method computes breaks using nested means : a first (arithmetic) mean divides the series in two, then each group is again split by its mean, and so on, until the desired number of classes is obtained. As such, the number of classes requested must be a power of 2 (2, 4, 8, etc.).
breaks(data, {method: "nested", nb: 8, precision: 2 })3. Object-oriented API
For each classification method, you can also use an object-oriented API.
Classes available are: JenksClassifier, EqualClassifier, GeometricProgressionClassifier, HeadTailClassifier, MsdClassifier, PrettyBreaksClassifier, QuantileClassifier, Q6Classifier, ArithmeticProgressionClassifier, NestedMeansClassifier and CustomBreaksClassifier.
For example
series = new discr.JenksClassifier(data, 2)where data is an array of values and 2 the precision.
classify computes the break values for the given number of classes and returns it.
series.classify(7)countByClass count how many individuals in each class
series.countByClass()splitByClass returns values for each class
series.splitByClass()getClass get the class index for a specific individual. For example, the value 30000 is in the index 2 class, i.e. the third class.
series.getClass(30000)You can use also min, max, mean, median, stddev and population.
series.min()series.max()series.population()series.mean()series.median()series.stddev()4. Live demo
Live demo available here: https://observablehq.com/@neocartocnrs/hello-statsbreaks