Downloads and processes MCAS assessment data from the Massachusetts Department of Elementary and Secondary Education (DESE) via their Socrata API (educationtocareer.data.mass.gov).
Usage
fetch_assessment(
end_year,
grade = NULL,
subject = NULL,
subgroup = NULL,
tidy = TRUE,
exclude_aggregated = TRUE,
use_cache = TRUE
)Arguments
- end_year
A school year. Year is the end of the academic year - eg 2024-25 school year is year '2025'. Valid values are 2017-2019, 2021-2025.
- grade
Filter by grade level. Options include "03", "04", "05", "06", "07", "08", "10", "HS SCI", or "ALL (03-08)". If NULL (default), returns all grades.
- subject
Filter by subject. Options include "ela", "math", "science", "biology", "physics", "civics". If NULL (default), returns all subjects.
- subgroup
Filter by student subgroup. Use lowercase names like "all", "white", "black", "hispanic", "english_learner", "special_ed", etc. If NULL (default), returns all subgroups.
- tidy
If TRUE (default), returns data in long (tidy) format with subgroup column. If FALSE, returns wide format.
- exclude_aggregated
If TRUE (default), excludes aggregated grade rows (e.g., "ALL (03-08)"). Set to FALSE to include aggregated rows.
- use_cache
If TRUE (default), uses locally cached data when available. Set to FALSE to force re-download from DESE.
Value
Data frame with assessment data. Includes columns for end_year, type, district_id, school_id, grade, subject, subgroup, achievement counts and percentages, participation rate, scaled score, and student growth percentiles.
Examples
if (FALSE) { # \dontrun{
# Get 2025 assessment data (2024-25 school year)
assess_2025 <- fetch_assessment(2025)
# Get grade 10 data only
g10 <- fetch_assessment(2025, grade = "10")
# Get statewide math results
math <- fetch_assessment(2025, subject = "math")
# Filter to all students subgroup
all_students <- fetch_assessment(2025, subgroup = "all")
# Get district-level data
districts <- assess_2025 |>
dplyr::filter(is_district)
# Compare Boston and Springfield math achievement
assess_multi <- fetch_assessment_multi(2019:2025)
assess_multi |>
dplyr::filter(district_id %in% c("0035", "0281"),
grade == "10",
subject == "math",
subgroup == "all") |>
dplyr::select(end_year, district_name, meeting_exceeding_pct)
} # }