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

Stock-Scoring Peer Cohort Resolver

Install and import#

bash
npm install fintech-algorithms
ts
import { stockScoringPeerCohortResolver } from "fintech-algorithms/fundamental-analysis-and-valuation/integrated-equity-scoring/stock-scoring-peer-cohort-resolver";

Signature#

stockScoringPeerCohortResolver(data)

Resolves the peer cohort for one target by keeping universe rows that were listed and already available at the as-of date, share the target's sector and country, and clear a market-cap floor, ordered by market-cap distance.

Parameters#

NameTypeNotes
data{ as_of: string; target_id: string; target_sector: string; target_country: string; min_market_cap: number; min_peers: number; universe: Array<{ id: string; market_cap: number; available_at: string; listed: boolean; sector: string; country: string }> }The cohort request. as_of is a YYYY-MM-DD date and target_id must occur in universe. Every other row is excluded when its market_cap or available_at is invalid, its available_at is after as_of, its listed is not exactly true, its sector differs from target_sector, its country differs from target_country, or its market_cap is below min_market_cap. min_peers is truncated to an integer and sets the size the cohort must reach.

Returns#

{ state: string; method: string; as_of: string; eligible_ids: string[]; cohort_count: number; minimum_required: number; coverage: number; exclusions: Array<{ id: string; reason: string }>; tie_break: string }

eligible_ids lists the surviving peers ordered by absolute market-cap distance from the target and then by id, cohort_count is their number, minimum_required echoes min_peers, coverage is the count over that minimum, exclusions gives one reason per dropped row, and state is resolved when the cohort reaches the minimum, otherwise abstain.

Errors#

  • When as_of is not a YYYY-MM-DD string, or the target identifiers and cohort dimensions are not text — throws TypeError
  • When universe is not a nonempty list — throws TypeError
  • When min_market_cap is negative, or min_peers is not positive — throws RangeError
  • When target_id does not occur in universe, or the target row's market_cap is not positive — 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
{
  "as_of": "2025-03-31",
  "target_id": "TGT",
  "target_sector": "software",
  "target_country": "US",
  "min_market_cap": 500,
  "min_peers": 3,
  "universe": [
    {
      "id": "TGT",
      "sector": "software",
      "country": "US",
      "market_cap": 2000,
      "available_at": "2025-03-31",
      "listed": true
    },
    {
      "id": "P01",
      "sector": "software",
      "country": "US",
      "market_cap": 1800,
      "available_at": "2025-03-20",
      "listed": true
    },
    {
      "id": "P02",
      "sector": "software",
      "country": "US",
      "market_cap": 1500,
      "available_at": "2025-03-20",
      "listed": true
    }
  ]
}

Call#

stockScoringPeerCohortResolver(data)

Returns#

object with 9 fields: state, method, as_of, eligible_ids, cohort_count, minimum_required, coverage, exclusions, …

{
  "state": "resolved",
  "method": "point-in-time-sector-country-market-cap-cohort",
  "as_of": "2025-03-31",
  "eligible_ids": ["P01", "P02", "P03"],
  "cohort_count": 3,
  "minimum_required": 3,
  "coverage": 1,
  "exclusions": [
    {
      "id": "P04",
      "reason": "below market-cap floor"
    },
    {
      "id": "P05",
      "reason": "country mismatch"
    },
    {
      "id": "P06",
      "reason": "not available at as-of date"
    }
  ],
  "tie_break": "absolute market-cap distance, then stable entity id"
}

Other exports#

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

Stock-Scoring Peer Cohort Resolver — evidence clock
Stock-Scoring Peer Cohort Resolver — model anatomy
Stock-Scoring Peer Cohort Resolver — system map
Stock-Scoring Peer Cohort Resolver — threshold and interpretation
Stock-Scoring Peer Cohort Resolver — 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#