skfolio.containers.Field3D#

class skfolio.containers.Field3D(values, third_axis_name, third_axis_labels, third_axis_groups=None, *, inactive_policy=MISSING)[source]#

Numeric 3D field with axes (observations, assets, third_axis).

Use this field for homogeneous tensors (e.g. factor exposures). The third-axis metadata is stored on the field. The array is stored physically in 3D so that operations along any axis remain vectorized and avoid stacking many 2D arrays which is expensive for large panels. When you need repeated tensor operations, prefer a Field3D instead of multiple Field2D.

Parameters:

valuesndarray of shape (n_observations, n_assets, n_third_axis): Numeric 3D values. Object dtype is rejected.
third_axis_namestr: Name describing what the third axis represents (e.g. factor).
third_axis_labelsndarray of shape (n_third_axis,): Labels for entries along the third axis such as factor names (size, momentum). Labels must be unique.
third_axis_groupsndarray of shape (n_third_axis,), optional: Optional group label for each third-axis entry such as factor families (e.g. style, industry, country).

Attributes:

dtype: Dtype of the underlying values.
inactive_policy
is_3d: Whether or not the field is a 3D field.
is_categorical: Whether or not the field is a categorical field.
missing_mask: Return a boolean mask indicating missing entries.
n_assets: Number of assets.
n_observations: Number of observations.
ndim: Number of dimensions of the underlying values.
shape: Shape of the underlying values.
third_axis_groups
third_axis_labels
third_axis_name
values

Methods

`copy`(*[, deep])	Return a copy of the field.
`with_values`(values)	Return a field of the same type with replacement values.

copy(*, deep=False)#

Return a copy of the field.

Parameters:

deepbool, default=False: If True, copy NumPy arrays stored by the field. If False, reuse the same array objects.

Returns:

fieldBaseField: Field instance of the same concrete class.

property dtype#: Dtype of the underlying values.

property is_3d#: Whether or not the field is a 3D field.

property is_categorical#: Whether or not the field is a categorical field.

property missing_mask#

Return a boolean mask indicating missing entries.

Returns:

maskndarray of bool: Boolean array with the same shape as values. Entries are True where values is NaN for floating-point fields and False elsewhere. Non-floating fields without a missing-value convention return an all-False mask; subclasses override this method when they define their own convention.

property n_assets#: Number of assets.

property n_observations#: Number of observations.

property ndim#: Number of dimensions of the underlying values.

property shape#: Shape of the underlying values.

with_values(values)#

Return a field of the same type with replacement values.

Metadata arrays are reused. The replacement values are validated by the concrete field class constructor.

Parameters:

valuesarray-like: Replacement field values.

Returns:

fieldBaseField: Field instance of the same concrete class.