---
title: "Basic usage of edfinr"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Basic usage of edfinr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
# chunks that download hosted data are skipped on CRAN machines; set
# NOT_CRAN=true (as the pkgdown workflow does) to evaluate everything
NOT_CRAN <- identical(Sys.getenv("NOT_CRAN"), "true")
knitr::opts_chunk$set(
  message = FALSE,
  warning = FALSE,
  eval = NOT_CRAN
)
```

## Introduction

The `edfinr` package provides tidy, analysis-ready school district finance data for the United States — NCES F-33 revenues and expenditures joined with enrollment, poverty, community, and labor-cost measures — assembled with an opinionated cleaning methodology. This vignette will help you get started with the package's core functionality.

```{r setup, include = FALSE, eval = TRUE}
library(edfinr)
library(dplyr)
library(ggplot2)
```

```{r, eval = FALSE}
library(edfinr)
library(dplyr)
library(ggplot2)
```

## Core function: get_finance_data()

The primary function in `edfinr` is `get_finance_data()`, which provides access to school finance data from school years 2011-12 through 2022-23. NCES F-33 data are released roughly two years after a fiscal year closes, so FY2023 (SY2022-23) is the most recent federal release. The function combines data from multiple sources:

- **Financial data**: Revenue and expenditure data (including capital outlay, debt, and fund balances) from the National Center for Education Statistics (NCES) version of the F-33 survey.
- **Enrollment**: Fall membership counts (F-33 item V33), the denominator for all per-pupil measures.
- **Demographics**: Poverty estimates from the U.S. Census Bureau Small Area Income and Poverty Estimates (SAIPE).
- **Community characteristics**: Income and education data from American Community Survey (ACS).
- **Labor costs**: The NCES EDGE Comparable Wage Index for Teachers (CWIFT).
- **Inflation adjustments**: Consumer Price Index for All Urban Consumers (CPI-U) data for constant dollar calculations.

## Basic usage

The simplest way to use `get_finance_data()` is to specify a year and state. For example, to get finance data for Kentucky school districts from the 2022-23 school year:

```{r example-1}
ky_sy23 <- get_finance_data(yr = "2023", geo = "KY")
glimpse(ky_sy23)
```

## Dataset types: skinny vs. full

By default, `get_finance_data()` returns a "skinny" dataset with 59 essential variables covering:

- District identifiers and characteristics.
- Total revenues by source (local, state, federal).
- Current expenditures and total capital outlay (`exp_cap_total`, `exp_cap_total_pp`).
- Key demographic and economic indicators (including the CWIFT teacher-wage index).
- District land area and student density (`land_area_sq_mi`, `s_per_sq_mi`).

For more detailed analysis, you can request the "full" dataset with 124 variables that includes:

- All skinny dataset variables.
- Detailed expenditure data.
- Data on spending of temporary pandemic-related federal funding.
- Detailed capital outlay, debt stocks, and fund balances (see the "Capital and Facilities" article).
- The CWIFT standard error and imputation method (see the "CWIFT" article).

```{r example-2}
ky_full_sy23 <- get_finance_data(yr = "2023", geo = "KY", dataset_type = "full")
setdiff(names(ky_full_sy23), names(ky_sy23))
```

## Finding variables

With 124 variables in the full dataset, the data dictionary is the fastest way to find what you need. `list_variables()` returns it as a tibble, so you can filter and search it like any other data.

```{r finding-variables, eval = TRUE}
vars <- list_variables("full")
vars

# filter by category
list_variables("full", category = "debt")
```

## Multiple years and states

The `get_finance_data()` function makes it easy to access data across multiple years and states:

```{r example-3}
sec_data <- get_finance_data(
  yr = "2019:2023",  # years 2019 through 2023
  geo = "AL,AR,FL,GA,KY,LA,MS,MO,OK,SC,TN,TX"  # comma-separated state codes
)

us_sy23 <- get_finance_data(yr = "2023", geo = "all")
```

## Downloads and caching

Only the requested year(s) are downloaded: each year is hosted as its own file (roughly 3-6 MB), so a single-year or short-range request is lightweight even though the full panel spans 2012-2023. Requesting `yr = "all"` downloads the entire history from one combined file.

Downloaded files are cached in R's temporary directory for the length of your R session, so repeated calls with the same years re-read the cache instead of re-downloading. Two arguments control this behavior: `refresh = TRUE` forces a fresh download (for example, after a data update is announced), and `quiet = TRUE` suppresses the download progress messages.

```{r caching, eval = FALSE}
# re-download even if a cached copy exists, without progress messages
ky_fresh <- get_finance_data(yr = "2023", geo = "KY", refresh = TRUE, quiet = TRUE)
```

## Working with the data

Once you've retrieved the data, you can use standard data manipulation tools to analyze it. Here are some common analysis patterns:

### Do high local revenue share districts end up with more total revenue?

```{r analysis-1, fig.width = 7, fig.height = 5, fig.alt = "Scatterplot of Connecticut districts' local share of revenue versus total revenue per-pupil for SY2022-23, with point size showing enrollment and color showing urbanicity; the most locally-reliant districts tend to have higher total revenue per-pupil."}
ct_sy23 <- get_finance_data(yr = "2023", geo = "CT")

ggplot(ct_sy23) +
  geom_point(aes(
    x = rev_local / rev_total,
    y = rev_total_pp,
    color = urbanicity,
    size = enroll),
    alpha = .6) +
  scale_size_area(
    max_size = 10,
    labels = scales::label_comma()
    ) +
  scale_x_continuous(labels = scales::label_percent()) +
  scale_y_continuous(labels = scales::label_dollar()) +
  labs(
    title = "Connecticut Districts' Local Revenue Share vs. Total Revenue Per-Pupil, SY2022-23",
    x = "Local Share of Total Revenue",
    y = "Total Revenue Per-Pupil",
    size = "Enrollment",
    color = "Urbanicity") +
  theme_bw()
```

### How do revenue sources differ by urbanicity?

```{r analysis-2}
# compare revenue mix across urbanicity groups (dollar-weighted)
revenue_analysis <- ct_sy23 |>
  group_by(urbanicity) |>
  summarize(
    pct_local = sum(rev_local, na.rm = TRUE) / sum(rev_total, na.rm = TRUE),
    pct_state = sum(rev_state, na.rm = TRUE) / sum(rev_total, na.rm = TRUE),
    pct_federal = sum(rev_fed, na.rm = TRUE) / sum(rev_total, na.rm = TRUE),
    n_districts = n(),
    enrollment = sum(enroll, na.rm = TRUE)
  )

revenue_analysis
```

## See also

- The [CPI Adjustments](cpi-adjustments.html) vignette for inflation adjustment across years.
- The [Data Sources and Methodology](data-sources-methods.html) vignette for detailed methodology and the F-33 crosswalk.
- On the package website: articles on [capital and facilities](https://bellwetherorg.github.io/edfinr/articles/capital-facilities.html), [CWIFT](https://bellwetherorg.github.io/edfinr/articles/cwift.html), COVID relief spending, [community and economic context](https://bellwetherorg.github.io/edfinr/articles/community-context.html), data quality and comparability, and [mapping school finance data](https://bellwetherorg.github.io/edfinr/articles/mapping.html).