@mark1russell7/rigor-statistics 0.1.10 → 0.1.11

package/README.md

@@ -123,6 +123,8 @@ The default expansion has one product for each pair of levels of two dimensions.
 | `holm(pValues, level)` | The Holm correction of a family of tests. |
 | `spearman`, `kendallTau`, `ranks` | The rank correlations, with mean ranks for ties. |
 | `compareRatios`, `noiseFloor`, `noiseVerdict` | The comparison with a baseline, the noise floor of the 5-seed rule with a margin of practical effect, and the state of a difference over the seeds. |
+| `modeCount(values, { minShare, valleyRatio })` | The count of the modes of a sample, from a kernel density estimate. |
+| `smoothLawScores(values)`, `bestSmoothLaw(values)` | The mean log density of the uniform, normal, exponential, log-normal and Pareto laws at their fits, and the best of them. |
 | `brier`, `calibration` | The Brier score of predictions, and the hit rate of each stated level. |
 | `fitResponse(data, options)` | A record of the format `response-records/1`, with one model for each measure and held-out folds. |
 | `parseResponseRecord(value)` | The examination of unknown data. It gives the record, or one fault with a path for each error. |
@@ -134,6 +136,72 @@ The default expansion has one product for each pair of levels of two dimensions.
 
 Each function throws a RangeError for an empty list, for a NaN and for a parameter out of its range. Thus a missing value cannot make a quiet NaN in a record.
 
+### The limits of the shape of a sample
+
+`modeCount` has two reads. A sample with 24 or fewer distinct values, and 4 or more copies of each value on average, gets a direct read. That read uses the counts of the values. A kernel estimate reads each other sample.
+
+The count is the same for `x` and `-x`. Two humps join in the order of the depth of their valleys, not in the order of their positions. A test holds this on seeded random laws.
+
+The direct read does not change with the size of the sample, so one discrete law gives one result. A test holds this table, with a gap of 100 between the groups.
+
+| Groups of equal values | 10 values each | 50 values each | 200 values each | 1,000 values each |
+| --- | --- | --- | --- | --- |
+| 2 | 2 | 2 | 2 | 2 |
+| 3 | 3 | 3 | 3 | 3 |
+| 6 | 6 | 6 | 6 | 6 |
+| 10 | 10 | 10 | 10 | 10 |
+| 12 | 12 | 12 | 12 | 12 |
+| 16 | 16 | 16 | 16 | 16 |
+| 24 | 24 | 24 | 24 | 24 |
+| 25 | 1 | 1 | 1 | 1 |
+
+- Flat counts give one mode for each value. So a rounded uniform law with 24 or fewer steps gives one mode for each value, and two close values are two modes.
+- Counts with one rise and one fall give one mode. This read needs 4 or more values. A normal law at a step of 2 SD has 3 values, so it gives 3.
+- A value under 1 percent of the sample is out of this read.
+- Under 1,000 values the noise of a sample can move the count of a rounded uniform law with 10 or more steps by 1.
+
+The kernel joins more than approximately 24 evenly spaced clusters, because its grid has 96 points. A tight cluster also needs more than approximately `n ** 0.8 / 8` values in a sample of `n` values. A cluster with an SD over 5 percent of the gap to the next cluster can join it. Under these limits a test holds the count at 20 clusters. A step of rounding is no gap between clusters. So the width of the kernel stays over the median gap of the distinct values of a tight sample.
+
+The default counts the modes that hold 10 percent of the mass. A caller who needs all modes passes a smaller `minShare`.
+
+A small smooth sample can give a false extra mode. This table gives the share of 500 seeded samples of each law with a count of 1. A test holds it.
+
+| Values | uniform | normal | exponential | log-normal | Pareto |
+| --- | --- | --- | --- | --- | --- |
+| 10 | 0.54 | 0.51 | 0.54 | 0.55 | 0.50 |
+| 30 | 0.80 | 0.81 | 0.76 | 0.70 | 0.77 |
+| 100 | 0.99 | 0.98 | 0.88 | 0.92 | 0.91 |
+| 300 | 1.00 | 1.00 | 0.98 | 0.99 | 0.99 |
+| 1,000 | 1.00 | 1.00 | 1.00 | 1.00 | 1.00 |
+
+A discrete law with one mode can also give a false count. This table gives the share of 1,000 seeded samples with a count that is not 1. A test holds it.
+
+| Law | 100 values | 300 values | 1,000 values |
+| --- | --- | --- | --- |
+| Rounded normal, SD 4 | 0.003 | 0.001 | 0.001 |
+| Poisson, mean 3 | 0.006 | 0.001 | 0.000 |
+| Poisson, mean 10 | 0.001 | 0.000 | 0.000 |
+| Binomial, 10 trials, p 0.5 | 0.008 | 0.009 | 0.001 |
+| Binomial, 100 trials, p 0.5 | 0.001 | 0.000 | 0.000 |
+| Poisson, mean 1 | 0.000 | 0.000 | 0.000 |
+| Geometric, p 0.1 | 0.213 | 0.028 | 0.000 |
+
+- Do not trust one count at 100 values. Use the table to find the risk.
+- In the first five rows a false count is rare, and most of them are large. A bell passes the flat test, so each of its values counts as a mode.
+- The kernel reads a geometric law with p 0.1 at these sizes. A false count from it is one extra mode.
+
+`bestSmoothLaw` is not reliable under 300 values. The laws with a fitted end have a benefit at small sizes. This table gives the share of correct results for 500 seeded samples of each law. A test holds it.
+
+| Values | uniform | normal | exponential | log-normal | Pareto |
+| --- | --- | --- | --- | --- | --- |
+| 10 | 0.96 | 0.01 | 0.45 | 0.02 | 0.69 |
+| 30 | 1.00 | 0.30 | 0.90 | 0.25 | 0.87 |
+| 100 | 1.00 | 0.68 | 0.99 | 0.71 | 0.99 |
+| 300 | 1.00 | 0.85 | 1.00 | 0.99 | 1.00 |
+| 1,000 | 1.00 | 0.97 | 1.00 | 1.00 | 1.00 |
+
+The samples use a normal law with a mean of 100 and an SD of 10, where the normal and log-normal laws are close.
+
 ## Moves from the copies
 
 The tests prove that these functions give the same numbers as the copies in the engines, to the bit:

