https://github.com/chirindaopensource/search_benford_law_compatibility
End-to-End Python scalable forensic accounting toolkit implementing Benford's Law analysis for FTSE financial data. Delivers automated anomaly detection with Chi-Squared/MAD testing, comprehensive validation pipelines, and risk-based prioritization of investigative resources. Replicates Ausloos et al.'s (2025) methodology with full reproducibility.
https://github.com/chirindaopensource/search_benford_law_compatibility
academic-research anomaly-detection benfords-law chi-squared-test data-validation econometrics financial-analysis financial-data forensic-accounting fraud-detection ftse goodness-of-fit jupyter-notebook numpy pandas python reproducible-research risk-management scipy statistical-testing
Last synced: 5 months ago
JSON representation
End-to-End Python scalable forensic accounting toolkit implementing Benford's Law analysis for FTSE financial data. Delivers automated anomaly detection with Chi-Squared/MAD testing, comprehensive validation pipelines, and risk-based prioritization of investigative resources. Replicates Ausloos et al.'s (2025) methodology with full reproducibility.
- Host: GitHub
- URL: https://github.com/chirindaopensource/search_benford_law_compatibility
- Owner: chirindaopensource
- License: mit
- Created: 2025-09-13T16:59:18.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-09-13T17:10:49.000Z (12 months ago)
- Last Synced: 2025-09-13T19:08:40.536Z (12 months ago)
- Topics: academic-research, anomaly-detection, benfords-law, chi-squared-test, data-validation, econometrics, financial-analysis, financial-data, forensic-accounting, fraud-detection, ftse, goodness-of-fit, jupyter-notebook, numpy, pandas, python, reproducible-research, risk-management, scipy, statistical-testing
- Language: Jupyter Notebook
- Homepage:
- Size: 81.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# `README.md`
# A Scalable Framework for Benford's Law Conformity Testing of Financial Data
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://github.com/psf/black)
[](https://pycqa.github.io/isort/)
[](http://mypy-lang.org/)
[](https://jupyter.org/)
[](https://arxiv.org/abs/2509.09415)
[](https://github.com/chirindaopensource/search_benford_law_compatibility)
[](https://github.com/chirindaopensource/search_benford_law_compatibility)
[](https://github.com/chirindaopensource/search_benford_law_compatibility)
[](https://www.refinitiv.com/en/products/eikon-trading-software)
[](https://pandas.pydata.org/)
[](https://numpy.org/)
[](https://scipy.org/)
[](https://pyyaml.org/)
--
**Repository:** `https://github.com/chirindaopensource/search_benford_law_compatibility`
**Owner:** 2025 Craig Chirinda (Open Source Projects)
This repository contains an **independent**, professional-grade Python implementation of the research methodology from the 2025 paper entitled **"Note on pre-taxation reported data by UK FTSE-listed companies. A search for Benford's laws compatibility"** by:
* Marcel Ausloos
* Probowo Erawan Sastroredjo
* Polina Khrennikova
The project provides a complete, end-to-end computational framework for testing the conformity of financial datasets with Benford's Law. It delivers a modular, auditable, and extensible pipeline that replicates the paper's entire workflow: from rigorous data and configuration validation, through robust, mathematically-grounded digit extraction, to the precise calculation of Chi-Squared and Mean Absolute Deviation (MAD) test statistics and the final generation of publication-quality results tables.
## Table of Contents
- [Introduction](#introduction)
- [Theoretical Background](#theoretical-background)
- [Features](#features)
- [Methodology Implemented](#methodology-implemented)
- [Core Components (Notebook Structure)](#core-components-notebook-structure)
- [Key Callable: execute_full_project_workflow](#key-callable-execute_full_project_workflow)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Input Data Structure](#input-data-structure)
- [Usage](#usage)
- [Output Structure](#output-structure)
- [Project Structure](#project-structure)
- [Customization](#customization)
- [Contributing](#contributing)
- [Recommended Extensions](#recommended-extensions)
- [License](#license)
- [Citation](#citation)
- [Acknowledgments](#acknowledgments)
## Introduction
This project provides a Python implementation of the methodologies presented in the 2025 paper "Note on pre-taxation reported data by UK FTSE-listed companies. A search for Benford's laws compatibility." The core of this repository is the iPython Notebook `search_benford_law_compatibility_draft.ipynb`, which contains a comprehensive suite of functions to replicate the paper's findings, from initial data validation to the final generation and analysis of conformity test results.
The paper addresses a classic problem in forensic accounting and auditing: using statistical laws to identify potential anomalies in reported financial data. This codebase operationalizes the paper's approach, allowing users to:
- Rigorously validate input data and methodological parameters against a predefined schema.
- Perform a detailed data quality audit, identifying outliers and missing value patterns without altering the source data.
- Create derived analytical variables (e.g., PI/TA ratio) and segmented datasets (e.g., profitable vs. unprofitable firms).
- Apply robust, mathematically-grounded algorithms to extract the first, second, and first-two significant digits from numerical data.
- Calculate the theoretical probability distributions for Benford's Law (BL1, BL2, BL12) with high precision.
- Execute Pearson's Chi-Squared (χ²) and Mean Absolute Deviation (MAD) goodness-of-fit tests to quantify deviations from the theoretical benchmarks.
- Generate a full suite of publication-quality tables that precisely replicate the findings in the source paper.
- Conduct a comprehensive series of robustness checks, including bootstrap resampling, parameter sensitivity analysis, and temporal stability analysis.
## Theoretical Background
The implemented methods are grounded in Probability Theory, Statistics, and Forensic Accounting.
**1. Benford's Law (The First-Digit Law):**
Benford's Law states that in many naturally occurring sets of numbers, the leading significant digit is more likely to be small. The probability of a first digit `d` is given by:
$$ P(d_1 = i) = \log_{10}\left(1 + \frac{1}{i}\right) \quad \text{for } i \in \{1, ..., 9\} $$
This principle extends to second and subsequent digits, as well as to blocks of digits, with specific logarithmic formulas. Deviations from these expected frequencies can suggest that a dataset was not naturally generated and may be the result of manipulation, fabrication, or systemic error.
**2. Chi-Squared (χ²) Goodness-of-Fit Test:**
This is a classical statistical test used to determine if there is a significant difference between observed and expected frequencies. The test statistic is calculated as:
$$ \chi^2 = \sum_{i=1}^{K} \frac{(O_i - E_i)^2}{E_i} $$
where `O` are the observed counts and `E` are the expected counts across `K` bins. A large χ² statistic suggests that the observed data does not fit the theoretical distribution.
**3. Mean Absolute Deviation (MAD) Test:**
The MAD test provides a direct measure of the magnitude of the deviation between the observed proportions (`fₒ`) and the expected proportions (`fₑ`). The paper uses the sum of absolute deviations:
$$ \text{MAD} = \sum_{i=1}^{K} |f_{o,i} - f_{e,i}| $$
This statistic is less sensitive to sample size than the χ² test and provides an intuitive measure of non-conformity, which is then compared against established thresholds.
## Features
The provided iPython Notebook (`search_benford_law_compatibility_draft.ipynb`) implements the full research pipeline, including:
- **Modular, Task-Based Architecture:** The entire pipeline is broken down into 18 distinct, modular tasks, from data validation to final packaging.
- **Configuration-Driven Design:** All methodological parameters are managed in an external `config.yaml` file, allowing for easy customization without code changes.
- **Professional-Grade Data Validation:** A comprehensive validation suite ensures all inputs (data and configurations) conform to the required schema before execution.
- **Robust, Mathematical Digit Extraction:** Numerically stable, from-scratch implementations of logarithmic algorithms for extracting significant digits, avoiding common pitfalls of string-based methods.
- **High-Fidelity Statistical Testing:** Precise, vectorized implementations of the Chi-Squared and Mean Absolute Deviation tests.
- **Automated Report Generation:** Programmatic generation of all 6 analytical tables (Tables 3-8) from the paper with high fidelity to the original formatting.
- **Advanced Robustness Toolkit:**
- A framework for conducting **bootstrap resampling** to assess the stability of test statistics.
- A framework for **parameter sensitivity analysis** to test the impact of varying alpha levels and MAD thresholds.
- A framework for **temporal stability analysis** to check for consistency of results over time.
- **Automated Replication Validation:** A final quality assurance step that programmatically compares the generated results against the paper's published statistics and produces a certification report.
## Methodology Implemented
The core analytical steps directly implement the methodology from the paper:
1. **Validation (Tasks 1-3):** Ingests and rigorously validates the raw data and `config.yaml` file, and performs a detailed data quality audit.
2. **Preprocessing (Tasks 4-6):** Prepares the data by flagging outliers, creating the PI/TA ratio, segmenting the data by profitability, and generating the summary statistics table (Table 1).
3. **Digit Extraction (Tasks 7-9):** Applies robust mathematical algorithms to extract the first, second, and first-two significant digits for all relevant variables.
4. **Theoretical Distribution Generation (Tasks 10-12):** Calculates the high-precision theoretical probabilities and expected frequencies for BL1, BL2, and BL12.
5. **Statistical Testing & Reporting (Tasks 13-15):** Executes the Chi-Squared and MAD tests for all variable-digit combinations and compiles the results into replications of Tables 3-8.
6. **Robustness & Packaging (Tasks 16-18):** Orchestrates the entire pipeline, runs the optional robustness checks, and performs the final validation and packaging of all outputs.
## Core Components (Notebook Structure)
The `search_benford_law_compatibility_draft.ipynb` notebook is structured as a logical pipeline with modular orchestrator functions for each of the major tasks. All functions are self-contained, fully documented with type hints and docstrings, and designed for professional-grade execution.
## Key Callable: execute_full_project_workflow
The central function in this project is `execute_full_project_workflow`. It orchestrates the entire analytical workflow, providing a single entry point for running the baseline study replication and the advanced robustness checks.
```python
def execute_full_project_workflow(
raw_financial_data: pd.DataFrame,
study_configuration: Dict[str, Any],
output_directory: str,
run_robustness_checks: bool = True
) -> Dict[str, Any]:
"""
Executes the entire, end-to-end research project workflow.
"""
# ... (implementation is in the notebook)
```
## Prerequisites
- Python 3.9+
- Core dependencies: `pandas`, `numpy`, `scipy`, `pyyaml`, `tqdm`.
## Installation
1. **Clone the repository:**
```sh
git clone https://github.com/chirindaopensource/search_benford_law_compatibility.git
cd search_benford_law_compatibility
```
2. **Create and activate a virtual environment (recommended):**
```sh
python -m venv venv
source venv/bin/activate # On Windows, use `venv\Scripts\activate`
```
3. **Install Python dependencies:**
```sh
pip install pandas numpy scipy pyyaml tqdm
```
## Input Data Structure
The pipeline requires two primary inputs:
1. **`raw_financial_data`:** A `pandas.DataFrame` containing the panel data. It **must** have a `MultiIndex` with the levels `['CompanyID', 'Year']` and the columns `['CompanyName', 'PreTaxIncome_GBP', 'TotalAssets_GBP']`. Financial columns must be `float64`.
2. **`study_configuration`:** A Python dictionary loaded from the `config.yaml` file, which controls all methodological parameters.
A mock data generation function is provided in the main notebook to create a valid example DataFrame for testing the pipeline.
## Usage
The `search_benford_law_compatibility_draft.ipynb` notebook provides a complete, step-by-step guide. The core workflow is:
1. **Prepare Inputs:** Load your `raw_financial_data` DataFrame. Ensure the `config.yaml` file is present in the same directory.
2. **Execute Pipeline:** Call the grand orchestrator function.
```python
# This single call runs the entire project.
final_project_outputs = execute_full_project_workflow(
raw_financial_data=my_company_data_df,
study_configuration=my_config_dict,
output_directory="research_outputs",
run_robustness_checks=False # Set to True for the full analysis
)
```
3. **Inspect Outputs:** All results are saved to the specified output directory. You can also programmatically access any result from the returned dictionary.
## Output Structure
The `execute_full_project_workflow` function returns a single, comprehensive dictionary containing all generated artifacts. Additionally, the `output_directory` will be populated with:
- `replication_validation_report.json`: A report certifying the accuracy of the replication.
- `data_quality_report.json`: A detailed audit of the input data quality.
- `table_1_summary_statistics.csv`: The replicated descriptive statistics table.
- `table_3_body.csv`, `table_3_stats.csv`, etc.: Pairs of CSV files for each analytical table (3-8).
- `raw_test_results.json`: A comprehensive file with the detailed numerical outputs of all statistical tests.
- `robustness_analysis_report.json`: (If run) A file with the results of all robustness checks.
## Project Structure
```
search_benford_law_compatibility/
│
├── search_benford_law_compatibility_draft.ipynb # Main implementation notebook
├── config.yaml # Master configuration file
├── requirements.txt # Python package dependencies
├── LICENSE # MIT license file
└── README.md # This documentation file
```
## Customization
The pipeline is highly customizable via the `config.yaml` file. Users can easily modify all methodological parameters, such as statistical thresholds, critical values, and bin definitions, without altering the core Python code.
## Contributing
Contributions are welcome. Please fork the repository, create a feature branch, and submit a pull request with a clear description of your changes. Adherence to PEP 8, type hinting, and comprehensive docstrings is required.
## Recommended Extensions
Future extensions could include:
- **Additional Goodness-of-Fit Tests:** Implementing other statistical tests for Benford's Law conformity, such as the Kolmogorov-Smirnov test or Kuiper's test.
- **Visualization Module:** Creating a function that takes the final results and generates plots of the observed vs. expected distributions, similar to Figures 2-4 in the paper.
- **Automated Reporting:** Building a module that uses the generated tables and plots to automatically create a full PDF or HTML summary report of the findings.
- **Integration with Database:** Developing a data ingestion module to pull data directly from a SQL database instead of a CSV file.
## License
This project is licensed under the MIT License. See the `LICENSE` file for details.
## Citation
If you use this code or the methodology in your research, please cite the original paper:
```bibtex
@article{ausloos2025note,
title={{Note on pre-taxation reported data by UK FTSE-listed companies. A search for Benford's laws compatibility}},
author={Ausloos, Marcel and Sastroredjo, Probowo Erawan and Khrennikova, Polina},
journal={arXiv preprint arXiv:2509.09415},
year={2025}
}
```
For the implementation itself, you may cite this repository:
```
Chirinda, C. (2025). A Python Implementation for Benford's Law Conformity Testing of Financial Data.
GitHub repository: https://github.com/chirindaopensource/search_benford_law_compatibility
```
## Acknowledgments
- Credit to **Marcel Ausloos, Probowo Erawan Sastroredjo, and Polina Khrennikova** for their foundational research, which forms the entire basis for this computational replication.
- This project is built upon the exceptional tools provided by the open-source community. Sincere thanks to the developers of the scientific Python ecosystem, including **Pandas, NumPy, SciPy, and PyYAML**, whose work makes complex computational analysis accessible and robust.
--
*This README was generated based on the structure and content of `search_benford_law_compatibility_draft.ipynb` and follows best practices for research software documentation.*