lawkit-core 2.6.1

Core library for statistical law analysis with international number support
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

use crate::common::{filtering::RiskThreshold, risk::RiskLevel};
use crate::error::{BenfError, Result};

#[derive(Debug, Clone)]
pub struct BenfordResult {
    pub dataset_name: String,
    pub numbers_analyzed: usize,
    pub digit_distribution: [f64; 9], // Observed percentages for digits 1-9
    pub expected_distribution: [f64; 9], // Benford's Law expected percentages
    pub chi_square: f64,
    pub p_value: f64,
    pub mean_absolute_deviation: f64,
    pub risk_level: RiskLevel,
    pub verdict: String,
}

impl BenfordResult {
    pub fn new(dataset_name: String, numbers: &[f64]) -> Result<Self> {
        Self::new_with_threshold(dataset_name, numbers, &RiskThreshold::Auto, 5)
    }

    pub fn new_with_threshold(
        dataset_name: String,
        numbers: &[f64],
        threshold: &RiskThreshold,
        min_count: usize,
    ) -> Result<Self> {
        if numbers.is_empty() {
            return Err(BenfError::NoNumbersFound);
        }

        // Check minimum count requirement
        if numbers.len() < min_count {
            return Err(BenfError::InsufficientData(numbers.len()));
        }

        // Issue warning for small datasets but continue analysis
        if numbers.len() < 30 {
            eprintln!("Warning: {numbers_analyzed} numbers analyzed. For reliable Benford's Law analysis, 30+ numbers recommended.", numbers_analyzed=numbers.len());
        }

        let digit_distribution = super::analysis::calculate_digit_distribution(numbers);
        let expected_distribution = super::analysis::BENFORD_EXPECTED_PERCENTAGES;
        let chi_square = crate::common::statistics::calculate_chi_square(
            &digit_distribution,
            &expected_distribution,
        );
        let p_value = crate::common::statistics::calculate_p_value(chi_square, 8); // 8 degrees of freedom
        let mean_absolute_deviation =
            crate::common::statistics::calculate_mad(&digit_distribution, &expected_distribution);

        // Use custom threshold if provided, otherwise use default logic
        let risk_level = threshold.evaluate_risk(p_value);

        let verdict = match risk_level {
            RiskLevel::Low => "NORMAL_DISTRIBUTION".to_string(),
            RiskLevel::Medium => "SLIGHT_DEVIATION".to_string(),
            RiskLevel::High => "SIGNIFICANT_DEVIATION".to_string(),
            RiskLevel::Critical => "STRONG_EVIDENCE_OF_MANIPULATION".to_string(),
        };

        Ok(BenfordResult {
            dataset_name,
            numbers_analyzed: numbers.len(),
            digit_distribution,
            expected_distribution,
            chi_square,
            p_value,
            mean_absolute_deviation,
            risk_level,
            verdict,
        })
    }

    pub fn new_with_confidence(
        dataset_name: String,
        numbers: &[f64],
        _threshold: &RiskThreshold,
        min_count: usize,
        confidence_level: f64,
    ) -> Result<Self> {
        if numbers.is_empty() {
            return Err(BenfError::NoNumbersFound);
        }

        // Check minimum count requirement
        if numbers.len() < min_count {
            return Err(BenfError::InsufficientData(numbers.len()));
        }

        // Issue warning for small datasets but continue analysis
        if numbers.len() < 30 {
            eprintln!("Warning: {numbers_analyzed} numbers analyzed. For reliable Benford's Law analysis, 30+ numbers recommended.", numbers_analyzed=numbers.len());
        }

        let digit_distribution = super::analysis::calculate_digit_distribution(numbers);
        let expected_distribution = super::analysis::BENFORD_EXPECTED_PERCENTAGES;
        let chi_square = crate::common::statistics::calculate_chi_square(
            &digit_distribution,
            &expected_distribution,
        );

        // Use standard p-value calculation (confidence level adjustment in interpretation)
        let p_value = crate::common::statistics::calculate_p_value(chi_square, 8);

        let mean_absolute_deviation =
            crate::common::statistics::calculate_mad(&digit_distribution, &expected_distribution);

        // Adjust risk assessment based on confidence level
        let adjusted_alpha = 1.0 - confidence_level;
        let risk_level = if p_value < adjusted_alpha / 4.0 {
            RiskLevel::Critical
        } else if p_value < adjusted_alpha / 2.0 {
            RiskLevel::High
        } else if p_value < adjusted_alpha {
            RiskLevel::Medium
        } else {
            RiskLevel::Low
        };

        let verdict = match risk_level {
            RiskLevel::Low => "NORMAL_DISTRIBUTION".to_string(),
            RiskLevel::Medium => "SLIGHT_DEVIATION".to_string(),
            RiskLevel::High => "SIGNIFICANT_DEVIATION".to_string(),
            RiskLevel::Critical => "STRONG_EVIDENCE_OF_MANIPULATION".to_string(),
        };

        Ok(BenfordResult {
            dataset_name,
            numbers_analyzed: numbers.len(),
            digit_distribution,
            expected_distribution,
            chi_square,
            p_value,
            mean_absolute_deviation,
            risk_level,
            verdict,
        })
    }
}