# Stock-Scoring Peer Cohort Resolver

`D18-F09-A02` · Fundamental Analysis and Valuation → Integrated Equity Scoring · archetype `record-transform` · difficulty 3/5 · verification **verified**

Full page: https://docs.thefintechbuilder.com/fundamental-analysis-and-valuation/integrated-equity-scoring/stock-scoring-peer-cohort-resolver/
Agent skill: `npx skills add IslamBaraka90/Fintech-Algorithms-Library` — https://docs.thefintechbuilder.com/guides/agent-skill/

## 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

```ts
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

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `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 }> }` | yes | 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

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`:

```json
{
  "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

```ts
stockScoringPeerCohortResolver(data)
```

### Returns

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

```json
{
  "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

`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.

## Verification and provenance

Tier: **verified** (via D).

The worked example below is the figure published in this algorithm's article, replayed and asserted by the test suite on every build. The arithmetic cannot drift without the build failing.

Both tiers guarantee the signature. Full explanation: https://docs.thefintechbuilder.com/guides/verification/

Generated from the docs.json payload shipped inside fintech-algorithms@0.13.0.
The signature and parameter list are checked against the compiled implementation at build time,
so a description that contradicts the code fails the build rather than reaching this file.

## Links

- Article (how it works, step by step): https://thefintechbuilder.com/fundamental-analysis-and-valuation/integrated-equity-scoring/stock-scoring-peer-cohort-resolver/
- Implementation source: https://github.com/IslamBaraka90/Fintech-Algorithms-Library/blob/main/src/fundamental-analysis-and-valuation/integrated-equity-scoring/stock-scoring-peer-cohort-resolver/impl.ts
- Package on npm: https://www.npmjs.com/package/fintech-algorithms
- Domain index for agents: https://docs.thefintechbuilder.com/fundamental-analysis-and-valuation/llms.txt