linked-rolls 0.42.0 → 0.44.0

package/lib/statistics.js

@@ -0,0 +1,121 @@
+import { quantity } from "./Quantity";
+/**
+ * The statistics a sample of measurements is described with.
+ *
+ * The centre and the scatter are taken from the median rather than from
+ * the mean, because the departures a measurement over an edition looks
+ * for are in the sample it is taken over. A mean and a standard
+ * deviation would grow towards those departures until they no longer
+ * stood out; a median and a median absolute deviation leave them out of
+ * account.
+ */
+/** The middle of a sample, the mean of the two middle values where it has an even number of them. */
+export const medianOf = (values) => {
+    if (values.length === 0)
+        return undefined;
+    const sorted = [...values].sort((a, b) => a - b);
+    const middle = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 1
+        ? sorted[middle]
+        : quantity((sorted[middle - 1] + sorted[middle]) / 2);
+};
+/** What the median absolute deviation must be multiplied by to estimate the standard deviation of a normal sample. */
+const MAD_TO_SIGMA = 1.4826;
+/** Where the sample sits and how far it scatters, or nothing for an empty sample. */
+export const spreadOf = (values) => {
+    const median = medianOf(values);
+    if (median === undefined)
+        return undefined;
+    const deviations = values.map(value => quantity(Math.abs(value - median)));
+    return {
+        n: values.length,
+        median,
+        sigma: quantity(MAD_TO_SIGMA * (medianOf(deviations) ?? 0))
+    };
+};
+/** How far the value lies from the centre of the spread, in units of its scatter. */
+export const standardise = (value, spread) => (value - spread.median) / spread.sigma;
+/** The complementary error function, after Press et al., whose fractional error stays below 1.2e-7. */
+const erfc = (x) => {
+    const z = Math.abs(x);
+    const t = 1 / (1 + z / 2);
+    const tail = t * Math.exp(-z * z - 1.26551223 + t * (1.00002368 + t * (0.37409196 + t * (0.09678418 +
+        t * (-0.18628806 + t * (0.27886807 + t * (-1.13520398 + t * (1.48851587 +
+            t * (-0.82215223 + t * 0.17087277)))))))));
+    return x >= 0 ? tail : 2 - tail;
+};
+/** The share of a normal sample lying below `z` standard deviations. */
+export const normalBelow = (z) => erfc(-z / Math.SQRT2) / 2;
+/** The share of a normal sample lying further than `z` standard deviations from its centre, on either side. */
+export const normalBeyond = (z) => erfc(z / Math.SQRT2);
+const horner = (coefficients, x) => coefficients.reduce((total, coefficient) => total * x + coefficient, 0);
+const CENTRAL_NUMERATOR = [
+    -3.969683028665376e+01, 2.209460984245205e+02, -2.759285104469687e+02,
+    1.383577518672690e+02, -3.066479806614716e+01, 2.506628277459239e+00
+];
+const CENTRAL_DENOMINATOR = [
+    -5.447609879822406e+01, 1.615858368580409e+02, -1.556989798598866e+02,
+    6.680131188771972e+01, -1.328068155288572e+01
+];
+const TAIL_NUMERATOR = [
+    -7.784894002430293e-03, -3.223964580411365e-01, -2.400758277161838e+00,
+    -2.549732539343734e+00, 4.374664141464968e+00, 2.938163982698783e+00
+];
+const TAIL_DENOMINATOR = [
+    7.784695709041462e-03, 3.224671290700398e-01, 2.445134137142996e+00, 3.754408661907416e+00
+];
+/** Outside this share the tail approximation is used in place of the central one. */
+const CENTRAL_SHARE = 0.02425;
+const tailQuantile = (share) => {
+    const q = Math.sqrt(-2 * Math.log(share));
+    return horner(TAIL_NUMERATOR, q) / (horner(TAIL_DENOMINATOR, q) * q + 1);
+};
+/**
+ * How many standard deviations out the given share of a normal sample
+ * lies below, after Acklam's rational approximation, whose relative
+ * error stays below 1.15e-9. The inverse of `normalBelow`.
+ */
+export const normalQuantile = (share) => {
+    if (share <= 0)
+        return -Infinity;
+    if (share >= 1)
+        return Infinity;
+    if (share < CENTRAL_SHARE)
+        return tailQuantile(share);
+    if (share > 1 - CENTRAL_SHARE)
+        return -tailQuantile(1 - share);
+    const q = share - 0.5;
+    const r = q * q;
+    return horner(CENTRAL_NUMERATOR, r) * q / (horner(CENTRAL_DENOMINATOR, r) * r + 1);
+};
+/**
+ * How much heavier the tails of a standardised sample are than a normal
+ * sample's. Zero for a normal shape, positive where more of the sample
+ * lies far out than the curve allows.
+ */
+export const excessKurtosisOf = (standardised) => standardised.reduce((total, z) => total + z ** 4, 0) / standardised.length - 3;
+/** What the sample puts beyond the given distance, against what a normal sample would. */
+export const tailOf = (standardised, beyond) => ({
+    beyond,
+    observed: standardised.filter(z => Math.abs(z) > beyond).length,
+    expected: standardised.length * normalBeyond(beyond)
+});
+/**
+ * The sample counted into bins of the given width, laid out on
+ * multiples of that width so that two histograms of one width share
+ * their bounds. Nothing for an empty sample or a width of nothing.
+ */
+export const histogramOf = (values, binWidth) => {
+    if (values.length === 0 || binWidth <= 0)
+        return undefined;
+    const first = Math.floor(Math.min(...values) / binWidth) * binWidth;
+    const last = Math.ceil(Math.max(...values) / binWidth) * binWidth;
+    const bins = Math.max(1, Math.round((last - first) / binWidth));
+    return {
+        edges: Array.from({ length: bins + 1 }, (_, i) => quantity(first + i * binWidth)),
+        counts: values.reduce((tally, value) => {
+            tally[Math.min(bins - 1, Math.floor((value - first) / binWidth))] += 1;
+            return tally;
+        }, new Array(bins).fill(0))
+    };
+};

