@thi.ng/random 3.6.38 → 3.7.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-03-13T14:04:31Z
+- **Last updated**: 2024-03-21T16:11:49Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,12 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [3.7.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/random@3.7.0) (2024-03-21)
+
+#### 🚀 Features
+
+- add weightedProbability() ([393dcaa](https://github.com/thi-ng/umbrella/commit/393dcaa))
+
 ### [3.6.13](https://github.com/thi-ng/umbrella/tree/@thi.ng/random@3.6.13) (2023-11-09)
 
 #### ♻️ Refactoring

package/README.md

@@ -98,7 +98,7 @@ For Node.js REPL:
 const random = await import("@thi.ng/random");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.99 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 2.02 KB
 
 ## Dependencies
 

package/index.d.ts

@@ -15,6 +15,7 @@ export * from "./smush32.js";
 export * from "./system.js";
 export * from "./unique-indices.js";
 export * from "./uuid.js";
+export * from "./weighted-probability.js";
 export * from "./weighted-random.js";
 export * from "./xorshift128.js";
 export * from "./xorwow.js";

package/index.js

@@ -15,6 +15,7 @@ export * from "./smush32.js";
 export * from "./system.js";
 export * from "./unique-indices.js";
 export * from "./uuid.js";
+export * from "./weighted-probability.js";
 export * from "./weighted-random.js";
 export * from "./xorshift128.js";
 export * from "./xorwow.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/random",
-  "version": "3.6.38",
+  "version": "3.7.0",
   "description": "Pseudo-random number generators w/ unified API, distributions, weighted choices, ID generation",
   "type": "module",
   "module": "./index.js",
@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "@thi.ng/api": "^8.9.30",
-    "@thi.ng/checks": "^3.5.3",
+    "@thi.ng/checks": "^3.5.4",
     "@thi.ng/errors": "^2.5.1",
     "@thi.ng/hex": "^2.3.40"
   },
@@ -135,6 +135,9 @@
     "./uuid": {
       "default": "./uuid.js"
     },
+    "./weighted-probability": {
+      "default": "./weighted-probability.js"
+    },
     "./weighted-random": {
       "default": "./weighted-random.js"
     },
@@ -157,5 +160,5 @@
       "ksuid"
     ]
   },
-  "gitHead": "bc0f3cb07d6f1cab6dbdc5ff57428f5484e711bb\n"
+  "gitHead": "da965520b2f3f8c259a791e8e8864308be2ba0be\n"
 }

package/weighted-probability.d.ts

@@ -0,0 +1,70 @@
+import type { FnN } from "@thi.ng/api";
+import type { IRandom } from "./api.js";
+/**
+ * Takes a `weight` function and optional {@link IRandom} instance (default:
+ * {@link SYSTEM}). The weight function accepts a number in [0,1) interval and
+ * returns a number in [0,1]. Draws two random numbers `a` and `b` via
+ * {@link IRandom.float} and returns a tuple of `[a, b < weight(a)]`.
+ *
+ * @example
+ * ```ts tangle:../export/weighted-probability.ts
+ * import { weightedProbability } from "@thi.ng/random";
+ *
+ * const [param, success] = weightedProbability((x) => x** 2);
+ *
+ * console.log(success ? "SUCCESS" : "FAIL", param);
+ * ```
+ *
+ * @example
+ * ```ts tangle:../export/weighted-probability-viz.ts
+ * import { weightedProbability } from "@thi.ng/random";
+ * import { barChartVStr } from "@thi.ng/text-canvas";
+ * import {
+ *     comp, filter, frequencies, map, repeatedly, transduce
+ * } from "@thi.ng/transducers";
+ *
+ * // custom weighting function
+ * const weight = (x: number) => Math.sin(x * Math.PI);
+ *
+ * // draw N samples (`[number, boolean]` tuples)
+ * const samples = repeatedly(
+ *     () => weightedProbability(weight),
+ *     // number of samples
+ *     1e6
+ * );
+ *
+ * // binning helper for histogram
+ * const bin = (x: number, n: number) => Math.floor(x * n) / n;
+ *
+ * // compute histogram, i.e. a Map of `bin => numSuccess` pairs
+ * const histogram = transduce(
+ *     // filter out failures, apply binning
+ *     comp(filter(x => x[1]), map(x => bin(x[0], 40))),
+ *     // collect histogram
+ *     frequencies(),
+ *     // input samples
+ *     samples
+ * );
+ *
+ * // visualize as ASCII art bar chart
+ * console.log(
+ *     barChartVStr(10, [...histogram].sort().map(x => x[1]))
+ * );
+ *
+ * //               ▃▅▇████▇▅▃
+ * //            ▂▆████████████▅▁
+ * //          ▂▇████████████████▆▂
+ * //         ▅████████████████████▆
+ * //       ▃████████████████████████▃
+ * //      ▆██████████████████████████▆
+ * //    ▁██████████████████████████████▁
+ * //   ▃████████████████████████████████▃
+ * //  ▅██████████████████████████████████▅
+ * // ▇████████████████████████████████████▇
+ * ```
+ *
+ * @param weight
+ * @param rnd
+ */
+export declare const weightedProbability: (weight: FnN, rnd?: IRandom) => [number, boolean];
+//# sourceMappingURL=weighted-probability.d.ts.map

package/weighted-probability.js

@@ -0,0 +1,9 @@
+import { SYSTEM } from "./system.js";
+const weightedProbability = (weight, rnd = SYSTEM) => {
+  const a = rnd.float();
+  const b = rnd.float();
+  return [a, b < weight(a)];
+};
+export {
+  weightedProbability
+};