How the Benford's Law Check Works in AI Berkshire: Implementation and Usage Guide

The AI Berkshire repository validates financial data against Benford's Law through the benford_check function in tools/financial_rigor.py, using Mean Absolute Deviation (MAD) and Chi-square statistics to detect anomalous digit distributions.

AI Berkshire is an open-source financial analysis toolkit that includes a Financial Rigor Toolkit for detecting data irregularities. The Benford's Law check serves as a statistical sanity test to identify potential fabrication or manipulation in numeric datasets. This implementation provides both command-line accessibility and programmatic integration for automated data quality pipelines.

The benford_check Function Implementation

The core logic resides in tools/financial_rigor.py within the benford_check function. This self-contained routine performs an eight-step statistical validation process.

Leading Digit Extraction

The function first converts each supplied numeric value to a positive float and isolates the most significant digit using int(sig). Only digits 1 through 9 are retained for analysis, excluding zeros and negative values.

Sample Size Guard

Benford analysis requires statistical significance. The implementation enforces a minimum threshold of 50 observations. If the digit list contains fewer values, the function aborts with a warning to prevent unreliable conclusions.

Expected Benford Distribution

The theoretical benchmark uses pre-computed constants defined as _BENFORD[d] = log10(1 + 1/d) for each digit 1-9. These values represent the expected probability distribution according to Benford's Law.

Statistical Metrics Calculation

The function computes two key divergence measures:

• Mean Absolute Deviation (MAD): The average absolute difference between observed and expected frequencies across all digits.
• Chi-square (χ²): The classic goodness-of-fit statistic quantifying the overall distribution mismatch.

Conformity Classification

Based on the MAD score, the data receives one of four conformity labels:

MAD Range	Conformity Label
< 0.006	"Close (高度符合)"
< 0.012	"Acceptable (可接受)"
< 0.015	"Marginally Acceptable (边缘)"
≥ 0.015	"Nonconforming (不符合 ⚠️)"

Additionally, the system flags any individual digit where the absolute deviation exceeds 0.03.

How to Run the Benford's Law Check

Command Line Interface

Invoke the check directly from the terminal using the module's CLI:

python -m tools.financial_rigor benford \
    --values '[1234, 2345, 3456, 4567, 5678, 6789, 7890, 8912, 9123, ...]'

This interface accepts JSON-formatted value arrays and prints the formatted results table to stdout.

Programmatic Usage

Import benford_check directly for integration into Python workflows:

from tools.financial_rigor import benford_check

# Example list of financial figures (e.g., yearly revenues)

values = [
    1_234_567, 2_345_678, 3_456_789, 4_567_890,
    5_678_901, 6_789_012, 7_890_123, 8_901_234,
    9_012_345, 1_123_456, 2_234_567, 3_345_678,
    # … add more to reach >= 50 observations

]

result = benford_check(values)

print("MAD:", result["mad"])
print("Conforms to Benford's Law:", result["is_conforming"])

Interpreting the Results

The function returns a dictionary containing mad, chi2, conformity, and a Boolean is_conforming. The CLI output displays a formatted table:

------------------------------------------------------------
Benford定律检测 (Financial Data Fabrication Check)
------------------------------------------------------------
  样本量:    52
  MAD:       0.004321
  Chi-sq:    3.27
  符合度:    Close (高度符合)

  首位数   观测    Benford期望    偏差
  -----   ----    ------------    ----
      1   0.302   0.301          +0.001
      2   0.176   0.176          +0.000
      …

A final verdict displays as ✅ for conforming data or ❌ for nonconforming datasets, accompanied by a brief advisory note highlighting specific anomalous digits.

Summary

• The Benford's Law check in AI Berkshire is implemented in tools/financial_rigor.py via the benford_check function.
• The analysis requires a minimum of 50 observations to ensure statistical reliability.
• Conformity is determined using MAD thresholds (0.006, 0.012, 0.015) with additional flagging for individual digit deviations exceeding 0.03.
• The function returns a structured dictionary with mad, chi2, conformity, and is_conforming values for programmatic use.
• Both CLI and Python API interfaces are available for flexible integration into data quality workflows.

Frequently Asked Questions

What is the minimum sample size required for the Benford's Law check in AI Berkshire?

The implementation requires at least 50 observations to perform the analysis. If fewer values are provided, the function aborts with a warning, as smaller samples lack the statistical power to reliably detect deviations from Benford's expected distribution.

How does AI Berkshire classify conformity to Benford's Law?

The system uses Mean Absolute Deviation (MAD) thresholds to categorize results: "Close (高度符合)" for MAD < 0.006, "Acceptable (可接受)" for MAD < 0.012, "Marginally Acceptable (边缘)" for MAD < 0.015, and "Nonconforming (不符合 ⚠️)" for MAD ≥ 0.015. Individual digits exceeding 0.03 absolute deviation are flagged separately.

Can I integrate the Benford's Law check into an automated data pipeline?

Yes. The benford_check function returns a Python dictionary containing mad, chi2, conformity, and is_conforming fields, making it suitable for automated data quality monitoring. You can import the function from tools.financial_rigor and use the Boolean is_conforming value to trigger alerts or downstream processing.

What files contain the Benford's Law implementation in AI Berkshire?

The primary implementation resides in tools/financial_rigor.py, which contains the benford_check function and CLI integration. Documentation references appear in README.md, README_EN.md, and repository layout details are described in AGENTS.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}