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

> Learn how the Benford's Law check in AI Berkshire works. Discover its implementation using MAD and Chi-square statistics in tools/financial_rigor.py to find data anomalies.

- Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire)
- Tags: how-to-guide
- Published: 2026-07-10

---

**The AI Berkshire repository validates financial data against Benford's Law through the `benford_check` function in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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:

```bash
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:

```python
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:

```text
------------------------------------------------------------
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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)**, which contains the `benford_check` function and CLI integration. Documentation references appear in [`README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README.md), [`README_EN.md`](https://github.com/xbtlin/ai-berkshire/blob/main/README_EN.md), and repository layout details are described in [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md).