% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ato-package.R
\docType{package}
\name{ato-package}
\alias{ato}
\alias{ato-package}
\title{ato: Australian Taxation Office Data}
\description{
Tidy R access to Australian Taxation Office ('ATO') Taxation
Statistics and related datasets via the 'data.gov.au' CKAN API.
}
\section{Main function families}{

\itemize{
\item \code{\link[=ato_catalog]{ato_catalog()}}, \code{\link[=ato_download]{ato_download()}}: discovery and generic
resource access.
\item \code{\link[=ato_individuals]{ato_individuals()}}, \code{\link[=ato_individuals_postcode]{ato_individuals_postcode()}},
\code{\link[=ato_individuals_occupation]{ato_individuals_occupation()}}: individual tax return items.
\code{ato_individuals_postcode()} accepts a vector of years for
time-series panels.
\item \code{\link[=ato_companies]{ato_companies()}}: company tax across Tables 1-9 (snapshot,
by size, by entity type, by industry, by industry-and-size,
by sub-industry, by taxable status, by source, by expenses).
\item \code{\link[=ato_super_funds]{ato_super_funds()}}: APRA-regulated super funds and SMSFs.
\item \code{\link[=ato_top_taxpayers]{ato_top_taxpayers()}}: Corporate Tax Transparency release
(Income tax or PRRT sheet).
\item \code{\link[=ato_gst]{ato_gst()}}, \code{\link[=ato_industry]{ato_industry()}}: GST and industry aggregates.
\item \code{\link[=ato_tax_gaps]{ato_tax_gaps()}}: annual Tax Gap estimates across tax heads.
\item \code{\link[=ato_rdti]{ato_rdti()}}: Research and Development Tax Incentive
claimants.
\item \code{\link[=ato_irpd]{ato_irpd()}}: International Related Party Dealings (BEPS /
transfer pricing).
\item \code{\link[=ato_excise]{ato_excise()}}: excise rates, fuel tax credits, beer and
spirits clearances.
\item \code{\link[=ato_sme_benchmarks]{ato_sme_benchmarks()}}: Small Business Benchmarks.
\item \code{\link[=ato_help]{ato_help()}}: HELP / AASL / VSL student-loan statistics.
\item \code{\link[=ato_cite]{ato_cite()}}: citation helper (BibTeX, APA, plain text).
\item \code{\link[=ato_cache_info]{ato_cache_info()}}, \code{\link[=ato_clear_cache]{ato_clear_cache()}}: cache management.
}
}

\section{Caveats for users of ATO data}{


\strong{Nominal AUD.} All monetary values are in nominal Australian
dollars of the reporting year. Use \code{inflateR::inflate()} or
ABS CPI series for real-term comparisons across years.

\strong{Fiscal year convention.} \code{"2022-23"} refers to the
Australian income year from 1 July 2022 to 30 June 2023.

\strong{Confidentiality suppression.} The ATO replaces values with
\code{"np"} (not published), \code{"*"}, \code{"\\u2021"}, or similar tokens when
fewer than ten taxpayers (or fewer than 50 returns for
postcode data) fall in a cell. The package coerces these to
\code{NA} so numeric columns stay numeric. Summing a column with
\code{na.rm = TRUE} is the correct default; be explicit about what
you do with suppressed cells in any distributional analysis.

\strong{Schema drift.} Column names and table numbering shift
year-to-year (e.g. occupation data has been T13, T14, T15 in
different years). The package cleans names to snake_case on
ingestion but does not normalise schemas across years. A
cross-year join requires explicit column mapping.

\strong{Classification migration.} ANZSIC 2006 to ANZSIC 2020 and
ANZSCO 2013 to ANZSCO 2021 recodes affect industry and
occupation series. Users stacking across releases should
inspect the classification version used in each release.

\strong{Silent revisions.} CKAN \code{metadata_modified} timestamps
change without a version bump when the ATO republishes a
corrected file. Run \code{\link[=ato_clear_cache]{ato_clear_cache()}} to force a refresh.

\strong{Microdata is out of scope.} The 2\% Individual Sample File
is distributed separately through Hugh Parsonage's
\href{https://github.com/HughParsonage/taxstats}{taxstats} DRAT
repo. ALife (the ATO Longitudinal Information Files) is
restricted-access microdata via the ATO DataLab and requires
a researcher application; it is not provided by this package.

\strong{Citation.} Use \code{\link[=ato_cite]{ato_cite()}} on any returned \code{ato_tbl} to
produce a Treasury-grade footnote, APA reference, or BibTeX
entry with the source URL, licence, retrieval date, and title.
}

\section{Data source}{

Taxation Statistics are published annually by the ATO on
\url{https://www.ato.gov.au/about-ato/research-and-statistics/} and
mirrored at \url{https://data.gov.au/data/organization/australiantaxationoffice}.
Most datasets are licensed under Creative Commons Attribution 2.5
Australia; Corporate Tax Transparency and the Voluntary Tax
Transparency Code are CC BY 3.0 Australia.
}

\seealso{
Useful links:
\itemize{
  \item \url{https://charlescoverdale.github.io/ato/}
  \item \url{https://github.com/charlescoverdale/ato}
  \item Report bugs at \url{https://github.com/charlescoverdale/ato/issues}
}

}
\author{
\strong{Maintainer}: Charles Coverdale \email{charlesfcoverdale@gmail.com}

}
\concept{Australian tax}
\concept{income distribution}
\concept{taxation statistics}
\keyword{internal}
