NEWS.md

In BORG: Bounded Outcome Risk Guard for Model Evaluation

BORG 0.2.3

Native R Integration

This release replaces custom functions with standard R S3 methods for a more idiomatic interface.

S3 methods for plotting

• plot(BorgRisk): Visualize risk assessment results
• plot(borg_result): Visualize CV fold splits
• plot(borg_comparison): Compare random vs blocked CV results

S3 methods for summaries

• summary(BorgDiagnosis): Generate methods section text for publications
• summary(BorgRisk): Summarize detected risks
• summary(borg_result): Generate methods text from borg() output
• summary(borg_comparison): Detailed comparison summary

Dedicated export functions

• borg_certificate(): Create structured validation certificate
• borg_export(): Write certificate to YAML/JSON file

Removed

• borg_plot() - use plot() instead
• borg_report() - use summary(), borg_certificate(), or borg_export()
• Legacy plot functions (plot_split, plot_risk, etc.)
• Legacy report functions (borg_methods_text)

BORG 0.2.2

New features

Framework wrappers

BORG-guarded versions of common CV functions that block random CV when dependencies detected:

• borg_vfold_cv(): Wraps rsample::vfold_cv() with dependency checking
• Blocks random CV when spatial/temporal/clustered dependencies detected
• auto_block = TRUE automatically switches to appropriate blocked CV

• allow_override = TRUE allows proceeding with warning

• borg_group_vfold_cv(): Wraps rsample::group_vfold_cv() with additional checks

• Warns about dependencies not handled by grouping alone

• borg_initial_split(): Wraps rsample::initial_split()

• Enforces chronological splits when time specified

• Warns about spatial dependencies

• borg_trainControl(): Wraps caret::trainControl()

• Blocks random resampling methods with detected dependencies

Hook system (experimental)

• borg_register_hooks(): Register validation hooks on framework functions
• borg_unregister_hooks(): Remove registered hooks

BORG 0.2.1

New features

Empirical CV comparison

• borg_compare_cv(): Run random vs blocked CV on the same data to empirically demonstrate metric inflation
• Supports spatial, temporal, and clustered data
• Custom model and predict functions
• Multiple metrics: RMSE, MAE, R², AUC, accuracy
• Paired t-test for statistical significance
• Plot methods: boxplot, density, paired comparison

Publication-ready reporting

• borg_methods_text(): Generate copy-paste methods section text for manuscripts
• Includes dependency diagnosis details
• Cites quantitative metrics (Moran's I, ICC, etc.)
• Optional empirical comparison results

• BORG package citation

• borg_certificate(): Create structured validation certificates

• Machine-readable format
• Includes data characteristics, diagnosis, and inflation estimates

• Timestamps and version tracking

• borg_export(): Export certificates to YAML or JSON format

API improvements

• Unified borg() entry point with two modes:

• Diagnosis mode: borg(data, coords=, time=, groups=) returns diagnosis + CV folds

• Validation mode: borg(data, train_idx=, test_idx=) validates existing splits

• Renamed parameters for consistency: temporal_col → time, group_col → groups, spatial_cols → coords

BORG 0.2.0

Major changes: From Validator to Enforcer

BORG now detects data dependency structure and enforces appropriate cross-validation strategies. Random CV is blocked when dependencies are detected.

Dependency diagnosis

• borg_diagnose(): Automatically detects data dependency structure
• Spatial autocorrelation: Moran's I test, variogram-based range estimation
• Temporal autocorrelation: ACF/Ljung-Box test, decorrelation lag detection
• Clustered structure: ICC computation, design effect estimation
• Returns severity assessment and recommended CV strategy

• Estimates metric inflation from using random CV

• BorgDiagnosis S4 class: Structured diagnosis results with slots for:

• dependency_type: "none", "spatial", "temporal", "clustered", "mixed"
• severity: "none", "moderate", "severe"
• recommended_cv: appropriate CV strategy
• inflation_estimate: estimated AUC/RMSE bias from random CV

Enforced CV generation

• borg_cv(): Generates valid CV schemes based on diagnosis

• Spatial blocking: k-means clustering with block size > autocorrelation range

• Temporal blocking: chronological splits with embargo periods

• Group CV: leave-group-out with balanced fold assignment
• Mixed strategies: spatial-temporal, spatial-group, temporal-group
• Random CV disabled when dependencies detected (requires explicit allow_random = TRUE)
• Output formats: list, rsample, caret, mlr3

New features

Visualization functions

• plot_split(): Visualize train/test split distribution with temporal or group structure
• plot_risk(): Display risk assessment results as horizontal bar chart
• plot_temporal(): Timeline visualization with gap analysis and look-ahead detection
• plot_spatial(): Spatial split visualization with convex hulls
• plot_groups(): Group-based split visualization with leakage highlighting

Model inspection

• Extended borg_inspect() to support fitted model objects:
• lm and glm models (checks data used in fitting)
• ranger random forest models
• xgboost models
• lightgbm models
• parsnip model fits
• workflow objects (tidymodels)

Audit functions

• audit_predictions(): Validate prediction vectors against expected indices
• cv_leakage_report(): Generate detailed cross-validation leakage reports
• audit_importance(): Detect feature importance computed on test data (SHAP, permutation)

Tidymodels integration

• Added tune_results inspection for tidymodels tuning objects
• Detects when hyperparameter tuning uses test data in resamples

Configuration

• Added borg_auto_check() to enable/disable automatic validation
• Added borg_options() to query current configuration
• New options: borg.auto_check, borg.strict, borg.verbose

Bug fixes

• Fixed rsample vfold_cv inspection for attribute structure changes

BORG 0.1.0

Initial release.

Core functionality

• borg_guard(): Creates a validation context for train/test splits with support for temporal, spatial, and grouped structures
• borg_validate(): Comprehensive workflow validation including:
• Index overlap detection
• Duplicate row detection
• Target leakage detection (suspicious naming, perfect separation)
• Feature engineering leakage (global standardization, rank features)
• Threshold selection leakage
• Spatial autocorrelation checks
• HPO validation checks (test data usage, non-nested CV)
• borg_inspect(): Inspects preprocessing objects for data leakage:
• caret preProcess objects
• caret trainControl objects

• tidymodels recipe objects

• prcomp PCA objects

• rsample resampling objects
• borg_assimilate(): Assimilates leaky pipelines into compliance (auto-fix)
• BorgRisk S4 class for structured risk assessment reports

Performance

• C++ backends via Rcpp for fast hash-based index overlap and duplicate detection

Framework integration

• caret: preProcess, trainControl, train objects
• tidymodels: recipe, rsplit, vfold_cv, rset objects
• mlr3: task and resampling validation
• Base R: manual index-based splits

BORG documentation built on March 20, 2026, 5:09 p.m.