Examples¶

← User Guide | Reports →

This section contains practical examples of using torchregress for various regression tasks. The examples are designed to demonstrate key features and use cases of the library.

Start Here (Task-First)¶

If you are choosing a method for a hard regression problem (outliers, multimodal targets, calibration, OOD robustness, noisy features, imbalance), start with the Task-First Method Selection Matrix and then come back to this page for runnable examples. For budget/latency/coverage constraints, use Choosing Methods by Constraint before selecting an example. Use the Comparative Evidence Matrix to see which hard tasks currently have decision-grade comparisons vs demo-only examples.

Getting Started¶

New to torchregress? Start with the Concepts Guide to learn key concepts, then use the Task-First Method Selection Matrix to pick a method family.

Example Reading Guide (Audit Priority)¶

Use the comparison examples first when making implementation decisions:

• examples/comprehensive_comparison.py: robust losses + uncertainty + ensemble behavior on multiple scenarios
• examples/loss_comparison.py --suite comprehensive: controlled robust-loss comparisons
• examples/imbalanced_regression.py: tail performance vs calibration tradeoffs
• examples/conformal_regression_example.py --mode sweep: coverage vs interval width tradeoffs
• examples/ood_selective_prediction_comparison.py: OOD vs selective-prediction tradeoffs (AURC, rejection policy, OOD gap) across a deep ensemble, heteroscedastic ensemble, MC dropout, SWAG, and BNN; --dataset diabetes runs a real-data covariate-shift split
• examples/eiv_method_comparison.py: EIV method tradeoffs (analytic/MC/ODR/ensemble variants); --dataset diabetes runs on Diabetes with synthetic measurement-error injection
• examples/multimodal_method_comparison.py: Gaussian vs MDN vs optional flow on multimodal multi-target data; --dataset diabetes uses real Diabetes features + synthetic multimodal targets
• examples/contrastive_flow_parameter_estimation.py --mode compare: shared-budget synthetic comparison for Gaussian summary density vs plain flow vs contrastive flow vs NRE vs NPE
• examples/noisy_label_comparison.py: robust + probabilistic methods under label corruption with calibration metrics (--dataset synthetic|diabetes)
• examples/ordinal_regression_comparison.py: ordered-target comparison (OrdinalCrossEntropy, CumulativeLink); --dataset diabetes uses train-quantile binning of Diabetes targets
• examples/ordinal_uncertain_ground_truth_comparison.py: ordered-bin ambiguous-label comparison with soft plausibility targets and soft pseudo labels
• examples/censored_regression_comparison.py: censored/interval-censored comparison (CensoredGaussianNLL, CensoredQuantile, AFT); --dataset diabetes runs on Diabetes with shared synthetic censoring overlays
• examples/constraints_calibration_comparison.py: constrained heads + post-hoc calibration transforms comparison
• examples/transformed_target_regression_comparison.py: skewed-target transform comparison (MSE, LogTransform, BoxCox, Sqrt)
• examples/semi_supervised_regression_comparison.py: masked-label semi-supervised regression with pseudo labels and teacher consistency
• examples/ppi_calibrated_mean.py: raw vs affinely calibrated prediction-powered mean inference (arXiv:2604.21260)
• examples/ppi_mean_plus_split_conformal.py: PPI-style mean inference plus SplitConformal predictive bands with a labeled split (see docs/methods/inference.md)
• examples/uncertain_gt_density_conformal_comparison.py: uncertain-label losses + density/prevalence/MC conformal comparison (--dataset synthetic|diabetes)
• examples/causal_dr_uplift_comparison.py: doubly-robust ATE/CATE comparison with overlap diagnostics; --dataset diabetes uses real Diabetes covariates
• External comparison guide: MAPIE, crepes, torchcp, BoTorch and scikit-learn comparisons, run in torchregress-harness.
• examples/normalizing_flows_multitarget.py: multi-target multimodal modeling (single-method deep dive)
• examples/contrastive_flow_parameter_estimation.py --mode demo: nuisance-aware parameter scans with ContrastiveFlowLoss

When comparing methods, prefer examples that document:

• fixed seeds / shared splits
• comparable training budgets
• common metrics (accuracy, calibration, runtime)
• explicit failure modes / caveats

Basic Examples¶

Basic Usage¶

This tutorial covers the fundamental usage patterns of torchregress:

• Setting up simple regression models
• Choosing and applying loss functions
• Evaluating models with appropriate metrics
• Basic visualization of results

import torch
import torchregress as tr

# Example of basic torchregress usage
X_train, y_train = load_data()
model = MyRegressionModel()
loss_fn = tr.losses.WeightedHuberLoss()

# Train model
# ...

# Evaluate
predictions = model(X_test)
rmse = tr.metrics.rmse(predictions, y_test)

Loss Comparison¶

This example compares different loss functions on the same dataset (examples/loss_comparison.py; --suite basic for a linear model with seven losses, --suite comprehensive for an MLP with ten losses and point/CRPS/ECE metrics):

