Package 'readmit'

Inspect completed RRP assessments

Description

Read retained assessment rows and their run context without sourcing or invoking project-authored analytical functions. Both optional filters use exact identifier matching and may be combined.

Usage

rrp_inspect_history(path, run_id = NULL, episode_id = NULL)

Arguments

path	Path to an existing RRP project with initialized state.
run_id	Optional single nonblank run ID to select.
episode_id	Optional single nonblank episode ID to select.

Details

Initialize state with rrp_state_init() before inspecting history. Rows are ordered by run creation time, run ID, and episode ID. Reads use a read-only connection and never create state or modify history. A completed run with zero episodes contributes no assessment row.

Value

An ordinary data frame containing stored assessment identity, times, disposition, probability, failure detail, selected terminal-event context, and associated run metadata. Empty results retain the same columns and types, including UTC POSIXct timestamps.

Examples

project <- tempfile("rrp-inspect-")
rrp_project_init(project, "example-rrp")
rrp_state_init(project)
rrp_inspect_history(project)
unlink(project, recursive = TRUE)

---

Create an RRP project

Description

Copy the installed project template into a new, user-owned directory. The project contains editable configuration, branding, source-mapping and risk-provider scripts, and a Shiny application. Initialization does not create analytical state or products. The project owner must implement the two analytical scripts before running assessments.

Usage

rrp_project_init(path, project_id)

Arguments

path	Destination for the new project. Its parent directory must exist, and the destination itself must not exist, even as an empty directory.
project_id	A nonempty project identifier beginning with a letter or digit and containing only letters, digits, ., ⁠_⁠, or -. It fills the project identity and initial branding fields; edit ⁠_brand.yml⁠ afterward to change the displayed name or styling.

Details

The project-owned application runs separately with ordinary Shiny tooling, for example shiny::runApp("path/to/project/app"), after its dependencies are installed as described in the project's README.md.

Value

The normalized project path, invisibly.

Examples

project <- file.path(tempdir(), "example-rrp-project")
if (!file.exists(project)) {
  rrp_project_init(project, "example-rrp-project")
}

---

Summarize an RRP project's retained history

Description

Read project identity and completed-run status without sourcing the project's analytical scripts, executing an assessment, or changing state. This also works before analytical state has been initialized.

Usage

rrp_project_status(path)

Arguments

path	Path to an existing RRP project directory.

Details

The latest run is the most recently recorded completed run by created_at, not the largest analytical as_of_time. Ties in recorded creation time are broken by run_id. Reads use a read-only connection and do not initialize state.

Value

An ordinary named list containing character project_id, logical state_initialized, integer run_count, character latest_run_id, and UTC POSIXct latest_as_of_time. The latest fields are typed missing values when there are no runs.

Examples

project <- tempfile("rrp-status-")
rrp_project_init(project, "example-rrp")
rrp_project_status(project)
unlink(project, recursive = TRUE)

---

Check an RRP project's authoring structure

Description

Check that an existing project has readable rrp-project.dcf and rrp-authoring.dcf files and that their configured scripts define rrp_produce_canonical(project_root, as_of_time) and rrp_calculate_risk(project_root, request). A newly initialized project's deliberate function stubs pass this check.

Usage

rrp_project_validate(path)

Arguments

path	Path to an existing RRP project directory.

Details

The project-authored scripts are sourced, so their top-level R code can run. Neither authoring function is called. This is a structural check; it does not test source data, model behavior, analytical readiness, or the project's Shiny application.

Value

TRUE, invisibly, when the essential configuration and authoring functions load successfully. Missing or unusable resources raise an error.

Examples

project <- tempfile("rrp-validation-")
rrp_project_init(project, "example-rrp")
rrp_project_validate(project)
unlink(project, recursive = TRUE)

---

Refresh an RRP project's analytical product CSVs

Description

Derive the current clinically eligible risk pool, observed accepted-risk trajectories, and operational scope from retained assessment history. The selected completed run has the greatest analytical as_of_time; execution created_at and then run_id break ties. A later-executed historical backfill does not replace a newer analytical snapshot.

Usage

rrp_refresh_products(path)

Arguments

path	Path to an existing RRP project with initialized analytical state and at least one completed assessment run.

Details

Files are written under ⁠state/products/⁠ as current-remaining-risk.csv, remaining-risk-trajectory.csv, and operational-scope-summary.csv. The current-risk file includes clinically eligible provider-failure episodes with a missing probability, never zero or an earlier estimate. Refresh reads history only: it does not run the source mapper or provider, add a run, change retained history, or edit the project-owned app. All files are staged and checked before replacement. Replacement of the three files is not fully atomic if a filesystem error occurs during the final replacement sequence.

Value

Invisibly, a list with selected_run_id, UTC as_of_time, and named character files containing the three generated CSV paths.

---

Run an RRP assessment and retain its history

Description

Run the configured project source mapper at one analytical time, determine which discharge episodes remain eligible for first readmission in the remaining 30-day follow-up window, and call the project risk provider once per eligible episode. Accepted estimates, provider failures, and ineligible outcomes are retained together as one completed run.

Usage

rrp_run(path, as_of_time)

Arguments

path	Path to an existing RRP project with initialized analytical state.
as_of_time	One finite UTC POSIXct analytical instant. This same time is used for source production, eligibility, provider requests, and history.

Details

Call rrp_state_init() before the first run. The project owner must implement the configured rrp_produce_canonical() and rrp_calculate_risk() functions. A provider failure affects its episode, while a source or persistence failure stops the run without a partial completed record. Analytical products are generated separately.

Value

An ordinary list with run_id, as_of_time, episodes_processed, accepted, provider_failures, and ineligible. Counts are integers; the run ID belongs to a successfully committed run.

Examples

## Not run: 
assessment_time <- as.POSIXct("2026-01-10 12:00:00", tz = "UTC")
rrp_run("my-rrp-project", assessment_time)

## End(Not run)

---

Initialize persistent history for an RRP project

Description

Create state/history.duckdb and its empty runs and assessments tables for an existing project. This is separate from project creation and does not execute assessments or generate analytical products.

Usage

rrp_state_init(path)

Arguments

path	Path to an existing RRP project that passes structural validation.

Details

Initialization refuses to overwrite any existing ⁠state/⁠ directory. Project-authored scripts are loaded during structural validation, but their source-mapping and risk-provider functions are not called.

Value

The normalized project path, invisibly.

Examples

project <- tempfile("rrp-state-")
rrp_project_init(project, "example-rrp")
rrp_state_init(project)
unlink(project, recursive = TRUE)

---