---

name: uncertainty-advanced description: "Route advanced Chemprop workflows for uncertainty estimation, calibration, conformal evaluation, Ray Tune hpopt, model conversion, transfer/foundation starts, and interpretation planning." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

Chemprop Uncertainty and Advanced Workflows

Use this sub-skill when the user needs Chemprop 2.2.x uncertainty outputs or advanced workflow routing around chemprop predict, chemprop hpopt, chemprop convert, transfer/foundation starts, or interpretation. Keep basic chemprop train command construction in training-cli, prediction mechanics in prediction-fingerprints, and Python model internals in python-api-modeling.

Route Here For

• Selecting --uncertainty-method, --calibration-method, and --evaluation-methods for prediction-time uncertainty.
• Checking compatibility between uncertainty estimators and training task types such as regression-mve, regression-evidential, regression-quantile, classification-dirichlet, and multiclass-dirichlet.
• Designing calibration datasets and matching calibration feature side files to test/prediction inputs.
• Adding conformal prediction coverage checks for regression, multilabel classification, or multiclass classification.
• Planning Ray Tune hyperparameter optimization with chemprop hpopt and optional dependency caveats.
• Converting older model artifacts with chemprop convert, then routing converted models into prediction with the correct featurizer mode.
• Triaging transfer learning, foundation initialization, and interpretation workflows when they affect advanced Chemprop routing.

Route Elsewhere

• Ordinary chemprop train commands, task/loss/metric basics, split handling, ensembles, replicates, and output layout: use ../training-cli/SKILL.md.
• Plain chemprop predict or chemprop fingerprint command mechanics, output suffixes, model path discovery, and fingerprint layer selection: use ../prediction-fingerprints/SKILL.md.
• Programmatic construction of Chemprop datasets, MPNN modules, predictors, metrics, or Lightning loops: use ../python-api-modeling/SKILL.md.
• Deep schema design for reaction, multicomponent, atom/bond, constraint, or descriptor inputs: use the data and specialized task sub-skills when present.

Fast Uncertainty Patterns

Regression MVE with calibration and evaluation:

chemprop predict \
  --test-path test.csv \
  --model-path runs/mve/model_0/best.pt \
  --output test_mve_unc.csv \
  --uncertainty-method mve \
  --cal-path calibration.csv \
  --calibration-method zscaling \
  --evaluation-methods nll-regression miscalibration_area ence spearman

Ensemble variance from multiple model files:

chemprop predict \
  --test-path test.csv \
  --model-paths runs/ensemble/model_0/best.pt runs/ensemble/model_1/best.pt \
  --output ensemble_unc.csv \
  --uncertainty-method ensemble

Quantile conformal regression:

chemprop predict \
  --test-path test_with_targets.csv \
  --model-path runs/quantile/model_0/best.pt \
  --output conformal_intervals.csv \
  --uncertainty-method quantile-regression \
  --cal-path calibration.csv \
  --calibration-method conformal-regression \
  --conformal-alpha 0.1 \
  --evaluation-methods conformal-coverage-regression

Required Reading

• references/uncertainty.md: estimator, calibrator, evaluator aliases; compatibility rules; output interpretation; calibration feature alignment.
• references/hyperparameter-optimization.md: chemprop hpopt command design, Ray Tune controls, search-space pruning, and optional dependency failures.
• references/conversion-transfer-interpretation.md: chemprop convert, v1 featurizer requirements, transfer/foundation routing, and interpretation triage.
• references/troubleshooting.md: fixes for missing hpopt dependencies, calibration mismatches, evaluator target requirements, method/task incompatibility, conformal alpha, conversion, and foundation model issues.
• scripts/chemprop_uncertainty_args.py: self-contained planner that validates common uncertainty/hpopt/convert flag combinations without importing Chemprop.

Decision Checklist

1. Identify the trained model family before choosing uncertainty flags: plain regression/classification, MVE, evidential, quantile, Dirichlet, dropout, or ensemble.
2. Decide whether uncertainty is raw, calibrated, or conformalized; calibration requires --cal-path plus matching parsing and feature flags for calibration data.
3. Add --evaluation-methods only when the prediction/test CSV includes target labels that match model output columns.
4. For ensemble, pass at least two model artifacts; for dropout, choose --uncertainty-dropout-p and --dropout-sampling-size deliberately.
5. Use hpopt for training hyperparameter search, then apply the generated best_config.toml in a later chemprop train run.
6. Use chemprop convert before inference only for older model artifact formats; v1-to-v2 converted models need v1 atom featurization at prediction time.
7. When foundation or transfer initialization is part of the plan, confirm checkpoint/foundation exclusivity and freeze semantics before adding hpopt or uncertainty layers.

Evidence Base

This sub-skill distills Chemprop 2.2.3 behavior from the uncertainty estimator/calibrator/evaluator registries, prediction-time uncertainty CLI implementation, hpopt and convert CLI implementations, public hpopt/convert tutorials, uncertainty and hpopt notebook recipes, transfer/foundation examples, interpretation examples, and unit tests for uncertainty utilities and conversion. Runtime content is self-contained and does not require reopening repository docs, examples, or tests.