Skip to contents

Introduction

The njschooldata package provides a simple interface for accessing New Jersey Department of Education (NJ DOE) school data in R. The NJ DOE publishes raw data files covering enrollment, assessments, graduation rates, and more - but these files use inconsistent formats across years, making longitudinal analysis challenging.

This package solves that problem by:

  • Automatically downloading data from NJ DOE servers
  • Parsing various file formats (fixed-width, Excel, CSV)
  • Standardizing column names across years
  • Providing both wide and tidy data formats

Installation

Install the package from GitHub:

# Using remotes (recommended)
remotes::install_github("almartin82/njschooldata")

# Or using devtools
devtools::install_github("almartin82/njschooldata")

Load the package:

library(njschooldata)
library(dplyr)  # for data manipulation examples

Understanding NJ Education Data

The end_year Convention

All functions use end_year to specify the school year. This refers to the spring semester year:

School Year end_year Value
2023-24 2024
2022-23 2023
2019-20 2020

CDS Codes

New Jersey uses a County-District-School (CDS) identifier system:

  • county_id: 2-digit county code (e.g., “13” = Essex County)
  • district_id: 4-digit district code
  • school_id: 3-digit school code (“999” indicates a district-level aggregate)
# A complete CDS code example:
# County 13 (Essex), District 3570 (Newark), School 050 (specific school)

Aggregation Levels

Data is provided at multiple aggregation levels, identified by boolean flags:

Level is_state is_district is_school Description
State TRUE FALSE FALSE Statewide totals
District FALSE TRUE FALSE District totals (school_id = “999”)
School FALSE FALSE TRUE Individual school data

Quick Start: Enrollment Data

Fetching Basic Enrollment

# Get 2024 enrollment data (2023-24 school year)
enr_2024 <- fetch_enr(2024)

# View the structure
glimpse(enr_2024)
#> Rows: 54,009
#> Columns: 44
#> $ end_year                    <dbl> 2024, 2024, 2024, 2024, 2024, 2024, 2024, …
#> $ cds_code                    <chr> "010010999", "010010999", "010010999", "01…
#> $ county_id                   <chr> "01", "01", "01", "01", "01", "01", "01", …
#> $ county_name                 <chr> "Atlantic", "Atlantic", "Atlantic", "Atlan…
#> $ district_id                 <chr> "0010", "0010", "0010", "0010", "0010", "0…
#> $ district_name               <chr> "Absecon Public Schools District", "Abseco…
#> $ school_id                   <chr> "999", "999", "999", "999", "999", "999", …
#> $ school_name                 <chr> "District Total", "District Total", "Distr…
#> $ program_code                <chr> "PH", "PF", "KH", "KF", "01", "02", "03", …
#> $ program_name                <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ male                        <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ female                      <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ non_binary                  <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ white                       <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ black                       <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ hispanic                    <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ asian                       <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ native_american             <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ pacific_islander            <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ multiracial                 <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ row_total                   <dbl> 0, 123, 0, 77, 89, 69, 85, 91, 73, 113, 10…
#> $ free_lunch                  <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ reduced_lunch               <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ lep                         <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ migrant                     <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ homeless                    <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ grade_level                 <chr> "PK", "PK", "K", "K", "01", "02", "03", "0…
#> $ military                    <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ free_lunch_value_source     <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ reduced_lunch_value_source  <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ lep_value_source            <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ migrant_value_source        <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ homeless_value_source       <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ military_value_source       <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ non_binary_value_source     <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ free_lunch_published_pct    <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ reduced_lunch_published_pct <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ lep_published_pct           <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ migrant_published_pct       <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ military_published_pct      <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ homeless_published_pct      <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ non_binary_published_pct    <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
#> $ nces_dist                   <chr> "3400660", "3400660", "3400660", "3400660"…
#> $ nces_sch                    <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…

# Check dimensions
dim(enr_2024)  # Rows and columns
#> [1] 54009    44

Wide vs. Tidy Format

The tidy parameter transforms data for easier analysis:

