maxframe 2.4.0rc1__cp312-cp312-win32.whl

maxframe/dataframe/sort/argsort.py

@@ -0,0 +1,68 @@
+# 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 series_argsort(series, axis=0, kind="quicksort", order=None, stable=None):
+    """
+    Return the integer indices that would sort the Series values.
+
+    Override ndarray.argsort. Argsorts the value, omitting NA/null values,
+    and places the result in the same locations as the non-NA values.
+
+    Parameters
+    ----------
+    axis : {0 or 'index'}
+        Unused. Parameter needed for compatibility with DataFrame.
+    kind : {'mergesort', 'quicksort', 'heapsort', 'stable'}, default 'quicksort'
+        Choice of sorting algorithm. See :func:`numpy.sort` for more
+        information. 'mergesort' and 'stable' are the only stable algorithms.
+    order : None
+        Has no effect but is accepted for compatibility with numpy.
+    stable : None
+        Has no effect but is accepted for compatibility with numpy.
+
+    Returns
+    -------
+    Series[np.intp]
+        Positions of values within the sort order with -1 indicating
+        nan values.
+
+    See Also
+    --------
+    maxframe.tensor.argsort : Returns the indices that would sort this array.
+
+    Examples
+    --------
+    >>> import maxframe.tensor as mt
+    >>> import maxframe.dataframe as md
+    >>> s = md.Series([3, 2, 1])
+    >>> s.argsort().execute()
+    0    2
+    1    1
+    2    0
+    dtype: int64
+    """
+    from ... import tensor as mt
+    from ..datasource.from_tensor import series_from_tensor
+
+    _ = axis, order, stable
+    axis = 0
+    t = mt.argsort(series.to_tensor(), axis=axis, kind=kind)
+    return series_from_tensor(t, index=series.index)
+
+
+def index_argsort(index, *args, **kwargs):
+    from ... import tensor as mt
+
+    return mt.argsort(index.to_tensor(), *args, **kwargs)

maxframe/dataframe/sort/core.py

@@ -0,0 +1,37 @@
+# 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 ...serialization.serializables import (
+    AnyField,
+    BoolField,
+    FieldTypes,
+    Int32Field,
+    Int64Field,
+    ListField,
+    StringField,
+)
+from ..operators import DataFrameOperator
+
+
+class DataFrameSortOperator(DataFrameOperator):
+    axis = Int32Field("axis")
+    ascending = AnyField("ascending")
+    inplace = BoolField("inplace")
+    kind = StringField("kind")
+    na_position = StringField("na_position")
+    ignore_index = BoolField("ignore_index")
+    parallel_kind = StringField("parallel_kind")
+    psrs_kinds = ListField("psrs_kinds", FieldTypes.string, default=None)
+    nrows = Int64Field("nrows", default=None)
+    keep_kind = StringField("keep_kind", default="head")

maxframe/dataframe/sort/nlargest.py

