# auditsample A command-line tool for statistical audit sampling. It selects defensible samples from a ledger (monetary unit, attribute and classical variables sampling), writes selection lists and workpaper-style reports, and evaluates the audited results into an upper misstatement limit or a confidence interval. Selections are seeded and reproducible, and all statistical factors (Poisson reliability factors, binomial and hypergeometric limits) are computed from the distributions, not looked up. ## Features - Population import from CSV or XLSX, descriptive statistics, cumulative sqrt(f) stratification and a 100% tested top stratum. - Monetary unit sampling (MUS): Poisson reliability factors for any number of expected errors and confidence, sampling interval and size, systematic or cell selection with a recorded seed, evaluation with tainting, basic precision and incremental allowance, for overstatement and understatement separately. - Attribute sampling: exact binomial (or hypergeometric when the population size is given) sample size and upper deviation limit. - Classical variables sampling: mean-per-unit, difference and ratio estimators, stratified, with Neyman allocation and a precision statement. - Outputs: selection lists (CSV/XLSX) with the selection reason, and Markdown/HTML workpapers recording parameters, method, seed and results. ## Install Python 3.12+. ```bash uv venv .venv && uv pip install -p .venv/bin/python -e '.[dev]' source .venv/bin/activate ``` ## Quickstart ```bash python examples/make_ar_ledger.py # regenerate the 5,000 item AR ledger (already included) auditsample mus select examples/ar_ledger.csv -t 400000 -c 95 --seed 2026 -o out/sel.csv --report out/sel.md python examples/fill_audited.py out/sel.csv examples/ar_findings.csv # simulates the audit work auditsample mus evaluate out/sel.csv --report out/eval.html ``` In real use you fill the `audited_value` column of the selection list yourself. ## Usage Population files need an identifier and an amount column (`--id-col`, `--amount-col`, defaults `id` and `amount`); all other columns are carried into the selection list. Confidence and rates accept `0.95` or `95`. ### Population and stratification ``` $ auditsample describe examples/ar_ledger.csv --strata 4 --top-threshold 100000 items 5,000 net_total 21,972,829.06 absolute_total 22,276,525.58 mean 4,394.57 std_dev 9,099.88 min -37,007.92 q1 825.87 median 1,949.65 q3 4,574.67 max 188,100.11 zero_items 0 negative_items 85 stratum range (|amount|) items book total TOP >= 100,000.00 8 1,099,041.97 S1 0.00 - 3,000.63 3,174 3,830,869.71 S2 3,000.63 - 6,975.92 1,051 4,742,553.78 S3 6,975.92 - 19,895.59 593 6,418,263.13 S4 19,895.59 - max 174 5,882,100.47 ``` ### Monetary unit sampling `mus factors` prints the Poisson reliability factors; `mus size` previews the interval and size; `mus select` draws the sample; `mus evaluate` evaluates it. ``` $ auditsample mus factors errors 80.0% 90.0% 95.0% 99.0% 0 1.6094 2.3026 2.9957 4.6052 1 2.9943 3.8897 4.7439 6.6384 2 4.2790 5.3223 6.2958 8.4059 3 5.5150 6.6808 7.7537 10.0451 4 6.7210 7.9936 9.1535 11.6046 5 7.9060 9.2747 10.5130 13.1085 $ auditsample mus select examples/ar_ledger.csv -t 400000 -c 95 --seed 2026 -o out/ar_selection.csv --report out/mus_selection.md Selected 166 items (3 top stratum + 163 sampled), interval 133,523.28 Selection: out/ar_selection.csv Parameters: out/ar_selection.params.json Report written to out/mus_selection.md $ auditsample mus evaluate out/ar_selection.csv --report out/mus_evaluation.md Interval 133,523.28 confidence 95.00% tolerable 400,000.00 Sampled items 163, top stratum items 3 Overstatement Understatement Errors in sample 7 0 Known (top stratum) 22,347.80 0.00 Projected misstatement 333,813.65 0.00 Basic precision 400,000.00 400,000.00 Incremental allowance 191,628.94 0.00 Upper misstatement limit 947,790.39 400,000.00 Conclusion: REJECT: an upper limit exceeds tolerable misstatement. ``` Options: `--expected-errors K` (uses the K-error reliability factor, giving a smaller interval and larger sample), `--variant systematic|cell`, `.xlsx` output. Full workpapers from this run are in `examples/output/`. ### Attribute sampling ``` $ auditsample attr size -t 5 -e 1 -c 95 Sample size: 93 $ auditsample attr size -t 5 -c 95 --population 800 Sample size: 57 $ auditsample attr evaluate --sample-size 93 --deviations 2 -t 5 Sample size 93, deviations 2 (2.15% sample rate) Upper deviation limit at 95.00% confidence: 6.62% Conclusion: Control not supported: upper limit 6.62% exceeds tolerable rate 5.00%. ``` `attr select FILE -t 5 --seed N -o sel.csv` draws a simple random sample; record failures in a `deviation` column (`1`/`y`) and run `attr evaluate sel.csv`. ### Variables sampling `--method mpu|diff|ratio`. Difference and ratio need `--expected-sd`, the expected standard deviation of the item differences, for sizing. ``` $ auditsample var select examples/ar_ledger.csv --method mpu --precision 600000 --strata 4 --top-threshold 100000 --seed 7 -o out/var_sel.csv $ auditsample var plan examples/ar_ledger.csv --method mpu --precision 600000 --strata 4 --top-threshold 100000 stratum items book total std dev sample TOP 8 1,099,041.97 - 8 S1 3,174 3,830,869.71 852.90 162 S2 1,051 4,742,553.78 1,414.19 89 S3 593 6,418,263.13 3,397.49 121 S4 174 5,882,100.47 16,370.89 171 Total sample: 551 $ auditsample var evaluate out/var_sel.csv Estimator mpu Book total 21,972,829.06 Estimated total 21,611,908.51 Std error 319,870.95 Precision (+/-) 626,935.55 at 95.00% Interval 20,984,972.96 to 22,238,844.06 Est. misstatement (audited - book) -360,920.55 Conclusion: Book value lies within the confidence interval: no evidence of material misstatement at this precision. ``` The ledger's true planted misstatement is -441,138; the ratio estimator (`--method ratio --expected-sd 1500 --strata 3`, 1,627 items) estimates -443,273 with precision +/-184,476, and correctly flags the book value as outside its interval. ## Configuration There is no config file. Everything is a CLI option; the `select` commands write `.params.json` beside the selection list (confidence, tolerable amount, interval, seed, strata) and `evaluate` reads it, so keep the two files together. ## Architecture | Module | Purpose | |---|---| | `auditsample/stats.py` | Poisson, binomial, hypergeometric CDFs; reliability factors | | `auditsample/population.py` | Import, statistics, cumulative sqrt(f) strata, top stratum | | `auditsample/mus.py` | MUS plan, selection, evaluation | | `auditsample/attribute.py` | Attribute sample size and upper deviation limit | | `auditsample/variables.py` | MPU / difference / ratio estimators, Neyman sizing | | `auditsample/report.py` | Markdown and HTML workpapers | | `auditsample/io.py` | CSV/XLSX tables | | `auditsample/cli.py` | Click commands | Methods and formulas, with worked examples, are in [docs/methods.md](docs/methods.md). ## Tests ```bash pytest ``` 71 tests, including reliability factors against published AICPA values (95%: 3.00, 4.75, 6.30, 7.76, 9.16), attribute sizes against standard tables (59, 93, 124, 153, 149, 29, 45), hand-computed MUS evaluation and variables estimators, stratification boundaries, seeded reproducibility and end-to-end CLI runs. ## Limitations - Variables precision uses the normal approximation (z), which is appropriate for the usual sample sizes (30+ per stratum) but not tiny samples. - MUS treats negative items by absolute value and caps taintings at 100%; it is intended for populations that are mostly overstatement-prone debit balances. It sizes by the Poisson factor for the expected number of errors rather than the AICPA expansion-factor shortcut for an expected misstatement amount. - Zero-value items cannot be selected by MUS; test them separately. - A reliability factor of 4.7439 is the exact value; the AICPA table rounds the 95%/1-error entry to 4.75. - This tool supports, and does not replace, professional judgement on sample design and conclusions.