pyvallocation.utils.weights module

Helpers for working with weight matrices/series across the library.

The routines in this module centralise the logic that used to live inside pyvallocation.ensembles so other modules (frontiers, stress utilities, discrete allocation, etc.) can reuse the exact same conversions and label handling.

pyvallocation.utils.weights.ensure_samples_matrix(sample_portfolios, *, allow_empty=False)[source]

Convert sample portfolios into a (n_assets, n_samples) float array.

Parameters:

  • sample_portfolios – Array/Series/DataFrame where columns correspond to portfolios.

  • allow_empty – When True the helper permits zero columns (useful for tests).

Returns:

Tuple[np.ndarray, Optional[List[str]], Optional[List[str]]] – (matrix, asset_names, sample_names).

Parameters:

  • sample_portfolios (numpy.ndarray | pandas.DataFrame | pandas.Series)

  • allow_empty (bool)

Return type:

Tuple[numpy.ndarray, List[str] | None, List[str] | None]

pyvallocation.utils.weights.normalize_weights(weights, num_samples, sample_names=None)[source]

Normalise a weight vector while supporting pandas-labelled inputs.

When weights is None the helper returns a uniform allocation.

Parameters:

  • weights – Optional weights vector or Series.

  • num_samples – Expected number of samples.

  • sample_names – Optional sample labels for alignment.

Returns:

np.ndarray – Normalized weight vector summing to one.

Parameters:

  • weights (Sequence[float] | pandas.Series | None)

  • num_samples (int)

  • sample_names (List[str] | None)

Return type:

numpy.ndarray

pyvallocation.utils.weights.wrap_exposure_vector(vector, asset_names, *, label)[source]

Return a pandas Series when asset names are provided, else fall back to ndarray.

Parameters:

  • vector – Exposure vector.

  • asset_names – Optional asset labels.

  • label – Optional Series name.

Returns:

Union[np.ndarray, pd.Series] – Wrapped exposure vector.

Parameters:

  • vector (numpy.ndarray | Sequence[float])

  • asset_names (List[str] | None)

  • label (str | None)

Return type:

numpy.ndarray | pandas.Series