maxframe.liteframe.LiteFrame.flat_apply#
- LiteFrame.flat_apply(func, *, dtypes=None, skip_infer=False, input_frame_type='pandas', subset=None, args=(), **kwargs)#
Apply
functo each row, expanding it to 0-N output rows.flat_applyis the LiteFrame analogue ofmf.flatmap:funcreceives one row (apandas.Seriesforinput_frame_type="pandas", a single-rowpolars.DataFrameforinput_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
subsetare broadcast (repeated for every output row produced from the same input row), mirroringpandas.DataFrame. explode. The function-output columns are inserted at the position where the firstsubsetcolumn 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
funcis a class, it is instantiated once per chunk,__call__is invoked per row, andclose()(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 insubsetare 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
subsetcolumn, with broadcast columns keeping their relative order.- Return type:
Notes
The row count may change (1:N expansion), so – like
apply(axis=0)andapply_chunk– hidden columns are dropped from the UDF input and not carried into the output. Users who need a hidden column to travel throughflat_applyshouldselectit first. Range columns are materialized to physicalint64before the UDF runs; a broadcast range column becomes a regularint64column in the output.See also
apply_chunkApply 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
subsetto broadcast non-subset columns (Bis 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
Noneto 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