Skip to content

Index API Reference

msm.api.indices

FormulaIndex

Bases: BaseModel

Canonical Index identity with one persisted formula version and its inputs.

activate()

Activate this draft and retire the open predecessor atomically.

calculate_from_sources(*, start, end, times=None)

Read the pinned MetaTables over one bounded interval and calculate.

retire(*, valid_to=None)

Retire this formula version at an exclusive validity boundary.

upsert(*, unique_identifier, index_type, display_name, definition, inputs, value_format, value_suffix=None, description=None, metadata_json=None) classmethod

Persist an idempotent Formula Index and exact source table bindings.

IncompleteFormulaObservationsError

Bases: IndexFormulaError

Raised when a formula configured with fail encounters missing observations.

Index

Bases: MarketsMetaTableRow

User-facing market index reference row.

list_page(request=None, **kwargs) classmethod

Return a typed, counted Index catalog page.

List related MetaTables, defaulting to numeric time-series contracts.

IndexCreate

Bases: BaseModel

Payload for creating an index reference row.

IndexFormula

Bases: BaseModel

Self-contained formula contract for evaluating historical observations.

evaluate_historical(observations, *, times=None)

Evaluate caller-supplied historical series without persisted Index state.

from_definition(definition, inputs) classmethod

Build a pure historical formula from one persisted definition contract.

IndexFormulaDefinition

Bases: BaseModel

Immutable versioned point-in-time formula definition.

IndexFormulaError

Bases: ValueError

Base strict formula calculation failure.

IndexFormulaEvaluation

Bases: BaseModel

Historical formula values and their latest source observation timestamps.

IndexFormulaInput

Bases: BaseModel

Exact public source binding for one formula reference.

IndexFormulaResult

Bases: BaseModel

Pure formula result in canonical Index observation shape.

IndexFormulaSourceReference

Bases: BaseModel

Stable source identity used by a formula input.

IndexType

Bases: MarketsMetaTableRow

Typed row for the index type registry.

IndexTypeCreate

Bases: BaseModel

Payload for creating an index type registry row.

IndexTypeUpdate

Bases: BaseModel

Payload for updating mutable index type fields.

IndexTypeUpsert

Bases: IndexTypeCreate

Payload for inserting or updating an index type by registry key.

IndexUpdate

Bases: BaseModel

Payload for updating mutable index reference fields.

IndexUpsert

Bases: IndexCreate

Payload for inserting or updating an index by unique identifier.

calculate_formula_index(*, index_identifier, definition, inputs, observations, times=None)

Calculate one formula definition without querying or mutating platform state.

normalize_index_type(index_type)

Return the canonical index type key stored by the typed API.

msm.api.formula_indices

FormulaIndex

Bases: BaseModel

Canonical Index identity with one persisted formula version and its inputs.

activate()

Activate this draft and retire the open predecessor atomically.

calculate_from_sources(*, start, end, times=None)

Read the pinned MetaTables over one bounded interval and calculate.

retire(*, valid_to=None)

Retire this formula version at an exclusive validity boundary.

upsert(*, unique_identifier, index_type, display_name, definition, inputs, value_format, value_suffix=None, description=None, metadata_json=None) classmethod

Persist an idempotent Formula Index and exact source table bindings.

msm.analytics.indices

Strict Index formula calculation and independent spread analytics.

FormulaSyntaxError

Bases: ValueError

Raised when a formula uses syntax outside the supported arithmetic grammar.

IncompleteFormulaObservationsError

Bases: IndexFormulaError

Raised when a formula configured with fail encounters missing observations.

IndexFormula

Bases: BaseModel

Self-contained formula contract for evaluating historical observations.

evaluate_historical(observations, *, times=None)

Evaluate caller-supplied historical series without persisted Index state.

from_definition(definition, inputs) classmethod

Build a pure historical formula from one persisted definition contract.

IndexFormulaDefinition

Bases: BaseModel

Immutable versioned point-in-time formula definition.

IndexFormulaError

Bases: ValueError

Base strict formula calculation failure.

IndexFormulaEvaluation

Bases: BaseModel

Historical formula values and their latest source observation timestamps.

IndexFormulaInput

Bases: BaseModel

Exact public source binding for one formula reference.

IndexFormulaResult

Bases: BaseModel

Pure formula result in canonical Index observation shape.

IndexFormulaSourceReference

Bases: BaseModel

