# Getting Started with piiR

## What is the Predictive Information Index (PII)?

The Predictive Information Index (PII) quantifies how much outcome-relevant information is retained when reducing a set of predictors (e.g., items) to a composite score.

One version of PII, the variance-based form, is defined as:

    \text{PII}_{v} = 1 - \frac{\text{Var}(\hat{Y}_{\text{Full}} - \hat{Y}_{\text{Score}})}{\text{Var}(\hat{Y}_{\text{Full}})}

Where: - \(\hat{Y}_{\text{Full}}\): predictions from a full model (e.g., all items or predictors) - \(\hat{Y}_{\text{Score}}\): predictions from a reduced score (e.g., mean or sum)

A PII of 1 means no predictive information was lost. A PII near 0 means the score loses most predictive information.

## Example: Using `pii()`

    library(piiR)

    # Simulate an outcome and two prediction vectors
    set.seed(123)
    y     <- rnorm(100)                        # observed outcome
    full  <- y + rnorm(100, sd = 0.3)          # full-model predictions
    score <- y + rnorm(100, sd = 0.5)          # score-based predictions

    # Compute the three PII variants
    pii(y, score, full, type = "r2")  # variance explained

    ## [1] 0.7248883

    pii(y, score, full, type = "rm")  # RMSE ratio

    ## [1] -1.690292

    pii(y, score, full, type = "v")   # variance ratio

    ## [1] 0.6619032