skfolio.seriation.SpectralSeriation#

class skfolio.seriation.SpectralSeriation[source]#

Sort assets by spectral coordinates with persistent orientation.

The spectral approach is based on Atkins, Boman and Hendrickson [1]. Each partial_fit recomputes coordinates from the complete current distance matrix. Previous coordinates and ordering align the orientation and resolve ties on assets shared with the previous snapshot. fit starts a new ordering and discards this history.

For recursive portfolio allocation, spectral seriation can reduce turnover compared with hierarchical seriation. It derives coordinates from the full distance matrix without discrete cluster merges. Small distance changes can then leave allocation groups unchanged. Preserving the previous solution through partial_fit also avoids arbitrary changes between equivalent spectral solutions. See Seriation and Turnover for the benefits and limits.

Attributes:

ordering_ndarray of shape (n_investable_assets,): Positions in the original input matrix, listed in the computed order. Each investable asset appears exactly once. Empty when no assets are investable. A single investable asset produces its original position.
investable_mask_ndarray of shape (n_assets,): Boolean mask selecting investable assets for the current ordering.
coordinates_ndarray of shape (n_assets,): Spectral coordinates, with NaN for non-investable assets. The vector over investable assets has unit Euclidean norm when at least two assets are investable. A single investable asset has coordinate zero.
eigenvalue_multiplicity_int: Dimension of the selected eigenspace. Zero for fewer than two investable assets.
spectral_gap_float: Relative separation of the two largest nonconstant eigenvalues of the scaled Laplacian, \((\lambda_1 - \lambda_2) / \lambda_1\). Zero when these eigenvalues are numerically tied. NaN for fewer than three investable assets or when all distances are zero.
n_features_in_int: Number of assets in the full schema.
feature_names_in_ndarray of shape (n_features_in_,): Asset names, defined when the input names are all strings.

Methods

`fit`(X[, y])	Start a new ordering from a distance snapshot.
`get_metadata_routing`()	Get metadata routing of this object.
`get_params`([deep])	Get parameters for this estimator.
`partial_fit`(X[, y])	Order a replacement snapshot aligned to the previous ordering.
`set_params`(**params)	Set the parameters of this estimator.

Notes

For the investable distance matrix \(D\), form \(B=(D/\max(D))^2\) and \(L=\mathrm{diag}(B\mathbf{1})-B\). When all distances are zero, set \(B=0\). Select the largest-eigenvalue eigenspace of \(L\) on the subspace orthogonal to the constant vector. For all-zero distances, this is the whole nonconstant subspace.

The selected subspace is the Fiedler eigenspace of the unnormalized Laplacian of the affinity \(A=\mathbf{1}\mathbf{1}^{\mathsf{T}}-B\). This also holds for repeated eigenvalues. With angular distances, it is the same Fiedler subspace as the dense affinity \((1+\rho)/2\) used by Peter Cotton’s allocation package [2].

Repeated eigenspaces use projected previous coordinates, or a deterministic projected anchor when history is unavailable. Ties use input positions. Surviving assets preserve their previous relative order within coordinate ties. Asset names are used for schema validation and do not affect the computed coordinates or ordering.

Coordinates can change sharply when the leading eigenvalues are close, and sorting can change allocation groups when coordinates cross. The estimator does not minimize turnover or guarantee continuous weights.

A small spectral_gap_ indicates weak separation of the leading direction. A repeated leading eigenvalue gives a zero gap even if its eigenspace is separated from the remaining directions. Small perturbations can split that eigenvalue and change the selected coordinates. The gap is not a turnover prediction.

Dense decomposition costs \(O(k^3)\) time and \(O(k^2)\) working memory for \(k\) investable assets. Only \(O(n_{assets})\) orientation history persists.

References

[1]

“A Spectral Algorithm for Seriation and the Consecutive Ones Problem”. Jonathan E. Atkins, Erik G. Boman and Bruce Hendrickson, SIAM Journal on Computing (1998).

[2]

“allocation: Streaming online portfolio construction”. Peter Cotton (2026). microprediction/allocation

fit(X, y=None)[source]#

Start a new ordering from a distance snapshot.

Parameters:

Xarray-like of shape (n_assets, n_assets): Distance snapshot. NaN diagonal entries mark non-investable assets.
yIgnored: Not used, present for API consistency by convention.

Returns:

selfSpectralSeriation: Fitted estimator.

get_metadata_routing()#

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:

routingMetadataRequest: A MetadataRequest encapsulating routing information.

get_params(deep=True)#

Get parameters for this estimator.

Parameters:

deepbool, default=True: If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

paramsdict: Parameter names mapped to their values.

partial_fit(X, y=None)[source]#

Order a replacement snapshot aligned to the previous ordering.

Recompute spectral coordinates from the complete current distance matrix. Use fit to change the full asset universe or discard history.

Parameters:

Xarray-like of shape (n_assets, n_assets): Complete distance matrix with the same assets in the same row and column order as previous calls. NaN diagonal entries mark assets that are currently non-investable.
yIgnored: Not used, present for API consistency by convention.

Returns:

selfSpectralSeriation: Updated estimator.

set_params(**params)#

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:

**paramsdict: Estimator parameters.

Returns:

selfestimator instance: Estimator instance.