OrdinalRegression<T>

Models & Types · AiDotNet.Classification

Implements Ordinal Regression (Proportional Odds Model) for predicting ordered categorical outcomes.

Inheritance: ClassifierBase<T> → OrdinalRegression<T>

Implements: IGeneratedParameterRegistrar<T>, IGradientComputable<T, Matrix<T>, Vector<T>>

How It Works

Ordinal Regression is used when the target variable has naturally ordered categories. It models the cumulative probability of being in category k or lower using the proportional odds assumption: P(Y ≤ k) = sigmoid(α_k - β^T × x) where α_k are ordered thresholds (one less than the number of classes) and β are feature coefficients.

Key properties:

  • Respects the natural ordering of categories
  • Uses single set of feature coefficients (proportional odds assumption)
  • Ordered thresholds separate adjacent categories
  • Probabilities for individual classes: P(Y = k) = P(Y ≤ k) - P(Y ≤ k-1)

For Beginners: Ordinal Regression is perfect when your categories have a natural order but the distances between them may not be equal. Examples include:

  • Star ratings (1-5 stars): You know 5 > 4 > 3 > 2 > 1, but the difference between 1 and 2

stars might not equal the difference between 4 and 5 stars

  • Survey responses: Strongly Disagree < Disagree < Neutral < Agree < Strongly Agree
  • Education levels: High School < Bachelor’s < Master’s < PhD
  • Pain levels: None < Mild < Moderate < Severe

The model learns:

  1. Feature coefficients (β): How each feature pushes predictions up or down the ordinal scale
  2. Thresholds (α): Where to draw the lines between adjacent categories

This is better than treating it as regular classification (which ignores order) or as regression (which assumes equal distances between categories).

Example

// Create ordinal regression for ordered categorical prediction (e.g., star ratings 1-5)
var options = new OrdinalRegressionOptions<double>();
            
// Prepare training data with features and ordinal labels (0, 1, 2 for Low, Medium, High)
var features = new Matrix<double>(6, 2);
features[0, 0] = 1.0; features[0, 1] = 0.5;
features[1, 0] = 1.5; features[1, 1] = 1.0;
features[2, 0] = 2.0; features[2, 1] = 1.5;
features[3, 0] = 2.5; features[3, 1] = 2.0;
features[4, 0] = 3.0; features[4, 1] = 2.5;
features[5, 0] = 3.5; features[5, 1] = 3.0;
var labels = new Vector<double>(new double[] { 0, 0, 1, 1, 2, 2 });
            
// Train with proportional odds model
var result = new AiModelBuilder<double, Matrix<double>, Vector<double>>()
    .ConfigureModel(new OrdinalRegression<double>(options))
    .Build(features, labels);
            
// Predict ordinal class for new data
var newSample = new Matrix<double>(1, 2);
newSample[0, 0] = 2.2; newSample[0, 1] = 1.8;
var prediction = result.Predict(newSample);
// Result is available in the returned value

Constructors

Constructor Summary
OrdinalRegression(OrdinalRegressionOptions<T> options, IRegularization<T, Matrix<T>, Vector<T>> regularization) Initializes a new instance of the OrdinalRegression class with the specified options and regularization.

Properties

Property Summary
Vector<T> Coefficients { get; } Gets the feature coefficients.
Vector<T> Thresholds { get; } Gets the threshold parameters.

Methods

Method Summary
Dictionary<string, T> GetFeatureImportance() Gets the feature importance scores (absolute coefficient values).
IFullModel<T, Matrix<T>, Vector<T>> WithParameters(Vector<T> parameters) Creates a new instance of the model with specified parameters.
Matrix<T> PredictProbabilities(Matrix<T> input) Returns the probability estimates for all classes.
ModelOptions GetOptions()
Vector<T> ComputeGradients(Matrix<T> input, Vector<T> target, ILossFunction<T> lossFunction) Computes gradients for the model parameters.
Vector<T> Predict(Matrix<T> input) Predicts class labels for the given input data.
void ApplyGradients(Vector<T> gradients, T learningRate) Applies gradients to update the model parameters.
void Train(Matrix<T> x, Vector<T> y) Trains the ordinal regression model on the provided data.