@@ -0,0 +1,238 @@
+# 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 ...core import OutputType
+from .sort_values import DataFrameSortValues
+
+
+def _nlargest(df, n, columns=None, keep="first"):
+    op = DataFrameSortValues(
+        output_types=[OutputType.dataframe],
+        axis=0,
+        by=columns,
+        ignore_index=False,
+        ascending=False,
+        nrows=n,
+        keep_kind=keep,
+    )
+    return op(df)
+
+
+def df_nlargest(df, n, columns, keep="first"):
+    """
+    Return the first `n` rows ordered by `columns` in descending order.
+
+    Return the first `n` rows with the largest values in `columns`, in
+    descending order. The columns that are not specified are returned as
+    well, but not used for ordering.
+
+    This method is equivalent to
+    ``df.sort_values(columns, ascending=False).head(n)``, but more
+    performant.
+
+    Parameters
+    ----------
+    n : int
+        Number of rows to return.
+    columns : label or list of labels
+        Column label(s) to order by.
+    keep : {'first', 'last', 'all'}, default 'first'
+        Where there are duplicate values:
+
+        - `first` : prioritize the first occurrence(s)
+        - `last` : prioritize the last occurrence(s)
+        - ``all`` : do not drop any duplicates, even it means
+                    selecting more than `n` items.
+
+    Returns
+    -------
+    DataFrame
+        The first `n` rows ordered by the given columns in descending
+        order.
+
+    See Also
+    --------
+    DataFrame.nsmallest : Return the first `n` rows ordered by `columns` in
+        ascending order.
+    DataFrame.sort_values : Sort DataFrame by the values.
+    DataFrame.head : Return the first `n` rows without re-ordering.
+
+    Notes
+    -----
+    This function cannot be used with all column types. For example, when
+    specifying columns with `object` or `category` dtypes, ``TypeError`` is
+    raised.
+
+    Examples
+    --------
+    >>> import maxframe.dataframe as md
+    >>> df = md.DataFrame({'population': [59000000, 65000000, 434000,
+    ...                                   434000, 434000, 337000, 11300,
+    ...                                   11300, 11300],
+    ...                    'GDP': [1937894, 2583560 , 12011, 4520, 12128,
+    ...                            17036, 182, 38, 311],
+    ...                    'alpha-2': ["IT", "FR", "MT", "MV", "BN",
+    ...                                "IS", "NR", "TV", "AI"]},
+    ...                   index=["Italy", "France", "Malta",
+    ...                          "Maldives", "Brunei", "Iceland",
+    ...                          "Nauru", "Tuvalu", "Anguilla"])
+    >>> df.execute()
+              population      GDP alpha-2
+    Italy       59000000  1937894      IT
+    France      65000000  2583560      FR
+    Malta         434000    12011      MT
+    Maldives      434000     4520      MV
+    Brunei        434000    12128      BN
+    Iceland       337000    17036      IS
+    Nauru          11300      182      NR
+    Tuvalu         11300       38      TV
+    Anguilla       11300      311      AI
+
+    In the following example, we will use ``nlargest`` to select the three
+    rows having the largest values in column "population".
+
+    >>> df.nlargest(3, 'population').execute()
+            population      GDP alpha-2
+    France    65000000  2583560      FR
+    Italy     59000000  1937894      IT
+    Malta       434000    12011      MT
+
+    When using ``keep='last'``, ties are resolved in reverse order:
+
+    >>> df.nlargest(3, 'population', keep='last').execute()
+            population      GDP alpha-2
+    France    65000000  2583560      FR
+    Italy     59000000  1937894      IT
+    Brunei      434000    12128      BN
+
+    When using ``keep='all'``, all duplicate items are maintained:
+
+    >>> df.nlargest(3, 'population', keep='all').execute()
+              population      GDP alpha-2
+    France      65000000  2583560      FR
+    Italy       59000000  1937894      IT
+    Malta         434000    12011      MT
+    Maldives      434000     4520      MV
+    Brunei        434000    12128      BN
+
+    To order by the largest values in column "population" and then "GDP",
+    we can specify multiple columns like in the next example.
+
+    >>> df.nlargest(3, ['population', 'GDP']).execute()
+            population      GDP alpha-2
+    France    65000000  2583560      FR
+    Italy     59000000  1937894      IT
+    Brunei      434000    12128      BN
+    """
+    return _nlargest(df, n, columns, keep=keep)
+
+
+def series_nlargest(df, n, keep="first"):
+    """
+    Return the largest `n` elements.
+
+    Parameters
+    ----------
+    n : int, default 5
+        Return this many descending sorted values.
+    keep : {'first', 'last', 'all'}, default 'first'
+        When there are duplicate values that cannot all fit in a
+        Series of `n` elements:
+
+        - ``first`` : return the first `n` occurrences in order
+            of appearance.
+        - ``last`` : return the last `n` occurrences in reverse
+            order of appearance.
+        - ``all`` : keep all occurrences. This can result in a Series of
+            size larger than `n`.
+
+    Returns
+    -------
+    Series
+        The `n` largest values in the Series, sorted in decreasing order.
+
+    See Also
+    --------
+    Series.nsmallest: Get the `n` smallest elements.
+    Series.sort_values: Sort Series by values.
+    Series.head: Return the first `n` rows.
+
+    Notes
+    -----
+    Faster than ``.sort_values(ascending=False).head(n)`` for small `n`
+    relative to the size of the ``Series`` object.
+
+    Examples
+    --------
+    >>> import maxframe.dataframe as md
+    >>> countries_population = {"Italy": 59000000, "France": 65000000,
+    ...                         "Malta": 434000, "Maldives": 434000,
+    ...                         "Brunei": 434000, "Iceland": 337000,
+    ...                         "Nauru": 11300, "Tuvalu": 11300,
+    ...                         "Anguilla": 11300, "Montserrat": 5200}
+    >>> s = md.Series(countries_population)
+    >>> s.execute()
+    Italy       59000000
+    France      65000000
+    Malta         434000
+    Maldives      434000
+    Brunei        434000
+    Iceland       337000
+    Nauru          11300
+    Tuvalu         11300
+    Anguilla       11300
+    Montserrat      5200
+    dtype: int64
+
+    The `n` largest elements where ``n=5`` by default.
+
+    >>> s.nlargest().execute()
+    France      65000000
+    Italy       59000000
+    Malta         434000
+    Maldives      434000
+    Brunei        434000
+    dtype: int64
+
+    The `n` largest elements where ``n=3``. Default `keep` value is 'first'
+    so Malta will be kept.
+
+    >>> s.nlargest(3).execute()
+    France    65000000
+    Italy     59000000
+    Malta       434000
+    dtype: int64
+
+    The `n` largest elements where ``n=3`` and keeping the last duplicates.
+    Brunei will be kept since it is the last with value 434000 based on
+    the index order.
+
+    >>> s.nlargest(3, keep='last').execute()
+    France      65000000
+    Italy       59000000
+    Brunei        434000
+    dtype: int64
+
+    The `n` largest elements where ``n=3`` with all duplicates kept. Note
+    that the returned Series has five elements due to the three duplicates.
+
+    >>> s.nlargest(3, keep='all').execute()
+    France      65000000
+    Italy       59000000
+    Malta         434000
+    Maldives      434000
+    Brunei        434000
+    dtype: int64
+    """
+    return _nlargest(df, n, keep=keep)

