skfolio.containers.AssetPanelView

class skfolio.containers.AssetPanelView(owner, observation_selector=None, _local_fields=None)

Observation-sliced view into an AssetPanel.

A view stores an observation selector, a reference to its owner and optional view-local fields. Owner field arrays are sliced lazily on access through fields, __getitem__ and get_field, so building a view never copies owner field data.

When the selector is a slice, all access remains zero-copy and composing nested views produces another zero-copy slice. When the selector is an integer or boolean array, NumPy fancy indexing is applied on access and the resulting arrays may be copies.

New fields can also be added directly to a view. These view-local fields are useful for derived data that only belongs to one slice (e.g. values computed for a cross-validation fold). They are stored on the view, do not modify the owner panel, and must have shape (n_view_observations, n_assets, …).

Parameters:

ownerAssetPanel

Panel that owns the underlying arrays.

observation_selectorslice or ndarray of integers, optional

Selector applied to the owner observation axis. Slices preserve zero-copy semantics. Integer arrays follow NumPy fancy-indexing semantics on access. The default (None) selects all observations.

_local_fieldsdict[str, BaseField], optional

View-local fields. This argument is for internal use. Use view[name] = value to add local fields.

Attributes:

active_mask

Active mask selected by the view.

asset_names

Asset labels.

estimation_mask

Estimation mask selected by the view.

fields

Lazy mapping of field objects with view-sized values.

n_assets

Number of assets.

n_observations

Number of observations in the view.

ndim

Number of dimensions used by scikit-learn sample indexing.

observation_selector

observations

Observation labels selected by the view.

owner

shape

Shape tuple used by scikit-learn sample indexing.

Methods

add_2d_field(name, values, *[, inactive_policy])	Add or replace a numeric 2D field.
add_3d_field(name, values, *, ...[, ...])	Add or replace a numeric 3D field.
add_categorical_field(name, values, *, levels)	Add or replace a 2D categorical field.
copy(*[, deep, copy_owner])	Return a copy of the view.
decode_categorical_field(name, *[, ...])	Decode a categorical field to labels.
get_field(name)	Return a local field or an owner field sliced to the view.
keys()	Return field names visible from the view.
sel_3d(name, *[, labels, groups])	Select entries from the third axis of a 3D field by label.
to_dataframe(*[, fields, assets, ...])	Convert 2D fields to a pandas DataFrame.
to_panel(*[, fields, deep])	Return a new AssetPanel for the view's selected observations.

See also

AssetPanel

Owning container.

AssetPanel.isel

Returns a view for observation-only selections.

AssetPanel.sel

Label-based equivalent of AssetPanel.isel.

property active_mask

Active mask selected by the view.

add_2d_field(name, values, *, inactive_policy=MISSING)

Add or replace a numeric 2D field.

Parameters:

namestr

Field name.

valuesarray-like of shape (n_observations, n_assets)

Numeric 2D values.

inactive_policyInactivePolicy, default=InactivePolicy.MISSING

Validation policy for values outside active_mask.

Returns:

selfBaseAssetPanel

The modified container.

add_3d_field(name, values, *, third_axis_name, third_axis_labels, third_axis_groups=None, inactive_policy=MISSING)

Add or replace a numeric 3D field.

This is a convenience wrapper around assigning a Field3D. The first two axes of values must be observations and assets with shape (n_observations, n_assets). The third axis stores a homogeneous block such as factors.

Parameters:

namestr

Field name.

valuesarray-like of shape (n_observations, n_assets, n_third_axis)

Numeric 3D values.

third_axis_namestr

Name describing what the third axis represents (e.g. factor).

third_axis_labelsarray-like of shape (n_third_axis,)

Labels for entries along the third axis such as factor names (e.g. size, momentum).

third_axis_groupsarray-like of shape (n_third_axis,), optional

Optional group label for each third-axis entry such as factor families (e.g. style, industry).

inactive_policyInactivePolicy, default=InactivePolicy.MISSING

Validation policy for values outside active_mask.

Returns:

selfBaseAssetPanel

The modified container.

add_categorical_field(name, values, *, levels, inactive_policy=MISSING)

