neuralib.util.dataframe.DataFrameWrapper

class neuralib.util.dataframe.DataFrameWrapper[source]

Bases: object

Abstract wrapper class for a polars.DataFrame, enabling convenient and composable dataframe operations in a subclassable, object-oriented interface.

This base class is intended to be inherited by custom data structures whose core data is represented as a polars.DataFrame. It provides a suite of standard dataframe operations (e.g., filtering, sorting, renaming, joining) that return the wrapper instance (Self), preserving method chaining and encapsulation.

This allows users to write clean, expressive logic using their custom wrapper class while still leveraging the full power of Polars.

Subclasses must implement the dataframe method to get or set the internal polars.DataFrame.

Examples

A minimal subclass that wraps a Polars DataFrame:

>>> class MyTable(DataFrameWrapper):
...     def __init__(self, data: pl.DataFrame):
...         self._data = data
...
...     def dataframe(self, dataframe: pl.DataFrame = None, may_inplace=True):
...         if dataframe is None:
...             return self._data
...         if may_inplace:
...             self._data = dataframe
...             return self
...         else:
...             return MyTable(dataframe)

>>> df = pl.DataFrame({'a': [1, 2, 3], 'b': [10, 20, 30]})
>>> t = MyTable(df)
>>> t = t.filter(pl.col("a") > 1).rename({"b": "B"})
>>> print(t.dataframe())
shape: (2, 2)
┌─────┬─────┐
│ a   │ B   │
├─────┼─────┤
│ 2   │ 20  │
│ 3   │ 30  │
└─────┴─────┘

Notes

All supported operations delegate to the underlying polars.DataFrame and return the modified wrapper instance.
The actual dataframe storage and logic is delegated to subclasses via the abstract dataframe() getter/setter method.
This class is designed for flexible and extensible use in applications such as data modeling, pipelines, or typed schema handling.

Supported Operations

Accessors: columns, schema, __len__, __array__, __dataframe__
Indexing: __getitem__
Structure: filter, drop, drop_nulls, fill_null, fill_nan, select,
with_columns, with_row_index, rename, slice, head, tail, limit, sort
Aggregation: group_by
Partitioning: partition_by
Joining: join
Transformation: pipe, clone, lazy

See Also

polars.DataFrame : The underlying DataFrame API polars.Expr : Expression system used throughout the API

__init__()

Methods

`__init__`()
`clear`([n])	See polars.DataFrame.clear.
`clone`()	Clone the wrapper.
`dataframe`(-> ~polars.dataframe.frame.DataFrame)	Getter/setter for the internal Polars DataFrame.
`drop`(*columns[, strict])	See polars.DataFrame.drop.
`drop_nulls`(subset)	See polars.DataFrame.drop_nulls.
`fill_nan`([value])	See polars.DataFrame.fill_nan.
`fill_null`([value, strategy, limit])	See polars.DataFrame.fill_null.
`filter`(predicates, *constraints)	See polars.DataFrame.filter.
`group_by`(*by[, maintain_order])	See polars.DataFrame.group_by.
`head`([n])	See polars.DataFrame.head.
`join`(other, on[, how, left_on, right_on, ...])	See polars.DataFrame.join.
`lazy`()	Wrap dataframe in a lazy wrapper.
`limit`([n])	See polars.DataFrame.limit.
`partition_by`(-> list[Self])	See polars.DataFrame.partition_by.
`pipe`(function, args, *kwargs)	See polars.DataFrame.pipe.
`rename`(mapping)	See polars.DataFrame.rename.
`select`(exprs, *named_exprs)	See polars.DataFrame.select.
`slice`(offset[, length])	See polars.DataFrame.slice.
`sort`(by, *more_by[, descending, nulls_last, ...])	See polars.DataFrame.sort.
`tail`([n])	See polars.DataFrame.tail.
`with_columns`(exprs, *named_exprs)	See polars.DataFrame.with_columns.
`with_row_index`([name, offset])	See polars.DataFrame.with_row_index.

Attributes

`columns`	See polars.DataFrame.columns.
`schema`	See polars.DataFrame.schema.

abstractmethod dataframe() → DataFrame[source]

abstractmethod dataframe(dataframe: DataFrame, may_inplace: bool = True) → Self

Getter/setter for the internal Polars DataFrame.

Parameters:

dataframe (pl.DataFrame | None) – Optional new dataframe to set.
may_inplace (bool) – If True, update current instance. Otherwise, return new instance.

Returns:

The current dataframe or a modified wrapper instance.

Return type:

pl.DataFrame | Self

property columns: list[str]: See polars.DataFrame.columns.

property schema: Schema: See polars.DataFrame.schema.

