_pkgdown.yml

url: https://ntiGideon.github.io/ReproStat

# ---------------------------------------------------------------------------
# Open Graph / social card metadata
# ---------------------------------------------------------------------------
opengraph:
  twitter:
    card: summary_large_image

# ---------------------------------------------------------------------------
# Site template — Bootstrap 5 + bslib theming
# ---------------------------------------------------------------------------
template:
  bootstrap: 5
  bootswatch: flatly
  css: pkgdown/extra.css
  bslib:
    # Brand colours
    primary:        "#2C7FB8"   # steel blue  — buttons, links, active nav
    secondary:      "#1B9E77"   # forest green — accents
    success:        "#41AE76"   # muted green
    warning:        "#E07B39"   # amber
    danger:         "#C0392B"   # red
    info:           "#31B0D5"   # sky blue

    # Backgrounds & surface colours
    body-bg:        "#FFFFFF"
    body-color:     "#2d3748"
    light:          "#F4F7FA"
    dark:           "#1a202c"

    # Typography
    base_font:      {google: "Inter"}
    heading_font:   {google: "Inter"}
    code_font:      {google: "Fira Code"}
    font-size-base: "0.935rem"
    headings-color: "#1a202c"
    headings-font-weight: "600"

    # Links
    link-color:           "#2C7FB8"
    link-hover-color:     "#1a5a8a"
    link-decoration:      "none"
    link-hover-decoration: "underline"

    # Code
    code-color:  "#C0392B"
    code-bg:     "#F7F4F4"

    # Cards & borders
    border-radius:      "0.5rem"
    border-radius-lg:   "0.75rem"
    card-border-width:  "0"
    box-shadow:         "0 2px 8px rgba(0,0,0,0.07)"

    # Spacing
    spacer: "1.1rem"

  includes:
    in_header: |
      <meta name="description"
            content="ReproStat is an R package for reproducibility diagnostics
            in statistical modeling. Quantify coefficient, p-value, selection,
            and prediction stability under bootstrap, subsampling, and noise
            perturbations, and summarise results with a 0–100 Reproducibility
            Index." />
      <meta name="keywords"
            content="reproducibility, statistical modeling, R package, stability
            diagnostics, bootstrap, perturbation, reproducibility index,
            coefficient stability, model comparison" />
      <meta property="og:type"    content="website" />
      <meta property="og:title"   content="ReproStat — Reproducibility Diagnostics for R" />
      <meta property="og:description"
            content="Bootstrap, subsample, and noise-based stability diagnostics
            for statistical models in R. Includes a composite Reproducibility
            Index, CI estimation, repeated CV ranking stability, and four
            modelling backends." />
      <meta name="twitter:card"  content="summary" />
      <meta name="twitter:title" content="ReproStat — Reproducibility Diagnostics for R" />

# ---------------------------------------------------------------------------
# Home page
# ---------------------------------------------------------------------------
home:
  title: "ReproStat — Reproducibility Diagnostics for Statistical Modeling"
  description: >
    ReproStat answers a question standard model summaries leave open:
    *if the data changed a little, would the conclusion still hold?*
    It perturbs a dataset B times, refits the same model each time, and
    aggregates how much coefficient estimates, significance decisions,
    variable-selection patterns, and predictions move — producing a
    0–100 Reproducibility Index with bootstrap uncertainty intervals.
    Four modelling backends (lm, glm, rlm, glmnet) and repeated
    cross-validation ranking stability are supported out of the box.
  strip_header: false
  links:
    - text: "CRAN"
      href: https://cran.r-project.org/package=ReproStat
    - text: "GitHub"
      href: https://github.com/ntiGideon/ReproStat
    - text: "JSS article"
      href: https://github.com/ntiGideon/ReproStat
    - text: "Report a bug"
      href: https://github.com/ntiGideon/ReproStat/issues
  sidebar:
    structure: [links, license, citation, authors, dev]

# ---------------------------------------------------------------------------
# Navigation bar
# ---------------------------------------------------------------------------
navbar:
  bg: primary
  type: dark
  structure:
    left:  [intro, articles, reference, news]
    right: [search, github]
  components:
    intro:
      text: "Get Started"
      href: articles/ReproStat-intro.html
    articles:
      text: "Articles"
      menu:
        - text: "─── Foundations ───────────────"
        - text: "Introduction & Quick Start"
          href: articles/ReproStat-intro.html
        - text: "Interpreting ReproStat Outputs"
          href: articles/interpreting-reprostat.html
        - text: "─── Going Deeper ───────────────"
        - text: "Choosing a Modeling Backend"
          href: articles/backend-guide.html
        - text: "Practical Workflow Patterns"
          href: articles/workflow-patterns.html
    reference:
      text: "Reference"
      href: reference/index.html
    news:
      text: "Changelog"
      href: news/index.html
    github:
      icon: fa-github
      href: https://github.com/ntiGideon/ReproStat
      aria-label: "View source on GitHub"

# ---------------------------------------------------------------------------
# Articles (vignettes)
# ---------------------------------------------------------------------------
articles:
  - title: "Foundations"
    desc: >
      Start here if you are new to ReproStat. These articles explain what the
      package does, how to run your first analysis, and how to read the outputs
      it produces.
    contents:
      - ReproStat-intro
      - interpreting-reprostat
  - title: "Going Deeper"
    desc: >
      These articles cover modelling backend selection and practical patterns
      for incorporating reproducibility diagnostics into applied analysis
      workflows.
    contents:
      - backend-guide
      - workflow-patterns

