Skip to content

Commit 388a05a

Browse files
committed
Add Quantile Regression support to LightGbmRegressionTrainer (dotnet#7603)
1 parent 3ff4be3 commit 388a05a

2 files changed

Lines changed: 150 additions & 1 deletion

File tree

‎src/Microsoft.ML.LightGbm/LightGbmRegressionTrainer.cs‎

Lines changed: 47 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,21 @@ public enum EvaluateMetricType
129129
MeanSquaredError
130130
};
131131

132+
/// <summary>
133+
/// The type of regression objective to use.
134+
/// </summary>
135+
public enum RegressionObjective
136+
{
137+
/// <summary>
138+
/// Standard L2 (least squares) regression.
139+
/// </summary>
140+
Regression,
141+
/// <summary>
142+
/// Quantile regression. Use <see cref="Alpha"/> to set the target quantile.
143+
/// </summary>
144+
Quantile
145+
}
146+
132147
/// <summary>
133148
/// Determines what evaluation metric to use.
134149
/// </summary>
@@ -137,6 +152,25 @@ public enum EvaluateMetricType
137152
ShortName = "em")]
138153
public EvaluateMetricType EvaluationMetric = EvaluateMetricType.RootMeanSquaredError;
139154

155+
/// <summary>
156+
/// The regression objective type. Use <see cref="RegressionObjective.Quantile"/> with
157+
/// <see cref="Alpha"/> for quantile regression.
158+
/// </summary>
159+
[Argument(ArgumentType.AtMostOnce,
160+
HelpText = "Regression objective type. Use 'Quantile' for quantile regression.",
161+
ShortName = "obj")]
162+
public RegressionObjective Objective = RegressionObjective.Regression;
163+
164+
/// <summary>
165+
/// The quantile to predict when <see cref="Objective"/> is <see cref="RegressionObjective.Quantile"/>.
166+
/// Must be in the open interval (0, 1). For example, 0.05 for the 5th percentile or
167+
/// 0.95 for the 95th percentile.
168+
/// </summary>
169+
[Argument(ArgumentType.AtMostOnce,
170+
HelpText = "The alpha (quantile) value for quantile regression. Must be in (0, 1).",
171+
ShortName = "qa")]
172+
public double Alpha = 0.5;
173+
140174
static Options()
141175
{
142176
NameMapping.Add(nameof(EvaluateMetricType), "metric");
@@ -240,7 +274,19 @@ private protected override void CheckDataValid(IChannel ch, RoleMappedData data)
240274

241275
private protected override void CheckAndUpdateParametersBeforeTraining(IChannel ch, RoleMappedData data, float[] labels, int[] groups)
242276
{
243-
GbmOptions["objective"] = "regression";
277+
var regressionOptions = (Options)LightGbmTrainerOptions;
278+
279+
if (regressionOptions.Objective == Options.RegressionObjective.Quantile)
280+
{
281+
Contracts.CheckUserArg(regressionOptions.Alpha > 0 && regressionOptions.Alpha < 1,
282+
nameof(Options.Alpha), "Alpha for quantile regression must be in the open interval (0, 1).");
283+
GbmOptions["objective"] = "quantile";
284+
GbmOptions["alpha"] = regressionOptions.Alpha;
285+
}
286+
else
287+
{
288+
GbmOptions["objective"] = "regression";
289+
}
244290
}
245291

246292
private protected override SchemaShape.Column[] GetOutputColumnsCore(SchemaShape inputSchema)

‎test/Microsoft.ML.Tests/TrainerEstimators/TreeEstimators.cs‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -244,6 +244,109 @@ public void LightGBMRegressorEstimator()
244244
Done();
245245
}
246246