Add or replace a 2D categorical field.

This is a convenience wrapper around assigning a FieldCategorical. The field values must be integer codes with shape (n_observations, n_assets). Code -1 is reserved for missing values. Code 0 selects levels[0], code 1 selects levels[1] and so on.

Parameters:

namestr

Field name.

valuesarray-like of integers, shape (n_observations, n_assets)

Integer category codes.

levelsarray-like of shape (n_levels,)

Category labels selected by codes 0, 1 and so on.

inactive_policyInactivePolicy, default=InactivePolicy.MISSING

Validation policy for codes outside active_mask.

Returns:

selfBaseAssetPanel

The modified container.

property asset_names

Asset labels.

copy(*, deep=False, copy_owner=True)

Return a copy of the view.

Parameters:

deepbool, default=False

If True, copy local field arrays and the observation selector when it is an ndarray.

copy_ownerbool, default=True

If True, copy the owner panel. If False, the copied view points to the same owner.

Returns:

viewAssetPanelView

Copied view.

decode_categorical_field(name, *, missing_label='MISSING')

Decode a categorical field to labels.

Parameters:

namestr

Name of a FieldCategorical field.

missing_labelstr, default=”MISSING”

Label assigned to missing or out-of-bound codes.

Returns:

decodedndarray

Decoded labels with shape (n_observations, n_assets).

property estimation_mask

Estimation mask selected by the view.

property fields

Lazy mapping of field objects with view-sized values.

Field objects are constructed on access and reuse the owner array sliced by observation_selector. Iterating through this mapping does not materialize sliced arrays for fields that are not accessed.

get_field(name)

Return a local field or an owner field sliced to the view.

Parameters:

namestr

Field name.

Returns:

fieldBaseField

Field object with first two axes matching the view.

keys()

Return field names visible from the view.

Returns:

nameslist of str

Union of view-local field names and owner field names. Local fields shadow owner fields with the same name. Owner field order is preserved and local-only fields are appended in insertion order.

property n_assets

Number of assets.

property n_observations

Number of observations in the view.

property ndim

Number of dimensions used by scikit-learn sample indexing.

property observations

Observation labels selected by the view.

sel_3d(name, *, labels=None, groups=None)

Select entries from the third axis of a 3D field by label.

Exactly one of labels or groups must be provided. Selecting a single label returns a 2D array with shape (n_observations, n_assets). Selecting multiple labels or any group returns a 3D array whose first two axes are unchanged.

Parameters:

namestr

Name of a Field3D.

labelsscalar, iterable, or None, optional

Third-axis labels to select.

groupsscalar, iterable, or None, optional

Third-axis group labels to select. The field must define third_axis_groups.

Returns:

valuesndarray

Selected values. A scalar labels selection returns 2D values. All other selections return 3D values.

property shape

Shape tuple used by scikit-learn sample indexing.

to_dataframe(*, fields=None, assets=None, output_format='long', decode_categoricals=True)

Convert 2D fields to a pandas DataFrame.

Parameters:

fieldsstr, iterable of str, or None, optional

Field names to include. If a single string is passed, the result is a simple field DataFrame with observations as index and assets as columns. If None, all 2D fields are included.

assetsstr, iterable of str, or None, optional

Asset labels to include. If None, all assets are included.

output_format{“long”, “wide”}, default=”long”

Output format used when fields is not a single string. In long format, rows are indexed by (observation, asset) and filtered by active_mask. In wide format, columns are indexed by (field, asset).

decode_categoricalsbool, default=True

If True, categorical codes are decoded to labels.

Returns:

dfpandas.DataFrame

DataFrame representation of the selected 2D fields.

to_panel(*, fields=None, deep=True)

Return a new AssetPanel for the view’s selected observations.

Parameters:

fieldsstr, iterable of str, or None, optional

Field names to include. If None, all visible fields are included.

deepbool, default=True

If True, copy field arrays and label arrays. If False, field arrays and labels may share memory with the view source. Masks are always copied so the returned panel owns independent lockable mask arrays.

Returns:

panelAssetPanel

Panel containing only the view’s observations and selected fields.