WOLFRAM

Wolfram Language & System Documentation Center

UtilityFunction

is an option for Predict, Classify, and related functions that specifies the utility value to assign to each possible pairing of actual and predicted values.

Details
Details and Options Details and Options
Examples  
Basic Examples  
Scope  
Applications  
Properties & Relations  
See Also
History
Cite this Page

UtilityFunction

UtilityFunction

is an option for Predict, Classify, and related functions that specifies the utility value to assign to each possible pairing of actual and predicted values.

Details

  • With UtilityFunctionf, the utility value assigned to actual value va and predicted value vp is taken to be f[va,vp].
  • In the case of Classify, f is typically an association of associations, of the form <|class1<|class1u11,class2u12…|>,…|>. Here uij is the utility matrix, with i being the actual class and j the predicted class.

Examples

open all close all

Basic Examples  (2)

Train a classifier:

Wolfram Language code: c = Classify[{0 -> "healthy", 1 -> "healthy", 2 -> "diseased", 3 -> "healthy", 4 -> "diseased", 5 -> "diseased"}]

For a new example, the most probable class is predicted:

Wolfram Language code: c[1.5, "Probabilities"]
Wolfram Language code: c[1.5]

Set the decision utility to penalize misclassification of "diseased" class member as "healthy":

Wolfram Language code: c[1.5, UtilityFunction -> <| "healthy" -> <|"healthy" -> 1, "diseased" -> 0|>, "diseased" -> <|"healthy" -> -3, "diseased" -> 1|> |>]

Train a predictor:

Wolfram Language code: p = Predict[{1 -> 2.2, 2 -> 4.4, 3 -> 5.5, 4 -> 7.7, 5 -> 9.4}]

By default, the value with the highest probability density is predicted:

Wolfram Language code: p[4]

Set a utility function that penalizes the predicted value being smaller than the actual value:

Wolfram Language code: p[4, UtilityFunction -> Function[{actual, prediction}, -Piecewise[{{Exp[prediction - actual], actual < prediction}, {Exp[3 * (actual - prediction)], actual ≥ prediction}}] ]]

Scope  (7)

Set the UtilityFunction at classifier training:

Wolfram Language code: c = Classify[{0 -> "healthy", 1 -> "healthy", 2 -> "diseased", 3 -> "healthy", 4 -> "diseased", 5 -> "diseased"}, UtilityFunction -> <| "healthy" -> <|"healthy" -> 1, "diseased" -> 0|>, "diseased" -> <|"healthy" -> -3, "diseased" -> 1|> |>]

Obtain the classification:

Wolfram Language code: c[1.5]

Extract the UtilityFunction from a ClassifierFunction

Wolfram Language code: Information[ClassifierFunction[Association["ExampleNumber" -> 6, "ClassNumber" -> 2, "Input" -> Association["Preprocessor" -> MachineLearning`MLProcessor["ToMLDataset", Association["Input" -> Association["f1" -> Association["Type" -> "Numerical"]], ... te" -> DateObject[{2026, 2, 5, 14, 28, 25.083556`8.151964087135537}, "Instant", "Gregorian", 1.], "ProcessorCount" -> 4, "ProcessorType" -> "x86-64", "OperatingSystem" -> "MacOSX", "SystemWordLength" -> 64, "Evaluations" -> {}]]], UtilityFunction]

Use a utility function that includes an Indeterminate decision possibility (independently of the option IndeterminateThreshold):

Wolfram Language code: ClassifierFunction[Association["ExampleNumber" -> 6, "ClassNumber" -> 2, "Input" -> Association["Preprocessor" -> MachineLearning`MLProcessor["ToMLDataset", Association["Input" -> Association["f1" -> Association["Type" -> "Numerical"]], ... te" -> DateObject[{2026, 2, 5, 14, 28, 25.083556`8.151964087135537}, "Instant", "Gregorian", 1.], "ProcessorCount" -> 4, "ProcessorType" -> "x86-64", "OperatingSystem" -> "MacOSX", "SystemWordLength" -> 64, "Evaluations" -> {}]]][1.5, UtilityFunction -> <| "healthy" -> <|"healthy" -> 1, "diseased" -> 0, Indeterminate -> 0.8|>, "diseased" -> <|"healthy" -> 0, "diseased" -> 1, Indeterminate -> 0.9|> |>]

