benford-law 1.0.0

package/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Maxime Golfier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# benford-law
+
+Benford's law is an observation that in many real-life sets of numerical data, the leading digit is likely to be small. In sets that obey the law, the number 1 appears as the leading significant digit about 30% of the time, while 9 appears as the leading significant digit less than 5% of the time. If the digits were distributed uniformly, they would each occur about 11.1% of the time. Benford's law also makes predictions about the distribution of second digits, third digits, digit combinations, and so on.
+
+To get a better understanding of Benford's law, check out [this article](https://en.wikipedia.org/wiki/Benford%27s_law).
+
+## Installation
+
+```bash
+yarn add benford-law
+```
+
+## Usage
+
+```ts
+import {
+  processBenfordLaw,
+  generateBenfordLawNumbers,
+  generateBenfordLawNumber,
+} from 'benford-law';
+
+// to generate a random number that follows Benford's law
+console.log(generateBenfordLawNumber());
+
+// to generate an array of 10 random numbers that follow Benford's law
+console.log(generateBenfordLawNumbers(10));
+
+// to process an array of numbers and get the distribution
+console.log(processBenfordLaw(generateBenfordLawNumbers(50000), 0.01));
+// {
+//   isFollowingBenfordLaw: true,
+//   firstDigitProbabilities: {
+//     '1': 0.29908,
+//     '2': 0.17694,
+//     '3': 0.1255,
+//     '4': 0.09742,
+//     '5': 0.0793,
+//     '6': 0.06712,
+//     '7': 0.0571,
+//     '8': 0.05124,
+//     '9': 0.0463
+//   },
+//   firstDigitCounts: {
+//     '1': 14954,
+//     '2': 8847,
+//     '3': 6275,
+//     '4': 4871,
+//     '5': 3965,
+//     '6': 3356,
+//     '7': 2855,
+//     '8': 2562,
+//     '9': 2315
+//   },
+//   firstDigitAccuracy: {
+//     '1': 0.0019199999999999773,
+//     '2': 0.0009399999999999964,
+//     '3': 0.0005000000000000004,
+//     '4': 0.0004200000000000037,
+//     '5': 0.0002999999999999947,
+//     '6': 0.00011999999999999511,
+//     '7': 0.000900000000000005,
+//     '8': 0.0002400000000000041,
+//     '9': 0.00030000000000000165
+//   }
+// }
+```

package/build/benford.d.ts

@@ -0,0 +1,8 @@
+export declare const generateBenfordLawNumber: () => number;
+export declare const generateBenfordLawNumbers: (length: number) => number[];
+export declare const processBenfordLaw: (numbers: number[], threshold?: number, benfordProbabilities?: Record<string, number>) => {
+    isFollowingBenfordLaw: boolean;
+    firstDigitCounts: Record<string, number>;
+    firstDigitProbabilities: Record<string, number>;
+    firstDigitAccuracy: Record<string, number>;
+};

