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

Point-in-Time Stock-Scoring Input Assembly

Install and import#

bash
npm install fintech-algorithms
ts
import { pointInTimeStockScoringInputAssembly } from "fintech-algorithms/fundamental-analysis-and-valuation/integrated-equity-scoring/point-in-time-stock-scoring-input-assembly";

Signature#

pointInTimeStockScoringInputAssembly(data)

Resolves each required field to the latest original filing fact that was already available at the knowledge cutoff and that matches the requested period, currency and scale, and reports what could not be resolved.

Parameters#

NameTypeNotes
data{ knowledge_cutoff: string; period_end: string; currency: string; scale: string; required_fields: string[]; facts: Array<{ field: string; value: number; available_at: string; period_end: string; currency: string; scale: string; revision: string }> }The assembly request. knowledge_cutoff and period_end are YYYY-MM-DD strings and required_fields names the fields to resolve. A row of facts is a candidate only when its field matches, its value is a finite number, its available_at is at or before the cutoff, its period_end equals the requested one, its currency and scale equal the requested ones, and its revision is original; the candidate with the latest available_at wins.

Returns#

{ state: string; method: string; as_of: string; accepted_fields: string[]; selected_values: Record<string, number>; rejected_fields: Array<{ field: string; reason: string }>; completeness: number; ready: boolean; clock_policy: string }

selected_values holds one value per resolved field and accepted_fields their sorted names, rejected_fields carries a reason for each unresolved field, completeness is the resolved share of required_fields, ready is true when that share is one, and state is ready or incomplete accordingly. as_of echoes the knowledge cutoff.

Errors#

  • When knowledge_cutoff or period_end is not a YYYY-MM-DD string — throws TypeError
  • When currency or scale is not nonempty text — throws TypeError
  • When required_fields is not a nonempty list of nonempty strings, or facts is not a list — throws TypeError

Complexity: time O(m * n log n), space O(m + 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
{
  "knowledge_cutoff": "2025-03-31",
  "period_end": "2024-12-31",
  "currency": "USD",
  "scale": "millions",
  "required_fields": ["revenue", "total_assets", "net_income", "operating_cash_flow"],
  "facts": [
    {
      "field": "revenue",
      "value": 1200,
      "period_end": "2024-12-31",
      "available_at": "2025-02-15",
      "revision": "original",
      "currency": "USD",
      "scale": "millions"
    },
    {
      "field": "total_assets",
      "value": 1000,
      "period_end": "2024-12-31",
      "available_at": "2025-02-15",
      "revision": "original",
      "currency": "USD",
      "scale": "millions"
    },
    {
      "field": "net_income",
      "value": 90,
      "period_end": "2024-12-31",
      "available_at": "2025-02-15",
      "revision": "original",
      "currency": "USD",
      "scale": "millions"
    }
  ]
}

Call#

pointInTimeStockScoringInputAssembly(data)

Returns#

object with 9 fields: state, method, as_of, accepted_fields, selected_values, rejected_fields, completeness, ready, …

{
  "state": "ready",
  "method": "point-in-time-filing-fact-assembly",
  "as_of": "2025-03-31",
  "accepted_fields": ["net_income", "operating_cash_flow", "revenue", "total_assets"],
  "selected_values": {
    "revenue": 1200,
    "total_assets": 1000,
    "net_income": 90,
    "operating_cash_flow": 120
  },
  "rejected_fields": [],
  "completeness": 1,
  "ready": true,
  "clock_policy": "availability_at <= knowledge_cutoff; original revision; exact period/currency/scale"
}

Other exports#

This module also exports calculate, stockScoringPeerCohortResolver, 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#

Point-in-Time Stock-Scoring Input Assembly — evidence clock
Point-in-Time Stock-Scoring Input Assembly — model anatomy
Point-in-Time Stock-Scoring Input Assembly — system map
Point-in-Time Stock-Scoring Input Assembly — threshold and interpretation
Point-in-Time Stock-Scoring Input Assembly — 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#