# ---------------------------------------------------------------------------
# Reference (function documentation)
# ---------------------------------------------------------------------------
reference:
  # ── Overview ──────────────────────────────────────────────────────────────
  - title: "Package Overview"
    desc: >
      High-level entry point and the S3 class that all diagnostic functions
      operate on.  Start here if you are reading the reference for the first
      time.
    contents:
      - ReproStat-package
      - run_diagnostics
      - print.reprostat

  # ── Perturbation ──────────────────────────────────────────────────────────
  - title: "Data Perturbation"
    desc: >
      `perturb_data()` is the building block underneath `run_diagnostics()`.
      Use it directly when you need fine-grained control over how the data
      are perturbed — for example, to pass the perturbed datasets to an
      external modelling pipeline.

      Three strategies are available:

      - **Bootstrap** (`"bootstrap"`) — draws *n* rows with replacement,
        mimicking ordinary sampling variability.
      - **Subsampling** (`"subsample"`) — draws *m = ⌊ρn⌋* rows without
        replacement, stressing robustness to sample composition.
      - **Noise injection** (`"noise"`) — adds Gaussian noise scaled to each
        predictor's standard deviation, simulating measurement error.
    contents:
      - perturb_data

  # ── Stability metrics ─────────────────────────────────────────────────────
  - title: "Stability Metrics"
    desc: >
      Four complementary views of how model outputs move across perturbation
      runs.  Each function takes a `reprostat` object returned by
      `run_diagnostics()` and returns a numeric summary.

      | Function | Question answered | Unit |
      |---|---|---|
      | `coef_stability()` | How much do coefficient estimates vary? | variance (lower = more stable) |
      | `pvalue_stability()` | How often is each predictor significant? | frequency in [0, 1] |
      | `selection_stability()` | Do predictors keep the same direction/inclusion? | proportion in [0, 1] |
      | `prediction_stability()` | How much do predictions change? | variance (lower = more stable) |

      `pvalue_stability()` and `selection_stability()` measure *different*
      things: the former asks about the stability of a binary significance
      decision; the latter asks about the direction or inclusion pattern of each
      predictor.
    contents:
      - coef_stability
      - pvalue_stability
      - selection_stability
      - prediction_stability

  # ── Composite RI ──────────────────────────────────────────────────────────
  - title: "Reproducibility Index"
    desc: >
      The Reproducibility Index (RI) aggregates the four stability components
      into a single 0–100 score using a per-component normalisation and a
      simple average.  `ri_confidence_interval()` estimates uncertainty in
      that score by resampling the stored perturbation draws — no additional
      model fitting required.

      **RI quick-reference guide**

      | RI | Interpretation |
      |---|---|
      | 90–100 | Highly stable under the chosen perturbation design |
      | 70–89  | Moderately stable; overall pattern is dependable |
      | 50–69  | Mixed stability; inspect component breakdown |
      | < 50   | Low stability; results may be fragile |

      These are interpretive anchors, not universal cutoffs.  Always inspect
      the component decomposition alongside the aggregate score.
    contents:
      - reproducibility_index
      - ri_confidence_interval

  # ── Model comparison ──────────────────────────────────────────────────────
  - title: "Cross-Validation Ranking Stability"
    desc: >
      `cv_ranking_stability()` evaluates *model-selection* stability: given
      several candidate formulas, which one wins most consistently across
      repeated K-fold cross-validation?  It records each model's rank in every
      repeat and summarises the distribution of those ranks.

      Two summary statistics are particularly useful:

      - **`top1_frequency`** — proportion of repeats in which a model ranked
        first.  High values mean the model is a consistently strong choice.
      - **`mean_rank`** — average rank across all repeats (lower is better).
        It is possible for the model with the lowest mean error to *not* have
        the highest top-1 frequency.

      Supports the same four backends as `run_diagnostics()`.
    contents:
      - cv_ranking_stability
      - plot_cv_stability
      - plot_cv_stability_gg

  # ── Visualization ─────────────────────────────────────────────────────────
  - title: "Visualization"
    desc: >
      Two families of plotting helpers are provided.  The base-graphics
      functions (`plot_stability()`, `plot_cv_stability()`) have no external
      dependencies.  The **ggplot2** variants (`plot_stability_gg()`,
      `plot_cv_stability_gg()`) return `ggplot` objects that can be further
      customised with standard ggplot2 layers and themes.

      Both families are called for their side effects; the ggplot2 variants
      additionally return a `ggplot` object invisibly.
    contents:
      - plot_stability
      - plot_stability_gg

# ---------------------------------------------------------------------------
# Changelog (NEWS.md)
# ---------------------------------------------------------------------------
news:
  one_page: true
  cran_dates: true
  releases:
    - text: "ReproStat 0.1.1"
      href: https://github.com/ntiGideon/ReproStat/releases/tag/v0.1.1
    - text: "ReproStat 0.1.0"
      href: https://github.com/ntiGideon/ReproStat/releases/tag/v0.1.0

# ---------------------------------------------------------------------------
# Footer
# ---------------------------------------------------------------------------
footer:
  structure:
    left:  [package]
    right: [developed_by, built_with]
  components:
    package: >
      **ReproStat** is free software released under the
      [GPL (&ge;&nbsp;3)](https://www.gnu.org/licenses/gpl-3.0.html) licence.

# ---------------------------------------------------------------------------
# Authors
# ---------------------------------------------------------------------------
authors:
  "Gideon Nti Boateng":
    href: "mailto:gidiboateng200@gmail.com"

# ---------------------------------------------------------------------------
# Search
# ---------------------------------------------------------------------------
search:
  exclude: ["news/index.html"]