• Comparing traditional vs. robust losses
• Analyzing how different losses handle outliers
• Visualizing the effect of loss choice on predictions
• Determining which loss is best for different data characteristics

import torchregress as tr

# Dictionary of loss functions to compare
losses = {
    "MSE": tr.losses.WeightedMSELoss(),
    "MAE": tr.losses.WeightedL1Loss(),
    "Huber": tr.losses.WeightedHuberLoss(),
    "Barron": tr.losses.BarronLoss(alpha=1.0, scale=1.0),
    "LogCosh": tr.losses.LogCoshLoss(),
}

# Compare losses and visualize results
# ...

Comprehensive Comparison 🆕¶

All-in-one comparison demonstrating the three main capabilities of torchregress:

• Robust Regression - Handling outliers (MSE vs. Huber vs. Cauchy)
• Uncertainty Estimation - Quantifying confidence (Gaussian NLL, ensembles)
• Ensemble Methods - Combining models (Deep Ensemble, Heteroscedastic Ensemble)

Three challenging scenarios: 1. Clean data (baseline comparison) 2. Data with outliers (robust losses) 3. Heteroscedastic data (uncertainty decomposition)

# Compare robust losses on outlier data
losses = {
    "MSE": WeightedMSELoss(),      # Sensitive to outliers
    "Huber": WeightedHuberLoss(delta=1.0),  # Balanced
    "Barron": BarronLoss(alpha=1.0, scale=1.0),  # Smooth adaptive family
    "Cauchy": CauchyLoss(scale=0.5) # Very robust
}

Advanced Examples¶

OT shift conformal demo¶

• Synthetic calibration vs shifted target scores; prints CDF-gap diagnostic, weighted split-conformal threshold, and mean prediction-set size on random candidate score matrices.
• Script: examples/ot_shift_conformal_demo.py.

Bayesian linear head (test-time) demo¶

• --mode exactness: synthetic linear targets on fixed features; compares batch BayesianLinearHead.fit to two-step RecursiveBayesianHead.partial_fit with forgetting_factor=1, reports posterior error vs a known weight vector, and prints rough held-out Gaussian interval coverage.
• --mode adapter: thin SupportsPredictiveBatch wrapper exposing predict_distribution(...) around BayesianLinearHead.predictive_batch; prints PredictiveBatch diagnostics.
• Script: examples/test_time_bayesian_linear_head_demo.py.

Gaussian Wasserstein bound demo¶

• --mode loss: one-step mean + full-covariance supervision with GaussianWassersteinBoundLoss; prints loss and gradient norms.
• --mode hybrid: tiny scalar head; neighbourhood covariance pseudo-labels + diagonal Wasserstein-bound pretrain, then Gaussian NLL fine-tune; prints NLL before/after the second phase.
• Script: examples/gaussian_wasserstein_bound_demo.py.

Beta-NLL heteroscedastic demo¶

• Small Gaussian-head MLP on synthetic heteroscedastic noise (scale grows with \(|x|\)).
• Trains with GaussianNLLLoss vs BetaNLLLoss from the same initial weights; reports validation RMSE and validation Gaussian NLL.
• Script: examples/heteroscedastic_beta_nll_demo.py.

Ensemble Methods 🆕¶

Complete guide to uncertainty quantification with ensembles:

• Deep Ensemble - Epistemic uncertainty from model disagreement
• Heteroscedastic Ensemble - Both epistemic and aleatoric uncertainty
• Batch Ensemble - Efficient alternative for limited compute
• Uncertainty Decomposition - Separating model vs. data uncertainty

Includes decision trees, comparison tables, and complete working example (ensemble_tutorial.py).

# Train a heteroscedastic ensemble (n_models members), then decompose
ensemble_models = train_heteroscedastic_ensemble(n_models=5)
epistemic, aleatoric = ensemble_variance_decomposition(means, log_vars)

→ See uncertainty_decomposition and Ensemble API.

Ordinal Regression Comparison¶

• Shared-budget comparison on a synthetic latent-score task or (--dataset diabetes) real Diabetes covariates/targets with train-quantile binning.
• Compares class-logit cross-entropy against the cumulative-link objective.
• Reports ordinal accuracy, class-index MAE, QWK, and runtime.

Ordinal Uncertain Ground Truth Comparison¶

• Ordered-bin regression-as-classification comparison for ambiguous labels represented as soft class probabilities.
• Compares hard sampled labels, soft plausibility targets, soft pseudo labels, and a cumulative-link soft-target variant.
• Reports ordinal accuracy, class-index MAE, QWK, true-class NLL, plausibility cross-entropy, pseudo-label acceptance, and runtime.

Censored Regression Comparison¶

• Shared-budget comparison for right/left and interval-censored targets.
• Compares Gaussian NLL, quantile, and AFT censored losses.
• Reports true-target MAE, observed MAE, concordance index, censoring rate, and runtime.
• --dataset diabetes runs the same comparison on real Diabetes covariates/targets with synthetic censoring overlays.

