Benford's Law

Simple Laravel console app that calculates if an array of integers follows Benford's Law

Assumptions

• Benford's Law percentages taken from Wikipedia
  • Percentages are located in the benfordslaw.php config file
• The application tests for the distribution of leading digit only
• The application does not test for an exact match and instead allows for a slight variance in the distribution percentage, this is set in the benfordslaw.php config file
  • EX: Benford's Law says all integers with a leading digit of 1 should have a 30.1% distribution, but if the variance is set to 2 it will allow the distribution to range from 28.1% to 32.1%
• ALL leading digit distributions must be within the variance threshold in order to pass
• Integers must be positive and must be integers (no floats, negatives, etc.)
  • There is some minor validations around this
• Although this is a console app, the logic for determining Benford's Law lives in the BenfordsLawService.php
  • The idea is this service class could easily be re-used with an HTTP controller, command, queued job, etc.
  • BenfordsLawService.php is provided to the container as a singleton (it is assumed the config values would be application-wide)
• The service requires at least 10 integers be passed in, this is also configurable

Prerequisites

• Docker Desktop
• This application does not have a custom URL and will just run on localhost, make sure this is not blocked by another container or modify the docker-compose.yml

Installation

git clone [email protected]:pardamike/benfords-law.git
cd benfords-law
cp .env.example .env
docker compose up -d

Console Command Usage

To use, simply call the benfords-law:run Artisan command and pass in a comma or space separated list of integers

docker exec benfords-law-laravel.test-1 php artisan benfords-law:run <LIST OF INTEGERS>

Running Tests

There are some basic unit tests for the BenfordsLawService.php class, to run them, simply run:

docker exec benfords-law-laravel.test-1 php artisan test

Example Console Output

Success

SUCCESS: This data set follows Benfords Law!
+-----+------+-------+-------------+-------------------------+
|  n  | Freq | Pct   | Benford Pct | Within Variance (+/-2%) |
+-----+------+-------+-------------+-------------------------+
| 1   | 960  | 30.54 | 30.1        | Yes                     |
| 2   | 580  | 18.45 | 17.6        | Yes                     |
| 3   | 381  | 12.12 | 12.5        | Yes                     |
| 4   | 297  | 9.45  | 9.7         | Yes                     |
| 5   | 234  | 7.45  | 7.9         | Yes                     |
| 6   | 203  | 6.46  | 6.7         | Yes                     |
| 7   | 173  | 5.50  | 5.8         | Yes                     |
| 8   | 163  | 5.19  | 5.1         | Yes                     |
| 9   | 152  | 4.84  | 4.6         | Yes                     |
+-----+------+-------+-------------+-------------------------+

Failure

FAIL: Distribution of one or more numbers fall below Benfords Law - using variance threshold of 2%
+-----+------+-------+-------------+-------------------------+
|  n  | Freq | Pct   | Benford Pct | Within Variance (+/-2%) |
+-----+------+-------+-------------+-------------------------+
| 1   | 344  | 10.90 | 30.1        | No                      |
| 2   | 356  | 11.28 | 17.6        | No                      |
| 3   | 337  | 10.68 | 12.5        | Yes                     |
| 4   | 353  | 11.19 | 9.7         | Yes                     |
| 5   | 350  | 11.09 | 7.9         | No                      |
| 6   | 354  | 11.22 | 6.7         | No                      |
| 7   | 369  | 11.69 | 5.8         | No                      |
| 8   | 333  | 10.55 | 5.1         | No                      |
| 9   | 360  | 11.41 | 4.6         | No                      |
+-----+------+-------+-------------+-------------------------+