ledgerlens 0.1.2__py3-none-any.whl

ledgerlens/__init__.py

@@ -0,0 +1,60 @@
+"""ledgerlens - forensic accounting analytics for Python.
+
+Three building blocks:
+
+* :mod:`ledgerlens.benford`  - Benford's Law digit tests following Nigrini (2012)
+* :mod:`ledgerlens.jet`      - journal entry tests for general-ledger data
+* :mod:`ledgerlens.scores`   - Beneish M-Score, Altman Z-Score, Piotroski F-Score
+
+Quick start::
+
+    import ledgerlens as ll
+
+    res = ll.benford(df["Amount"], test="first_two")
+    print(res.summary())
+
+    report = ll.JournalEntryTester(gl, entry_id="je_id", date="post_date",
+                                   amount="amount", account="account").run_all()
+    report.to_excel("jet_report.xlsx")
+"""
+
+from .benford import (
+    BenfordResult,
+    benford,
+    expected_distribution,
+    mantissa_arc_test,
+    number_duplication,
+    second_order,
+    summation_test,
+)
+from .jet import JETReport, JournalEntryTester, TestResult
+from .scores import (
+    AltmanResult,
+    BeneishResult,
+    PiotroskiResult,
+    altman_z,
+    beneish_m,
+    piotroski_f,
+)
+
+__version__ = "0.1.2"
+
+__all__ = [
+    "AltmanResult",
+    "BeneishResult",
+    "BenfordResult",
+    "JETReport",
+    "JournalEntryTester",
+    "PiotroskiResult",
+    "TestResult",
+    "altman_z",
+    "benford",
+    "beneish_m",
+    "expected_distribution",
+    "mantissa_arc_test",
+    "number_duplication",
+    "piotroski_f",
+    "second_order",
+    "summation_test",
+    "__version__",
+]

ledgerlens/_utils.py

@@ -0,0 +1,90 @@
+"""Internal helpers shared across modules."""
+
+from __future__ import annotations
+
+from typing import Optional, Tuple
+
+import numpy as np
+import pandas as pd
+
+# Relative nudge used when extracting digits. Binary floating point cannot
+# represent most decimals exactly (0.29 / 0.1 == 2.8999999999999995), which
+# would make naive truncation report 28 instead of 29 as the first-two digits.
+# Accounting amounts rarely carry more than ~12 significant digits, so a
+# 1e-12 relative nudge fixes representation error without changing any value
+# a human would have typed.
+_EPS = 1e-12
+
+
+def clean_numeric(
+    data, sign: str = "positive"
+) -> Tuple[np.ndarray, pd.Index]:
+    """Return (positive magnitudes, original index) after the sign filter.
+
+    ``sign`` follows the usual Benford-software convention:
+
+    * ``"positive"`` - keep values > 0 (default; recommended by Nigrini)
+    * ``"negative"`` - keep values < 0, analysed as magnitudes
+    * ``"both"``     - keep every non-zero value, analysed as magnitudes
+    """
+    if isinstance(data, pd.DataFrame):
+        raise TypeError("Pass a single column (Series), not a DataFrame.")
+    s = data if isinstance(data, pd.Series) else pd.Series(np.asarray(data).ravel())
+    s = pd.to_numeric(s, errors="coerce").astype(float)
+    s = s[np.isfinite(s.to_numpy())]
+
+    if sign == "positive":
+        s = s[s > 0]
+    elif sign == "negative":
+        s = -s[s < 0]
+    elif sign == "both":
+        s = s[s != 0].abs()
+    else:
+        raise ValueError("sign must be 'positive', 'negative' or 'both'")
+    return s.to_numpy(dtype=float), s.index
+
+
+def leading_digits(x: np.ndarray, n: int) -> np.ndarray:
+    """First ``n`` significant digits of each positive value, as integers.
+
+    ``leading_digits([1234.5, 0.029], 2) -> [12, 29]``
+    """
+    x = np.asarray(x, dtype=float)
+    if x.size == 0:
+        return np.array([], dtype=np.int64)
+    if np.any(x <= 0):
+        raise ValueError("leading_digits expects strictly positive values")
+    e = np.floor(np.log10(x))
+    s = x / np.power(10.0, e)
+    # log10 can land a hair on the wrong side of an integer for exact powers.
+    hi = s >= 10
+    s[hi] /= 10
+    lo = s < 1
+    s[lo] *= 10
+    d = np.floor(s * 10 ** (n - 1) * (1 + _EPS)).astype(np.int64)
+    # 9.999999999999998 nudged to 10.000000000001 really means 10**(e+1).
+    d[d >= 10**n] = 10 ** (n - 1)
+    return d
+
+
+def last_two_digits(x: np.ndarray, decimals: int = 0) -> Tuple[np.ndarray, np.ndarray]:
+    """Last two digits of each value after scaling by ``10**decimals``.
+
+    Returns ``(digits, mask)`` where ``mask`` marks values whose scaled
+    integer is at least 10 (a one-digit number has no "last two digits").
+    """
+    scaled = np.rint(np.asarray(x, dtype=float) * 10**decimals)
+    mask = scaled >= 10
+    digits = np.mod(scaled[mask], 100).astype(np.int64)
+    return digits, mask
+
+
+def require_columns(df: pd.DataFrame, cols: dict) -> None:
+    missing = {k: v for k, v in cols.items() if v is not None and v not in df.columns}
+    if missing:
+        detail = ", ".join(f"{k}={v!r}" for k, v in missing.items())
+        raise KeyError(f"Column(s) not found in data: {detail}")
+
+
+def fmt_pct(x: Optional[float], digits: int = 1) -> str:
+    return "n/a" if x is None or not np.isfinite(x) else f"{x * 100:.{digits}f}%"

