---

name: inference description: "Run and validate DeepMedic 0.8.4 whole-volume inference from a compatible model checkpoint and NIFTI inputs, including TestConfig authoring, tiling, ROI restriction, probability/feature outputs, and DSC reporting." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

DeepMedic inference

Use this skill when a trained DeepMedic network must segment unseen, co-registered NIFTI volumes or when an inference result needs a deterministic output check. This is an operating guide for the installed DeepMedic 0.8.4 package. It does not create a network architecture or a raw-data manifest. For those tasks use the model-architecture skill and the data-preparation skill.

Fast route

1. Confirm that the model configuration describes the exact architecture used to make the checkpoint: input-channel count, class count, pathway choices, layer/kernel definitions, subsampling factors, and inference segment size.
2. Create a test configuration with a writable output folder, one channel list per model input channel, and one output name per case. Add ROI and labels only when their files exist and are shape-compatible.
3. Run the installed CLI with -model, -test, and either -load or cnnModelFilePath. Select -dev cpu, -dev cuda, or -dev cudaN after checking the TensorFlow/CUDA installation.
4. Check the session log and validate every expected output with scripts/check_inference_outputs.py. Inspect NIFTI shape, affine, dtype, finite values, class probabilities, and ROI behavior before consuming a result downstream.

Read test-config.md for the configuration contract, workflows.md for the complete run and validation sequence, and troubleshooting.md when a run fails.

Preconditions and boundaries

• Inputs are NIFTI volumes (.nii or .nii.gz). Each case's modalities, optional label, and optional ROI must be co-registered and have identical voxel dimensions. The dataset should use a consistent voxel size across cases; labels use background 0 and consecutive class IDs.
• The number and order of channel list files must match the model's input channel count. A - line in a channel list deliberately creates a zero-filled channel; use it only when that modality is intentionally absent.
• A checkpoint is a TensorFlow checkpoint prefix, conventionally ending in .model.ckpt, not the .data-*, .index, or .meta companion file. A directory is also accepted; DeepMedic asks TensorFlow for its latest checkpoint.
• Do not use a checkpoint with a different architecture. TensorFlow restore errors are commonly caused by variable/name/shape mismatch, not by bad NIFTI data. Reuse the model configuration that produced the checkpoint.
• A feature-map request is optional and can consume many times more disk and memory than segmentation. Request narrow layer/range slices first.

TestConfig contract

TestConfig(abs_path_to_cfg) executes the configuration as Python and exposes its variables through the Config interface. Therefore use ordinary Python syntax, keep the file trusted, and make all paths either absolute or relative to the test-config file (except the command-line -load path, which is first resolved relative to the process working directory).

Required for the legacy list-file input path:

• folderForOutput: writable main output directory.
• channels: list of channel-list files, one per model input channel.
• namesForPredictionsPerCase: a list file with exactly one safe output name per case. Use names that do not contain / or begin with . (the source includes this convention helper, though the current test-session path does not invoke it consistently). The name may be a basename, a .nii, or a .nii.gz name; DeepMedic appends the configured suffix.

sessionName is strongly recommended; its default is testSession. A missing checkpoint is not silently safe: the CLI asks whether to test a randomly initialized model, and non-interactive runs should decline by supplying a checkpoint instead.

The v0.8.4 parser also accepts dataframe, where pandas reads a CSV and sorts columns beginning with channel_ alphabetically. Optional columns are ground_truth, roi_mask, and prediction_filename. When dataframe is used, those paths replace the legacy lists; prediction_filename supplies output names. Keep the legacy channels plus names lists when portability and explicit ordering matter. See test-config.md for all defaults and invariants.

CLI and precedence

The normal form is:

deepMedicRun -model MODEL_CFG -test TEST_CFG [-load CHECKPOINT] [-dev cpu|cuda|cudaN]

-model is required by the top-level CLI and must be supplied even when TEST_CFG contains the checkpoint. -test selects inference and cannot be combined with -train. -load is valid with -test or -train; for testing, it overrides cnnModelFilePath in the test configuration. The override is absolute-resolved from the current working directory, while a model path read from the config is resolved relative to that config file. Put the prefix, not a checkpoint shard, in either location.

