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+.
uv venv .venv && uv pip install -p .venv/bin/python -e '.[dev]'
source .venv/bin/activate
Quickstart
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 <selection>.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.
Tests
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.