backtest / wire operation
Run a cross-sectional backtest
totalfinance.backtest.cross_sectional_run
Backtest a point-in-time cross-sectional strategy: a returns dataset with declared features, a universe history with entries and exits, one declarative signal (a versioned factor recipe, a composite score, or a screen), a rebalance schedule, and a portfolio construction (quantile/count/fraction selection on each side; equal, score, inverse-volatility, or risk-budget weights; dollar/sector/beta/factor neutrality; position, weight, turnover, and participation caps — every trim a reported goal). Fills go through the execution policy into the portfolio ledger; the final value reconciles to the ledger NAV. Rebalances, holdings, fills, the ledger, the timeline, attribution, the benchmark block, and the performance summary — crossSectionalBacktest(...) verbatim. Opt-in (backtestPack): payloads and runtime are heavier than the default set; bulk row sets above the row cap travel by handle.
| Pack / profiles | backtest / backtesting, full |
|---|---|
| Default discovery | Opt-in |
| Required capabilities | None |
| Effects / authorization | none / none |
| Cost / cancellation | job / Do not assume inline interruption |
| Handle-eligible inputs | dataset |
| Idempotency | not-applicable |
Input schema
{
"type": "object",
"properties": {
"dataset": {
"type": "object",
"properties": {
"observations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"instrumentId": {
"type": "string",
"minLength": 1
},
"availableTimestampMs": {
"type": "number"
},
"fields": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"description": "Declared fields only; null is a stated missing value"
}
},
"additionalProperties": false,
"required": [
"instrumentId",
"availableTimestampMs",
"fields"
]
}
},
"fieldDefinitions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"fieldName": {
"type": "string",
"minLength": 1
},
"kind": {
"type": "string",
"enum": [
"numeric",
"category",
"text",
"boolean"
]
},
"unit": {
"type": "string"
},
"description": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"fieldName",
"kind"
]
},
"minItems": 1
},
"returns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"instrumentId": {
"type": "string",
"minLength": 1
},
"tradingSessionDate": {
"type": "string",
"format": "date"
},
"simpleReturn": {
"type": "number"
}
},
"additionalProperties": false,
"required": [
"instrumentId",
"tradingSessionDate",
"simpleReturn"
]
},
"description": "Per instrument per session; prices are return-index levels (base 100)"
},
"benchmarkReturns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"instrumentId": {
"type": "string",
"minLength": 1
},
"tradingSessionDate": {
"type": "string",
"format": "date"
},
"simpleReturn": {
"type": "number"
}
},
"additionalProperties": false,
"required": [
"instrumentId",
"tradingSessionDate",
"simpleReturn"
]
}
},
"groups": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"sizeField": {
"type": "string"
},
"classification": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {}
}
},
"averageDailyVolumes": {
"type": "object",
"additionalProperties": {
"type": "number"
}
},
"betas": {
"type": "object",
"additionalProperties": {
"type": "number"
}
}
},
"additionalProperties": false,
"required": [
"observations",
"fieldDefinitions",
"returns"
]
},
"universeHistory": {
"type": "object",
"properties": {
"universeId": {
"type": "string",
"minLength": 1
},
"members": {
"type": "array",
"items": {
"type": "object",
"properties": {
"instrumentId": {
"type": "string",
"minLength": 1
},
"fromTimestampMs": {
"type": "number"
},
"toTimestampMs": {
"type": "number"
},
"exitReason": {
"type": "string",
"enum": [
"removed",
"delisted",
"merged",
"other"
]
},
"delistingReturn": {
"type": "number"
}
},
"additionalProperties": false,
"required": [
"instrumentId",
"fromTimestampMs"
]
},
"minItems": 1
}
},
"additionalProperties": false,
"required": [
"universeId",
"members"
]
},
"signal": {
"anyOf": [
{
"type": "object",
"properties": {
"factorRecipe": {
"type": "object",
"properties": {
"recipeName": {
"type": "string",
"minLength": 1
},
"recipeVersion": {
"type": "integer",
"exclusiveMinimum": 0
},
"disclosure": {
"type": "string"
},
"direction": {
"type": "string",
"enum": [
"higher-is-better",
"lower-is-better"
]
},
"features": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string",
"minLength": 1
},
"transform": {
"type": "string",
"enum": [
"raw",
"winsorize-then-z-score",
"percentile-rank"
]
},
"weight": {
"type": "number"
}
},
"additionalProperties": false,
"required": [
"field",
"transform",
"weight"
]
},
"minItems": 1
},
"lagTradingSessions": {
"type": "integer",
"minimum": 0
},
"neutralization": {
"type": "string",
"enum": [
"none",
"sector",
"sector-and-size"
]
},
"missingValuePolicy": {
"type": "string",
"enum": [
"exclude",
"renormalize-weights"
]
}
},
"additionalProperties": false,
"required": [
"recipeName",
"recipeVersion",
"disclosure",
"direction",
"features",
"lagTradingSessions",
"neutralization",
"missingValuePolicy"
],
"description": "A versioned research FactorRecipe (canonical or caller-authored), validated by the engine"
}
},
"additionalProperties": false,
"required": [
"factorRecipe"
]
},
{
"type": "object",
"properties": {
"score": {
"type": "object",
"properties": {
"components": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string"
},
"weight": {
"type": "number",
"exclusiveMinimum": 0
},
"direction": {
"type": "string",
"enum": [
"higher-is-better",
"lower-is-better"
]
},
"standardization": {
"type": "string",
"enum": [
"z-score",
"percentile-rank"
]
}
},
"additionalProperties": false,
"required": [
"field",
"weight",
"direction",
"standardization"
]
},
"minItems": 1
},
"missingValuePolicy": {
"type": "string",
"enum": [
"exclude",
"renormalize-weights"
]
}
},
"additionalProperties": false,
"required": [
"components",
"missingValuePolicy"
]
}
},
"additionalProperties": false,
"required": [
"score"
]
},
{
"type": "object",
"properties": {
"screen": {
"type": "object",
"properties": {
"filter": {
"type": "object",
"additionalProperties": {}
},
"orderBy": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string"
},
"direction": {
"type": "string",
"enum": [
"ascending",
"descending"
]
}
},
"additionalProperties": false,
"required": [
"field",
"direction"
]
},
"minItems": 1
},
"missingValuePolicy": {
"type": "string",
"enum": [
"exclude",
"evaluate-as-false"
]
}
},
"additionalProperties": false,
"required": [
"orderBy",
"missingValuePolicy"
]
}
},
"additionalProperties": false,
"required": [
"screen"
]
}
],
"description": "The three declarative signal forms; a signal callback is SDK-only"
},
"rebalanceSchedule": {
"type": "object",
"properties": {
"frequency": {
"type": "string",
"enum": [
"daily",
"weekly",
"monthly",
"quarterly"
]
},
"session": {
"type": "string",
"enum": [
"open",
"close"
]
},
"bufferBand": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"frequency",
"session"
]
},
"portfolioConstruction": {
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"equal-weight",
"score-weight",
"inverse-volatility",
"risk-budget"
],
"description": "'supplied-weights' takes a caller function and is SDK-only"
},
"long": {
"anyOf": [
{
"type": "object",
"properties": {
"topQuantile": {
"type": "number",
"exclusiveMinimum": 0
}
},
"additionalProperties": false,
"required": [
"topQuantile"
]
},
{
"type": "object",
"properties": {
"count": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"additionalProperties": false,
"required": [
"count"
]
},
{
"type": "object",
"properties": {
"fraction": {
"type": "number",
"exclusiveMinimum": 0
}
},
"additionalProperties": false,
"required": [
"fraction"
]
}
]
},
"short": {
"anyOf": [
{
"type": "object",
"properties": {
"bottomQuantile": {
"type": "number",
"exclusiveMinimum": 0
}
},
"additionalProperties": false,
"required": [
"bottomQuantile"
]
},
{
"type": "object",
"properties": {
"count": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"additionalProperties": false,
"required": [
"count"
]
},
{
"type": "object",
"properties": {
"fraction": {
"type": "number",
"exclusiveMinimum": 0
}
},
"additionalProperties": false,
"required": [
"fraction"
]
}
]
},
"neutrality": {
"type": "string",
"enum": [
"none",
"dollar",
"sector",
"beta",
"factor"
]
},
"neutralizeAgainst": {
"type": "object",
"properties": {
"field": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false,
"required": [
"field"
]
},
"maximumPositions": {
"type": "integer",
"exclusiveMinimum": 0
},
"maximumPositionWeight": {
"type": "number",
"exclusiveMinimum": 0
},
"minimumPositionWeight": {
"type": "number",
"minimum": 0
},
"maximumTurnover": {
"type": "number",
"minimum": 0
},
"maximumParticipation": {
"type": "number",
"exclusiveMinimum": 0
},
"volatilityLookbackSessions": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"additionalProperties": false,
"required": [
"method",
"long"
]
},
"execution": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1
},
"ambiguity": {
"type": "string",
"enum": [
"optimistic",
"pessimistic",
"deterministic-path",
"reject"
]
},
"costs": {
"type": "object",
"properties": {
"commission": {
"anyOf": [
{
"type": "object",
"properties": {
"model": {
"const": "none",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"model"
]
},
{
"type": "object",
"properties": {
"model": {
"const": "bps",
"type": "string"
},
"bps": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"model",
"bps"
]
},
{
"type": "object",
"properties": {
"model": {
"const": "perShare",
"type": "string"
},
"amountPerShare": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"model",
"amountPerShare"
]
},
{
"type": "object",
"properties": {
"model": {
"const": "fixed",
"type": "string"
},
"amount": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"model",
"amount"
]
}
],
"description": "A declarative commission model (fees.none / bps / perShare / fixed)"
},
"slippage": {
"anyOf": [
{
"type": "object",
"properties": {
"model": {
"const": "none",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"model"
]
},
{
"type": "object",
"properties": {
"model": {
"const": "bps",
"type": "string"
},
"bps": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"model",
"bps"
]
},
{
"type": "object",
"properties": {
"model": {
"const": "fixed",
"type": "string"
},
"perShare": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"model",
"perShare"
]
},
{
"type": "object",
"properties": {
"model": {
"const": "spread",
"type": "string"
},
"spread": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"model",
"spread"
]
}
],
"description": "A declarative slippage model (slippage.none / bps / fixed / spread)"
},
"spread": {
"anyOf": [
{
"type": "object",
"properties": {
"model": {
"const": "none",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"model"
]
},
{
"type": "object",
"properties": {
"model": {
"const": "halfSpreadBps",
"type": "string"
},
"bps": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"model",
"bps"
]
}
]
},
"marketImpact": {
"anyOf": [
{
"type": "object",
"properties": {
"model": {
"const": "none",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"model"
]
},
{
"type": "object",
"properties": {
"model": {
"const": "squareRoot",
"type": "string"
},
"coefficient": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"model",
"coefficient"
]
}
]
},
"latencySessions": {
"type": "integer",
"minimum": 0
},
"participation": {
"type": "number",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"partialFills": {
"type": "string",
"enum": [
"allow",
"reject"
]
},
"timeInForce": {
"type": "object",
"properties": {
"default": {
"type": "string",
"enum": [
"day",
"gtc"
]
},
"expireAtSessionClose": {
"type": "boolean"
}
},
"additionalProperties": false,
"required": [
"default",
"expireAtSessionClose"
]
},
"margin": {
"type": "object",
"properties": {
"buyingPowerMultiplier": {
"type": "number",
"exclusiveMinimum": 0
},
"initialMarginRate": {
"type": "number",
"minimum": 0
},
"maintenanceMarginRate": {
"type": "number",
"minimum": 0
},
"forcedLiquidation": {
"type": "string",
"enum": [
"none",
"close-largest-loss",
"pro-rata"
]
}
},
"additionalProperties": false,
"required": [
"buyingPowerMultiplier",
"initialMarginRate",
"maintenanceMarginRate",
"forcedLiquidation"
]
}
},
"additionalProperties": false,
"required": [
"label"
],
"description": "A declared execution policy over session bars (execution.declared): the label is the caller's claim; a caller fill model, session rules, and quote/order-book observations are SDK-only"
},
"transactionCostModel": {
"type": "object",
"properties": {
"commission": {
"anyOf": [
{
"type": "object",
"properties": {
"model": {
"const": "none",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"model"
]
},
{
"type": "object",
"properties": {
"model": {
"const": "bps",
"type": "string"
},
"bps": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"model",
"bps"
]
},
{
"type": "object",
"properties": {
"model": {
"const": "perShare",
"type": "string"
},
"amountPerShare": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"model",
"amountPerShare"
]
},
{
"type": "object",
"properties": {
"model": {
"const": "fixed",
"type": "string"
},
"amount": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"model",
"amount"
]
}
],
"description": "A declarative commission model (fees.none / bps / perShare / fixed)"
},
"slippage": {
"anyOf": [
{
"type": "object",
"properties": {
"model": {
"const": "none",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"model"
]
},
{
"type": "object",
"properties": {
"model": {
"const": "bps",
"type": "string"
},
"bps": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"model",
"bps"
]
},
{
"type": "object",
"properties": {
"model": {
"const": "fixed",
"type": "string"
},
"perShare": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"model",
"perShare"
]
},
{
"type": "object",
"properties": {
"model": {
"const": "spread",
"type": "string"
},
"spread": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"model",
"spread"
]
}
],
"description": "A declarative slippage model (slippage.none / bps / fixed / spread)"
}
},
"additionalProperties": false
},
"initialCapital": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Default 1,000,000"
},
"baseCurrency": {
"type": "string",
"minLength": 1,
"description": "Default 'USD'"
},
"window": {
"type": "object",
"properties": {
"fromTimestampMs": {
"type": "number"
},
"toTimestampMs": {
"type": "number"
}
},
"additionalProperties": false
},
"periodsPerYear": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Default 252"
},
"riskFreeRate": {
"type": "number",
"description": "Per-period; default 0"
},
"seed": {
"type": "integer",
"minimum": 0,
"description": "Seeds only the bootstrap confidence intervals; absent = none"
}
},
"additionalProperties": false,
"required": [
"dataset",
"universeHistory",
"signal",
"rebalanceSchedule",
"portfolioConstruction"
]
}Output schema
{
"type": "object",
"properties": {
"rebalances": {
"type": "array",
"items": {
"type": "object"
}
},
"holdings": {
"type": "array",
"items": {
"type": "object"
}
},
"points": {
"type": "array",
"items": {
"type": "object"
}
},
"returns": {
"type": "array",
"items": {
"type": "number"
}
},
"trades": {
"type": "array",
"items": {
"type": "object"
}
},
"fills": {
"type": "array",
"items": {
"type": "object"
}
},
"ledger": {
"type": "object",
"description": "The portfolio ledger snapshot (events)"
},
"timeline": {
"type": "object",
"description": "The ledger timeline"
},
"attribution": {
"type": "object"
},
"benchmark": {
"type": [
"object",
"null"
]
},
"performance": {
"type": "object",
"description": "The standard performance summary"
},
"performanceConfidence": {
"type": [
"object",
"null"
]
},
"finalValue": {
"type": "number"
},
"runId": {
"type": "string"
},
"assumptions": {
"type": "object",
"description": "Applied conventions"
},
"diagnostics": {
"type": "object",
"description": "Engine, method, warnings"
}
},
"required": [
"rebalances",
"holdings",
"points",
"returns",
"trades",
"fills",
"ledger",
"timeline",
"attribution",
"benchmark",
"performance",
"performanceConfidence",
"finalValue",
"runId",
"assumptions",
"diagnostics"
]
}