# Wide format (default) - one row per school, many demographic columns
enr_wide <- fetch_enr(2024, tidy = FALSE)

# Tidy format - one row per school-subgroup combination
enr_tidy <- fetch_enr(2024, tidy = TRUE)

The tidy format is better for: - Comparing subgroups within schools - Longitudinal analysis across years - Filtering to specific demographics

Filtering to Specific Levels

# Get only district-level totals
district_totals <- enr_tidy %>%
  filter(is_district, subgroup == "total_enrollment")

# Get only school-level data
school_data <- enr_tidy %>%
  filter(is_school)

# Get state totals
state_totals <- enr_tidy %>%
  filter(is_state)

Assessment Data

NJSLA / PARCC (2015-present)

Use fetch_parcc() for both NJSLA (2019+) and PARCC (2015-2018) data:

# Get 2024 Grade 4 Math results
math_g4_2024 <- fetch_parcc(
  end_year = 2024,
  grade_or_subj = 4,
  subj = "math"
)

# Get 2024 Grade 8 ELA results
ela_g8_2024 <- fetch_parcc(
  end_year = 2024,
  grade_or_subj = 8,
  subj = "ela"
)

# Get Algebra 1 results (high school)
alg1_2024 <- fetch_parcc(
  end_year = 2024,
  grade_or_subj = "ALG1",
  subj = "math"
)

Note: 2020 assessments were cancelled due to COVID-19.

Available Grade Levels

Subject PARCC (2015-2018) NJSLA (2019+)
ELA Grades 3-11 Grades 3-10
Math Grades 3-8 Grades 3-8
Math Courses ALG1, GEO, ALG2 ALG1, GEO, ALG2

Legacy Assessments (2004-2014)

For historical data, use fetch_old_nj_assess():

# Get 2010 Grade 5 NJASK results
njask_2010 <- fetch_old_nj_assess(
  end_year = 2010,
  grade = 5,
  tidy = TRUE
)

Graduation Data

Graduation Rates

# Get 4-year graduation rates for 2024
grad_rate_2024 <- fetch_grad_rate(
  end_year = 2024,
  methodology = "4 year"
)

# Get 5-year graduation rates (available 2012-2019)
grad_rate_5yr <- fetch_grad_rate(
  end_year = 2019,
  methodology = "5 year"
)

Graduation Counts

# Get graduation counts
grad_count_2024 <- fetch_grad_count(end_year = 2024)

School and District Directories

Get metadata about schools and districts:

# Current NJ education directory: entities (districts + schools) and
# personnel roles (superintendents, principals, etc.), directory-contract/v1
directory <- fetch_directory()

schools <- directory$entities[directory$entities$entity_type == "school", ]
districts <- directory$entities[directory$entities$entity_type == "district", ]

# Source status (the NJDOE Homeroom endpoints sit behind bot protection that
# blocks some automated clients; when challenged, source_status reports
# "source_unavailable" rather than silently returning empty data as if it
# were a real zero)
directory$meta$source_status
#> [1] "ok"

# Existing callers can use the compatibility data-frame front doors
# get_school_directory() and get_district_directory(). They make separate live
# requests, so this vignette does not call them again after fetch_directory().

# View available columns
names(schools)
#>  [1] "state"              "entity_type"        "entity_subtype"    
#>  [4] "district_id"        "school_id"          "district_name"     
#>  [7] "school_name"        "nces_district_id"   "nces_school_id"    
#> [10] "parent_district_id" "county_name"        "grades_served"     
#> [13] "address"            "city"               "zip"               
#> [16] "phone"              "website"            "status"            
#> [19] "is_charter"

Data Coverage Summary

Data Type Function Years Available
Enrollment fetch_enr() 1999-2026
NJSLA/PARCC fetch_parcc() 2015-2019, 2022-2025
NJASK fetch_old_nj_assess() 2004-2014
Four-year Graduation Rates fetch_grad_rate() 2011-2025
Graduation Counts fetch_grad_count() 2012-2025 tidy; raw sources begin in 1998

Common Subgroups

When working with tidy data, you’ll encounter these subgroup codes:

Race/Ethnicity

  • white, black, hispanic, asian
  • pacific_islander, native_american, multiracial

Other Demographics

  • male, female
  • free_lunch, reduced_lunch, free_reduced_lunch
  • lep (English learners)
  • migrant
  • total_enrollment

Note: Special education data is available via fetch_sped(), not through enrollment subgroups.

Tips and Best Practices

1. Use Session Caching

The package includes built-in session caching to avoid re-downloading:

# Use session cache (avoids re-downloading within same session)
enr_2024 <- fetch_enr(2024, tidy = TRUE, use_cache = TRUE)

# Or save to disk for reuse across sessions
saveRDS(enr_2024, "data/enr_2024.rds")
enr_2024 <- readRDS("data/enr_2024.rds")

# Check cache status
njsd_cache_info()

2. Handle Suppressed Data

Small cell sizes are suppressed with * or NA:

# Filter out suppressed values before calculations
reliable_data <- enr_tidy %>%
  filter(!is.na(n_students), n_students >= 10)

3. Multi-Year Analysis

Use purrr::map_df() for combining multiple years:

library(purrr)

# Fetch 5 years of enrollment data
years <- 2020:2024
multi_year_enr <- map_df(years, ~fetch_enr(.x, tidy = TRUE))

# Now you can analyze trends
enrollment_trends <- multi_year_enr %>%
  filter(is_state, subgroup == "total_enrollment") %>%
  select(end_year, n_students)

Next Steps

Getting Help

sessionInfo()
#> R version 4.6.2 (2026-10-29)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 26.04.1 LTS
#> 
#> Matrix products: default
#> BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 
#> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.32.so;  LAPACK version 3.12.0
#> 
#> locale:
#>  [1] LC_CTYPE=C.UTF-8       LC_NUMERIC=C           LC_TIME=C.UTF-8       
#>  [4] LC_COLLATE=C.UTF-8     LC_MONETARY=C.UTF-8    LC_MESSAGES=C.UTF-8   
#>  [7] LC_PAPER=C.UTF-8       LC_NAME=C              LC_ADDRESS=C          
#> [10] LC_TELEPHONE=C         LC_MEASUREMENT=C.UTF-8 LC_IDENTIFICATION=C   
#> 
#> time zone: UTC
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] purrr_1.2.2         dplyr_1.2.1         njschooldata_0.11.0
#> 
#> loaded via a namespace (and not attached):
#>  [1] rappdirs_0.3.4    sass_0.5.0        generics_0.1.4    tidyr_1.3.2      
#>  [5] stringi_1.8.9     hms_1.1.4         digest_0.6.39     magrittr_2.0.5   
#>  [9] evaluate_1.0.5    timechange_0.4.0  fastmap_1.2.0     cellranger_1.1.0 
#> [13] jsonlite_2.0.0    httr_1.4.9        codetools_0.2-20  textshaping_1.1.0
#> [17] jquerylib_0.1.4   cli_3.6.6         crayon_1.5.3      rlang_1.3.0      
#> [21] bit64_4.8.6       withr_3.0.3       cachem_1.1.0      yaml_2.3.12      
#> [25] otel_0.3.0        parallel_4.6.2    tools_4.6.2       tzdb_0.5.0       
#> [29] curl_8.1.0        vctrs_0.7.3       R6_2.6.1          lifecycle_1.0.5  
#> [33] lubridate_1.9.5   snakecase_0.11.1  stringr_1.6.0     bit_4.6.0        
#> [37] fs_2.1.0          vroom_1.7.1       ragg_1.5.2        janitor_2.2.1    
#> [41] pkgconfig_2.0.3   desc_1.4.3        pkgdown_2.2.1     pillar_1.11.1    
#> [45] bslib_0.12.0      glue_1.8.1        systemfonts_1.3.3 xfun_0.62        
#> [49] tibble_3.3.1      tidyselect_1.2.1  knitr_1.52        htmltools_0.5.9  
#> [53] rmarkdown_2.32    readr_2.2.0       compiler_4.6.2    readxl_1.6.0