r4subscore: Submission Confidence Index Engine

Description

Converts standardized R4SUB (R for Regulatory Submission) evidence into indicator scores, pillar scores, and a Submission Confidence Index (SCI). Provides sensitivity analysis, explainability tables, and decision band classification to answer the question: are we ready for regulatory submission.

Author(s)

Maintainer: Pawan Rama Mali prm@outlook.in [copyright holder]

See Also

Useful links:

• https://github.com/R4SUB/r4subscore

• Report bugs at https://github.com/R4SUB/r4subscore/issues

Classify SCI Value into Decision Band

Description

Classify SCI Value into Decision Band

Usage

classify_band(sci_value, bands = sci_config_default()$bands)

Arguments

Value

Character band name.

Examples

classify_band(92)
classify_band(55)

Compute Indicator-Level Scores

Description

Converts each indicator in an evidence table into a numeric score (0–1) using severity-weighted result scoring.

Usage

compute_indicator_scores(evidence)

Arguments

Details

For each evidence row:

• result_score = r4subcore::result_to_score(result) (pass=1, warn=0.5, fail=0)

• severity_weight = r4subcore::severity_to_weight(severity) (info=0, ..., critical=1)

• weighted_score = result_score * (1 - severity_weight)

Rows are grouped by indicator_id and indicator_domain, and the indicator score is the mean of weighted_score within each group.

Value

A tibble with columns: indicator_id, indicator_name, indicator_domain, n_evidence, indicator_score.

Examples

ctx <- r4subcore::r4sub_run_context(study_id = "STUDY01")
ev <- r4subcore::as_evidence(
  data.frame(
    asset_type = "dataset", asset_id = "ADSL",
    source_name = "test", source_version = "1.0",
    indicator_id = "Q-001", indicator_name = "Test",
    indicator_domain = "quality", severity = "high",
    result = "fail", metric_value = 1, metric_unit = "n",
    message = "Example finding", location = "ADSL",
    evidence_payload = "{}", stringsAsFactors = FALSE
  ), ctx = ctx
)
scores <- compute_indicator_scores(ev)
scores

Compute Pillar Scores

Description

Aggregates indicator scores into pillar-level scores (one per domain). Each pillar score is the mean of its indicator scores.

Usage

compute_pillar_scores(evidence, config = sci_config_default())

Arguments

Value

A tibble with columns: pillar, pillar_score, n_indicators, weight.

Examples

ctx <- r4subcore::r4sub_run_context(study_id = "STUDY01")
ev <- r4subcore::as_evidence(
  data.frame(
    asset_type = "dataset", asset_id = "ADSL",
    source_name = "test", source_version = "1.0",
    indicator_id = "Q-001", indicator_name = "Test",
    indicator_domain = "quality", severity = "high",
    result = "fail", metric_value = 1, metric_unit = "n",
    message = "Example finding", location = "ADSL",
    evidence_payload = "{}", stringsAsFactors = FALSE
  ), ctx = ctx
)
ps <- compute_pillar_scores(ev)
ps

Compute Submission Confidence Index (SCI)

Description

Computes the SCI from pillar scores as a weighted sum scaled to 0–100, with decision band classification.

Usage

compute_sci(pillar_scores, config = sci_config_default())

Arguments

Details

The SCI is computed as:

SCI = round(sum(pillar_score * weight) * 100, 1)

Pillars with NA scores are excluded from both the numerator and the weight normalization denominator.

Value

A list of class "sci_result" with:

• SCI: numeric 0–100

• band: character band classification

• pillar_scores: the input pillar scores tibble

• weights_used: named numeric vector of effective weights

Examples

