Methodology: hand-computed worked examples

Every formula function in ato is verifiable with pen and paper. This vignette walks through the three arithmetic methods and confirms each against a hand calculation. A referee checking a published result against the package can use this page as the reference implementation.

1. ato_deflate()

Formula

Proportional (Laspeyres-style) adjustment:

$$\mathrm{real}_t \;=\; \mathrm{nominal}_t \times \frac{CPI_{\text{base}}}{CPI_t}$$

Source: Diewert (1998), ; ABS cat. 6461.0, Concepts, Sources and Methods.

Hand calculation

Take AUD 100 in 2012-13 nominal and deflate to 2022-23 real AUD.

From ato_crosswalk("cpi"):

cpi <- ato_crosswalk("cpi")
cpi[cpi$financial_year %in% c("2012-13", "2022-23"), ]
#>    financial_year cpi_all_groups_australia base_2011_12
#> 19        2012-13                    101.7        1.025
#> 29        2022-23                    132.9        1.339

Reading off the table: - $CPI_{2012\text{-}13} = 101.7$ - $CPI_{2022\text{-}23} = 132.9$

Hand calculation:

$$100 \times \frac{132.9}{101.7} \;=\; 100 \times 1.30678 \;=\; 130.68$$

Package output:

ato_deflate(100, year = "2012-13", base = "2022-23")
#> [1] 130.6785

The package returns exactly 130.6785 (to four decimals), which matches the hand calculation to within rounding.

Sanity: identity at the base year

ato_deflate(100, year = "2022-23", base = "2022-23")
#> [1] 100

As expected: when the source year equals the base year the index ratio is 1 and the real-term value equals the nominal value.

2. ato_reconcile()

Formula

$$\Delta \;=\; V - R, \qquad \pi \;=\; \frac{V - R}{R}$$

where $V$ is the value from Taxation Statistics and $R$ is the Final Budget Outcome reference total for the same year and measure.

Hand calculation

From ato_crosswalk("budget"):

bud <- ato_crosswalk("budget")
bud[bud$financial_year == "2022-23" &
    bud$measure == "individuals_income_tax_net", ]
#>   financial_year                    measure value_aud_billion
#> 3        2022-23 individuals_income_tax_net             316.4
#>                                   source
#> 3 Final Budget Outcome 2022-23 Table 4.2
#>                                                                         definition
#> 3 Gross income tax on individuals less refunds (cash basis, Commonwealth receipts)
#>   note
#> 3 <NA>

Reference: $R = 316.4 \times 10^9$ AUD.

Suppose we fetch the ATO 2022-23 Individuals snapshot and sum the tax_payable column. Say our sum is $V = 310.0 \times 10^9$ (hypothetical; real sums typically fall 1 to 3 per cent below the cash-basis FBO).

Hand:

$$\Delta = 310.0 - 316.4 = -6.4 \text{ (AUD billion)}$$

$$\pi = \frac{-6.4}{316.4} = -0.02023 = -2.02\%$$

Package output:

res <- ato_reconcile(310.0e9, "2022-23", "individuals_income_tax_net")
res[, c("diff_aud", "pct_diff")]
#>   diff_aud    pct_diff
#> 1 -6.4e+09 -0.02022756

Agrees with hand calculation.

Warning threshold

The package warns when abs(pct_diff) > 0.05. Test:

res <- tryCatch(
  ato_reconcile(400e9, "2022-23", "individuals_income_tax_net"),
  warning = function(w) {
    message("Captured warning: ", conditionMessage(w))
    NULL
  }
)
#> Captured warning: Reconciliation diff 26.4% for "individuals_income_tax_net" ("2022-23").
#> ℹ ATO data: "400,000,000,000".
#> ℹ Reference: "316,400,000,000".
#> ℹ Expected 1-3% accrual-vs-cash gap; investigate larger.

At $V = 400 \text{ AUD billion}$, the diff is +83.6 billion and $\pi = 26.4\%$ which exceeds the 5% threshold, so the warning fires.

3. ato_per_capita()

Formula

$$\mathrm{per\_capita}_t \;=\; \frac{x_t}{\mathrm{ERP}_t}$$

where $\mathrm{ERP}_t$ is the ABS Estimated Resident Population at 30 June of the financial year end (cat. 3101.0).

Hand calculation

From ato_crosswalk("erp"):

erp <- ato_crosswalk("erp")
erp[erp$financial_year == "2022-23", ]
#>    financial_year erp_june_australia_thousands note
#> 29        2022-23                        26638 <NA>

ERP 2022-23 = 26,638 thousand = 26,638,000 persons.

Commonwealth individual income tax for 2022-23 = AUD 316.4 billion (from ato_reconcile() reference).

Hand:

$$\frac{316.4 \times 10^9}{26.638 \times 10^6} \;=\; 11{,}878 \text{ AUD per person}$$

Package output:

ato_per_capita(316.4e9, "2022-23")
#> [1] 11877.77

Agrees.

4. ato_sha256()

Specification

SHA-256 as defined in NIST FIPS 180-4. For the empty string, the published digest is:

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Verification

f <- tempfile()
file.create(f)
#> [1] TRUE
ato_sha256(f)
#> [1] "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

Matches the NIST FIPS 180-4 reference digest exactly. The package-level test suite also cross-checks against openssl::sha256 for further independence.

Summary

Function	Formula	Reference	Status
ato_deflate	Laspeyres ratio	Diewert 1998 + ABS 6461.0	Verified
ato_reconcile	(V - R) / R	FBO + ATO tax gap methodology	Verified
ato_per_capita	x / ERP	ABS 3101.0	Verified
ato_sha256	NIST FIPS 180-4	digest + openssl	Verified

A reviewer can reproduce each worked example on paper and confirm the package output. Any disagreement is a bug in the package; please file an issue.