package/lib/utils.d.ts

@@ -14,6 +14,8 @@ export type WithId = {
 };
 /** Whether a value is a date as the format writes one, `YYYY-MM-DD`. */
 export declare const isDateString: (value: unknown) => value is string;
+/** The items by the key each of them gives, every group in the order its first item came in. */
+export declare const groupBy: <T>(items: readonly T[], keyOf: (item: T) => string) => Map<string, T[]>;
 export type WithNote = {
     /**
      * A free-text note providing additional context.

package/lib/utils.js

@@ -1,2 +1,12 @@
 /** Whether a value is a date as the format writes one, `YYYY-MM-DD`. */
 export const isDateString = (value) => typeof value === 'string' && /^\d{4}-\d{1,2}-\d{1,2}$/.test(value);
+/** The items by the key each of them gives, every group in the order its first item came in. */
+export const groupBy = (items, keyOf) => items.reduce((groups, item) => {
+    const key = keyOf(item);
+    const group = groups.get(key);
+    if (group)
+        group.push(item);
+    else
+        groups.set(key, [item]);
+    return groups;
+}, new Map());

package/lib/vocabulary.d.ts

@@ -0,0 +1,15 @@
+import { Concept } from "./Agent";
+/**
+ * The concepts the type vocabulary declares, whatever kind they are:
+ * the reproducing systems and the procedures. An edition names one of
+ * them by its IRI alone.
+ */
+export declare const vocabulary: readonly Concept[];
+/** The concept of that IRI, where the vocabulary declares one. */
+export declare const conceptOf: (id: string | undefined) => Concept | undefined;
+/**
+ * What a concept is called: the name it states, else the one the
+ * vocabulary gives it, else its IRI, so that a reader always has
+ * something to show.
+ */
+export declare const nameOf: (concept: Concept) => string;

package/lib/vocabulary.js

@@ -0,0 +1,20 @@
+import { procedures } from "./procedures";
+import { systemOf } from "./TrackerBar";
+import { trackerBars } from "./systems";
+/**
+ * The concepts the type vocabulary declares, whatever kind they are:
+ * the reproducing systems and the procedures. An edition names one of
+ * them by its IRI alone.
+ */
+export const vocabulary = [
+    ...trackerBars.map(systemOf),
+    ...procedures
+];
+/** The concept of that IRI, where the vocabulary declares one. */
+export const conceptOf = (id) => id === undefined ? undefined : vocabulary.find(concept => concept.id === id);
+/**
+ * What a concept is called: the name it states, else the one the
+ * vocabulary gives it, else its IRI, so that a reader always has
+ * something to show.
+ */
+export const nameOf = (concept) => concept.name ?? conceptOf(concept.id)?.name ?? concept.id ?? '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linked-rolls",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "description": "Digital editions of piano rolls: import, collation, editorial assumptions, JSON-LD export, and emulation through a reproducing system",
   "license": "MIT",
   "repository": {