maxframe 2.4.0rc1__cp312-cp312-win32.whl

maxframe/dataframe/indexing/__init__.py

@@ -0,0 +1,104 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+def _install():
+    from ..core import DATAFRAME_TYPE, INDEX_TYPE, SERIES_TYPE
+    from .add_prefix_suffix import (
+        df_add_prefix,
+        df_add_suffix,
+        series_add_prefix,
+        series_add_suffix,
+    )
+    from .align import align
+    from .at import at
+    from .droplevel import df_series_droplevel, index_droplevel
+    from .filter import filter_dataframe
+    from .get_level_values import get_level_values
+    from .getitem import dataframe_getitem, series_getitem
+    from .iat import iat
+    from .iloc import head, iloc, index_getitem, index_setitem, tail
+    from .insert import df_insert, index_insert
+    from .loc import loc
+    from .reindex import reindex, reindex_like
+    from .rename import df_rename, index_rename, index_set_names, series_rename
+    from .rename_axis import rename_axis
+    from .reorder_levels import df_reorder_levels, series_reorder_levels
+    from .reset_index import df_reset_index, series_reset_index
+    from .sample import sample
+    from .set_axis import df_set_axis, series_set_axis
+    from .set_index import set_index
+    from .setitem import dataframe_setitem
+    from .swaplevel import df_swaplevel, series_swaplevel
+    from .take import take
+    from .truncate import truncate
+    from .where import mask, where
+    from .xs import xs
+
+    for cls in DATAFRAME_TYPE + SERIES_TYPE:
+        setattr(cls, "at", property(fget=at))
+        setattr(cls, "droplevel", df_series_droplevel)
+        setattr(cls, "filter", filter_dataframe)
+        setattr(cls, "head", head)
+        setattr(cls, "iat", property(fget=iat))
+        setattr(cls, "iloc", property(fget=iloc))
+        setattr(cls, "loc", property(fget=loc))
+        setattr(cls, "mask", mask)
+        setattr(cls, "reindex", reindex)
+        setattr(cls, "reindex_like", reindex_like)
+        setattr(cls, "rename_axis", rename_axis)
+        setattr(cls, "sample", sample)
+        setattr(cls, "tail", tail)
+        setattr(cls, "take", take)
+        setattr(cls, "truncate", truncate)
+        setattr(cls, "where", where)
+        setattr(cls, "xs", xs)
+
+    for cls in DATAFRAME_TYPE:
+        setattr(cls, "add_prefix", df_add_prefix)
+        setattr(cls, "add_suffix", df_add_suffix)
+        setattr(cls, "align", align)
+        setattr(cls, "__getitem__", dataframe_getitem)
+        setattr(cls, "insert", df_insert)
+        setattr(cls, "rename", df_rename)
+        setattr(cls, "reorder_levels", df_reorder_levels)
+        setattr(cls, "reset_index", df_reset_index)
+        setattr(cls, "set_axis", df_set_axis)
+        setattr(cls, "set_index", set_index)
+        setattr(cls, "__setitem__", dataframe_setitem)
+        setattr(cls, "swaplevel", df_swaplevel)
+
+    for cls in SERIES_TYPE:
+        setattr(cls, "add_prefix", series_add_prefix)
+        setattr(cls, "add_suffix", series_add_suffix)
+        setattr(cls, "align", align)
+        setattr(cls, "__getitem__", series_getitem)
+        setattr(cls, "rename", series_rename)
+        setattr(cls, "reorder_levels", series_reorder_levels)
+        setattr(cls, "reset_index", series_reset_index)
+        setattr(cls, "set_axis", series_set_axis)
+        setattr(cls, "swaplevel", series_swaplevel)
+
+    for cls in INDEX_TYPE:
+        setattr(cls, "droplevel", index_droplevel)
+        setattr(cls, "get_level_values", get_level_values)
+        setattr(cls, "__getitem__", index_getitem)
+        setattr(cls, "insert", index_insert)
+        setattr(cls, "rename", index_rename)
+        setattr(cls, "__setitem__", index_setitem)
+        setattr(cls, "set_names", index_set_names)
+
+
+_install()
+del _install

maxframe/dataframe/indexing/add_prefix_suffix.py

