---
title: "Getting Started with readmit"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with readmit}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
library(readmit)
```

After discharge, a hospital may want to reassess how much readmission risk
remains as follow-up time passes. Readmission Risk Pool (RRP) estimates the
probability of a **first readmission strictly after an assessment time through
30 elapsed days after discharge**. A new assessment uses the time still left
in that original 30-day period; it does not start another one. `readmit`
supplies the project, eligibility, history, and product operations. The project
owner supplies the clinical source mapping and a model that estimates risk.

This small example follows four discharge episodes through one assessment and
shows what the package records. Its probability formula is only an illustration,
not a fitted or clinically validated model. For source mapping, a trained
assessment-time model, repeated assessments, and application customization, see
[Implementing RRP: A Simulated Hospital Walkthrough](https://readmit.centralstatz.com/articles/implementing-rrp.html).

## Create a project and supply canonical facts

Initialization creates an ordinary project directory. Its
`R/produce-canonical.R` and `R/calculate-risk.R` scripts are the owner's two
analytical implementation points. We replace their initial stubs below.

```{r project}
project <- rrp_project_init(tempfile("rrp-getting-started-"), "example-rrp")
as_of_time <- as.POSIXct("2026-01-10 12:00:00", tz = "UTC")
discharge_time <- as.POSIXct(c(
  "2026-01-08 12:00:00", "2026-01-01 12:00:00",
  "2025-12-01 12:00:00", "2026-01-04 12:00:00"
), tz = "UTC")
episodes <- data.frame(
  episode_id = paste0("episode-", 1:4),
  patient_id = paste0("patient-", 1:4),
  index_encounter_id = paste0("encounter-", 1:4),
  admission_time = discharge_time - 2 * 86400,
  discharge_time = discharge_time
)
events <- data.frame(
  terminal_event_id = c("event-2", "event-4"),
  episode_id = c("episode-2", "episode-4"),
  event_type = c("readmission", "death"),
  occurred_at = as.POSIXct(c(
    "2026-01-06 12:00:00", "2026-01-07 12:00:00"
  ), tz = "UTC")
)
saveRDS(list(discharge_episode = episodes, terminal_event = events),
        file.path(project, "canonical.rds"))
```

At the January 10 assessment, all four episodes have been discharged, but only
episode 1 remains eligible for a new risk estimate. Episode 2 has already been
readmitted, episode 3 is past its original 30-day endpoint, and episode 4 has
experienced a death. The package considers a supplied readmission or death
when its occurrence time satisfies `occurred_at <= as_of_time`.

For a real assessment, the hospital's source mapper must supply the complete
relevant discharge population at *each* assessment time. Every supplied episode
must satisfy `discharge_time <= as_of_time`; a discharge exactly at that time
is valid. The saved list above is for one assessment only. The package rejects
a future discharge before checking eligibility, calling the model, or writing
history.

The project-authored mapper reads those typed facts. The example risk provider
starts with an arbitrary 0.30 and scales it by the share of the original 30-day
period still remaining. It uses the package's `remaining_seconds` request
field, so it does not restart the follow-up window. This arithmetic has no
clinical meaning; a real project requires its own suitable model.

```{r author}
writeLines(c(
  "rrp_produce_canonical <- function(project_root, as_of_time) {",
  "  readRDS(file.path(project_root, 'canonical.rds'))",
  "}"
), file.path(project, "R", "produce-canonical.R"))
writeLines(c(
  "rrp_calculate_risk <- function(project_root, request) {",
  "  list(probability = 0.30 * request$remaining_seconds / (30 * 86400))",
  "}"
), file.path(project, "R", "calculate-risk.R"))
rrp_project_validate(project)
rrp_state_init(project)
```

`rrp_project_validate()` checks that required project resources and functions
load. It does not test the supplied data, formula, or clinical suitability.

## Run and inspect an assessment

```{r assess}
assessment <- rrp_run(project, as_of_time)
assessment[c("episodes_processed", "accepted", "provider_failures", "ineligible")]

status <- rrp_project_status(project)
status[c("state_initialized", "run_count")]
history <- rrp_inspect_history(project)
history[c("episode_id", "disposition", "probability")]
stopifnot(assessment$accepted == 1L, assessment$ineligible == 3L,
          isTRUE(all.equal(history$probability[history$disposition == "accepted"],
                           0.28)))
```

Only episode 1 was eligible, so the package asked the project risk provider for
an estimate for that episode alone. Its illustrative result was 0.28. The other
three history rows record why no new estimate was requested for those episodes.
History retains the assessment and can be inspected later.

## Refresh the three products

History is the retained record of the assessment. Product refresh reads that
record and creates CSV files for review and for the project application; it
does not reassess anyone or edit the application.

```{r products}
products <- rrp_refresh_products(project)
current_risk <- read.csv(products$files[["current_risk"]])
trajectory <- read.csv(products$files[["trajectory"]])
scope <- read.csv(products$files[["scope"]])

current_risk[c("episode_id", "disposition", "probability")]
trajectory[c("episode_id", "probability")]
scope[c("episodes_assessed", "eligible_count", "accepted_count",
        "known_readmission_count", "known_death_count", "window_closed_count")]
stopifnot(nrow(current_risk) == 1L, nrow(trajectory) == 1L,
          scope$episodes_assessed == 4L)
```

The current-risk CSV contains eligible episode 1. The trajectory CSV contains
its recorded accepted estimate, and the scope CSV counts all four assessment
outcomes. These files can be refreshed from history without changing the
original assessment.
The project-contained Shiny app reads these products. After installing its
runtime packages as listed in the project's `README.md`, launch it manually:

```r
shiny::runApp(file.path(project, "app"))
```