PairwiseCouplingTrainer Class


The IEstimator<TTransformer> for training a pairwise coupling multi-class classifier that uses the specified binary classifier.

public sealed class PairwiseCouplingTrainer : Microsoft.ML.Trainers.MetaMulticlassTrainer<Microsoft.ML.Data.MulticlassPredictionTransformer<Microsoft.ML.Trainers.PairwiseCouplingModelParameters>,Microsoft.ML.Trainers.PairwiseCouplingModelParameters>
type PairwiseCouplingTrainer = class
    inherit MetaMulticlassTrainer<MulticlassPredictionTransformer<PairwiseCouplingModelParameters>, PairwiseCouplingModelParameters>
Public NotInheritable Class PairwiseCouplingTrainer
Inherits MetaMulticlassTrainer(Of MulticlassPredictionTransformer(Of PairwiseCouplingModelParameters), PairwiseCouplingModelParameters)


To create this trainer, use PairwiseCoupling.

Input and Output Columns

The input label column data must be key type and the feature column must be a known-sized vector of Single.

This trainer outputs the following columns:

Output Column Name Column Type Description
Score Vector of Single The scores of all classes. Higher value means higher probability to fall into the associated class. If the i-th element has the largest value, the predicted label index would be i. Note that i is zero-based index.
PredictedLabel key type The predicted label's index. If its value is i, the actual label would be the i-th category in the key-valued input label type.

Trainer Characteristics

Machine learning task Multiclass classification
Is normalization required? Depends on the underlying binary classifier
Is caching required? Yes
Required NuGet in addition to Microsoft.ML None
Exportable to ONNX No

Training Algorithm Details

In this strategy, a binary classification algorithm is trained on each pair of classes. The pairs are unordered but created with replacement: so, if there were three classes, 0, 1, 2, we would train classifiers for the pairs (0,0), (0,1), (0,2), (1,1), (1,2), and (2,2). For each binary classifier, an input data point is considered a positive example if it is in either of the two classes in the pair, and a negative example otherwise. At prediction time, the probabilities for each pair of classes is considered as the probability of being in either class of the pair given the data, and the final predictive probabilities out of that per class are calculated given the probability that an example is in any given pair.

This can allow you to exploit trainers that do not naturally have a multiclass option, for example, using the FastTreeBinaryTrainer to solve a multiclass problem. Alternately, it can allow ML.NET to solve a "simpler" problem even in the cases where the trainer has a multiclass option, but using it directly is not practical due to, usually, memory constraints. For example, while a multiclass logistic regression is a more principled way to solve a multiclass problem, it requires that the trainer store a lot more intermediate state in the form of L-BFGS history for all classes simultaneously, rather than just one-by-one as would be needed for a pairwise coupling classification model.

Check the See Also section for links to usage examples.


Info (Inherited from MetaMulticlassTrainer<TTransformer,TModel>)



Fits the data to the transformer


Gets the output columns.

(Inherited from MetaMulticlassTrainer<TTransformer,TModel>)

Extension Methods

AppendCacheCheckpoint<TTrans>(IEstimator<TTrans>, IHostEnvironment)

Append a 'caching checkpoint' to the estimator chain. This will ensure that the downstream estimators will be trained against cached data. It is helpful to have a caching checkpoint before trainers that take multiple data passes.

WithOnFitDelegate<TTransformer>(IEstimator<TTransformer>, Action<TTransformer>)

Given an estimator, return a wrapping object that will call a delegate once Fit(IDataView) is called. It is often important for an estimator to return information about what was fit, which is why the Fit(IDataView) method returns a specifically typed object, rather than just a general ITransformer. However, at the same time, IEstimator<TTransformer> are often formed into pipelines with many objects, so we may need to build a chain of estimators via EstimatorChain<TLastTransformer> where the estimator for which we want to get the transformer is buried somewhere in this chain. For that scenario, we can through this method attach a delegate that will be called once fit is called.

Applies to

See also