@@ -0,0 +1,110 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import textwrap
+from functools import partial
+
+
+def _get_prefix_suffix_docs(is_prefix: bool):
+    if is_prefix:
+        action, pos = "prefix", "before"
+        r_action = "suffix"
+    else:
+        action, pos = "suffix", "after"
+        r_action = "prefix"
+
+    def mk_col(ch: str, s: str):
+        return f"{ch}_{s}" if is_prefix else f"{s}_{ch}"
+
+    doc = f"""
+    {action.capitalize()} labels with string `{action}`.
+
+    For Series, the row labels are {action}ed.
+    For DataFrame, the column labels are {action}ed.
+
+    Parameters
+    ----------
+    {action} : str
+        The string to add {pos} each label.
+
+    Returns
+    -------
+    Series or DataFrame
+        New Series or DataFrame with updated labels.
+
+    See Also
+    --------
+    Series.add_{r_action}: Suffix row labels with string `{r_action}`.
+    DataFrame.add_{r_action}: Suffix column labels with string `{r_action}`.
+
+    Examples
+    --------
+    >>> import maxframe.dataframe as md
+    >>> s = md.Series([1, 2, 3, 4])
+    >>> s.execute()
+    0    1
+    1    2
+    2    3
+    3    4
+    dtype: int64
+
+    >>> s.add_prefix({mk_col('item', '')!r}).execute()
+    {mk_col('item', '0')}    1
+    {mk_col('item', '1')}    2
+    {mk_col('item', '2')}    3
+    {mk_col('item', '3')}    4
+    dtype: int64
+
+    >>> df = md.DataFrame({{'A': [1, 2, 3, 4], 'B': [3, 4, 5, 6]}})
+    >>> df.execute()
+       A  B
+    0  1  3
+    1  2  4
+    2  3  5
+    3  4  6
+
+    >>> df.add_prefix({mk_col('col', '')!r}).execute()
+         {mk_col('col', 'A')}  {mk_col('col', 'B')}
+    0        1      3
+    1        2      4
+    2        3      5
+    3        4      6
+    """
+    return textwrap.dedent(doc).strip()
+
+
+def df_add_prefix(df, prefix):
+    f = partial("{prefix}{}".format, prefix=prefix)
+    return df.rename(columns=f)
+
+
+def series_add_prefix(series, prefix):
+    f = partial("{prefix}{}".format, prefix=prefix)
+    return series.rename(index=f)
+
+
+def df_add_suffix(df, suffix):
+    f = partial("{}{suffix}".format, suffix=suffix)
+    return df.rename(columns=f)
+
+
+def series_add_suffix(series, suffix):
+    f = partial("{}{suffix}".format, suffix=suffix)
+    return series.rename(index=f)
+
+
+df_add_prefix.__doc__ = _get_prefix_suffix_docs(True)
+series_add_prefix.__doc__ = df_add_prefix.__doc__
+df_add_suffix.__doc__ = _get_prefix_suffix_docs(False)
+series_add_suffix.__doc__ = df_add_suffix.__doc__

maxframe/dataframe/indexing/align.py

