Creation¶

Functions for constructing frame-labeled arrays. Both are re-exported at the top level, so they are also available as pld.from_values_and_labels and pld.from_frame. For a narrative introduction see Eager arrays and Lazy arrays.

from_values_and_labels ¶

from_values_and_labels(values: AnyArray, labels: Iterable[DataFrame | None], *, implementation: Literal[LAZY]) -> LazyFrameLabeledArray[DataFrame[DataFrame], LazyFrame[LazyFrame]]

from_values_and_labels(values: AnyArray, labels: Iterable[IntoDataFrameT | None], *, implementation: Literal[LAZY]) -> LazyFrameLabeledArray[DataFrame[IntoDataFrameT], Any]

from_values_and_labels(values: SomeValueArray, labels: Iterable[IntoDataFrameT | None], *, implementation: Literal[EAGER] = ...) -> EagerFrameLabeledArray[DataFrame[IntoDataFrameT], SomeValueArray]

from_values_and_labels(values: ndarray, labels: Iterable[IntoDataFrameT | None], *, implementation: Literal[EAGER] = ...) -> FrameLabeledArray[DataFrame[IntoDataFrameT], NumpyArray]

from_values_and_labels(values: Array, labels: Iterable[IntoDataFrameT | None], *, implementation: Literal[EAGER] = ...) -> FrameLabeledArray[DataFrame[IntoDataFrameT], JaxArray]

from_values_and_labels(values: AnyArray, labels: Iterable[IntoDataFrameT | None], *, implementation: FrameLabeledArrayImplementation = EAGER) -> FrameLabeledArray[DataFrame[IntoDataFrameT], Any]

Create a frame-labeled array from a value array and a label frame per axis.

There is one label frame per axis, so the number of frames must equal the number of dimensions of values, and the number of rows of each frame must match the size of the corresponding axis. A frame may have more than one column, which attaches several labels to the same axis. An axis of size 1 may be left unlabeled by passing None for its frame, which marks it as broadcastable.

Parameters:

Name	Type	Description	Default
`values`	`AnyArray`	The values to label. Any array following the array API is accepted by the eager implementation. The lazy implementation converts the values to NumPy.	required
`labels`	`Iterable[IntoDataFrameT \| None]`	One label frame (or None) per axis, in axis order. Each frame is anything Narwhals can wrap, such as a Polars DataFrame.	required
`implementation`	`FrameLabeledArrayImplementation`	The implementation to build. Defaults to EAGER.	`EAGER`

Returns:

Type	Description
`FrameLabeledArray[DataFrame[IntoDataFrameT], Any]`	A frame-labeled array of the requested implementation, wrapping the given values
`FrameLabeledArray[DataFrame[IntoDataFrameT], Any]`	and labels.

from_frame ¶

from_frame(frame: DataFrame[DataFrame], *, value_column: str = 'value', implementation: Literal[LAZY] = ...) -> LazyFrameLabeledArray[DataFrame[DataFrame], LazyFrame[LazyFrame]]

from_frame(frame: DataFrame[IntoDataFrameT], *, value_column: str = 'value', implementation: Literal[LAZY] = ...) -> LazyFrameLabeledArray[DataFrame[IntoDataFrameT], Any]

from_frame(frame: DataFrame[IntoDataFrameT], *, value_column: str = 'value', implementation: FrameLabeledArrayImplementation = LAZY) -> FrameLabeledArray[DataFrame[IntoDataFrameT], ndarray]

Create a one-dimensional frame-labeled array from a single frame in long format.

One column of the frame holds the values, and the remaining columns become the labels of the single axis. The resulting array is always one-dimensional. To obtain a higher-dimensional array, use from_values_and_labels or reshape with pivot.

Parameters:

Name	Type	Description	Default
`frame`	`DataFrame[IntoDataFrameT]`	A Narwhals DataFrame in long format, with one row per array element.	required
`value_column`	`str`	The name of the column holding the values. Defaults to "value".	`'value'`
`implementation`	`FrameLabeledArrayImplementation`	The implementation to build. Defaults to LAZY, since keeping the data in its DataFrame backend is the typical reason to start from a frame. The EAGER implementation is not yet supported by this function.	`LAZY`

Returns:

Type	Description
`FrameLabeledArray[DataFrame[IntoDataFrameT], ndarray]`	A one-dimensional frame-labeled array of the requested implementation.

Raises:

Type	Description
`NotImplementedError`	If the EAGER implementation is requested.