package/build/index.d.ts

@@ -140,6 +140,56 @@ export declare function bootstrapMedian(values: readonly number[], options?: Boo
  * are in the order of their first row.
  */
 export declare function bootstrapClusters<T>(rows: readonly T[], cluster: (row: T) => string, statistic: (rows: readonly T[]) => number, options?: BootstrapOptions): Interval;
+/** The smooth laws that `smoothLawScores` compares. Each law has 2 fitted numbers. */
+type SmoothLaw = "uniform" | "normal" | "exponential" | "log-normal" | "pareto";
+/** The value of one law at its fit. */
+interface SmoothLawScore {
+  readonly law: SmoothLaw;
+  /** The mean log density of the values at the fit of the law. A larger value is a better fit. */
+  readonly meanLogDensity: number;
+}
+/** The options of `modeCount`. */
+interface ModeOptions {
+  /**
+   * The smallest share of the mass that makes a mode. The default is `0.1`. Half of the mass of the largest mode also
+   * makes a mode, so many equal modes each count.
+   */
+  readonly minShare?: number;
+  /** The valley between two peaks of the kernel is under this share of the lower peak. The default is `0.5`. */
+  readonly valleyRatio?: number;
+}
+/**
+ * This function counts the modes of a sample. A mode counts when it holds `minShare` of the mass. The default counts the
+ * modes that hold 10 percent, and a caller who needs all modes passes a smaller value. The result is at least 1. The
+ * result is the same for `x` and `-x`.
+ *
+ * A sample with 24 or fewer distinct values, and 4 or more copies of each value on average, gets a direct read.
+ * That read uses the counts of the values, and it does not change with the size of the sample.
+ * It gives one mode for each value of a flat discrete law. So even groups give the count of the groups, and so does a
+ * rounded uniform law with 24 or fewer steps. It gives one mode for each hump of a rounded smooth law.
+ * The direct read of a sample with 3 or fewer values gives one mode for each value that holds the share.
+ *
+ * A kernel estimate on a grid reads each other sample. The grid has 96 points, so the kernel joins more than
+ * approximately 24 evenly spaced clusters. A tight cluster also needs more than approximately `n ** 0.8 / 8` values for
+ * a sample of `n` values. A cluster with an SD over 5 percent of the gap to the next cluster can join it.
+ *
+ * The function throws a RangeError for an empty list or for a value that is not finite.
+ */
+export declare function modeCount(values: readonly number[], options?: ModeOptions): number;
+/**
+ * This function gives the mean log density of the values under each smooth law, at the closed-form fit of that law.
+ * Each law has 2 fitted numbers, so the function adds no penalty. The uniform, the shifted exponential and the Pareto
+ * law take the smallest value as their lower limit. This fitted end helps them at small sizes. All values are exact
+ * maximum likelihoods.
+ * The function throws a RangeError for an empty list, for a value that is not positive and finite, or for equal values.
+ */
+export declare function smoothLawScores(values: readonly number[]): readonly SmoothLawScore[];
+/**
+ * This function gives the smooth law with the highest likelihood. Under 300 values the result is not reliable: the
+ * normal and the log-normal law lose to the laws with a fitted end. The README gives the measured shares of correct
+ * results. The function throws as `smoothLawScores` does.
+ */
+export declare function bestSmoothLaw(values: readonly number[]): SmoothLaw;
 /**
  * The ridge solve of a least-squares problem from its normal equations. The caller gives the matrix `X'X` and the
  * vector `X'y`. Thus it can make them from sparse rows. It can also remove the sums of one fold of a cross-validation.
@@ -920,5 +970,5 @@ interface CalibrationLevel {
 }
 /** The hit rate of each stated level, from the lowest level. */
 export declare function calibration(forecasts: readonly Forecast[]): CalibrationLevel[];
-export type { BootstrapOptions, CalibrationLevel, CategoricalDimension, CompareOptions, Comparison, ContinuousDimension, Corrected, CountInterval, Effect, Forecast, Interval, LeastSquaresFit, LeastSquaresOptions, MedianInterval, NoiseOptions, NoiseState, NoiseVerdict, OrdinalDimension, ParsedResponseRecord, PermutationOptions, PermutationResult, Proportion, QuantileInterval, QuantileMethod, ResponseAbsentPoint, ResponseBand, ResponseCurvePoint, ResponseData, ResponseDimension, ResponseDimensionBase, ResponseFactor, ResponseFault, ResponseFitOptions, ResponseFold, ResponseFoldError, ResponseHeldOutError, ResponseInputValue, ResponseMeasure, ResponseModel, ResponseModelBase, ResponsePoint, ResponseReason, ResponseRecord, ResponseSlice, ResponseSliceOptions, ResponseSlicePoint, ResponseSurface, ResponseSurfaceAbsentPoint, ResponseSurfaceOptions, ResponseSurfacePoint, ResponseTableCell, ResponseValue, ResponseViewOptions, ResponseWhen, RidgeInput, RidgeInputBase, RidgeLevelInput, RidgeNumberInput, RidgeOptions, RidgeRankInput, RidgeResponseModel, RidgeTerm, Summary, TableResponseModel };
+export type { BootstrapOptions, CalibrationLevel, CategoricalDimension, CompareOptions, Comparison, ContinuousDimension, Corrected, CountInterval, Effect, Forecast, Interval, LeastSquaresFit, LeastSquaresOptions, MedianInterval, ModeOptions, NoiseOptions, NoiseState, NoiseVerdict, OrdinalDimension, ParsedResponseRecord, PermutationOptions, PermutationResult, Proportion, QuantileInterval, QuantileMethod, ResponseAbsentPoint, ResponseBand, ResponseCurvePoint, ResponseData, ResponseDimension, ResponseDimensionBase, ResponseFactor, ResponseFault, ResponseFitOptions, ResponseFold, ResponseFoldError, ResponseHeldOutError, ResponseInputValue, ResponseMeasure, ResponseModel, ResponseModelBase, ResponsePoint, ResponseReason, ResponseRecord, ResponseSlice, ResponseSliceOptions, ResponseSlicePoint, ResponseSurface, ResponseSurfaceAbsentPoint, ResponseSurfaceOptions, ResponseSurfacePoint, ResponseTableCell, ResponseValue, ResponseViewOptions, ResponseWhen, RidgeInput, RidgeInputBase, RidgeLevelInput, RidgeNumberInput, RidgeOptions, RidgeRankInput, RidgeResponseModel, RidgeTerm, SmoothLaw, SmoothLawScore, Summary, TableResponseModel };
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/describe.ts","../src/regression.ts","../src/bootstrap.ts","../src/ridge.ts","../src/response.ts","../src/response-parse.ts","../src/response-fit.ts","../src/tests.ts","../src/rank.ts","../src/discrete.ts","../src/compare.ts"],"mappings":";;;;;;KAOY;;wBAmBI,OAAO;wBAIP,KAAK;;;;;wBAgBL,GAAG;;;;;;;wBAgBH,eAAe,iCAAiC,WAAW,SAAQ;;wBAkBnE,SAAS,2BAA2B,WAAW,SAAQ;;;;;wBASvD,OAAO;;UAQN;WACN;WACA;;WAEA;WACA;;WAEA;WACA;;WAEA;WACA;;WAEA;;wBAGK,UAAU,4BAA4B;;;;;;UC3GrC;;WAEN;;UAGM;;WAEN;;WAEA;;;;;WAKA;;WAEA;;WAEA;;;;;;;;;;;wBAkBK,aAAa,mCAAmC,sBAAsB,UAAS,sBAA2B;UC/BzG;;WAEN;;WAEA;;WAEA;;WAEA,SAAS;;;;;;WAMT;;UAGM;;WAEN;WACA;WACA;WACA;WACA;;WAEA;;WAEA;;;;;;wBAOK,UAAU,GAAG,eAAe,KAAK,YAAY,iBAAiB,gBAAgB,UAAS,mBAAwB;;;;;;;;wBAsB/G,aAAa,GAAG,GAC9B,YAAY,KACZ,YAAY,KACZ,YAAY,YAAY,KAAK,YAAY,gBACzC,UAAS,mBACR;;;;;;wBAwBa,qBAAqB,8BAA8B,gCAAgC,UAAS,mBAAwB;;;;;;;wBAUpH,sBACd,mCACA,sBACA,UAAS,mBAAmB,sBAC3B;;wBAmFa,gBAAgB,2BAA2B,UAAS,mBAAwB;;;;;;wBAS5E,kBAAkB,GAChC,eAAe,KACf,UAAU,KAAK,cACf,YAAY,eAAe,gBAC3B,UAAS,mBACR;;;;;;;UCxMc;;WAEN;;;;;;;;;;;;wBAoBK,WAAW,MAAM,mBAAmB,QAAQ,mBAAmB,gBAAgB,UAAS;;qBCd3F;;KAGD;;KAGA,qBAAqB;;UAGhB;;WAEN;WACA,iBAAiB;;;UAIX;;WAEN;;WAEA;;WAEA;;WAEA,OAAO;;;UAID,4BAA4B;WAClC;;WAEA;;WAEA;;;UAIM,yBAAyB;WAC/B;WACA;;WAEA;;;UAIM,6BAA6B;WACnC;WACA;;;KAIC,oBAAoB,sBAAsB,mBAAmB;;UAGxD;;WAEN;WACA;;WAEA;;WAEA;;;;;WAKA;;;UAIM;;WAEN;;WAEA;;;UAIM;WACN;;WAEA,QAAQ,SAAS,eAAe;;WAEhC,UAAU,SAAS;;WAEnB;;WAEA,SAAS,SAAS;;;KAIjB;WAA4B;WAA4B;;WAA6B;WAA4B,OAAO;;;UAGnH;WACN;;WAEA;;;UAIM,yBAAyB;WAC/B;WACA;WACA;WACA;;;UAIM,uBAAuB;WAC7B;WACA;WACA;WACA;;;UAIM,wBAAwB;WAC9B;WACA;;;KAIC,aAAa,mBAAmB,iBAAiB;;UAG5C;WACN,kBAAkB;WAClB;;;UAIM;;WAEN;;WAEA;;WAEA;;;UAIM,2BAA2B;WACjC;;WAEA;WACA,iBAAiB;WACjB;WACA,gBAAgB;;;UAIV;;WAEN,aAAa;;WAEb;;WAEA;;;UAIM,2BAA2B;WACjC;WACA;;WAEA;WACA,gBAAgB;;WAEhB;;;KAIC,gBAAgB,qBAAqB;;UAGhC;;WAEN;;WAEA;;WAEA;;WAEA;;;UAIM;;WAEN;;WAEA,QAAQ,SAAS,eAAe;;;;;WAKhC,cAAc,SAAS,eAAe,SAAS;;;UAIzC;WACN,eAAe;WACf;WACA,qBAAqB;WACrB,mBAAmB;;WAEnB,mBAAmB;WACnB,iBAAiB;;;UAIX,uBAAuB;WAC7B,iBAAiB;WACjB,gBAAgB;;;UAIV;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;;UAIM;;WAEN,OAAO,SAAS,eAAe;;WAE/B;;;;;WAKA;;WAEA;;;UAIM,6BAA6B;;WAEnC;;;UAIM,+BAA+B;;WAErC;;;;;;UAOM;WACN;WACA;WACA;;;;;;;WAOA;;WAEA;;;UAIM,2BAA2B;;WAEjC,IAAI;;;UAIE;WACN;;WAEA,IAAI;WACJ;WACA;;;UAIM;WACN;;WAEA,IAAI;;WAEJ;WACA;;;UAIM;WACN;WACA;;WAEA,MAAM,SAAS,eAAe;WAC9B,gBAAgB;WAChB,iBAAiB;;WAEjB,iBAAiB;WACjB,OAAO;;WAEP;;;UAIM;WACN;;WAEA,cAAc,eAAe;WAC7B;WACA;;;UAIM;WACN;;WAEA,cAAc,eAAe;;WAE7B;WACA;;;UAIM;WACN;WACA;;WAEA,MAAM,SAAS,eAAe;WAC9B,YAAY;WACZ,YAAY;;WAEZ,0BAA0B;WAC1B,iBAAiB;;WAEjB,iBAAiB;WACjB,OAAO;;WAEP;;;wBAuBK,UAAU,WAAW,mBAAmB,QAAQ,SAAS;;;;;;;;;;;wBA4FzD,gBAAgB,OAAO,eAAe,QAAQ,SAAS,eAAe;;;;;wBAQtE,aAAa,QAAQ,KAAK,0BAA0B,kBAAkB;;;;;;;;;;;;wBAqCtE,eAAe,QAAQ,gBAAgB,iBAAiB,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAgPjF,cAAc,QAAQ,gBAAgB,iBAAiB,SAAS,uBAAuB;;;;;;;wBAsBvF,gBAAgB,QAAQ,gBAAgB,iBAAiB,SAAS,yBAAyB;;;;;;;;wBA4B3F,cAAc,QAAQ,KAAK,+BAA+B,0CAA0C;;qBC3yBvG;;UAGI;;WAEN;;WAEA;;;KAIC;WAAkC;WAAmB,QAAQ;;WAA8B;WAAoB,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;wBAgf5H,oBAAoB,iBAAiB;;UC/dpC;;WAEN;;WAEA;;WAEA;;WAEA;;;;;;;;;WASA;;WAEA,2BAA2B;;WAE3B;;WAEA;;WAEA;;;;;WAKA;;;qBAIE;;qBAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAoTG,YAAY,MAAM,cAAc,UAAS,qBAA0B;;;;;;wBCvVnE,SAAS,gBAAgB,eAAe;;;;;wBAaxC,cAAc,WAAW,gBAAc;;qBAO1C;;UAGI;WACN;WACA;;;;;;wBAOK,OAAO,WAAW,WAAW,aAAkB;;UAc9C;;WAEN;;WAEA;;WAEA;;;;;;;wBAQK,KAAK,4BAA4B,iBAAe;UAa/C;;WAEN;;WAEA;;WAEA,aAAa;;UAGP;;WAEN;;WAEA;WACA;;;;;;wBAOK,kBAAkB,8BAA8B,6BAA6B,UAAS,qBAA0B;;wBCtHhH,MAAM;;;;;wBAgBN,SAAS,sBAAsB;;qBAmBlC;;;;;;wBAQG,WAAW,sBAAsB,sBAAsB;;UC1BtD;WACN;WACA;;WAEA;;WAEA;;;;;;;;;;wBAWK,eAAe,2BAA2B,iBAAe;;UAqBxD;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;;;;;;;;wBAUK,iBAAiB,2BAA2B,WAAW,iBAAe;;;;;;wBAsCtE,gBAAgB,WAAW;;UAW1B;WACN;WACA;;WAEA;;;;;;;wBAQK,iBAAiB,WAAW,WAAW,iBAAe;;;;;;wBA2BtD,yBAAyB,mBAAmB,WAAW,iBAAe;UCvKrE;;WAEN;;WAEA;;;;;;WAMA;;;;;;wBAgBK,WAAW,2BAA2B,UAAS;;;;;KASnD;;UAGK;;WAEN;WACA;;WAEA;;WAEA;WACA;;WAEA;WACA,OAAO;;;;;;;;wBASF,aAAa,2BAA2B,UAAS;WAA0B;IAAqC;UAW/G;;WAEN;;WAEA;;WAEA;;;UAIM;WACN;WACA;;WAEA;;WAEA;;UAGM;;WAEN;WACA;;WAEA;;WAEA;;WAEA;;WAEA,QAAQ;;WAER;;WAEA;;WAEA;WACA,cAAc;;WAEd;WACA,cAAc;;;;;;;;wBAST,cAAc,2BAA2B,UAAS,iBAAsB;;UA6CvE;WACN;WACA;;;wBASK,MAAM,oBAAoB;;UAQzB;WACN;WACA;WACA;;WAEA;;WAEA,UAAU;;;wBAIL,YAAY,oBAAoB,aAAa"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/describe.ts","../src/regression.ts","../src/bootstrap.ts","../src/distribution.ts","../src/ridge.ts","../src/response.ts","../src/response-parse.ts","../src/response-fit.ts","../src/tests.ts","../src/rank.ts","../src/discrete.ts","../src/compare.ts"],"mappings":"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"}

