audit-labs/audit-tools

  1# Audit Sampling Tools
  2
  3This directory contains simple audit sampling utilities. The production-ready
  4CLI is `audit_sample.py`; the older `sample.py`, `sample.html`, and
  5`stratified_sample.py` examples remain for compatibility and learning.
  6
  7## Purpose
  8
  9`audit_sample.py` generates reproducible, documented samples from CSV and Excel
 10populations. Each run writes the selected sample, validated population,
 11reconciliation files, methodology notes, a manifest, and a log suitable for an
 12audit workpaper package.
 13
 14## Installation
 15
 16Sampling needs only the `analysis` extra (pandas + Excel support):
 17
 18```bash
 19pip install ".[analysis]"
 20```
 21
 22Supported input formats are `.csv`, `.xlsx`, `.xls`, and `.xlsm`.
 23
 24## Random Sampling Example
 25
 26```bash
 27python sampling/audit_sample.py \
 28  --input sampling/examples/users_population.csv \
 29  --id-column "User ID" \
 30  --method random \
 31  --sample-size 5 \
 32  --seed 20260707 \
 33  --out ./output
 34```
 35
 36## Stratified Counts Example
 37
 38```bash
 39python sampling/audit_sample.py \
 40  --input sampling/examples/changes_population.csv \
 41  --id-column "Change ID" \
 42  --method stratified \
 43  --stratify-column "Change Type" \
 44  --strata-counts "Normal=3,Emergency=2,Standard=2" \
 45  --seed 20260707 \
 46  --out ./output
 47```
 48
 49## Stratified Proportions Example
 50
 51```bash
 52python sampling/audit_sample.py \
 53  --input sampling/examples/changes_population.csv \
 54  --id-column "Change ID" \
 55  --method stratified \
 56  --stratify-column "Change Type" \
 57  --strata-proportions "Normal=0.50,Emergency=0.25,Standard=0.25" \
 58  --sample-size 8 \
 59  --seed 20260707 \
 60  --out ./output
 61```
 62
 63## Validate-Only Example
 64
 65```bash
 66python sampling/audit_sample.py \
 67  --input sampling/examples/changes_population.csv \
 68  --id-column "Change ID" \
 69  --method validate-only \
 70  --filter "Status=Closed" \
 71  --out ./output
 72```
 73
 74YAML config files are also supported. CLI arguments override config values:
 75
 76```bash
 77python sampling/audit_sample.py --config sampling/examples/stratified_config.yml
 78```
 79
 80## Output Files
 81
 82Each run creates `sample_<YYYY-MM-DD>_<HHMMSS>` under the selected output
 83directory.
 84
 85- `sample.csv`: selected sample rows for random and stratified runs.
 86- `population_validated.csv`: population after filters, blank-ID handling, and
 87  dedupe handling.
 88- `population_reconciliation.csv`: row-count tie-out metrics.
 89- `excluded_rows.csv`: rows removed by filters, blank-ID exclusion, or dedupe.
 90- `duplicate_ids.csv`: duplicate ID rows when duplicates are identified.
 91- `strata_summary.csv`: requested and actual counts for stratified runs.
 92- `methodology.txt`: audit workpaper narrative.
 93- `manifest.json`: machine-readable run metadata, input hash, options, and
 94  output list.
 95- `run.log`: start time, warnings, errors, output folder, and status.
 96
 97## Reproducibility
 98
 99Provide `--seed` to make row selection reproducible for the same input and
100options. If no seed is provided for sampling, the tool generates one, prints a
101warning, and records the generated seed in `manifest.json` and
102`methodology.txt`.
103
104The tool samples without replacement. Stratified sampling derives each stratum
105seed from the base seed by adding the stratum index.
106
107## Limitations
108
109Filters are exact matches in `Column=Value` form only. The tool does not yet
110perform monetary-unit sampling or statistical sample-size calculation.