maxframe.liteframe.LiteFrame.flat_apply#

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

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

flat_apply is the LiteFrame analogue of mf.flatmap: func receives one row (a pandas.Series for input_frame_type="pandas", a single-row polars.DataFrame for input_frame_type="polars") and returns / yields 0-N new rows or a new DataFrame. Each returned row is aligned to the function-output columns (dict / named-Series by key/label, list / tuple positionally, scalar to a single column).

Columns not in subset are broadcast (repeated for every output row produced from the same input row), mirroring pandas.DataFrame. explode. The function-output columns are inserted at the position where the first subset column originally located; broadcast columns keep their relative order around the func-out block.

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 chunk, __call__ is invoked per row, and close() (if defined) is always called at the end of the chunk.

  • dtypes (dict, pd.Series, or list, optional) – Expected output dtypes for the function-output columns only (the broadcast columns inherit their input dtypes automatically). A list of dicts/pd.Series declares multiple outputs. If omitted, inferred from func’s return annotation or a mock call.

  • 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. None (default) passes all visible columns (no broadcast columns, pure flatmap behaviour). Columns not in subset are broadcast across the expanded output rows.

  • 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.

Return type:

LiteFrame or tuple of LiteFrame

Notes

The row count may change (1:N expansion), so – like apply(axis=0) and apply_chunk – hidden columns are dropped from the UDF input and not carried into the output. Users who need a hidden column to travel through flat_apply should select it first. Range columns are materialized to physical int64 before the UDF runs; a broadcast range column becomes a regular int64 column in the output.

See also

apply_chunk

Apply a function per execution chunk.

Examples

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

Expand each row into multiple rows (1:N), like explode:

>>> result = lf.flat_apply(lambda row: [{'n': row['a']}, {'n': row['a'] * 10}],
...                        subset=['a'], dtypes={'n': int})
>>> result.execute()
    n  b
0   1  x
1  10  x
2   2  y
3  20  y

Use subset to broadcast non-subset columns (B is repeated for every expanded row):

>>> result = lf.flat_apply(lambda row: [row['a'], row['a'] + 1],
...                        subset=['a'], dtypes={'n': int})
>>> result.execute()
   n  b
0  1  x
1  2  x
2  2  y
3  3  y

Return None to drop an input row (0 output rows):

>>> result = lf.flat_apply(
...     lambda row: [{'n': row['a']}] if row['a'] > 1 else None,
...     subset=['a'], dtypes={'n': int})
>>> result.execute()
   n  b
0  2  y