package/build/index.js

@@ -363,6 +363,263 @@ function bootstrapClusters(rows, cluster, statistic, options = {}) {
 		estimate
 	};
 }
+// src/distribution.ts
+/**
+* The shape of a sample: the count of its modes, and the smooth law with the highest likelihood. Use them to read the
+* law that a generator really emits, from its values and not from its label.
+*/
+/** The points of the grid of the density estimate. */
+const GRID = 96;
+/** The width of the kernel, in the factor of Silverman's rule. The value 0.9 of that rule hides close modes. */
+const KERNEL_FACTOR = .45;
+/** The share of the values in a span of neighbours, as a factor of `n ** -0.2`. */
+const SPAN_FACTOR = .1;
+/** The quantile of the spans. A low quantile stays in the clusters when most spans cross a gap. */
+const SPAN_QUANTILE = .25;
+/**
+* The tight width replaces the width from the quartiles under this ratio. In seeded smooth samples the ratio stays over
+* 0.2, except for a heavy tail, and in tight clusters it stays under 0.02.
+*/
+const TIGHT_RATIO = .1;
+/** The kernels stop at this count of widths. */
+const KERNEL_REACH = 3;
+const HALF_LOG_2PI_E = .5 * Math.log(2 * Math.PI * Math.E);
+/** Two values closer than this share of the range are one value, so the noise of a float makes no new value. */
+const SAME_VALUE = 1e-9;
+/** The most distinct values of a direct read of their counts. The grid resolves no more than this count of clusters. */
+const FEW_VALUES = GRID / 4;
+/** The mean count of each value in a direct read. Under it the values are a small sample, and the kernel reads them. */
+const MIN_REPEATS = 4;
+/** The fewest values that show the shape of a law. A sample with fewer values gives one mode for each value. */
+const MIN_BELL_VALUES = 4;
+/** The ratio of the highest third of the counts to the lowest third, under which the counts are flat. */
+const FLAT_RATIO = 3;
+/** The ratio of the means of the three parts of the list of counts, under which the counts have no shape. */
+const SHAPE_RATIO = 1.75;
+/** A value with under this share of the sample is a tail. A rare value does not change the shape of the counts. */
+const RARE_VALUE = .01;
+/** The fewest values of a hump of a rounded law. When most humps are narrower, the values are a discrete law. */
+const MIN_HUMP_VALUES = 3;
+/**
+* This function gives the distances of the values from one end of the sample, in order. It takes the end that gives the
+* smaller list, so `x` and `-x` give one list and one count.
+*/
+function fromOneEnd(values) {
+	const order = sorted(values);
+	const low = order[0];
+	const high = order[order.length - 1];
+	const rising = order.map((x) => x - low);
+	const falling = order.map((x) => high - x).reverse();
+	const first = rising.findIndex((x, i) => x !== falling[i]);
+	return first >= 0 && falling[first] < rising[first] ? falling : rising;
+}
+/**
+* This function gives the width of the kernel. The width from the quartiles follows the distance between clusters, so
+* it hides many tight clusters. A low quantile of the spans of neighbouring values follows the width of a cluster.
+* The function uses the tight width only when it is far under the other width, so a smooth sample keeps its width.
+* The tight width stays over the grid step. No width goes under the median gap of the distinct values of a tight
+* sample. A step of rounding is no gap between clusters, so a rounded smooth sample keeps one mode at each size.
+*/
+function kernelWidth(values, low, high) {
+	const count = values.length;
+	const order = sorted(values);
+	const scale = Math.min(quantile(values, .75) - quantile(values, .25), high - low) / 1.34;
+	const wide = KERNEL_FACTOR * Math.max(scale, (high - low) / GRID) * count ** -.2;
+	const neighbours = Math.min(count - 1, Math.ceil(SPAN_FACTOR * count ** .8));
+	const tight = quantile(order.slice(neighbours).map((x, i) => x - order[i]), SPAN_QUANTILE);
+	if (tight >= TIGHT_RATIO * wide) return wide;
+	const distinct = order.filter((x, i) => i === 0 || x !== order[i - 1]);
+	const resolution = quantile(distinct.slice(1).map((x, i) => x - distinct[i]), .5);
+	return Math.max(resolution, Math.min(wide, Math.max(tight, (high - low) / GRID)));
+}
+/** This function gives the Gaussian kernel density of the values on a grid. */
+function densityGrid(values, low, high) {
+	const width = kernelWidth(values, low, high);
+	const start = low - KERNEL_REACH * width;
+	const step = (high - low + 6 * width) / 95;
+	const density = new Float64Array(GRID);
+	for (const x of values) {
+		const first = Math.max(0, Math.floor((x - KERNEL_REACH * width - start) / step));
+		const last = Math.min(95, Math.ceil((x + KERNEL_REACH * width - start) / step));
+		for (let i = first; i <= last; i++) {
+			const u = (start + i * step - x) / width;
+			density[i] += Math.exp(-.5 * u * u);
+		}
+	}
+	return density;
+}
+/**
+* This function gives the humps of a series. It first gives each rise and fall one hump. Then it joins the two neighbours
+* with the closest valley, and again, until each valley has a closeness under the limit. The result has no direction,
+* because the order of the joins comes from the depth of the valleys and not from their position.
+*/
+function humpsOf(series, closeness, limit) {
+	const humps = [];
+	const valleys = [];
+	let index = 0;
+	while (index < series.length) {
+		let top = index;
+		while (top + 1 < series.length && series[top + 1] >= series[top]) top++;
+		let end = top;
+		while (end + 1 < series.length && series[end + 1] < series[end]) end++;
+		let mass = 0;
+		for (let i = index; i <= end; i++) mass += series[i];
+		humps.push({
+			top: series[top],
+			mass,
+			points: end + 1 - index
+		});
+		if (end + 1 < series.length) valleys.push(series[end]);
+		index = end + 1;
+	}
+	while (valleys.length > 0) {
+		const scores = valleys.map((valley, i) => closeness(Math.min(humps[i].top, humps[i + 1].top), valley));
+		const closest = scores.indexOf(Math.max(...scores));
+		if (scores[closest] < limit) break;
+		const [left, right] = [humps[closest], humps[closest + 1]];
+		humps.splice(closest, 2, {
+			top: Math.max(left.top, right.top),
+			mass: left.mass + right.mass,
+			points: left.points + right.points
+		});
+		valleys.splice(closest, 1);
+	}
+	return humps;
+}
+/** This function gives the count of each distinct value, in the order of the values. */
+function valueCounts(values, low, high) {
+	const tie = SAME_VALUE * (high - low);
+	const counts = [];
+	let last = -Infinity;
+	for (const x of sorted(values)) {
+		if (x - last > tie) {
+			counts.push(0);
+			last = x;
+		}
+		counts[counts.length - 1]++;
+	}
+	return counts;
+}
+/**
+* This function tells that the counts are flat. The highest third of the counts stays under `FLAT_RATIO` times the
+* lowest third, so a list of heavy and light values is not flat. The means of the first, the middle and the last third
+* of the list stay under `SHAPE_RATIO` of each other. The noise of a sample cancels in those means, and a bell does not.
+*/
+function flatCounts(counts) {
+	const order = [...counts].sort((a, b) => a - b);
+	const third = Math.ceil(order.length / 3);
+	if (mean(order.slice(-third)) >= FLAT_RATIO * mean(order.slice(0, third))) return false;
+	const parts = [
+		counts.slice(0, third),
+		counts.slice(third, -third),
+		counts.slice(-third)
+	].filter((part) => part.length > 0).map((part) => mean(part));
+	return Math.max(...parts) < SHAPE_RATIO * Math.min(...parts);
+}
+/** This function gives the closeness of a count to a valley: the negative of its height over the noise of a sample. */
+const countCloseness = (lower, valley) => -(lower - valley) / Math.sqrt(lower + valley);
+/**
+* This function counts the modes of a sample with few distinct values, from the counts of those values. The result does
+* not change with the size of the sample. Flat counts are a discrete law with one mode for each value, so the noise of
+* a sample does not take a value out. Counts with one rise and one fall are a rounded smooth law with one mode.
+*/
+function fewValueModes(allCounts, total, minShare) {
+	const counts = allCounts.filter((count) => count / total >= RARE_VALUE);
+	const each = counts.map((count) => count / total);
+	const overLimit = (masses, limit) => masses.filter((share) => share >= limit).length;
+	if (counts.length < MIN_BELL_VALUES) return overLimit(each, Math.min(minShare, Math.max(...each) / 2));
+	if (flatCounts(counts)) return overLimit(each, Math.min(minShare, quantile(each, .5) / FLAT_RATIO));
+	const humps = humpsOf(counts, countCloseness, -3);
+	const masses = 2 * humps.filter((hump) => hump.points < MIN_HUMP_VALUES).length > humps.length ? each : humps.map((hump) => hump.mass / total);
+	return overLimit(masses, Math.min(minShare, Math.max(...masses) / 2));
+}
+/**
+* This function gives the mass of each mode from a kernel estimate on a grid. Two peaks stay apart when the valley
+* between them is under `valleyRatio` of the lower peak.
+*/
+function kernelMasses(values, low, high, valleyRatio) {
+	const density = densityGrid(values, low, high);
+	const total = density.reduce((sum, d) => sum + d, 0);
+	return humpsOf(density, (lower, valley) => valley / lower, valleyRatio).map((hump) => hump.mass / total);
+}
+/**
+* This function counts the modes of a sample. A mode counts when it holds `minShare` of the mass. The default counts the
+* modes that hold 10 percent, and a caller who needs all modes passes a smaller value. The result is at least 1. The
+* result is the same for `x` and `-x`.
+*
+* A sample with 24 or fewer distinct values, and 4 or more copies of each value on average, gets a direct read.
+* That read uses the counts of the values, and it does not change with the size of the sample.
+* It gives one mode for each value of a flat discrete law. So even groups give the count of the groups, and so does a
+* rounded uniform law with 24 or fewer steps. It gives one mode for each hump of a rounded smooth law.
+* The direct read of a sample with 3 or fewer values gives one mode for each value that holds the share.
+*
+* A kernel estimate on a grid reads each other sample. The grid has 96 points, so the kernel joins more than
+* approximately 24 evenly spaced clusters. A tight cluster also needs more than approximately `n ** 0.8 / 8` values for
+* a sample of `n` values. A cluster with an SD over 5 percent of the gap to the next cluster can join it.
+*
+* The function throws a RangeError for an empty list or for a value that is not finite.
+*/
+function modeCount(values, options = {}) {
+	const { minShare = .1, valleyRatio = .5 } = options;
+	if (values.length === 0) throw new RangeError("modeCount: the list is empty.");
+	for (const v of values) if (!Number.isFinite(v)) throw new RangeError("modeCount: each value must be finite.");
+	const distances = fromOneEnd(values);
+	const high = distances[distances.length - 1];
+	if (high === 0) return 1;
+	const counts = valueCounts(distances, 0, high);
+	if (counts.length <= FEW_VALUES && values.length >= MIN_REPEATS * counts.length) return fewValueModes(counts, values.length, minShare);
+	const masses = kernelMasses(distances, 0, high, valleyRatio);
+	const limit = Math.min(minShare, Math.max(...masses) / 2);
+	return masses.filter((share) => share >= limit).length;
+}
+/**
+* This function gives the mean log density of the values under each smooth law, at the closed-form fit of that law.
+* Each law has 2 fitted numbers, so the function adds no penalty. The uniform, the shifted exponential and the Pareto
+* law take the smallest value as their lower limit. This fitted end helps them at small sizes. All values are exact
+* maximum likelihoods.
+* The function throws a RangeError for an empty list, for a value that is not positive and finite, or for equal values.
+*/
+function smoothLawScores(values) {
+	if (values.length === 0) throw new RangeError("smoothLawScores: the list is empty.");
+	for (const v of values) if (!(v > 0 && Number.isFinite(v))) throw new RangeError("smoothLawScores: each value must be positive and finite.");
+	const logs = values.map((v) => Math.log(v));
+	const low = quantile(values, 0);
+	const high = quantile(values, 1);
+	if (low === high) throw new RangeError("smoothLawScores: the values are equal, so no law has a density.");
+	const meanLog = mean(logs);
+	const toExact = .5 * Math.log(values.length / (values.length - 1));
+	const alpha = 1 / (meanLog - Math.log(low));
+	return [
+		{
+			law: "uniform",
+			meanLogDensity: -Math.log(high - low)
+		},
+		{
+			law: "normal",
+			meanLogDensity: -Math.log(sd(values)) - HALF_LOG_2PI_E + toExact
+		},
+		{
+			law: "exponential",
+			meanLogDensity: -Math.log(mean(values) - low) - 1
+		},
+		{
+			law: "log-normal",
+			meanLogDensity: -Math.log(sd(logs)) - HALF_LOG_2PI_E - meanLog + toExact
+		},
+		{
+			law: "pareto",
+			meanLogDensity: Math.log(alpha) + alpha * Math.log(low) - (alpha + 1) * meanLog
+		}
+	];
+}
+/**
+* This function gives the smooth law with the highest likelihood. Under 300 values the result is not reliable: the
+* normal and the log-normal law lose to the laws with a fitted end. The README gives the measured shares of correct
+* results. The function throws as `smoothLawScores` does.
+*/
+function bestSmoothLaw(values) {
+	return smoothLawScores(values).reduce((best, score) => score.meanLogDensity > best.meanLogDensity ? score : best).law;
+}
 // src/ridge.ts
 /**
 * The relative tolerance of the Cholesky pivots. A pivot is the squared length of the part of a column that is
@@ -2434,6 +2691,6 @@ function calibration(forecasts) {
 		interval: wilson(hits, n)
 	}));
 }
-export { KENDALL_EXACT, RESPONSE_LAMBDAS, RESPONSE_MAX_POWER, RESPONSE_MAX_TERMS, RESPONSE_RECORDS_SCHEMA, Z95, binomialInterval, bootstrap, bootstrapClusters, bootstrapLeastSquares, bootstrapMedian, bootstrapMedianRatio, bootstrapTwo, brier, calibration, compareRatios, fitResponse, heldOutError, heldOutErrorAt, holm, kendallTau, leastSquares, mean, median, medianInterval, negativeBinomialInterval, noiseFloor, noiseVerdict, pairedPermutation, parseResponseRecord, predictResponse, quantile, quantileInterval, quantileSamples, quantileSorted, ranks, responseCells, ridgeSolve, sd, signTest, signTestPower, sliceResponse, sorted, spearman, summarize, surfaceResponse, whenHolds, wilson };
+export { KENDALL_EXACT, RESPONSE_LAMBDAS, RESPONSE_MAX_POWER, RESPONSE_MAX_TERMS, RESPONSE_RECORDS_SCHEMA, Z95, bestSmoothLaw, binomialInterval, bootstrap, bootstrapClusters, bootstrapLeastSquares, bootstrapMedian, bootstrapMedianRatio, bootstrapTwo, brier, calibration, compareRatios, fitResponse, heldOutError, heldOutErrorAt, holm, kendallTau, leastSquares, mean, median, medianInterval, modeCount, negativeBinomialInterval, noiseFloor, noiseVerdict, pairedPermutation, parseResponseRecord, predictResponse, quantile, quantileInterval, quantileSamples, quantileSorted, ranks, responseCells, ridgeSolve, sd, signTest, signTestPower, sliceResponse, smoothLawScores, sorted, spearman, summarize, surfaceResponse, whenHolds, wilson };
 
 //# sourceMappingURL=index.js.map