Constraints + Calibration Comparison¶

• Demonstrates output-head constraints and post-hoc calibration transforms in one workflow.
• Compares raw outputs against calibrated + constrained outputs.
• Reports MAE, NLL, PIT chi-square, crossing-rate, bound-violation, and runtime.

Transformed-Target Regression Comparison¶

• Shared-budget benchmark for skewed positive targets with multiplicative noise.
• Compares MSE against LogTransformLoss, BoxCoxTransformLoss, and SqrtTransformLoss.
• Reports MSE, MAE, R2, MAPE, upper-tail MAE, and runtime.

Semi-Supervised Regression Comparison¶

• Real-data proxy benchmark on Diabetes with train-label masking.
• Compares SupervisedMSE, PseudoLabelConsistencyLoss, and PseudoLabelNLL.
• Reports MSE, MAE, R2, pseudo-label acceptance/confidence, and runtime.

Uncertain-GT + Density Conformal Comparison¶

• Shared-budget comparison for uncertain ground-truth supervision and density-aware conformal intervals.
• Compares SplitConformal, DensityConformal, PrevalenceAdjustedCP, and MonteCarloConformal.
• Reports coverage/width plus uncertain-GT objective values (NoisyTargetNLL, ConsistencyLoss, PseudoLabelNLL).
• --dataset diabetes runs the same comparison on real Diabetes covariates/targets with feature-dependent annotation noise and a fitted MLP predictor.

Causal DR Uplift Comparison¶

• Shared-budget comparison for doubly-robust causal regression (dr_ate, dr_cate).
• Includes synthetic uplift and selection-bias scenarios.
• --dataset diabetes uses Diabetes features/baseline outcomes with confounded treatment assignment and known effect construction.
• Reports ATE error, CI quality, overlap-rate, and effective sample size diagnostics.

Conformal Regression¶

• Using conformal prediction to obtain prediction intervals with guaranteed coverage (SplitConformal, CQR).
• --mode tour walks through every predictor, --mode sweep compares coverage-vs-width tradeoffs across \(\alpha\), and --mode mondrian shows group-conditional (Mondrian) calibration.

Count and Zero-Inflated Regression¶

• examples/count_regression_demo.py --family poisson: Poisson deviance, likelihood ratio, zero-inflated Poisson and negative binomial losses on ZIP count data.
• --family tweedie: TweedieLoss and CompoundPoissonLoss on compound Poisson-Gamma (zero-inflated continuous) data.

Evidential Regression¶

• Decomposing uncertainty into aleatoric and epistemic components (EvidentialRegressionLoss).

Imbalanced Regression¶

• Handling imbalanced datasets in regression tasks.

Balanced MSE / Bin-Reweighted MSE¶

• Skewed targets: BalancedMSELoss and BinReweightedMSELoss vs plain MSE; script examples/balanced_mse_demo.py.
• Includes calibration-validation guidance because aggressive reweighting can distort uncertainty.

Noisy Labels Regression¶

• Training models on data with noisy labels.

Noisy Label Comparison¶

• Shared-budget comparison of robust/probabilistic methods under label corruption.
• Includes split-conformal coverage/width metrics plus native interval metrics for Gaussian/quantile heads.
• --dataset diabetes runs it on the Diabetes dataset with synthetic label corruption for real-data evidence breadth.

Normalizing Flows¶

• Using normalizing flows for multi-target regression.
• Multi-target/multimodal demo; compare with Gaussian and MDN baselines separately for decision-grade selection.

Multimodal Method Comparison¶

• Shared-budget comparison of GaussianNLL, MDN, and optional flow models on multimodal multi-target data.
• Includes common point metrics, NLL, calibration error, energy score, and runtime.
• --dataset diabetes runs on Diabetes features with synthetic multimodal multi-target outputs, adding real-covariate evidence breadth.

OOD / Selective Prediction Comparison¶

• Shared-budget comparison of uncertainty methods for risk-coverage and OOD signal behavior.
• Includes AURC, rejection-policy risk/coverage, split-conformal interval metrics, and OOD uncertainty-gap summaries.
• --dataset diabetes runs it on Diabetes with a deterministic covariate-shift OOD split for real-data evidence breadth.

EIV Method Comparison¶

• Shared-budget comparison of EIV variants (FunctionalEIV, StructuralEIV, ODR, EnsembleEIV).
• Includes clean-vs-observed test MSE and runtime tradeoffs.
• --dataset diabetes runs on Diabetes with synthetic feature/label measurement error, adding real-data evidence breadth.

Running the Examples¶

All examples can be run directly from the repository:

# Clone the repository
git clone https://github.com/astroai/torchregress.git
cd torchregress

# Install dependencies (dev + all extras)
pixi install

# Run a specific example
pixi run python examples/basic_usage.py

For questions or issues with the examples, please open an issue in the repository.