247+
/// <summary>
248+
/// LightGbmRegressionTrainer with quantile objective TrainerEstimator test
249+
/// </summary>
250+
[LightGBMFact]
251+
public void LightGBMQuantileRegressorEstimator()
252+
{
253+
var dataView = GetRegressionPipeline();
254+
255+
var trainer = ML.Regression.Trainers.LightGbm(new LightGbmRegressionTrainer.Options
256+
{
257+
Objective = LightGbmRegressionTrainer.Options.RegressionObjective.Quantile,
258+
Alpha = 0.5,
259+
NumberOfIterations = 10,
260+
NumberOfLeaves = 5,
261+
});
262+
263+
TestEstimatorCore(trainer, dataView);
264+
var model = trainer.Fit(dataView, dataView);
265+
Done();
266+
}
267+
268+
/// <summary>
269+
/// Verify that quantile regression predictions with different alpha values
270+
/// produce appropriately ordered results (lower quantile less than upper quantile).
271+
/// </summary>
272+
[LightGBMFact]
273+
public void LightGBMQuantileRegressorPredictionOrdering()
274+
{
275+
var dataView = GetRegressionPipeline();
276+
277+
// Train model for the 5th percentile
278+
var trainerLow = ML.Regression.Trainers.LightGbm(new LightGbmRegressionTrainer.Options
279+
{
280+
Objective = LightGbmRegressionTrainer.Options.RegressionObjective.Quantile,
281+
Alpha = 0.05,
282+
NumberOfIterations = 50,
283+
NumberOfLeaves = 10,
284+
});
285+
286+
// Train model for the 95th percentile
287+
var trainerHigh = ML.Regression.Trainers.LightGbm(new LightGbmRegressionTrainer.Options
288+
{
289+
Objective = LightGbmRegressionTrainer.Options.RegressionObjective.Quantile,
290+
Alpha = 0.95,
291+
NumberOfIterations = 50,
292+
NumberOfLeaves = 10,
293+
});
294+
295+
var modelLow = trainerLow.Fit(dataView);
296+
var modelHigh = trainerHigh.Fit(dataView);
297+
298+
var predictionsLow = modelLow.Transform(dataView);
299+
var predictionsHigh = modelHigh.Transform(dataView);
300+
301+
var scoresLow = predictionsLow.GetColumn<float>(predictionsLow.Schema["Score"]).ToArray();
302+
var scoresHigh = predictionsHigh.GetColumn<float>(predictionsHigh.Schema["Score"]).ToArray();
303+
304+
Assert.Equal(scoresLow.Length, scoresHigh.Length);
305+
Assert.True(scoresLow.Length > 0);
306+
307+
// On average, the 95th percentile predictions should exceed the 5th percentile predictions.
308+
var avgLow = scoresLow.Average();
309+
var avgHigh = scoresHigh.Average();
310+
Assert.True(avgHigh > avgLow,
311+
$"Expected average 95th percentile ({avgHigh}) > average 5th percentile ({avgLow})");
312+
313+
Done();
314+
}
315+
316+
/// <summary>
317+
/// Verify that invalid Alpha values are rejected for quantile regression.
318+
/// </summary>
319+
[LightGBMFact]
320+
public void LightGBMQuantileRegressorInvalidAlpha()
321+
{
322+
var dataView = GetRegressionPipeline();
323+
324+
// Alpha = 0 should fail
325+
var trainerZero = ML.Regression.Trainers.LightGbm(new LightGbmRegressionTrainer.Options
326+
{
327+
Objective = LightGbmRegressionTrainer.Options.RegressionObjective.Quantile,
328+
Alpha = 0.0,
329+
});
330+
Assert.ThrowsAny<Exception>(() => trainerZero.Fit(dataView));
331+
332+
// Alpha = 1 should fail
333+
var trainerOne = ML.Regression.Trainers.LightGbm(new LightGbmRegressionTrainer.Options
334+
{
335+
Objective = LightGbmRegressionTrainer.Options.RegressionObjective.Quantile,
336+
Alpha = 1.0,
337+
});
338+
Assert.ThrowsAny<Exception>(() => trainerOne.Fit(dataView));
339+
340+
// Alpha = -0.1 should fail
341+
var trainerNeg = ML.Regression.Trainers.LightGbm(new LightGbmRegressionTrainer.Options
342+
{
343+
Objective = LightGbmRegressionTrainer.Options.RegressionObjective.Quantile,
344+
Alpha = -0.1,
345+
});
346+
Assert.ThrowsAny<Exception>(() => trainerNeg.Fit(dataView));
347+
348+
Done();
349+
}
247350

248351
/// <summary>
249352
/// RegressionGamTrainer TrainerEstimator test

0 commit comments

Comments
 (0)