---
title: "Submission Confidence Index (SCI) Scoring"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Submission Confidence Index (SCI) Scoring}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

The `r4subscore` package computes the **Submission Confidence Index (SCI)**,
a composite 0-100 score summarising submission readiness across four pillars:
quality, trace, risk, and usability.

```{r load}
library(r4subscore)
```

## Default configuration

`sci_config_default()` returns the pillar weights and decision-band thresholds:

```{r config}
cfg <- sci_config_default()
cfg$pillar_weights
cfg$bands
```

The default weights are: quality 35%, trace 25%, risk 25%, usability 15%.

## Decision bands

| Band | SCI range | Meaning |
|------|-----------|---------|
| `ready` | 85-100 | Submission ready |
| `minor_gaps` | 70-84 | Minor gaps to address |
| `conditional` | 50-69 | Conditional — significant work needed |
| `high_risk` | 0-49 | High risk — submission not advised |

## Building example evidence

```{r evidence}
ev <- data.frame(
  run_id           = "run-001",
  study_id         = "STUDY01",
  asset_type       = "dataset",
  asset_id         = rep(c("ADSL", "ADAE"), each = 6),
  source_name      = "r4subcore",
  source_version   = "0.1.2",
  indicator_id     = paste0("X-00", 1:12),
  indicator_name   = paste0("Indicator ", 1:12),
  indicator_domain = rep(c("quality", "trace", "risk", "usability",
                           "quality", "trace"), 2),
  severity         = "info",
  result           = c("pass", "pass", "pass", "pass", "pass", "pass",
                       "warn", "pass", "fail", "pass", "pass", "warn"),
  metric_value     = c(1, 1, 1, 1, 1, 1, 0.8, 1, 0, 1, 1, 0.9),
  metric_unit      = "score",
  message          = paste0("Indicator ", 1:12, " result"),
  location         = rep(c("ADSL", "ADAE"), each = 6),
  evidence_payload = "{}",
  created_at       = Sys.time(),
  stringsAsFactors = FALSE
)
```

## Computing pillar scores

`compute_pillar_scores()` aggregates the mean metric value per domain:

```{r pillar-scores}
ps <- compute_pillar_scores(ev)
ps
```

## Computing the SCI

```{r sci}
result <- compute_sci(ps)
result$SCI
result$band
print(result)
```

## Detailed explanation

`sci_explain()` returns a breakdown showing each pillar's contribution to
the final SCI and any score loss:

```{r explain}
expl <- sci_explain(ev)
expl$pillar_contributions
```

## Sensitivity analysis

`sci_sensitivity_analysis()` evaluates the SCI across a grid of alternative
pillar weights, useful for understanding how robust the score is to weighting
choices:

```{r sensitivity}
grid <- data.frame(
  quality    = c(0.35, 0.50, 0.25),
  trace      = c(0.25, 0.20, 0.30),
  risk       = c(0.25, 0.20, 0.25),
  usability  = c(0.15, 0.10, 0.20)
)

sa <- sci_sensitivity_analysis(ev, weight_grid = grid)
sa
```

## Custom weights

Pass a custom config to favour particular pillars:

```{r custom-weights}
cfg_custom <- sci_config_default(
  pillar_weights = c(quality = 0.50, trace = 0.20,
                     risk = 0.20, usability = 0.10)
)
ps2   <- compute_pillar_scores(ev, config = cfg_custom)
sci2  <- compute_sci(ps2, config = cfg_custom)
sci2$SCI
sci2$band
```