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

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

```{r setup}
library(uroscores)
```

An instrument here is data, not code. The registry shows what is installed
and whether each definition has been checked against its primary source:

```{r}
list_instruments()
```

One engine scores everything. Wrappers like `score_ipss()` add
instrument-specific conveniences, in this case the separate quality-of-life
item and severity classification:

```{r}
d <- data.frame(
  ipss_q1 = c(1, 3), ipss_q2 = c(2, 4), ipss_q3 = c(3, 5),
  ipss_q4 = c(0, 2), ipss_q5 = c(4, 5), ipss_q6 = c(5, 3),
  ipss_q7 = c(2, 4), qol = c(3, 5)
)
score_ipss(d, qol = "qol", classify = TRUE)
```

Missing items are handled by the published rule for the instrument. The
IPSS has no published rule, so a missing item gives NA and asking for
proration is an error:

```{r, error = TRUE}
d_miss <- d
d_miss$ipss_q3[1] <- NA
score_ipss(d_miss, missing = "prorate")
```

UDI-6 does have a published rule (mean of answered items, at most two
missing), so it prorates by default with the published threshold:

```{r}
u <- data.frame(
  udi6_q1 = c(3, 0), udi6_q2 = c(3, 0), udi6_q3 = c(3, 3),
  udi6_q4 = c(3, 3), udi6_q5 = c(3, NA), udi6_q6 = c(NA, NA)
)
score_instrument(u, "udi6")
```

For responder analyses, look at the published statistics first, then pick
a threshold on purpose:

```{r}
mid_estimates("ipss")[, c("statistic", "value", "subgroup")]
responder(baseline = c(20, 12), followup = c(14, 11), "ipss", threshold = 3)
```