Obtain a new ClassifierFunction with a modified UtilityFunction value:

Wolfram Language code: Classify[ClassifierFunction[Association["ExampleNumber" -> 6, "ClassNumber" -> 2, "Input" -> Association["Preprocessor" -> MachineLearning`MLProcessor["ToMLDataset", Association["Input" -> Association["f1" -> Association["Type" -> "Numerical"]], ... te" -> DateObject[{2026, 2, 5, 14, 28, 25.083556`8.151964087135537}, "Instant", "Gregorian", 1.], "ProcessorCount" -> 4, "ProcessorType" -> "x86-64", "OperatingSystem" -> "MacOSX", "SystemWordLength" -> 64, "Evaluations" -> {}]]], UtilityFunction -> <| "healthy" -> <|"healthy" -> 1, "diseased" -> 0|>, "diseased" -> <|"healthy" -> 0, "diseased" -> 1|> |>]

Set the UtilityFunction at predictor training:

Wolfram Language code: p = Predict[{1 -> 2.2, 2 -> 4.4, 3 -> 5.5, 4 -> 7.7, 5 -> 9.4}, UtilityFunction -> Function[{actual, prediction}, -Piecewise[{{Exp[prediction - actual], actual < prediction}, {Exp[3 * (actual - prediction)], actual ≥ prediction}}] ]]

Obtain the prediction:

Wolfram Language code: p[4]

Extract the current UtilityFunction value from a PredictorFunction:

Wolfram Language code: Information[PredictorFunction[Association["ExampleNumber" -> 5, "Input" -> Association["Preprocessor" -> MachineLearning`MLProcessor["ToMLDataset", Association["Input" -> Association["f1" -> Association["Type" -> "Numerical"]], "Output" -> As ... te" -> DateObject[{2026, 2, 5, 14, 32, 38.007625`8.332445711286626}, "Instant", "Gregorian", 1.], "ProcessorCount" -> 4, "ProcessorType" -> "x86-64", "OperatingSystem" -> "MacOSX", "SystemWordLength" -> 64, "Evaluations" -> {}]]], UtilityFunction]

Obtain a new PredictorFunction with a modified UtilityFunction value:

Wolfram Language code: Predict[PredictorFunction[Association["ExampleNumber" -> 5, "Input" -> Association["Preprocessor" -> MachineLearning`MLProcessor["ToMLDataset", Association["Input" -> Association["f1" -> Association["Type" -> "Numerical"]], "Output" -> As ... te" -> DateObject[{2026, 2, 5, 14, 32, 38.007625`8.332445711286626}, "Instant", "Gregorian", 1.], "ProcessorCount" -> 4, "ProcessorType" -> "x86-64", "OperatingSystem" -> "MacOSX", "SystemWordLength" -> 64, "Evaluations" -> {}]]], UtilityFunction -> Function[DiracDelta[#2 - #1]]]

Applications  (1)

Load the training set and test set of the "Mushroom" dataset:

Wolfram Language code: trainingset = ExampleData[{"MachineLearning", "Mushroom"}, "TrainingData"];
Wolfram Language code: testset = ExampleData[{"MachineLearning", "Mushroom"}, "TestData"];

Train a classifier on a part of the training set:

Wolfram Language code: c = Classify[RandomSample[trainingset, 100]]

Visualize the confusion matrix of the classifier on the test set:

Wolfram Language code: ClassifierMeasurements[c, testset, "ConfusionMatrixPlot"]

Visualize the confusion matrix obtained when the classifier has a different value of UtilityFunction:

Wolfram Language code: utility = <| "edible" -> <|"edible" -> 1, "poisonous" -> 0, Indeterminate -> 0.5|>, "poisonous" -> <|"edible" -> -10, "poisonous" -> 1, Indeterminate -> 0.8|> |>;
Wolfram Language code: ClassifierMeasurements[c, testset, "ConfusionMatrixPlot", UtilityFunction -> utility]

Properties & Relations  (4)

The default utility function value for ClassifierFunction is the identity matrix:

Wolfram Language code: Information[Classify[{0 -> "healthy", 1 -> "healthy", 2 -> "diseased", 3 -> "healthy", 4 -> "diseased", 5 -> "diseased"}], UtilityFunction]

The classification decision maximizes the expected utility:

Wolfram Language code: ClassifierFunction[Association["ExampleNumber" -> 6, "ClassNumber" -> 2, "Input" -> Association["Preprocessor" -> MachineLearning`MLProcessor["ToMLDataset", Association["Input" -> Association["f1" -> Association["Type" -> "Numerical"]], ... te" -> DateObject[{2026, 2, 5, 14, 50, 41.562291`8.371274456737947}, "Instant", "Gregorian", 1.], "ProcessorCount" -> 4, "ProcessorType" -> "x86-64", "OperatingSystem" -> "MacOSX", "SystemWordLength" -> 64, "Evaluations" -> {}]]][1.5, "ExpectedUtilities", UtilityFunction -> <| "diseased" -> <|"diseased" -> 1, "healthy" -> -3, Indeterminate -> 0.1|>, "healthy" -> <| "diseased" -> 0, "healthy" -> 1, Indeterminate -> 0.1|> |>]
Wolfram Language code: ClassifierFunction[Association["ExampleNumber" -> 6, "ClassNumber" -> 2, "Input" -> Association["Preprocessor" -> MachineLearning`MLProcessor["ToMLDataset", Association["Input" -> Association["f1" -> Association["Type" -> "Numerical"]], ... te" -> DateObject[{2026, 2, 5, 14, 50, 41.562291`8.371274456737947}, "Instant", "Gregorian", 1.], "ProcessorCount" -> 4, "ProcessorType" -> "x86-64", "OperatingSystem" -> "MacOSX", "SystemWordLength" -> 64, "Evaluations" -> {}]]][1.5, UtilityFunction -> <| "diseased" -> <|"diseased" -> 1, "healthy" -> -3, Indeterminate -> 0.1|>, "healthy" -> <| "diseased" -> 0, "healthy" -> 1, Indeterminate -> 0.1|> |>]

The expected utility is the product of the utility values by their predicted probabilities:

Wolfram Language code: {{1., -3, 0.1}, {0., 1., 0.1}}.Lookup[c[1.5, "Probabilities"], {"diseased", "healthy"}]

The default utility function value for PredictorFunction is the Dirac delta:

Wolfram Language code: Information[Predict[{1 -> 2.2, 2 -> 4.4, 3 -> 5.5, 4 -> 7.7, 5 -> 9.4}], UtilityFunction]

The PredictorFunction prediction maximizes the expected utility:

Wolfram Language code: Predict[{1 -> 2.2, 2 -> 4.4, 3 -> 5.5, 4 -> 7.7, 5 -> 9.4}][4, UtilityFunction -> Function[{actual, prediction}, -Piecewise[{{Exp[prediction - actual], actual < prediction}, {Exp[3 * (actual - prediction)], actual ≥ prediction}}] ]]
Wolfram Research (2014), UtilityFunction, Wolfram Language function, https://reference.wolfram.com/language/ref/UtilityFunction.html.

Text

Wolfram Research (2014), UtilityFunction, Wolfram Language function, https://reference.wolfram.com/language/ref/UtilityFunction.html.

CMS

Wolfram Language. 2014. "UtilityFunction." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/UtilityFunction.html.

APA

Wolfram Language. (2014). UtilityFunction. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/UtilityFunction.html

BibTeX

@misc{reference.wolfram_2026_utilityfunction, author="Wolfram Research", title="{UtilityFunction}", year="2014", howpublished="\url{https://reference.wolfram.com/language/ref/UtilityFunction.html}", note=[Accessed: 13-June-2026]}

BibLaTeX

@online{reference.wolfram_2026_utilityfunction, organization={Wolfram Research}, title={UtilityFunction}, year={2014}, url={https://reference.wolfram.com/language/ref/UtilityFunction.html}, note=[Accessed: 13-June-2026]}