ctx <- r4subcore::r4sub_run_context(study_id = "STUDY01")
ev <- r4subcore::as_evidence(
  data.frame(
    asset_type = "dataset", asset_id = "ADSL",
    source_name = "test", source_version = "1.0",
    indicator_id = "Q-001", indicator_name = "Test",
    indicator_domain = "quality", severity = "high",
    result = "fail", metric_value = 1, metric_unit = "n",
    message = "Example finding", location = "ADSL",
    evidence_payload = "{}", stringsAsFactors = FALSE
  ), ctx = ctx
)
ps <- compute_pillar_scores(ev)
result <- compute_sci(ps)
result$SCI
result$band

Print SCI Result

Description

Print SCI Result

Usage

## S3 method for class 'sci_result'
print(x, ...)

Arguments

Value

Invisibly returns x. Called for its side effect of printing the Submission Confidence Index value, decision band, and per-pillar score breakdown (with weights) to the console.

Default SCI Configuration

Description

Returns a configuration list with default pillar weights, decision bands, and scoring parameters for the Submission Confidence Index.

Usage

sci_config_default(
  pillar_weights = c(quality = 0.35, trace = 0.25, risk = 0.25, usability = 0.15),
  bands = list(ready = c(85, 100), minor_gaps = c(70, 84), conditional = c(50, 69),
    high_risk = c(0, 49))
)

Arguments

Value

A list of class "sci_config" with elements: pillar_weights, bands.

Examples

cfg <- sci_config_default()
cfg$pillar_weights
cfg$bands

# Custom weights (must sum to 1)
sci_config_default(
  pillar_weights = c(quality = 0.40, trace = 0.20, risk = 0.30, usability = 0.10)
)

Explain SCI Contributors

Description

Identifies which indicators contribute most to SCI loss and provides a breakdown of pillar contributions.

Usage

sci_explain(evidence, config = sci_config_default())

Arguments

Details

For each indicator, the contribution to SCI loss is:

loss = pillar_weight * (1 - indicator_score) / n_indicators_in_pillar

This gives a sense of how much each indicator drags the SCI down. Results are sorted by loss descending (worst contributors first).

Value

A list with:

• indicator_contributions: tibble of per-indicator loss contributions

• pillar_contributions: tibble of per-pillar contributions to SCI

Examples

ctx <- r4subcore::r4sub_run_context(study_id = "STUDY01")
ev <- r4subcore::as_evidence(
  data.frame(
    asset_type = "dataset", asset_id = "ADSL",
    source_name = "test", source_version = "1.0",
    indicator_id = "Q-001", indicator_name = "Test",
    indicator_domain = "quality", severity = "high",
    result = "fail", metric_value = 1, metric_unit = "n",
    message = "Example finding", location = "ADSL",
    evidence_payload = "{}", stringsAsFactors = FALSE
  ), ctx = ctx
)
expl <- sci_explain(ev)
expl$indicator_contributions
expl$pillar_contributions

SCI Sensitivity Analysis

Description

Evaluates the stability of the Submission Confidence Index under alternative pillar weight scenarios.

Usage

sci_sensitivity_analysis(evidence, weight_grid)

Arguments

Value

A tibble with one row per scenario, containing: scenario (row number), the weight columns, SCI, and band.

Examples

ctx <- r4subcore::r4sub_run_context(study_id = "STUDY01")
ev <- r4subcore::as_evidence(
  data.frame(
    asset_type = "dataset", asset_id = "ADSL",
    source_name = "test", source_version = "1.0",
    indicator_id = "Q-001", indicator_name = "Test",
    indicator_domain = "quality", severity = "high",
    result = "fail", metric_value = 1, metric_unit = "n",
    message = "Example finding", location = "ADSL",
    evidence_payload = "{}", stringsAsFactors = FALSE
  ), ctx = ctx
)
grid <- data.frame(
  quality   = c(0.4, 0.3, 0.25),
  trace     = c(0.2, 0.3, 0.25),
  risk      = c(0.3, 0.2, 0.25),
  usability = c(0.1, 0.2, 0.25)
)
sci_sensitivity_analysis(ev, grid)