Stable source identity used by a formula input.

PairSpreadMetrics dataclass

Statistical summary for a two-leg spread.

Values are expressed in the same units as the supplied spread series. z_score is the latest observation's standard score against the full aligned history. half_life_periods is estimated from an AR(1)-style regression and is None when the history does not show mean reversion.

SpreadSeries dataclass

Aligned spread time series built from two caller-supplied legs.

values is computed as leg_a - hedge_ratio * leg_b. Inputs are copied into a new pandas Series, so submitted Series or arrays are not mutated. The helper makes no assumption about asset class, currency, vendor source, curve identity, or portfolio ownership.

build_pair_history_frame(leg_a, leg_b, *, hedge_ratio=1.0, leg_a_name='leg_a', leg_b_name='leg_b')

Return an aligned two-leg history with a computed spread column.

The returned frame has stable columns leg_a, leg_b, and spread. The spread is leg_a - hedge_ratio * leg_b. Observations are aligned by pandas index when Series are supplied and by positional index otherwise. Missing or non-finite rows are dropped from the returned copy.

Raises:

Type Description
ValueError

If hedge_ratio is not finite or there are no overlapping finite observations after alignment.

build_spread_series(leg_a, leg_b, *, hedge_ratio=1.0, name='spread', leg_a_name='leg_a', leg_b_name='leg_b', metadata_json=None)

Build a copy-based spread series from two aligned numeric legs.

The output values are leg_a - hedge_ratio * leg_b. Submitted Series and sequences are not mutated. The helper intentionally does not know whether the legs represent bonds, equities, indexes, commodities, options, or synthetic strategy marks.

calculate_formula_index(*, index_identifier, definition, inputs, observations, times=None)

Calculate one formula definition without querying or mutating platform state.

estimate_hedge_ratio(leg_a, leg_b, *, method='price_ols', include_intercept=True)

Estimate the hedge ratio that maps leg B onto leg A.

price_ols regresses aligned levels. return_ols regresses aligned percentage changes after pairwise alignment. The returned beta is suitable for leg_a - beta * leg_b spread construction. Inputs are copied and not mutated.

Raises:

Type Description
ValueError

If the method is unsupported or the hedge leg has no usable variation.

ornstein_uhlenbeck_forecast_cone(spread, *, horizon, std_multipliers=(1.0, 2.0))

Build a deterministic OU-style forecast cone from a spread history.

The helper estimates a univariate AR(1) approximation to a mean-reverting process and returns expected spread levels plus standard-deviation bands for horizons 1..horizon. Output units match the submitted spread series.

This implementation has no heavy optional dependency. More advanced volatility models should call require_optional_dependency(...) in their own helper before importing dependency-heavy packages.

Raises:

Type Description
ValueError

If fewer than three finite observations are supplied, horizon is not positive, or the fitted process is not mean reverting.

pair_spread_metrics(leg_a, leg_b, *, hedge_ratio=None, hedge_ratio_method='price_ols', spread_name='spread', leg_a_name='leg_a', leg_b_name='leg_b', ddof=1)

Return cross-asset pair metrics for an aligned two-leg spread.

When hedge_ratio is omitted, the ratio is estimated from the submitted history. No backend data is resolved and no instrument state is modified.

require_optional_dependency(module_name, *, feature)

Raise a clear error when a dependency-heavy optional feature is missing.

Parameters:

Name Type Description Default
module_name str

Importable Python module required by the optional feature.

 required
feature str

Human-readable feature name shown in the error message.

 required

Raises:

Type Description
ImportError

If module_name is not importable in the current environment.

rolling_spread_zscore(spread, *, window, min_periods=None, ddof=1)

Return rolling z-scores for a spread series.

The returned Series is a new object with the submitted spread's index. Missing or non-finite input observations propagate as missing output values.

spread_zscore(spread, *, ddof=1, min_observations=2)

Return the latest z-score for a spread series.

Units match the submitted spread series. None is returned when there are too few finite observations or the historical standard deviation is zero.

spread_zscore_matrix(spreads, *, ddof=1, min_observations=2)

Return latest z-score metrics for multiple spread series.

The result is indexed by spread name with columns latest_spread, mean, standard_deviation, z_score, and observation_count. This function is cross-asset: callers decide whether each spread represents an equity pair, yield spread, commodity calendar spread, volatility spread, or another strategy mark.