lazy()[source]

Wrap dataframe in a lazy wrapper.

Return type:: LazyDataFrameWrapper[Self]

rename(mapping)[source]

See polars.DataFrame.rename.

Parameters:: mapping (dict[str, str] | Callable[[str], str])
Return type:: Self

filter(*predicates, **constraints)[source]

See polars.DataFrame.filter.

Parameters:

predicates (pty.IntoExprColumn | Iterable[pty.IntoExprColumn] | bool | list[bool] | np.ndarray)
constraints (Any)

Return type:

Self

slice(offset, length=None)[source]

See polars.DataFrame.slice.

Parameters:

offset (int)
length (int | None)

Return type:

Self

head(n=5)[source]

See polars.DataFrame.head.

Parameters:: n (int)
Return type:: Self

tail(n=5)[source]

See polars.DataFrame.tail.

Parameters:: n (int)
Return type:: Self

limit(n=5)[source]

See polars.DataFrame.limit.

Parameters:: n (int)
Return type:: Self

sort(by, *more_by, descending=False, nulls_last=False, multithreaded=True, maintain_order=False)[source]

See polars.DataFrame.sort.

Parameters:

by (pty.IntoExpr | Iterable[pty.IntoExpr])
more_by (pty.IntoExpr)
descending (bool | Sequence[bool])
nulls_last (bool | Sequence[bool])
multithreaded (bool)
maintain_order (bool)

Return type:

Self

drop(*columns, strict=True)[source]

See polars.DataFrame.drop.

Parameters:

columns (pty.ColumnNameOrSelector | Iterable[pty.ColumnNameOrSelector])
strict (bool)

Return type:

Self

drop_nulls(subset)[source]

See polars.DataFrame.drop_nulls.

Parameters:: subset (pty.ColumnNameOrSelector | Collection[pty.ColumnNameOrSelector])
Return type:: Self

fill_null(value=None, strategy=None, limit=None, **kwargs)[source]

See polars.DataFrame.fill_null.

Parameters:

value (Any | pl.Expr | None)
strategy (pty.FillNullStrategy | None)
limit (int | None)

Return type:

Self

fill_nan(value=None)[source]

See polars.DataFrame.fill_nan.

Parameters:: value (pl.Expr | int | float | None)
Return type:: Self

clear(n=5)[source]

See polars.DataFrame.clear.

Parameters:: n (int)
Return type:: Self

clone()[source]

Clone the wrapper.

Return type:: Self

partition_by(by: pty.ColumnNameOrSelector | Iterable[pty.ColumnNameOrSelector], *more_by: pty.ColumnNameOrSelector, maintain_order: bool = True, include_key: bool = True, as_dict: Literal[False] = False) → list[Self][source]
partition_by(by: pty.ColumnNameOrSelector | Iterable[pty.ColumnNameOrSelector], *more_by: pty.ColumnNameOrSelector, maintain_order: bool = ..., include_key: bool = ..., as_dict: Literal[True]) → dict[tuple[object, ...], Self]: See polars.DataFrame.partition_by.

select(*exprs, **named_exprs)[source]

See polars.DataFrame.select.

Parameters:

exprs (pty.IntoExpr | Iterable[pty.IntoExpr])
named_exprs (pty.IntoExpr)

Return type:

Self

with_columns(*exprs, **named_exprs)[source]

See polars.DataFrame.with_columns.

Parameters:

exprs (pty.IntoExpr | Iterable[pty.IntoExpr])
named_exprs (pty.IntoExpr)

Return type:

Self

with_row_index(name='index', offset=0)[source]

See polars.DataFrame.with_row_index.

Parameters:

name (str)
offset (int)

Return type:

Self

join(other, on, how='inner', *, left_on=None, right_on=None, suffix='_right', validate='m:m', join_nulls=False, coalesce=None)[source]

See polars.DataFrame.join.

Parameters:

other (pl.DataFrame | DataFrameWrapper)
on (str | pl.Expr | Sequence[str | pl.Expr])
how (pty.JoinStrategy)
suffix (str)
validate (pty.JoinValidation)
join_nulls (bool)
coalesce (bool | None)

Return type:

Self

pipe(function, *args, **kwargs)[source]

See polars.DataFrame.pipe.

Parameters:

function (Callable[Concatenate[pl.DataFrame, P], pl.DataFrame])
args (P.args)
kwargs (P.kwargs)

Return type:

Self

group_by(*by, maintain_order=False, **named_by)[source]

See polars.DataFrame.group_by.

Parameters:

by (pty.IntoExpr | Iterable[pty.IntoExpr])
maintain_order (bool)
named_by (pty.IntoExpr)

Return type:

GroupBy