fintech-algorithms
/
Using a coding agent? Give it the skill: npx skills add IslamBaraka90/Fintech-Algorithms-Library What it does →

Market-Wide Stock Screening and Ranking

Install and import#

bash
npm install fintech-algorithms
ts
import { marketWideStockScreeningAndRanking } from "fintech-algorithms/fundamental-analysis-and-valuation/integrated-equity-scoring/market-wide-stock-screening-and-ranking";

Signature#

marketWideStockScreeningAndRanking(data)

Applies eligibility, score, confidence and liquidity floors to a universe of scored names, ranks the survivors, and records why each excluded name failed.

Parameters#

NameTypeNotes
data{ screen_floor: number; min_confidence: number; min_liquidity: number; universe: Array<{ id: string; eligible: boolean; score: number; confidence: number; liquidity: number; sector?: string }> }screen_floor is the minimum score and must be between 0 and 100, min_confidence a fraction between 0 and 1, and min_liquidity a nonnegative floor. Each universe row needs a text id, a score between 0 and 100, a confidence between 0 and 1 and a nonnegative liquidity; its eligible must be exactly true to pass, and sector falls back to unspecified.

Returns#

{ state: string; method: string; ranked: Array<{ rank: number; id: string; score: number; confidence: number; liquidity: number; sector: string }>; screened_count: number; universe_count: number; coverage: number; score_floor: number; confidence_floor: number; liquidity_floor: number; excluded: Array<{ id: string; score: number; confidence: number; liquidity: number; sector: string; reasons: string[] }>; tie_break: string }

ranked holds the survivors ordered by score descending, then confidence descending, then id ascending, each carrying a 1-based rank. excluded carries every failed row with its reasons list. screened_count over universe_count gives coverage, the three floor keys echo the thresholds, and state is ranked when anything survives, otherwise abstain.

Errors#

  • When universe is not a nonempty list, or a row lacks a text id — throws TypeError
  • When min_confidence or a row confidence is not a finite number — throws TypeError
  • When screen_floor or a row score is below 0 or above 100 — throws RangeError
  • When min_confidence or a row confidence is below 0 or above 1 — throws RangeError
  • When min_liquidity or a row liquidity is negative — throws RangeError

Complexity: time O(n log n), space O(n).

Worked example#

executed Captured by running this function on the input its own test provides. Real output of real code — but not asserted against a published figure.

Input#

data
{
  "screen_floor": 70,
  "min_confidence": 0.75,
  "min_liquidity": 50,
  "universe": [
    {
      "id": "AAA",
      "score": 82,
      "confidence": 0.96,
      "liquidity": 100,
      "eligible": true,
      "sector": "industrial"
    },
    {
      "id": "BBB",
      "score": 82,
      "confidence": 0.88,
      "liquidity": 80,
      "eligible": true,
      "sector": "software"
    },
    {
      "id": "CCC",
      "score": 76,
      "confidence": 0.81,
      "liquidity": 60,
      "eligible": true,
      "sector": "software"
    }
  ]
}

Call#

marketWideStockScreeningAndRanking(data)

Returns#

object with 11 fields: state, method, ranked, screened_count, universe_count, coverage, score_floor, confidence_floor, …

{
  "state": "ranked",
  "method": "eligibility-confidence-score-floor-ranking",
  "ranked": [
    {
      "rank": 1,
      "id": "AAA",
      "score": 82,
      "confidence": 0.96,
      "liquidity": 100,
      "sector": "industrial"
    },
    {
      "rank": 2,
      "id": "BBB",
      "score": 82,
      "confidence": 0.88,
      "liquidity": 80,
      "sector": "software"
    },
    {
      "rank": 3,
      "id": "CCC",
      "score": 76,
      "confidence": 0.81,
      "liquidity": 60,
      "sector": "software"
    }
  ],
  "screened_count": 3,
  "universe_count": 6,
  "coverage": 0.5,
  "score_floor": 70,
  "confidence_floor": 0.75,
  "liquidity_floor": 50,
  "excluded": [
    {
      "id": "DDD",
      "score": 74,
      "confidence": 0.62,
      "liquidity": 90,
      "sector": "bank",
      "reasons": ["below confidence floor"]
    },
    {
      "id": "EEE",
      "score": 68,
      "confidence": 0.95,
      "liquidity": 110,
      "sector": "industrial",
      "reasons": ["below score floor"]
    },
    {
      "id": "FFF",
      "score": 90,
      "confidence": 0.99,
      "liquidity": 100,
      "sector": "industrial",
      "reasons": ["not eligible"]
    }
  ],
  "tie_break": "score descending, confidence descending, stable id ascending"
}

Other exports#

This module also exports calculate, pointInTimeStockScoringInputAssembly, stockScoringPeerCohortResolver, fundamentalMetricDirectionAndPeerNormalization, modelApplicabilityAndVariantRouter, accountingFinancialHealthComposite, earningsQualityComposite, dividendSafetyScore, balanceSheetResilienceScore, distressModelEnsemble, crossModelConflictAndDoubleCountingResolver, overallExplainableStockScore, scoreConfidenceMissingDataPenaltyAndAbstention, stockScoreHistoryMigrationAndChangeAttribution. 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.

Diagrams#

Market-Wide Stock Screening and Ranking — evidence clock
Market-Wide Stock Screening and Ranking — model anatomy
Market-Wide Stock Screening and Ranking — system map
Market-Wide Stock Screening and Ranking — threshold and interpretation
Market-Wide Stock Screening and Ranking — variant boundaries

How it works#

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References#

The rest of the Integrated Equity Scoring family#