maxframe.liteframe.groupby.LiteFrameGroupBy.flat_apply#

LiteFrameGroupBy.flat_apply(func, *, dtypes=None, skip_infer=False, input_frame_type='pandas', subset=None, args=(), **kwargs)#

Apply func to each row within each group, expanding it to 0-N rows.

The groupby analogue of flat_apply(): the data is partitioned by the group keys, then func is applied per row within each group (not per group), returning / yielding 0-N rows. Non-subset columns are broadcast (repeated per output row) just like the non-groupby variant, and the per-group expanded frames are concatenated across groups in group-iteration order.

The effective columns (the schema the UDF sees) follow groupby semantics: groupby key columns are excluded by default (pandas 3.0), and an explicit groupby('k')[selection] restricts the UDF input to selection. subset is normalized against those effective columns; the rest are broadcast.

Parameters:
  • func (callable or callable class) –

    Function taking one row and returning / yielding 0-N rows (a DataFrame, generator, list-like, dict, Series, or scalar) or a tuple of such results (multiple outputs).

    If func is a class, it is instantiated once per group, __call__ is invoked per row, and close() (if defined) is always called at the end of each group.

  • dtypes (dict, pd.Series, or list, optional) – Expected output dtypes for the function-output columns only. A list of dicts/pd.Series declares multiple outputs.

  • skip_infer (bool, default False) – If True, skip dtype inference and produce an untyped output.

  • input_frame_type ({"pandas", "polars"}, default "pandas") – Frame type passed to func.

  • subset (list-like of str, optional) – Columns passed to func (relative to the effective groupby columns). Columns not in subset are broadcast.

  • args (tuple) – Extra positional arguments forwarded to func.

  • **kwargs – Extra keyword arguments forwarded to func.

Returns:

A new LiteFrame (or tuple of LiteFrames for multiple outputs) whose schema inserts the function-output columns at the position of the first subset column, with broadcast columns keeping their relative order; group keys are prepended when group_keys=True.

Return type:

LiteFrame or tuple of LiteFrame

Notes

The row count may change, so – like groupby.apply – hidden columns are dropped from the UDF input and not carried into the output. A callable-class UDF is instantiated fresh per group and its end flag fires on the last row of each group. Range columns follow the groupby path (they are dropped by the groupby shuffle, like other groupby functional ops).

See also

flat_apply

Apply a function per row, expanding to 0-N rows.

groupby_apply

Apply a function to each group as a whole frame.

Examples

>>> import maxframe.liteframe as mlf
>>> lf = mlf.LiteFrame({'key': ['a', 'a', 'b'], 'val': [1, 2, 3]})

Expand each row within its group (the group key key is excluded from the UDF input by default, so it is broadcast):

>>> result = lf.groupby('key').flat_apply(
...     lambda row: [{'n': row['val']}, {'n': row['val'] * 10}],
...     dtypes={'n': int})
>>> result.execute()
  key   n
0   a   1
1   a  10
2   a   2
3   a  20
4   b   3
5   b  30