package/build/benford.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processBenfordLaw = exports.generateBenfordLawNumbers = exports.generateBenfordLawNumber = void 0;
+const benfordProb = {
+    '1': 0.301,
+    '2': 0.176,
+    '3': 0.125,
+    '4': 0.097,
+    '5': 0.079,
+    '6': 0.067,
+    '7': 0.058,
+    '8': 0.051,
+    '9': 0.046,
+};
+const generateRandomNumber = (minimum, maximum) => Math.random() * (maximum - minimum) + minimum;
+const getFirstDigit = (number) => {
+    const string = number.toString();
+    return parseInt(string[0], 10);
+};
+const generateBenfordLawNumber = () => Math.exp(generateRandomNumber(Math.log(1), Math.log(1000)));
+exports.generateBenfordLawNumber = generateBenfordLawNumber;
+const generateBenfordLawNumbers = (length) => {
+    const numbers = [];
+    for (let i = 0; i < length; i++) {
+        numbers.push((0, exports.generateBenfordLawNumber)());
+    }
+    return numbers;
+};
+exports.generateBenfordLawNumbers = generateBenfordLawNumbers;
+const processBenfordLaw = (numbers, threshold = 0.01, benfordProbabilities = benfordProb) => {
+    const firstDigits = numbers.map(getFirstDigit);
+    const firstDigitCounts = firstDigits.reduce((acc, digit) => ({
+        ...acc,
+        [digit]: (acc[digit] || 0) + 1,
+    }), {});
+    const firstDigitProbabilities = Object.entries(firstDigitCounts).reduce((acc, [digit, count]) => ({
+        ...acc,
+        [digit]: count / numbers.length,
+    }), {});
+    const firstDigitAccuracy = Object.entries(firstDigitProbabilities).reduce((acc, [digit, probability]) => {
+        const benfordProbability = benfordProbabilities[digit];
+        const diff = Math.abs(benfordProbability - probability);
+        return {
+            ...acc,
+            [digit]: diff,
+        };
+    }, {});
+    const isBenford = Object.entries(benfordProbabilities).every(([digit, probability]) => {
+        const firstDigitProbability = firstDigitProbabilities[digit];
+        return (firstDigitProbability &&
+            Math.abs(firstDigitProbability - probability) < threshold);
+    });
+    return {
+        isFollowingBenfordLaw: isBenford,
+        firstDigitProbabilities,
+        firstDigitCounts,
+        firstDigitAccuracy,
+    };
+};
+exports.processBenfordLaw = processBenfordLaw;

package/build/index.d.ts

@@ -0,0 +1 @@
+export * from "./benford";

package/build/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./benford"), exports);

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "benford-law",
+  "version": "1.0.0",
+  "author": "maxgfr",
+  "license": "MIT",
+  "description": "A simple library to check if a dataset follows the Benford's law",
+  "main": "./build/index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/maxgfr/benford-law.git"
+  },
+  "bugs": {
+    "url": "https://github.com/maxgfr/benford-law/issues"
+  },
+  "homepage": "https://github.com/maxgfr/benford-law#readme",
+  "files": [
+    "build"
+  ],
+  "keywords": [
+    "benford",
+    "benford's law",
+    "trading",
+    "algorithm"
+  ],
+  "scripts": {
+    "start": "node build/index.js",
+    "dev": "nodemon",
+    "develop": "node -r @swc-node/register ./src/index.ts",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch",
+    "clean": "rimraf build",
+    "build": "tsc -p tsconfig.build.json",
+    "build:watch": "tsc -w -p tsconfig.build.json",
+    "build:swc": "swc ./src -d build",
+    "build:swc:watch": "swc ./src -d build -w",
+    "lint": "eslint ./src --ext .ts",
+    "prettier": "prettier --write './src/**/*.{ts,js,json}'",
+    "release": "semantic-release"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.2",
+    "@semantic-release/commit-analyzer": "^9.0.2",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^8.0.7",
+    "@semantic-release/npm": "^9.0.1",
+    "@semantic-release/release-notes-generator": "^10.0.3",
+    "@swc-node/register": "1.5.4",
+    "@swc/cli": "0.1.57",
+    "@swc/core": "1.3.21",
+    "@swc/jest": "0.2.23",
+    "@types/jest": "29.2.3",
+    "@types/node": "18.11.10",
+    "@typescript-eslint/eslint-plugin": "5.45.0",
+    "@typescript-eslint/parser": "5.45.0",
+    "eslint": "8.29.0",
+    "eslint-config-prettier": "8.5.0",
+    "eslint-plugin-jest": "27.1.6",
+    "jest": "29.3.1",
+    "nodemon": "2.0.20",
+    "prettier": "2.8.0",
+    "rimraf": "3.0.2",
+    "semantic-release": "19.0.5",
+    "typescript": "4.9.3"
+  }
+}