This document lists practices considered standard in our research activities.
How to download map boundary files (.json) using R
- Replace your-filename and your-subscription-key with appropriate values.
# Define the URL of the file to download
file_url <- "https://apims-nswers.azure-api.net/gis/v1/ccservicearea"
# file_url <- "https://apims-nswers.azure-api.net/gis/v1/county"
# file_url <- "https://apims-nswers.azure-api.net/gis/v1/district"
# file_url <- "https://apims-nswers.azure-api.net/gis/v1/esu"
# file_url <- "https://apims-nswers.azure-api.net/gis/v1/legislative"
# file_url <- "https://apims-nswers.azure-api.net/gis/v1/nuboard"
# file_url <- "https://apims-nswers.azure-api.net/gis/v1/seaboard"
# Geospatial data available at the geojson format
# Replace with desired local filename
tmp_geojson <- tempfile(fileext = ".geojson")
# tmp_geojson <- file.path("your-filename.geojson")
# Define your Azure API subscription key
subscription_key <- "your-subscription-key"
# Create a named character vector for the HTTP header
headers <- c("Nswers-Subscription-Key" = subscription_key)
# Use download.file to download the file with the specified headers
download.file(url = file_url,
destfile = tmp_geojson,
headers = headers)
# Read data (need sf pacakge)
# library(sf)
dat_sf <- read_sf(tmp_geojson)How to host Rmd-generated html files on our ts.nswers.org
- The key is essentially rendering as an html fragment and then copy/pasting that html into a custom html block in the article.
- See this example: https://ts.nswers.org/kb/research/suppression-with-suppress/
# in .rmd headers
output:
html_fragment:
number_sections: falseCohort year selection
- Only include a cohort year when sufficient data is available to observe the relevant outcome. This ensures equal follow‑up time for all students and maintains a consistent denominator across all outcome calculations.
- For example, workforce outcomes typically require a two‑year observation window after the event (e.g., high school graduation or postsecondary graduation). For this reason, the latest available cohort year for workforce outcomes in insights+ can currently go up to 2022 (as of 2026‑03‑26).
How to set up .Renviron file
- Download .Renviron file from Bitwarden. Change the name
Renviron.txtto.Renviron. - Never upload the file in the Azure DevOps repository.
How to set up .Rprofile file
- In Git Bash: run
touch ~/.Rprofilenotepad ~/.Rprofileto create a .Rprofile file. - In PowerShell: run
New-Item ~/.Rprofilenotepad ~/.Rprofileto create a .Rprofile file. - Include the following script in the file (adjust the names):
# replace the names with your names
options(
usethis.description = list(
"Authors@R" = utils::person(
"Alex", "Brodersen",
email = "alexbrodersen@nebraska.edu",
role = c("aut", "cre"),
comment = c(ORCID = "0000-0003-4063-9485")
),
Language = "en"
)
)
options(help_type = "text")
options(repos = c(CRAN = "https://packagemanager.posit.co/cran/2026-01-15"))
# this fixes an annoying feature with interactive logins for RGui users
# not necessary for Rstudio users
.Last <- function(){
if(interactive()){
windows()
dev.off()
}
}Initial renv setup for a project
- Run the following script. This ensures that the version of R and libraries are set to the right version / date for a project:
# choose the latest R version published before the chosen date
# https://cran.r-project.org/bin/windows/base/old/
# choose the date on posit package manager (PPM)
# you can also include this in .Rprofile
options(repos = c(CRAN = "https://packagemanager.posit.co/cran/2026-01-15"))
# install renv from the appropriate date
install.packages("renv") # repos = getOption("repos") is automatically set
# alternative approach
# install.packages("renv", repos = c(CRAN = "https://packagemanager.posit.co/cran/2026-01-15"))
# set up renv
# this will restart the R session (options will be reset)
renv::init(repos = getOption("repos")) # need to set repos argument manually
# alternative approach
# renv::init(repos = c(CRAN = "https://packagemanager.posit.co/cran/2026-01-15"))
# if you want to change the PPM date
# renv::checkout(date="2026-02-15", actions = c("restore", "snapshot"))
# if you need to add another package
# install.packages("pacakge_name", repos = c(CRAN = "https://packagemanager.posit.co/cran/2026-01-15"))
# renv::snapshot()
# to disable renv
# renv::deactivate(clean=TRUE) # clean=TRUE will remove the renv/ directory and the lockfile- Once renv is set up, make sure you share the following files in PR:
.Rprofile.,renv.lock, renv/activate.R, renv/setting.json - When sharing
.Rprofile, it should only include the following line:source(activate/R). Everything else should stay in your local R profile. - After the setup, consider creating a script under /requirements/bootstrap.R which includes the following code:
# ensure that the R version corresponds to the chosen date
# https://cran.r-project.org/bin/windows/base/old/
# activate renv if needed
# this will restart the R session (options will be reset)
# renv::activate()
# restore packages from the renv.lock file
renv::restore(exclude = c("NSWERSthemes", "NSWERSutils", "NSWERSrmd"))
# if you need to add another package
# install.packages("pacakge_name", repos = c(CRAN = "https://packagemanager.posit.co/cran/2026-01-15"))
# renv::snapshot()
# get package list
renv_packages <- renv::lockfile_read()
if(normalizePath(getwd()) != normalizePath(here::here())){
stop("Working directory is not project root.")
}
# install NSWERS packages
.install_internal_package <-
function(package,
version){
renv_present <- requireNamespace("renv", quietly = FALSE)
if(!renv_present){
stop("renv needs to be installed before using this function")
}
here_present <- requireNamespace("here", quietly = FALSE)
if(!here_present){
stop("`here` package needs to be installed before using this function")
}
internal_packages_dirname <- "internal_packages"
renv_active <- (!is.null(renv::project()))
if(renv_active){
message("RENV active. Installing in local directory")
ip_dir <- here::here(internal_packages_dirname,
package)
} else {
message("RENV NOT active. Installing from temp directory")
ip_dir <- file.path(tempdir(),
internal_packages_dirname)
}
if(!dir.exists(ip_dir)){
dir.create(ip_dir, recursive = TRUE)
}
system2("az", c("artifacts", "universal", "download",
"--organization", "https://dev.azure.com/NSWERS/",
"--feed", "nswers_r_internal",
"--name", tolower(package),
"--version", version,
"--path", shQuote(ip_dir)))
if(renv_active){
package_path <- file.path(".",
internal_packages_dirname,
package,
"bin",
"windows",
"contrib",
paste0(R.Version()$major,
".",
gsub("\\.[0-9]", "",
R.Version()$minor)),
paste0(package, "_", version, ".zip"))
renv::install(package_path,
prompt = FALSE,
repos = NULL)
} else {
package_path <- file.path(ip_dir,
"bin",
"windows",
"contrib",
paste0(R.Version()$major,
".",
gsub("\\.[0-9]", "",
R.Version()$minor)),
paste0(package, "_", version, ".zip"))
install.packages(package_path,
prompt = FALSE,
repos = NULL)
}
}
if(!is.null(renv_packages$Packages$NSWERSutils)){
.install_internal_package("NSWERSutils", "0.1.4")
}
if(!is.null(renv_packages$Packages$NSWERSthemes)){
.install_internal_package("NSWERSthemes", "2.0.10")
}
if(!is.null(renv_packages$Packages$NSWERSrmd)){
.install_internal_package("NSWERSrmd", "0.0.2")
}
Leave a Reply