@@ -0,0 +1,350 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Any, List, Optional, Union
+
+import numpy as np
+
+from ... import opcodes
+from ...core import EntityData, OutputType, get_output_types
+from ...serialization.serializables import (
+    AnyField,
+    Int16Field,
+    Int64Field,
+    KeyField,
+    StringField,
+)
+from ...typing_ import TileableType
+from ..core import IndexValue
+from ..operators import DataFrameOperator, DataFrameOperatorMixin
+from ..utils import build_empty_df, parse_index, validate_axis
+
+
+class _NoNeedToAlign(Exception):
+    pass
+
+
+class DataFrameAlign(DataFrameOperator, DataFrameOperatorMixin):
+    _op_type_ = opcodes.ALIGN
+
+    lhs = KeyField("lhs")
+    rhs = KeyField("rhs")
+    join = StringField("join", default=None)
+    axis = Int16Field("axis", default=None)
+    level = AnyField("level", default=None)
+    fill_value = AnyField("fill_value", default=None)
+    method = StringField("method", default=None)
+    limit = Int64Field("limit", default=None)
+    fill_axis = Int16Field("fill_axis", default=None)
+    broadcast_axis = Int16Field("broadcast_axis", default=None)
+
+    @property
+    def output_limit(self) -> int:
+        return 2
+
+    @classmethod
+    def _set_inputs(cls, op: "DataFrameAlign", inputs: List[EntityData]):
+        super()._set_inputs(op, inputs)
+        op.lhs = inputs[0]
+        op.rhs = inputs[1]
+
+    def __call__(self, lhs: TileableType, rhs: TileableType):
+        if self.broadcast_axis != 1 or lhs.ndim == rhs.ndim:
+            self._output_types = get_output_types(lhs, rhs)
+        else:
+            self._output_types = [OutputType.dataframe, OutputType.dataframe]
+
+        if lhs.ndim == rhs.ndim:
+            if lhs.ndim == 1:
+                return self._call_series_series(lhs, rhs)
+            else:
+                return self._call_dataframe_dataframe(lhs, rhs)
+        else:
+            if lhs.ndim == 1:
+                # join order need to be reversed if not symmetric
+                asym_joins = {"left", "right"} - {self.join}
+                if len(asym_joins) == 1:  # self.join in {"left", "right"}
+                    self.join = asym_joins.pop()
+                # need to put dataframe first
+                self._output_types = get_output_types(rhs, lhs)
+                return self._call_dataframe_series(rhs, lhs)[::-1]
+            else:
+                return self._call_dataframe_series(lhs, rhs)
+
+    def _call_dataframe_dataframe(self, lhs: TileableType, rhs: TileableType):
+        l_shape = list(lhs.shape)
+        r_shape = list(rhs.shape)
+        if self.axis is None or self.axis == 0:
+            l_idx_val = r_idx_val = self._merge_index(
+                lhs.index_value, rhs.index_value, how=self.join
+            )
+            l_shape[0] = r_shape[0] = np.nan
+        else:
+            l_idx_val, r_idx_val = lhs.index_value, rhs.index_value
+
+        if self.axis is None or self.axis == 1:
+            l_empty = build_empty_df(lhs.dtypes)
+            r_empty = build_empty_df(rhs.dtypes)
+            aligned, _ = l_empty.align(r_empty, axis=1)
+            l_dtypes = r_dtypes = aligned.dtypes
+            l_col_val = r_col_val = parse_index(aligned.columns, store_data=True)
+            l_shape[1] = r_shape[1] = len(l_dtypes)
+        else:
+            l_dtypes, r_dtypes = lhs.dtypes, rhs.dtypes
+            l_col_val, r_col_val = lhs.columns_value, rhs.columns_value
+
+        l_kws = {
+            "index_value": l_idx_val,
+            "dtypes": l_dtypes,
+            "shape": tuple(l_shape),
+            "columns_value": l_col_val,
+        }
+        r_kws = {
+            "index_value": r_idx_val,
+            "dtypes": r_dtypes,
+            "shape": tuple(r_shape),
+            "columns_value": r_col_val,
+        }
+        return self.new_tileables([lhs, rhs], kws=[l_kws, r_kws])
+
+    def _call_dataframe_series(self, lhs: TileableType, rhs: TileableType):
+        l_shape = list(lhs.shape)
+        if self.axis == 0 or self.broadcast_axis == 1:
+            dtypes = lhs.dtypes
+            col_val = lhs.columns_value
+            l_idx_val = r_idx_val = self._merge_index(
+                lhs.index_value, rhs.index_value, how=self.join
+            )
+            l_shape[0] = r_size = np.nan
+        else:
+            l_idx_val = lhs.index_value
+            if not rhs.index_value.has_value():
+                dtypes = None
+                l_shape[1] = r_size = np.nan
+                col_val = r_idx_val = self._merge_index(
+                    lhs.columns_value, rhs.index_value, how=self.join
+                )
+            else:
+                series_index = rhs.index_value.to_pandas()
+                dtypes = lhs.dtypes.reindex(
+                    lhs.dtypes.index.join(series_index, how=self.join)
+                ).fillna(np.dtype(float))
+                l_shape[1] = r_size = len(dtypes)
+                col_val = r_idx_val = parse_index(dtypes.index, store_data=True)
+
+        l_kws = {
+            "index_value": l_idx_val,
+            "dtypes": dtypes,
+            "shape": tuple(l_shape),
+            "columns_value": col_val,
+        }
+        if self.broadcast_axis == 1:
+            r_kws = {
+                "index_value": r_idx_val,
+                "dtypes": dtypes,
+                "shape": tuple(l_shape),
+                "columns_value": col_val,
+            }
+        else:
+            r_kws = {
+                "index_value": r_idx_val,
+                "shape": (r_size,),
+                "dtype": rhs.dtype,
+            }
+        return self.new_tileables([lhs, rhs], kws=[l_kws, r_kws])
+
+    def _call_series_series(self, lhs: TileableType, rhs: TileableType):
+        idx = self._merge_index(lhs.index_value, rhs.index_value, how=self.join)
+        kws = [
+            {"index_value": idx, "shape": (np.nan,), "dtype": lhs.dtype},
+            {"index_value": idx, "shape": (np.nan,), "dtype": rhs.dtype},
+        ]
+        return self.new_tileables([lhs, rhs], kws=kws)
+
+    @staticmethod
+    def _merge_index(
+        left_index_value: IndexValue, right_index_value: IndexValue, how: str = "outer"
+    ):
+        left_pd = left_index_value.to_pandas()
+        right_pd = right_index_value.to_pandas()
+
+        if not left_index_value.has_value() or not right_index_value.has_value():
+            left_pd = left_pd[:0]
+            right_pd = right_pd[:0]
+            store_data = False
+        else:
+            store_data = True
+
+        joined = left_pd.join(right_pd, how=how)
+        if store_data:
+            return parse_index(joined, store_data=store_data)
+        else:
+            return parse_index(
+                joined,
+                {left_index_value.key, right_index_value.key},
+                store_data=store_data,
+            )
+
+
+def align(
+    df,
+    other,
+    join: str = "outer",
+    axis: Union[int, str, None] = None,
+    level: Union[int, str, None] = None,
+    copy: bool = True,
+    fill_value: Any = None,
+    method: str = None,
+    limit: Optional[int] = None,
+    fill_axis: Union[int, str] = 0,
+    broadcast_axis: Union[int, str] = None,
+):
+    """
+    Align two objects on their axes with the specified join method.
+
+    Join method is specified for each axis Index.
+
+    Parameters
+    ----------
+    other : DataFrame or Series
+    join : {'outer', 'inner', 'left', 'right'}, default 'outer'
+    axis : allowed axis of the other object, default None
+        Align on index (0), columns (1), or both (None).
+    level : int or level name, default None
+        Broadcast across a level, matching Index values on the
+        passed MultiIndex level.
+    copy : bool, default True
+        Always returns new objects. If copy=False and no reindexing is
+        required then original objects are returned.
+    fill_value : scalar, default np.NaN
+        Value to use for missing values. Defaults to NaN, but can be any
+        "compatible" value.
+    method : {'backfill', 'bfill', 'pad', 'ffill', None}, default None
+        Method to use for filling holes in reindexed Series:
+
+        - pad / ffill: propagate last valid observation forward to next valid.
+        - backfill / bfill: use NEXT valid observation to fill gap.
+
+    limit : int, default None
+        If method is specified, this is the maximum number of consecutive
+        NaN values to forward/backward fill. In other words, if there is
+        a gap with more than this number of consecutive NaNs, it will only
+        be partially filled. If method is not specified, this is the
+        maximum number of entries along the entire axis where NaNs will be
+        filled. Must be greater than 0 if not None.
+    fill_axis : {0 or 'index', 1 or 'columns'}, default 0
+        Filling axis, method and limit.
+    broadcast_axis : {0 or 'index', 1 or 'columns'}, default None
+        Broadcast values along this axis, if aligning two objects of
+        different dimensions.
+
+    Notes
+    -----
+    Currently argument `level` is not supported.
+
+    Returns
+    -------
+    (left, right) : (DataFrame, type of other)
+        Aligned objects.
+
+    Examples
+    --------
+    >>> import maxframe.tensor as mt
+    >>> import maxframe.dataframe as md
+    >>> df = md.DataFrame(
+    ...     [[1, 2, 3, 4], [6, 7, 8, 9]], columns=["D", "B", "E", "A"], index=[1, 2]
+    ... )
+    >>> other = md.DataFrame(
+    ...     [[10, 20, 30, 40], [60, 70, 80, 90], [600, 700, 800, 900]],
+    ...     columns=["A", "B", "C", "D"],
+    ...     index=[2, 3, 4],
+    ... )
+    >>> df.execute()
+       D  B  E  A
+    1  1  2  3  4
+    2  6  7  8  9
+    >>> other.execute()
+        A    B    C    D
+    2   10   20   30   40
+    3   60   70   80   90
+    4  600  700  800  900
+
+    Align on columns:
+
+    >>> left, right = df.align(other, join="outer", axis=1)
+    >>> left.execute()
+       A  B   C  D  E
+    1  4  2 NaN  1  3
+    2  9  7 NaN  6  8
+    >>> right.execute()
+        A    B    C    D   E
+    2   10   20   30   40 NaN
+    3   60   70   80   90 NaN
+    4  600  700  800  900 NaN
+
+    We can also align on the index:
+
+    >>> left, right = df.align(other, join="outer", axis=0)
+    >>> left.execute()
+        D    B    E    A
+    1  1.0  2.0  3.0  4.0
+    2  6.0  7.0  8.0  9.0
+    3  NaN  NaN  NaN  NaN
+    4  NaN  NaN  NaN  NaN
+    >>> right.execute()
+        A      B      C      D
+    1    NaN    NaN    NaN    NaN
+    2   10.0   20.0   30.0   40.0
+    3   60.0   70.0   80.0   90.0
+    4  600.0  700.0  800.0  900.0
+
+    Finally, the default `axis=None` will align on both index and columns:
+
+    >>> left, right = df.align(other, join="outer", axis=None)
+    >>> left.execute()
+         A    B   C    D    E
+    1  4.0  2.0 NaN  1.0  3.0
+    2  9.0  7.0 NaN  6.0  8.0
+    3  NaN  NaN NaN  NaN  NaN
+    4  NaN  NaN NaN  NaN  NaN
+    >>> right.execute()
+           A      B      C      D   E
+    1    NaN    NaN    NaN    NaN NaN
+    2   10.0   20.0   30.0   40.0 NaN
+    3   60.0   70.0   80.0   90.0 NaN
+    4  600.0  700.0  800.0  900.0 NaN
+    """
+    axis = validate_axis(axis) if axis is not None else None
+    fill_axis = validate_axis(fill_axis) if fill_axis is not None else None
+    broadcast_axis = (
+        validate_axis(broadcast_axis) if broadcast_axis is not None else None
+    )
+
+    if level is not None:
+        raise NotImplementedError(f"Argument `level` not supported")
+    if df.ndim != other.ndim and axis is None:
+        raise ValueError("Must specify axis=0 or 1")
+
+    op = DataFrameAlign(
+        join=join,
+        axis=axis,
+        level=level,
+        copy=copy,
+        fill_value=fill_value,
+        method=method,
+        limit=limit,
+        fill_axis=fill_axis,
+        broadcast_axis=broadcast_axis,
+    )
+    return op(df, other)

