Panels, harmonisation, reconciliation, real terms, per-capita

This vignette walks through the four panel-ready transformations that take raw ATO fetches to a defensible longitudinal analysis:

1. Stack multiple years with year = vector input.
2. Harmonise column names across releases with ato_harmonise().
3. Reconcile totals against Final Budget Outcome with ato_reconcile().
4. Express in real terms and per capita with ato_deflate() and ato_per_capita().

Build a multi-year panel

library(ato)

pc <- ato_individuals_postcode(
  year = c("2018-19", "2019-20", "2020-21",
           "2021-22", "2022-23"),
  state = "NSW"
)

nrow(pc)
unique(pc$year)

Harmonise column names

Column names drift: total_income in some years, total_income_or_loss in others; state vs state_territory. ato_harmonise() renames columns to canonical names from ATO_COL_VARIANTS.

pc <- ato_harmonise(pc)
names(pc)

Reconcile against Commonwealth totals

Before reporting a panel sum in a paper, check it against the Final Budget Outcome. A 1-3 per cent accrual-vs-cash gap is expected; larger gaps warrant investigation.

ind_2223 <- ato_individuals(year = "2022-23")
total_tax <- sum(ind_2223$tax_payable, na.rm = TRUE)

ato_reconcile(
  value   = total_tax,
  year    = "2022-23",
  measure = "individuals_income_tax_net"
)

Real-terms comparison

ATO values are nominal AUD of the reporting year. For time-series comparison, deflate to a common base year using the bundled ABS CPI series.

panel_annual <- aggregate(taxable_income ~ year, data = pc, FUN = sum,
                          na.rm = TRUE)
panel_annual$real_2022_23 <- ato_deflate(
  panel_annual$taxable_income,
  year = panel_annual$year,
  base = "2022-23"
)
panel_annual

Per-capita normalisation

panel_annual$per_capita <- ato_per_capita(
  panel_annual$real_2022_23,
  year = panel_annual$year
)
panel_annual

The resulting four-column data frame (year, nominal, real, per capita) is the canonical shape for distributional and time-series tax papers.