diff --git a/DESCRIPTION b/DESCRIPTION index 99f0c0d..c79c38f 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -72,7 +72,7 @@ Depends: License: GPL (>= 3) Encoding: UTF-8 LazyData: true -RoxygenNote: 7.3.1 +RoxygenNote: 7.3.2 VignetteBuilder: knitr Config/testthat/edition: 3 Config/testthat/parallel: true diff --git a/NAMESPACE b/NAMESPACE index 7b79b71..680249b 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -14,6 +14,7 @@ export(ojo_connect) export(ojo_county_population) export(ojo_crim_cases) export(ojo_env) +export(ojo_eviction_cases) export(ojo_fill) export(ojo_fiscal_year) export(ojo_list_schemas) @@ -27,4 +28,12 @@ export(ojo_tbl) export(ojo_theme) export(ojo_version) import(dplyr) +importFrom(dplyr,case_when) +importFrom(dplyr,filter) +importFrom(dplyr,left_join) +importFrom(dplyr,mutate) +importFrom(dplyr,select) importFrom(ggplot2,"%+replace%") +importFrom(lubridate,as_date) +importFrom(lubridate,floor_date) +importFrom(stringr,str_detect) diff --git a/R/ojo_eviction_cases.R b/R/ojo_eviction_cases.R new file mode 100644 index 0000000..73ad479 --- /dev/null +++ b/R/ojo_eviction_cases.R @@ -0,0 +1,138 @@ +#' @title OJO Eviction Cases +#' +#' @description +#' Collects Oklahoma eviction data for the specified districts (or all of Oklahoma) +#' for the user specified time frame. If date_end is not specified, the +#' most up-to-date data will be collected. +#' +#' Function uses the latest methodology we use for identifying eviction cases +#' and outcomes in Oklahoma. As that methodology is updated, this function will +#' be updated to reflect those changes. +#' +#' @param district District code for which to collect data (default is "all", which collects data for all districts) +#' @param ... Placeholder for additional arguments +#' @param date_start Start date for the data collection period +#' @param date_end End date for the data collection period (default is NULL, which collects the most up-to-date data) +#' @param more_case_variables Additional variables from case table to include in the output +#' @param more_issue_variables Additional variables from issue table to include in the output +#' @param get_judgments Logical value indicating whether to include eviction judgment information in the output +#' +#' @importFrom dplyr filter select left_join mutate case_when +#' @importFrom stringr str_detect +#' @importFrom lubridate floor_date as_date +#' +#' @export ojo_eviction_cases +#' @return A dataframe containing eviction data +#' +#' @examples +#' \dontrun{ +#' ojo_eviction_cases() +#' ojo_eviction_cases(districts = c("TULSA", "ADAIR")) +#' ojo_eviction_cases( +#' districts = c("TULSA", "ADAIR"), +#' date_start = "2020-01-01", +#' date_end = "2020-01-31", +#' more_issue_variables = disposition_date +#' ) +#' ojo_eviction_cases( +#' districts = c("TULSA", "ADAIR"), +#' get_judgments = TRUE +#' ) +#' } +#' + +ojo_eviction_cases <- function(districts = "all", + ..., + date_start = NULL, + date_end = NULL, + more_case_variables = NULL, + more_issue_variables = NULL, + get_judgments = TRUE) { + #### Variable Handling + .district <- toupper(districts) + + ##### Data Wrangling / Cleaning + ## Construct Data + data <- ojodb::ojo_tbl("case") + + if (!any(.district == "ALL")) { + data <- data |> + dplyr::filter(district %in% .district) + } + + if (!is.null(date_end)) { + data <- data |> + dplyr::filter(date_filed <= date_end) + } + + if (!is.null(date_start)) { + data <- data |> + dplyr::filter(date_filed >= date_start) + } + + case_vars <- unique( + c( + "id", "district", "date_filed", "date_closed", "status", + more_case_variables + ) + ) + + issue_vars <- unique( + c( + "id", "case_id", "description", "disposition", + more_issue_variables + ) + ) + + data <- data |> + dplyr::filter(case_type == "SC") |> + dplyr::select(dplyr::all_of(case_vars)) |> + dplyr::left_join( + ojodb::ojo_tbl("issue") |> + dplyr::select(dplyr::all_of(issue_vars)), + by = c("id" = "case_id"), + suffix = c(".case", ".issue") + ) + + ## Keep Only Eviction Cases + # This our standard "strict" definition for research and analysis applications. + # For applications where we may want to allow for more errors such as for + # non-profit service providers, we may want to consider a more lenient definition. + data <- data |> + dplyr::filter( + stringr::str_detect( + description, + "RENT|FORCI|EVICT|DETAIN" + ) + ) + + if (get_judgments == TRUE) { + data <- data |> + dplyr::mutate(clean_disposition = case_when( + stringr::str_detect(disposition, "DISMISS") ~ "DISMISSED", + stringr::str_detect(disposition, "JUDGMENT|JUDGEMENT") ~ + case_when( + stringr::str_detect(disposition, "DEFAULT") ~ "DEFAULT JUDGMENT", + stringr::str_detect(disposition, "PLAINTIFF") ~ "JUDGMENT FOR PLAINTIFF", + stringr::str_detect(disposition, "DEFENDANT") ~ "JUDGMENT FOR DEFENDANT", + TRUE ~ "JUDGMENT ENTERED" + ), + stringr::str_detect(disposition, "ADVISEMENT") ~ "UNDER ADVISEMENT" + )) + + data <- data |> + dplyr::mutate( + judgment = dplyr::case_when( + clean_disposition %in% + c("DEFAULT JUDGMENT", "JUDGMENT FOR PLAINTIFF") ~ "Eviction Granted", + clean_disposition == "JUDGMENT FOR DEFENDANT" ~ "Eviction Denied", + clean_disposition == "JUDGMENT ENTERED" ~ "Case Decided, Outcome Unknown", + clean_disposition == "DISMISSED" ~ "Case Dismissed (Settled Outside Court)", + clean_disposition == "UNDER ADVISEMENT" ~ "Case Under Advisement", + .default = "Case Undecided" + ) + ) + } + + return(data) +} diff --git a/_pkgdown.yml b/_pkgdown.yml index c3cc44d..c6f16fc 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -8,6 +8,7 @@ reference: contents: - ojo_civ_cases - ojo_crim_cases + - ojo_eviction_cases - ojo_add_counts - ojo_add_minutes - ojo_add_issues diff --git a/man/ojo_eviction_cases.Rd b/man/ojo_eviction_cases.Rd new file mode 100644 index 0000000..db5f8b6 --- /dev/null +++ b/man/ojo_eviction_cases.Rd @@ -0,0 +1,60 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/ojo_eviction_cases.R +\name{ojo_eviction_cases} +\alias{ojo_eviction_cases} +\title{OJO Eviction Cases} +\usage{ +ojo_eviction_cases( + districts = "all", + ..., + date_start = NULL, + date_end = NULL, + more_case_variables = NULL, + more_issue_variables = NULL, + get_judgments = TRUE +) +} +\arguments{ +\item{...}{Placeholder for additional arguments} + +\item{date_start}{Start date for the data collection period} + +\item{date_end}{End date for the data collection period (default is NULL, which collects the most up-to-date data)} + +\item{more_case_variables}{Additional variables from case table to include in the output} + +\item{more_issue_variables}{Additional variables from issue table to include in the output} + +\item{get_judgments}{Logical value indicating whether to include eviction judgment information in the output} + +\item{district}{District code for which to collect data (default is "all", which collects data for all districts)} +} +\value{ +A dataframe containing eviction data +} +\description{ +Collects Oklahoma eviction data for the specified districts (or all of Oklahoma) +for the user specified time frame. If date_end is not specified, the +most up-to-date data will be collected. + +Function uses the latest methodology we use for identifying eviction cases +and outcomes in Oklahoma. As that methodology is updated, this function will +be updated to reflect those changes. +} +\examples{ +\dontrun{ +ojo_eviction_cases() +ojo_eviction_cases(districts = c("TULSA", "ADAIR")) +ojo_eviction_cases( + districts = c("TULSA", "ADAIR"), + date_start = "2020-01-01", + date_end = "2020-01-31", + more_issue_variables = disposition_date +) +ojo_eviction_cases( + districts = c("TULSA", "ADAIR"), + get_judgments = TRUE +) +} + +} diff --git a/tests/testthat/test-ojo_civ_cases.R b/tests/testthat/test-ojo_civ_cases.R index 254adc2..f2633b0 100644 --- a/tests/testthat/test-ojo_civ_cases.R +++ b/tests/testthat/test-ojo_civ_cases.R @@ -1,4 +1,4 @@ -test_that("ojo_civ_cases works", { +testthat::test_that("ojo_civ_cases works", { skip_on_runiverse() testthat::expect_no_error({ diff --git a/tests/testthat/test-ojo_eviction_cases.R b/tests/testthat/test-ojo_eviction_cases.R new file mode 100644 index 0000000..39447fc --- /dev/null +++ b/tests/testthat/test-ojo_eviction_cases.R @@ -0,0 +1,19 @@ +test_that("ojo_eviction_cases works", { + skip_on_runiverse() + + testthat::expect_no_error({ + ojo_eviction_cases() + }) +}) + +test_that("ojo_eviction_cases includes additional case variables if specified", { + skip_on_runiverse() + data <- ojo_eviction_cases(more_case_variables = "judge") + expect_true("judge" %in% colnames(data)) +}) + +test_that("ojo_eviction_cases includes additional issue variables if specified", { + skip_on_runiverse() + data <- ojo_eviction_cases(more_issue_variables = "disposition_date") + expect_true("disposition_date" %in% colnames(data)) +})