Gains, Lift, and Decile Capture

Install and import#

bash

npm install fintech-algorithms

import { gainsLiftAndDecileCapture } from "fintech-algorithms/model-validation-and-backtesting/classification-and-score-validation/gains-lift-and-decile-capture";

Signature#

gainsLiftAndDecileCapture(inputs)

Worked example#

verified This is the worked example published in the article, replayed by the test suite on every run. The output cannot drift.

Input#

inputs

{
  "records": [
    {
      "id": "R01",
      "label": 1,
      "score": 0.95,
      "probability": 0.92,
      "weight": 1,
      "sector": "Banking",
      "country": "Egypt",
      "regime": "Expansion",
      "score_available_at": "2025-01-01T00:00:00Z",
      "label_available_at": "2026-01-01T00:00:00Z"
    },
    {
      "id": "R02",
      "label": 0,
      "score": 0.9,
      "probability": 0.88,
      "weight": 1,
      "sector": "Insurance",
      "country": "Egypt",
      "regime": "Expansion",
      "score_available_at": "2025-01-01T00:00:00Z",
      "label_available_at": "2026-01-01T00:00:00Z"
    },
    {
      "id": "R03",
      "label": 1,
      "score": 0.9,
      "probability": 0.84,
      "weight": 1,
      "sector": "Markets",
      "country": "Saudi Arabia",
      "regime": "Expansion",
      "score_available_at": "2025-01-01T00:00:00Z",
      "label_available_at": "2026-01-01T00:00:00Z"
    }
  ],
  "evaluation_cutoff": "2026-06-30T00:00:00Z",
  "buckets": 10
}

Call#

gainsLiftAndDecileCapture(inputs)

Returns#

object with 8 fields: buckets, top_decile_capture, overall_prevalence, total_events, total_weight, bucket_count, tie_break, state

{
  "buckets": [
    {
      "bucket": 1,
      "rank_start": 1,
      "rank_end": 3,
      "record_count": 3,
      "population_weight": 3,
      "event_weight": 2,
      "population_share": 0.125,
      "event_capture": 0.2,
      "bucket_lift": 1.5999999999999999,
      "cumulative_population": 0.125,
      "cumulative_gain": 0.2,
      "cumulative_lift": 1.6
    },
    {
      "bucket": 2,
      "rank_start": 4,
      "rank_end": 5,
      "record_count": 2,
      "population_weight": 2,
      "event_weight": 1,
      "population_share": 0.08333333333333333,
      "event_capture": 0.1,
      "bucket_lift": 1.2,
      "cumulative_population": 0.20833333333333334,
      "cumulative_gain": 0.3,
      "cumulative_lift": 1.44
    },
    {
      "bucket": 3,
      "rank_start": 6,
      "rank_end": 8,
      "record_count": 3,
      "population_weight": 3,
      "event_weight": 2,
      "population_share": 0.125,
      "event_capture": 0.2,
      "bucket_lift": 1.5999999999999999,
      "cumulative_population": 0.3333333333333333,
      "cumulative_gain": 0.5,
      "cumulative_lift": 1.5
    }
  ],
  "top_decile_capture": 0.2,
  "overall_prevalence": 0.4166666666666667,
  "total_events": 10,
  "total_weight": 24,
  "bucket_count": 10,
  "tie_break": "score-descending-id-ascending",
  "state": "ranking-evaluated"
}

Other exports#

This module also exports rocCurveAndRocAuc, precisionRecallCurveAndPrAuc, brierScore, logLoss, reliabilityDiagramAndExpectedCalibrationError, costSensitiveThresholdOptimization, scoreStabilityAndMigrationMatrix, sliceBasedValidationBySectorCountryAndRegime, rareEventBacktestAndConfidenceBounds, calculate. Every module additionally exports run as an alias of its primary function, and a meta object carrying its catalog id, domain, family, shape and article URL.