maxframe/dataframe/sort/nsmallest.py

@@ -0,0 +1,228 @@
+# 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 ...core import OutputType
+from .sort_values import DataFrameSortValues
+
+
+def _nsmallest(df, n, columns=None, keep="first"):
+    op = DataFrameSortValues(
+        output_types=[OutputType.dataframe],
+        axis=0,
+        by=columns,
+        ignore_index=False,
+        ascending=True,
+        nrows=n,
+        keep_kind=keep,
+    )
+    return op(df)
+
+
+def df_nsmallest(df, n, columns, keep="first"):
+    """
+    Return the first `n` rows ordered by `columns` in ascending order.
+
+    Return the first `n` rows with the smallest values in `columns`, in
+    ascending order. The columns that are not specified are returned as
+    well, but not used for ordering.
+
+    This method is equivalent to
+    ``df.sort_values(columns, ascending=True).head(n)``, but more
+    performant.
+
+    Parameters
+    ----------
+    n : int
+        Number of items to retrieve.
+    columns : list or str
+        Column name or names to order by.
+    keep : {'first', 'last', 'all'}, default 'first'
+        Where there are duplicate values:
+
+        - ``first`` : take the first occurrence.
+        - ``last`` : take the last occurrence.
+        - ``all`` : do not drop any duplicates, even it means
+          selecting more than `n` items.
+
+    Returns
+    -------
+    DataFrame
+
+    See Also
+    --------
+    DataFrame.nlargest : Return the first `n` rows ordered by `columns` in
+        descending order.
+    DataFrame.sort_values : Sort DataFrame by the values.
+    DataFrame.head : Return the first `n` rows without re-ordering.
+
+    Examples
+    --------
+    >>> import maxframe.dataframe as md
+    >>> df = md.DataFrame({'population': [59000000, 65000000, 434000,
+    ...                                   434000, 434000, 337000, 337000,
+    ...                                   11300, 11300],
+    ...                    'GDP': [1937894, 2583560 , 12011, 4520, 12128,
+    ...                            17036, 182, 38, 311],
+    ...                    'alpha-2': ["IT", "FR", "MT", "MV", "BN",
+    ...                                "IS", "NR", "TV", "AI"]},
+    ...                   index=["Italy", "France", "Malta",
+    ...                          "Maldives", "Brunei", "Iceland",
+    ...                          "Nauru", "Tuvalu", "Anguilla"])
+    >>> df.execute()
+              population      GDP alpha-2
+    Italy       59000000  1937894      IT
+    France      65000000  2583560      FR
+    Malta         434000    12011      MT
+    Maldives      434000     4520      MV
+    Brunei        434000    12128      BN
+    Iceland       337000    17036      IS
+    Nauru         337000      182      NR
+    Tuvalu         11300       38      TV
+    Anguilla       11300      311      AI
+
+    In the following example, we will use ``nsmallest`` to select the
+    three rows having the smallest values in column "population".
+
+    >>> df.nsmallest(3, 'population').execute()
+              population    GDP alpha-2
+    Tuvalu         11300     38      TV
+    Anguilla       11300    311      AI
+    Iceland       337000  17036      IS
+
+    When using ``keep='last'``, ties are resolved in reverse order:
+
+    >>> df.nsmallest(3, 'population', keep='last').execute()
+              population  GDP alpha-2
+    Anguilla       11300  311      AI
+    Tuvalu         11300   38      TV
+    Nauru         337000  182      NR
+
+    When using ``keep='all'``, all duplicate items are maintained:
+
+    >>> df.nsmallest(3, 'population', keep='all').execute()
+              population    GDP alpha-2
+    Tuvalu         11300     38      TV
+    Anguilla       11300    311      AI
+    Iceland       337000  17036      IS
+    Nauru         337000    182      NR
+
+    To order by the smallest values in column "population" and then "GDP", we can
+    specify multiple columns like in the next example.
+
+    >>> df.nsmallest(3, ['population', 'GDP']).execute()
+              population  GDP alpha-2
+    Tuvalu         11300   38      TV
+    Anguilla       11300  311      AI
+    Nauru         337000  182      NR
+    """
+    return _nsmallest(df, n, columns, keep=keep)
+
+
+def series_nsmallest(df, n, keep="first"):
+    """
+    Return the smallest `n` elements.
+
+    Parameters
+    ----------
+    n : int, default 5
+        Return this many ascending sorted values.
+    keep : {'first', 'last', 'all'}, default 'first'
+        When there are duplicate values that cannot all fit in a
+        Series of `n` elements:
+
+        - ``first`` : return the first `n` occurrences in order
+            of appearance.
+        - ``last`` : return the last `n` occurrences in reverse
+            order of appearance.
+        - ``all`` : keep all occurrences. This can result in a Series of
+            size larger than `n`.
+
+    Returns
+    -------
+    Series
+        The `n` smallest values in the Series, sorted in increasing order.
+
+    See Also
+    --------
+    Series.nlargest: Get the `n` largest elements.
+    Series.sort_values: Sort Series by values.
+    Series.head: Return the first `n` rows.
+
+    Notes
+    -----
+    Faster than ``.sort_values().head(n)`` for small `n` relative to
+    the size of the ``Series`` object.
+
+    Examples
+    --------
+    >>> import maxframe.dataframe as md
+    >>> countries_population = {"Italy": 59000000, "France": 65000000,
+    ...                         "Brunei": 434000, "Malta": 434000,
+    ...                         "Maldives": 434000, "Iceland": 337000,
+    ...                         "Nauru": 11300, "Tuvalu": 11300,
+    ...                         "Anguilla": 11300, "Montserrat": 5200}
+    >>> s = md.Series(countries_population)
+    >>> s.execute()
+    Italy       59000000
+    France      65000000
+    Brunei        434000
+    Malta         434000
+    Maldives      434000
+    Iceland       337000
+    Nauru          11300
+    Tuvalu         11300
+    Anguilla       11300
+    Montserrat      5200
+    dtype: int64
+
+    The `n` smallest elements where ``n=5`` by default.
+
+    >>> s.nsmallest().execute()
+    Montserrat    5200
+    Nauru        11300
+    Tuvalu       11300
+    Anguilla     11300
+    Iceland     337000
+    dtype: int64
+
+    The `n` smallest elements where ``n=3``. Default `keep` value is
+    'first' so Nauru and Tuvalu will be kept.
+
+    >>> s.nsmallest(3).execute()
+    Montserrat   5200
+    Nauru       11300
+    Tuvalu      11300
+    dtype: int64
+
+    The `n` smallest elements where ``n=3`` and keeping the last
+    duplicates. Anguilla and Tuvalu will be kept since they are the last
+    with value 11300 based on the index order.
+
+    >>> s.nsmallest(3, keep='last').execute()
+    Montserrat   5200
+    Anguilla    11300
+    Tuvalu      11300
+    dtype: int64
+
+    The `n` smallest elements where ``n=3`` with all duplicates kept. Note
+    that the returned Series has four elements due to the three duplicates.
+
+    >>> s.nsmallest(3, keep='all').execute()
+    Montserrat   5200
+    Nauru       11300
+    Tuvalu      11300
+    Anguilla    11300
+    dtype: int64
+    """
+    return _nsmallest(df, n, keep=keep)