Add ojo_eviction_cases (#173)

* Add ojo_eviction_cases.R and test-ojo-eviction_cases.R

* Add ojo_eviction_cases tests and refine function

* Modify ojo_eviction_cases.R description

* Modify ojo_eviction_cases.R description

* Modify ojo_eviction_cases.R description

* Brancen review

* Add additional tests for ojo_eviction_cases

* Rename file

---------

Co-authored-by: Brancen Gregory <brancengregory@gmail.com>

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

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)

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)
+}

_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

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({

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))
+})