maxframe/dataframe/indexing/at.py

@@ -0,0 +1,83 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import numpy as np
+
+from .loc import DataFrameLoc
+
+
+class DataFrameAt:
+    def __init__(self, obj):
+        self._obj = obj
+        self._loc = DataFrameLoc(self._obj)
+
+    def __getitem__(self, indexes):
+        if not isinstance(indexes, tuple):
+            indexes = (indexes,)
+
+        for index in indexes:
+            if not np.isscalar(index):
+                raise ValueError("Invalid call for scalar access (getting)!")
+
+        return self._loc[indexes]
+
+
+def at(a):
+    """
+    Access a single value for a row/column label pair.
+
+    Similar to ``loc``, in that both provide label-based lookups. Use
+    ``at`` if you only need to get or set a single value in a DataFrame
+    or Series.
+
+    Raises
+    ------
+    KeyError
+        If 'label' does not exist in DataFrame.
+
+    See Also
+    --------
+    DataFrame.iat : Access a single value for a row/column pair by integer
+        position.
+    DataFrame.loc : Access a group of rows and columns by label(s).
+    Series.at : Access a single value using a label.
+
+    Examples
+    --------
+    >>> import maxframe.dataframe as md
+    >>> df = md.DataFrame([[0, 2, 3], [0, 4, 1], [10, 20, 30]],
+    ...                   index=[4, 5, 6], columns=['A', 'B', 'C'])
+    >>> df.execute()
+        A   B   C
+    4   0   2   3
+    5   0   4   1
+    6  10  20  30
+
+    Get value at specified row/column pair
+
+    >>> df.at[4, 'B'].execute()
+    2
+
+    # Set value at specified row/column pair
+    #
+    # >>> df.at[4, 'B'] = 10
+    # >>> df.at[4, 'B']
+    # 10
+
+    Get value within a Series
+
+    >>> df.loc[5].at['B'].execute()
+    4
+    """
+    return DataFrameAt(a)