---
title: "Interop with grattan and taxstats: costing a hypothetical reform"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Interop with grattan and taxstats: costing a hypothetical reform}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", eval = FALSE)
```

`ato` sits in a three-package constellation for Australian tax
research:

- `ato` : published aggregate data from ATO data.gov.au releases
- `taxstats` / `taxstats2` (Hugh Parsonage, DRAT) : 2 per cent
  individual microdata sample
- `grattan` (Hugh Parsonage, CRAN) : policy calculator
  (brackets, Medicare levy, LITO, LMITO, HELP repayments)

`ato` provides `ato_to_taxstats()` to rename aggregate columns to
the microdata schema, so analyses can move cleanly between views.

## Schema map

```{r}
library(ato)
head(ato_schema_map(), 15)
```

## Costing a hypothetical reform

Suppose we want a first-pass cost of lifting the Medicare Levy
Surcharge income threshold by AUD 10,000. Workflow:

1. Get MLS taxpayer counts and amounts by income band from ATO
   aggregates.
2. Check the total matches Budget Paper 1.
3. Hand off to `taxstats` 2 per cent sample for counterfactual
   microsimulation.
4. Use `grattan::income_tax()` for the new-regime liability.

```{r}
library(ato)

ato_snapshot("2026-04-24")

mls <- ato_medicare_levy(year = "2022-23", component = "surcharge")

# Reconcile the published MLS total against FBO where available
# (MLS does not have a direct FBO line; rolled into individuals
# income tax net).
ind_total <- sum(ato_individuals(year = "2022-23")$tax_payable,
                 na.rm = TRUE)
ato_reconcile(ind_total, "2022-23", "individuals_income_tax_net")
```

## Bridge to microdata

```{r}
# Rename columns to taxstats schema
mls_ts <- ato_to_taxstats(mls)

# Now these columns are consistent with what `taxstats::taxstats1819`
# uses. You can write analysis code that works on both.

# Example: use grattan to compute the new regime's tax for the 2% sample
# library(taxstats)
# library(grattan)
# sample_2pc <- taxstats1819
# sample_2pc$new_tax <- income_tax(
#   income = sample_2pc$Taxable_Income,
#   fy.year = "2023-24",
#   ...
# )
# reform_cost <- sum(sample_2pc$new_tax - sample_2pc$Tax_assessed_amt,
#                    na.rm = TRUE) * 50  # 2% -> 100%
```

## Summary

The three-package stack covers the full tax-research pipeline:
`ato` for authoritative aggregates and provenance, `taxstats` for
distributional microdata, `grattan` for policy simulation. Use
`ato_reconcile()` at the boundary to confirm the microdata
estimate lines up with the population total.