---

name: prediction-fingerprints description: "Run Chemprop prediction and fingerprint workflows from trained model artifacts, including model-path handling, output formats, ensembles, and fingerprint layer choices." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

Chemprop Prediction and Fingerprints

Use this sub-skill when an agent needs to run trained Chemprop model artifacts with chemprop predict or extract learned encodings with chemprop fingerprint. Keep prediction-time command construction, model path discovery, output naming, ensemble individual outputs, fingerprint layer choice, and inference artifact interpretation here.

When to Use

Use this sub-skill for:

• Building chemprop predict commands for CSV inputs and .pt or .ckpt model artifacts.
• Building chemprop fingerprint commands for learned model representations.
• Choosing legal prediction outputs (.csv, .pkl) or fingerprint outputs (.csv, .npz).
• Supplying one model, multiple model files, or directories of model files.
• Understanding averaged ensemble outputs and per-model individual output files.
• Reusing training-time parsing and featurization flags during prediction or fingerprint export.
• Diagnosing model path, output suffix, featurizer, reaction, multicomponent, and checkpoint loading failures.

Route elsewhere when the task is:

• Training, split selection, checkpoint creation, or training output layout: use training-cli.
• Input schema design, descriptors, atom/bond features, or NPZ side-file alignment: use the data-featurization sub-skill if present.
• Uncertainty method selection, calibration design, conformal interpretation, or calibration feature alignment: use uncertainty-advanced.
• Model conversion before inference: use uncertainty-advanced for conversion and compatibility decisions.
• Custom Python dataloaders or model internals: use the Python API sub-skill if present.

Quick Prediction Pattern

Minimum prediction command:

chemprop predict \
  --test-path new_inputs.csv \
  --model-path models/best.pt \
  --output predictions.csv

Core rules:

• --test-path must be a .csv file.
• --model-path and --model-paths are aliases and accept one or more paths.
• Each model path may be a .pt model file, .ckpt checkpoint, or directory.
• Directory model paths are searched recursively for .pt files only; pass .ckpt files explicitly.
• Prediction output may be .csv or .pkl; if omitted, Chemprop writes <test_stem>_preds.csv beside the input.
• With multiple discovered or supplied models, Chemprop writes averaged predictions to the requested output and a second file named <output_stem>_individual<suffix> with per-model columns.

See references/prediction-workflows.md for command patterns and output interpretation.

Quick Fingerprint Pattern

Minimum fingerprint command:

chemprop fingerprint \
  --test-path new_inputs.csv \
  --model-path models/best.pt \
  --ffn-block-index 0 \
  --output fingerprints.npz

Core rules:

• --ffn-block-index is required.
• --ffn-block-index 0 returns the post-aggregation representation before FFN layers.
• --ffn-block-index 1 returns the first FFN linear block output; higher valid indexes select later FFN blocks.
• Fingerprint output may be .csv or .npz; if omitted, Chemprop uses <test_stem>_fps.csv as the base output.
• Chemprop appends the model index to every fingerprint output, such as fingerprints_0.npz, fingerprints_1.npz, or new_inputs_fps_0.csv.
• Atom/bond prediction models can emit kind-specific files with _mol_fingerprints, _atom_fingerprints, and _bond_fingerprints in the stem.

See references/fingerprint-workflows.md for layer choice and output handling.

Match Training-Time Data Flags

Prediction and fingerprint commands must reuse the structure parsing and featurization choices used to train the model. Important flags include:

• --smiles-columns for named molecule columns and multicomponent molecule models.
• --reaction-columns plus --rxn-mode/--reaction-mode for atom-mapped reaction SMILES.
• --descriptors-path or --descriptors-columns for molecule-level descriptors.
• --atom-features-path, --atom-descriptors-path, --bond-features-path, and --bond-descriptors-path for side features.
• --multi-hot-atom-featurizer-mode, --keep-h, --add-h, --ignore-stereo, and --reorder-atoms for graph construction compatibility.

Single-molecule default when neither --smiles-columns nor --reaction-columns is supplied: Chemprop reads the first CSV column as SMILES.

Model Artifact Routing

Use references/model-artifacts.md when choosing model paths or interpreting artifacts.

Key facts:

• Chemprop prediction and fingerprint loading first inspect the first model artifact on CPU to detect model type, including atom/bond prediction models.
• .pt files are normal exported model artifacts; .ckpt files are Lightning checkpoints that can be loaded when passed explicitly.
• Directories are accepted but discover .pt files only.
• Prediction target names are loaded from the artifact when available; otherwise outputs use generic names such as pred_0, pred_1.
• CUDA-trained artifacts can be loaded for CPU prediction because Chemprop loads checkpoint metadata with CPU mapping before inference.

Bundled Command Builder

Use scripts/chemprop_predict_command_builder.py to plan commands without importing Chemprop or loading model files.

Examples:

python scripts/chemprop_predict_command_builder.py predict \
  --test-path new_inputs.csv \
  --model-path models/ \
  --output predictions.csv \
  --smiles-columns smiles

python scripts/chemprop_predict_command_builder.py fingerprint \
  --test-path new_inputs.csv \
  --model-path models/best.pt \
  --output fingerprints.npz \
  --ffn-block-index 0

The helper validates common suffix mistakes, notes model directory discovery behavior, warns about likely parsing mismatches, and can emit JSON with --json.

Troubleshooting First Pass

Use references/troubleshooting.md for failures.

Fast triage:

• Run chemprop --help, chemprop predict --help, or chemprop fingerprint --help to confirm CLI availability.
• Confirm input is .csv and output suffix is legal for the selected subcommand.
• Confirm every model path is a .pt, .ckpt, or directory, and that directory paths contain .pt files if relying on recursive discovery.
• Reuse the training-time component columns, reaction mode, descriptors, side features, and featurizer mode.
• If a v1 featurizer mismatch warning appears, rerun with --multi-hot-atom-featurizer-mode v1 or convert/verify the artifact before production inference.
• Prefer --accelerator cpu --devices 1 --num-workers 0 while debugging checkpoint loading or multiprocessing issues.