-dev cpu is the default and clears visible CUDA devices before creating the TensorFlow graph. -dev cuda lets TensorFlow see its available GPUs and uses the first suitable device. -dev cudaN exposes only GPU N and binds the graph to GPU 0 in the masked view. A requested GPU must be visible to the installed TensorFlow build and have compatible CUDA/cuDNN libraries; otherwise use CPU for a small smoke test or fix the runtime rather than assuming silent GPU use. The verified production environment for this skill was Python 3.8.20, TensorFlow 2.6.2, NumPy 1.19.5, and a CUDA TensorFlow build seeing A100 GPUs, but this is evidence for the packaged revision, not a universal hardware requirement.

What a successful run does

For each case DeepMedic loads all channels, optionally labels and an ROI, performs input checks, pads to cover the receptive field when padInputImagesBool=True, and applies the configured z-score normalization. It computes the normal-path output dimensions and tiles the padded volume. The tiling stride equals the number of central voxels predicted by one forward pass. Tiles are stitched into full-volume class probability arrays; argmax across classes produces the segmentation. ROI tiles with no positive voxel are skipped. After inference, padding is removed, then the segmentation and every probability map are multiplied by the unpadded ROI when an ROI was supplied. Thus ROI restriction affects both work and saved outputs; it is not merely an evaluation crop.

The session creates a main output tree containing logs and, under the session's prediction result, separate predictions/ and features/ directories. For an output name caseA.nii.gz and default suffixes, expect:

• caseA_Segm.nii.gz for the integer segmentation (if enabled).
• caseA_ProbMapClass0.nii.gz, caseA_ProbMapClass1.nii.gz, etc. for enabled class probabilities.
• caseA_pathwayP_layerL_fmF.nii.gz in features/ for each selected feature map, where pathway, layer, and FM indices are zero-based.

The first input channel is used as the NIFTI affine/header source. Validate that its affine and shape represent the intended case. DeepMedic saves segmentation as int16 and probabilities/features as float32.

If labels are supplied, DeepMedic reports per-case and mean DSC. calculate_dice uses 2 * sum(prediction * ground_truth) / (sum(prediction) + sum(ground_truth)); when the ground-truth foreground is empty it returns -1, which is rendered as an NA marker. For each class report there are three values: DICE1 compares the whole-volume prediction to whole-volume GT; DICE2 compares the prediction masked to the ROI against whole GT; DICE3 compares both prediction and GT inside the ROI. Class 0 means merged foreground (label > 0), not background. Consult DICE2/DICE3 when an ROI was part of the intended task.

Output acceptance gate

Do not call a run complete merely because the process exits. Confirm all of the following:

• The log says parameters loaded from the intended checkpoint and the expected number of cases was processed; no random-initialization prompt was accepted.

• Every expected segmentation and enabled class probability exists. Use the bundled checker for presence checks without modifying data:

  python scripts/check_inference_outputs.py PREDICTIONS_DIR caseA caseB --prob-classes 3 --require-features --feature-dir FEATURES_DIR
  

  The checker accepts case names with or without NIFTI extensions, reports all missing files, and exits nonzero on missing requested outputs. It performs a safe synthetic-directory check with --self-test; no NIFTI or checkpoint is needed for that check.

• NIFTI files have the expected spatial shape and affine, segmentation labels are integral and within [0, numberOfOutputClasses - 1], and probability maps are finite. Probability maps should be nonnegative and sum approximately to one over predicted voxels before any intentional ROI zeroing.

• Outside a supplied ROI, saved segmentation and probability values are zero. If padInputImagesBool=True, saved dimensions should return to the original unpadded dimensions.

• If labels were supplied, record the per-case and mean DSC from the log and distinguish NA (empty GT foreground) from a numerical zero.

• Feature-map presence is checked only when requested, and selected ranges are checked against the model's layer counts. Saving all maps indiscriminately is a storage and RAM hazard.

For a successful run, hand the output directory, checkpoint prefix, model configuration identity, test configuration, device selection, ROI choice, normalization settings, and checker report to the next pipeline stage. Keep this inference skill focused: architecture creation belongs to ../model-architecture/SKILL.md, and channel/ROI/label file preparation belongs to ../data-preparation/SKILL.md.