ledgerlens/benford.py

@@ -0,0 +1,518 @@
+"""Benford's Law tests for forensic analytics.
+
+Implements the digit tests described in Mark Nigrini, *Benford's Law:
+Applications for Forensic Accounting, Auditing, and Fraud Detection*
+(Wiley, 2012) - the de facto standard in audit practice:
+
+* first-digit, second-digit, first-two-digits, first-three-digits tests
+* last-two-digits test (invented / rounded numbers)
+* Mean Absolute Deviation (MAD) with Nigrini's conformity ranges
+* per-digit z-statistics with continuity correction
+* chi-square and Kolmogorov-Smirnov tests
+* summation test, number duplication test, second-order test
+* distortion factor and mantissa arc test
+
+Benford's Law does **not** prove fraud. Nonconformity tells an auditor where
+to look; whether the data *should* follow Benford at all (no built-in minimum
+or maximum, no assigned numbers such as invoice IDs, enough records spanning
+several orders of magnitude) has to be judged first.
+"""
+
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass, field
+from typing import Dict, Optional, Sequence, Tuple, Union
+
+import numpy as np
+import pandas as pd
+from scipy import stats
+
+from ._utils import clean_numeric, last_two_digits, leading_digits
+
+__all__ = [
+    "BenfordResult",
+    "benford",
+    "expected_distribution",
+    "mantissa_arc_test",
+    "number_duplication",
+    "second_order",
+    "summation_test",
+    "MAD_THRESHOLDS",
+]
+
+TestName = str
+
+_TEST_ALIASES = {
+    "first": "first",
+    "first_digit": "first",
+    "f1d": "first",
+    1: "first",
+    "second": "second",
+    "second_digit": "second",
+    "f2nd": "second",
+    "first_two": "first_two",
+    "first_two_digits": "first_two",
+    "f2d": "first_two",
+    2: "first_two",
+    "first_three": "first_three",
+    "first_three_digits": "first_three",
+    "f3d": "first_three",
+    3: "first_three",
+    "last_two": "last_two",
+    "last_two_digits": "last_two",
+    "l2d": "last_two",
+}
+
+_TEST_LABEL = {
+    "first": "First Digit",
+    "second": "Second Digit",
+    "first_two": "First-Two Digits",
+    "first_three": "First-Three Digits",
+    "last_two": "Last-Two Digits",
+}
+
+#: Nigrini (2012), Table 7.1: upper bounds of the close / acceptable /
+#: marginally-acceptable conformity ranges. Above the last bound = nonconformity.
+MAD_THRESHOLDS: Dict[str, Tuple[float, float, float]] = {
+    "first": (0.006, 0.012, 0.015),
+    "second": (0.008, 0.010, 0.012),
+    "first_two": (0.0012, 0.0018, 0.0022),
+    "first_three": (0.00036, 0.00044, 0.00050),
+}
+
+_CONFORMITY_LABELS = (
+    "Close conformity",
+    "Acceptable conformity",
+    "Marginally acceptable conformity",
+    "Nonconformity",
+)
+
+# Nigrini drops numbers that are too small to have the digits under test.
+_DEFAULT_MIN_VALUE = {
+    "first": None,
+    "second": 10.0,
+    "first_two": 10.0,
+    "first_three": 100.0,
+    "last_two": None,
+}
+
+# Expected mean of values collapsed into [10, 100) under Benford: 90 / ln(10).
+_BENFORD_COLLAPSED_MEAN = 90 / np.log(10)
+
+
+def _resolve_test(test) -> str:
+    key = test.lower() if isinstance(test, str) else test
+    if key not in _TEST_ALIASES:
+        raise ValueError(
+            f"Unknown test {test!r}. Use one of: "
+            "'first', 'second', 'first_two', 'first_three', 'last_two'."
+        )
+    return _TEST_ALIASES[key]
+
+
+def expected_distribution(test: Union[str, int] = "first_two") -> pd.Series:
+    """Benford (or uniform, for ``last_two``) expected proportions, indexed by digit."""
+    test = _resolve_test(test)
+    if test == "first":
+        d = np.arange(1, 10)
+        p = np.log10(1 + 1 / d)
+    elif test == "second":
+        d = np.arange(0, 10)
+        k = np.arange(1, 10)[:, None]
+        p = np.log10(1 + 1 / (10 * k + d)).sum(axis=0)
+    elif test == "first_two":
+        d = np.arange(10, 100)
+        p = np.log10(1 + 1 / d)
+    elif test == "first_three":
+        d = np.arange(100, 1000)
+        p = np.log10(1 + 1 / d)
+    else:  # last_two
+        d = np.arange(0, 100)
+        p = np.full(100, 0.01)
+    return pd.Series(p, index=pd.Index(d, name="digits"), name="expected")
+
+
+def _conformity(test: str, mad: float) -> Optional[str]:
+    if test not in MAD_THRESHOLDS or not np.isfinite(mad):
+        return None
+    close, acceptable, marginal = MAD_THRESHOLDS[test]
+    if mad <= close:
+        return _CONFORMITY_LABELS[0]
+    if mad <= acceptable:
+        return _CONFORMITY_LABELS[1]
+    if mad <= marginal:
+        return _CONFORMITY_LABELS[2]
+    return _CONFORMITY_LABELS[3]
+
+
+def _z_stats(actual: np.ndarray, expected: np.ndarray, n: int) -> np.ndarray:
+    """Nigrini's z-statistic; the 1/(2N) continuity correction is applied only
+    when it is smaller than the absolute difference."""
+    diff = np.abs(actual - expected)
+    cc = 1 / (2 * n)
+    num = np.where(cc < diff, diff - cc, diff)
+    return num / np.sqrt(expected * (1 - expected) / n)
+
+
+def distortion_factor(values: np.ndarray) -> float:
+    """Nigrini's distortion factor in percent.
+
+    Values >= 10 are collapsed into [10, 100) and their mean compared with
+    the Benford expectation 90 / ln(10) = 39.0865. Negative DF means the data
+    lean toward smaller numbers (e.g. amounts shaded under approval limits);
+    positive DF means inflated numbers.
+    """
+    v = np.asarray(values, dtype=float)
+    v = v[v >= 10]
+    if v.size == 0:
+        return float("nan")
+    collapsed = v / np.power(10.0, np.floor(np.log10(v)) - 1)
+    collapsed = np.where(collapsed >= 100, collapsed / 10, collapsed)
+    return float((collapsed.mean() - _BENFORD_COLLAPSED_MEAN) / _BENFORD_COLLAPSED_MEAN * 100)
+
+
+def mantissa_arc_test(data, sign: str = "positive") -> Tuple[float, float]:
+    """Mantissa arc test (Alexander, 2009).
+
+    Maps each mantissa ``log10(x) mod 1`` onto the unit circle; under Benford
+    the mantissas are uniform and their centre of mass sits near the origin.
+    Returns ``(L2, p_value)`` with ``p = exp(-L2 * N)``. Large samples reject
+    easily - treat it as a supporting statistic, as Nigrini advises for every
+    significance test on big data.
+    """
+    x, _ = clean_numeric(data, sign)
+    if x.size == 0:
+        return float("nan"), float("nan")
+    m = np.mod(np.log10(x), 1)
+    l2 = float(np.mean(np.cos(2 * np.pi * m)) ** 2 + np.mean(np.sin(2 * np.pi * m)) ** 2)
+    return l2, float(np.exp(-l2 * x.size))
+
+
+@dataclass
+class BenfordResult:
+    """Outcome of a single Benford digit test.
+
+    Attributes
+    ----------
+    test : str
+        ``first``, ``second``, ``first_two``, ``first_three`` or ``last_two``.
+    n : int
+        Number of records analysed after sign / minimum-value filtering.
+    table : pandas.DataFrame
+        One row per digit (combination): count, actual and expected
+        proportions, difference, z-statistic and a ``significant`` flag.
+    mad : float
+        Mean absolute deviation between actual and expected proportions.
+    conformity : str or None
+        Nigrini's conformity verdict for ``mad`` (None for ``last_two``).
+    chi2, chi2_p : float
+        Pearson chi-square statistic and p-value (df = digits - 1).
+    ks, ks_critical : float
+        Kolmogorov-Smirnov D statistic and its 5% critical value 1.36 / sqrt(N).
+    distortion_factor : float
+        Nigrini's distortion factor in percent (leading-digit tests only).
+    """
+
+    test: str
+    n: int
+    n_excluded: int
+    table: pd.DataFrame
+    mad: float
+    conformity: Optional[str]
+    chi2: float
+    chi2_df: int
+    chi2_p: float
+    ks: float
+    ks_critical: float
+    distortion_factor: float
+    alpha: float
+    values: pd.Series = field(repr=False)
+    digits: pd.Series = field(repr=False)
+
+    # ------------------------------------------------------------------ views
+    @property
+    def label(self) -> str:
+        return _TEST_LABEL[self.test]
+
+    @property
+    def ks_conforms(self) -> bool:
+        return bool(self.ks <= self.ks_critical)
+
+    @property
+    def mad_thresholds(self) -> Optional[Tuple[float, float, float]]:
+        return MAD_THRESHOLDS.get(self.test)
+
+    def suspects(self, top: Optional[int] = 10, only_excess: bool = True) -> pd.DataFrame:
+        """Digit combinations with statistically significant spikes, largest z first.
+
+        ``only_excess=True`` keeps digits that occur *more* often than expected,
+        which is where invented or threshold-driven amounts show up.
+        """
+        t = self.table[self.table["significant"]]
+        if only_excess:
+            t = t[t["difference"] > 0]
+        t = t.sort_values("z", ascending=False)
+        return t if top is None else t.head(top)
+
+    def records(self, digits: Union[int, Sequence[int], None] = None, top: int = 3) -> pd.Series:
+        """Original records whose digits are among ``digits``.
+
+        With ``digits=None`` the ``top`` most significant excess digits from
+        :meth:`suspects` are used. The returned Series keeps the original
+        index, so ``df.loc[result.records().index]`` pulls the full rows.
+        """
+        if digits is None:
+            digits = list(self.suspects(top=top).index)
+        elif np.isscalar(digits):
+            digits = [int(digits)]
+        mask = self.digits.isin(list(digits))
+        return self.values[mask]
+
+    def summary(self) -> str:
+        lines = [
+            f"Benford {self.label} test",
+            f"  records analysed : {self.n:,}"
+            + (f"  ({self.n_excluded:,} excluded by filters)" if self.n_excluded else ""),
+            f"  MAD              : {self.mad:.6f}"
+            + (f"  -> {self.conformity}" if self.conformity else ""),
+        ]
+        if self.mad_thresholds:
+            c, a, m = self.mad_thresholds
+            lines.append(f"  MAD ranges       : close <= {c}, acceptable <= {a}, marginal <= {m}")
+        lines += [
+            f"  chi-square       : {self.chi2:,.2f} (df={self.chi2_df}, p={self.chi2_p:.4g})",
+            f"  KS               : D={self.ks:.5f} vs critical {self.ks_critical:.5f}"
+            f" -> {'conforms' if self.ks_conforms else 'does not conform'}",
+        ]
+        if np.isfinite(self.distortion_factor):
+            lines.append(f"  distortion factor: {self.distortion_factor:+.2f}%")
+        if self.n < 1000:
+            lines.append("  caveat           : fewer than 1,000 observations; digit tests are less reliable")
+        if len(self.values) and self.values.max() / self.values.min() < 100:
+            lines.append("  caveat           : amounts span fewer than two orders of magnitude")
+        sus = self.suspects(top=5)
+        if len(sus):
+            width = 2 if self.test == "last_two" else 0
+            items = ", ".join(
+                f"{str(d).zfill(width)} (z={row.z:.1f}, {row.actual:.2%} vs {row.expected:.2%})"
+                for d, row in sus.iterrows()
+            )
+            lines.append(f"  largest spikes   : {items}")
+        else:
+            lines.append("  largest spikes   : none significant at "
+                         f"alpha={self.alpha}")
+        return "\n".join(lines)
+
+    def __str__(self) -> str:  # pragma: no cover - cosmetic
+        return self.summary()
+
+    def to_dict(self) -> dict:
+        return {
+            "test": self.test,
+            "n": self.n,
+            "mad": self.mad,
+            "conformity": self.conformity,
+            "chi2": self.chi2,
+            "chi2_df": self.chi2_df,
+            "chi2_p": self.chi2_p,
+            "ks": self.ks,
+            "ks_critical": self.ks_critical,
+            "distortion_factor": self.distortion_factor,
+        }
+
+    def plot(self, ax=None, title: Optional[str] = None):
+        """Bar chart of actual vs expected proportions (requires matplotlib)."""
+        try:
+            import matplotlib.pyplot as plt
+        except ImportError as exc:  # pragma: no cover
+            raise ImportError("plot() needs matplotlib: pip install 'ledgerlens[plot]'") from exc
+        if ax is None:
+            width = 10 if len(self.table) > 20 else 7
+            _, ax = plt.subplots(figsize=(width, 4))
+        t = self.table
+        x = np.arange(len(t))
+        colors = np.where(t["significant"] & (t["difference"] > 0), "#C0504D", "#4F81BD")
+        ax.bar(x, t["actual"], color=colors, width=0.8, label="Actual")
+        ax.plot(x, t["expected"], color="#222222", linewidth=1.6, label="Expected")
+        step = 1 if len(t) <= 20 else (10 if len(t) <= 100 else 100)
+        ticks = x[::step]
+        labels = [str(d).zfill(2) if self.test == "last_two" else str(d) for d in t.index[::step]]
+        ax.set_xticks(ticks)
+        ax.set_xticklabels(labels)
+        ax.set_ylabel("Proportion")
+        ax.set_title(title or f"{self.label} test  (N={self.n:,}, MAD={self.mad:.4f})")
+        ax.legend(frameon=False)
+        ax.spines[["top", "right"]].set_visible(False)
+        return ax
+
+
+def benford(
+    data,
+    test: Union[str, int] = "first_two",
+    sign: str = "positive",
+    min_value: Union[float, None, str] = "auto",
+    decimals: int = 0,
+    alpha: float = 0.05,
+) -> BenfordResult:
+    """Run a Benford's Law digit test.
+
+    Parameters
+    ----------
+    data : array-like or pandas.Series
+        The amounts to test. Non-numeric and non-finite values are dropped.
+    test : str or int
+        ``"first"``, ``"second"``, ``"first_two"`` (default, Nigrini's
+        workhorse test), ``"first_three"`` or ``"last_two"``. The integers
+        1, 2, 3 mean first, first-two and first-three digits.
+    sign : {"positive", "negative", "both"}
+        Which records to keep. Analyse debits and credits separately where
+        possible - incentives to manipulate differ.
+    min_value : float, None or "auto"
+        Drop magnitudes below this value. ``"auto"`` follows Nigrini: no floor
+        for the first-digit test, 10 for second / first-two digits, 100 for
+        first-three digits. Use ``None`` to keep everything (this matches the
+        R package *benford.analysis*), e.g. for percentages such as returns.
+    decimals : int
+        Only for ``last_two``: scale amounts by ``10**decimals`` first, so
+        ``decimals=2`` tests the cents.
+    alpha : float
+        Significance level for per-digit z-tests (two-sided).
+    """
+    test = _resolve_test(test)
+    x, idx = clean_numeric(data, sign)
+    n_raw = x.size
+
+    floor = _DEFAULT_MIN_VALUE[test] if min_value == "auto" else min_value
+    if floor is not None:
+        keep = x >= floor
+        x, idx = x[keep], idx[keep]
+        if n_raw and keep.mean() < 0.5:
+            warnings.warn(
+                f"min_value={floor} removed {1 - keep.mean():.0%} of the records. "
+                "For small-scale data (percentages, ratios) pass min_value=None.",
+                stacklevel=2,
+            )
+
+    if test == "last_two":
+        digits, mask = last_two_digits(x, decimals)
+        x, idx = x[mask], idx[mask]
+    elif test == "second":
+        digits = leading_digits(x, 2) % 10
+    else:
+        digits = leading_digits(x, {"first": 1, "first_two": 2, "first_three": 3}[test])
+
+    n = int(x.size)
+    if n == 0:
+        raise ValueError("No records left to analyse after filtering.")
+
+    expected = expected_distribution(test)
+    counts = pd.Series(digits).value_counts().reindex(expected.index, fill_value=0)
+    actual = counts / n
+    diff = actual - expected
+    z = _z_stats(actual.to_numpy(), expected.to_numpy(), n)
+    z_crit = stats.norm.ppf(1 - alpha / 2)
+
+    table = pd.DataFrame(
+        {
+            "count": counts.astype(int),
+            "expected_count": expected * n,
+            "actual": actual,
+            "expected": expected,
+            "difference": diff,
+            "abs_difference": diff.abs(),
+            "z": z,
+            "significant": z > z_crit,
+        }
+    )
+
+    mad = float(diff.abs().mean())
+    exp_counts = expected.to_numpy() * n
+    chi2 = float(((counts.to_numpy() - exp_counts) ** 2 / exp_counts).sum())
+    chi2_df = len(expected) - 1
+    ks = float(np.abs(actual.cumsum() - expected.cumsum()).max())
+
+    df_value = distortion_factor(x) if test in ("first", "first_two", "first_three") else float("nan")
+
+    return BenfordResult(
+        test=test,
+        n=n,
+        n_excluded=n_raw - n,
+        table=table,
+        mad=mad,
+        conformity=_conformity(test, mad),
+        chi2=chi2,
+        chi2_df=chi2_df,
+        chi2_p=float(stats.chi2.sf(chi2, chi2_df)),
+        ks=ks,
+        ks_critical=1.36 / np.sqrt(n),
+        distortion_factor=df_value,
+        alpha=alpha,
+        values=pd.Series(x, index=idx, name="value"),
+        digits=pd.Series(digits, index=idx, name="digits"),
+    )
+
+
+def summation_test(data, sign: str = "positive", min_value: Optional[float] = 10.0) -> pd.DataFrame:
+    """Nigrini's summation test on first-two digits.
+
+    Under Benford the *sums* of amounts in each first-two-digit group are
+    roughly equal (1/90 of the total each). A group with an outsized share
+    points at a few very large amounts, or many repeated mid-sized ones,
+    beginning with those digits. Returns one row per group, sorted by excess.
+    """
+    x, _ = clean_numeric(data, sign)
+    if min_value is not None:
+        x = x[x >= min_value]
+    if x.size == 0:
+        raise ValueError("No records left to analyse after filtering.")
+    d = leading_digits(x, 2)
+    sums = pd.Series(x).groupby(d).sum().reindex(range(10, 100), fill_value=0.0)
+    total = sums.sum()
+    out = pd.DataFrame(
+        {
+            "sum": sums,
+            "actual": sums / total,
+            "expected": 1 / 90,
+        }
+    )
+    out.index.name = "digits"
+    out["difference"] = out["actual"] - out["expected"]
+    out["ratio_to_expected"] = out["actual"] / out["expected"]
+    return out.sort_values("difference", ascending=False)
+
+
+def number_duplication(data, sign: str = "positive", decimals: int = 2, top: Optional[int] = 20) -> pd.DataFrame:
+    """Most frequently repeated exact amounts (Nigrini's number duplication test).
+
+    Repeated amounts are often legitimate (recurring fees, standard prices),
+    but the top of this list is where duplicate payments, split purchases and
+    made-up figures tend to sit.
+    """
+    x, _ = clean_numeric(data, sign)
+    rounded = pd.Series(np.round(x, decimals))
+    counts = rounded.value_counts()
+    out = pd.DataFrame({"count": counts})
+    out.index.name = "amount"
+    out["share"] = out["count"] / len(rounded)
+    out["first_two"] = leading_digits(out.index.to_numpy(dtype=float), 2) if len(out) else []
+    out["total"] = out.index.to_numpy(dtype=float) * out["count"]
+    out = out.sort_values(["count", "total"], ascending=False)
+    return out if top is None else out.head(top)
+
+
+def second_order(data, sign: str = "positive", decimals: int = 2, alpha: float = 0.05) -> BenfordResult:
+    """Nigrini's second-order test.
+
+    Sort the amounts, take the differences between neighbours and run the
+    first-two-digits test on those differences. Almost any data set - even
+    one that should not follow Benford - produces Benford-like differences,
+    so spikes here point at rounding, data-entry or processing errors.
+    ``decimals`` rounds the differences to strip floating-point noise.
+    """
+    x, _ = clean_numeric(data, sign)
+    gaps = np.round(np.diff(np.sort(x)), decimals)
+    gaps = gaps[gaps > 0]
+    if gaps.size == 0:
+        raise ValueError("All values are identical; no second-order differences.")
+    return benford(gaps, test="first_two", min_value=None, alpha=alpha)