maxframe 2.0.0b2__cp37-cp37m-win32.whl → 2.3.0rc1__cp37-cp37m-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

@@ -32,5 +32,6 @@ class DataFrameSortOperator(DataFrameOperator):
     na_position = StringField("na_position")
     ignore_index = BoolField("ignore_index")
     parallel_kind = StringField("parallel_kind")
-    psrs_kinds = ListField("psrs_kinds", FieldTypes.string)
+    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)

maxframe/dataframe/sort/rank.py

@@ -0,0 +1,147 @@
+# 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
+import pandas as pd
+
+from ...serialization.serializables import BoolField, StringField
+from ..operators import DataFrameOperatorMixin
+from .core import DataFrameSortOperator
+
+
+class DataFrameRank(DataFrameSortOperator, DataFrameOperatorMixin):
+    method = StringField("method", default=None)
+    numeric_only = BoolField("numeric_only", default=None)
+    pct = BoolField("pct", default=False)
+
+    @property
+    def na_option(self):
+        return self.na_position
+
+    def __call__(self, df_obj):
+        params = df_obj.params
+        if df_obj.ndim == 2:  # dataframe
+            if self.numeric_only:
+                sel_df = df_obj.select_dtypes(include=[np.number])
+                cols = sel_df.dtypes.index
+            else:
+                cols = df_obj.dtypes.index
+            params["dtypes"] = pd.Series([np.dtype(float)] * len(cols), index=cols)
+            return self.new_dataframe([df_obj], **params)
+        else:
+            params["dtypes"] = np.dtype(float)
+            return self.new_series([df_obj], **params)
+
+
+def rank(
+    df,
+    axis=0,
+    method="average",
+    numeric_only=False,
+    na_option="keep",
+    ascending=True,
+    pct=False,
+):
+    """
+    Compute numerical data ranks (1 through n) along axis.
+
+    By default, equal values are assigned a rank that is the average of the
+    ranks of those values.
+
+    Parameters
+    ----------
+    axis : {0 or 'index', 1 or 'columns'}, default 0
+        Index to direct ranking.
+    method : {'average', 'min', 'max', 'first', 'dense'}, default 'average'
+        How to rank the group of records that have the same value (i.e. ties):
+
+        * average: average rank of the group
+        * min: lowest rank in the group
+        * max: highest rank in the group
+        * first: ranks assigned in order they appear in the array
+        * dense: like 'min', but rank always increases by 1 between groups.
+
+    numeric_only : bool, optional
+        For DataFrame objects, rank only numeric columns if set to True.
+    na_option : {'keep', 'top', 'bottom'}, default 'keep'
+        How to rank NaN values:
+
+        * keep: assign NaN rank to NaN values
+        * top: assign lowest rank to NaN values
+        * bottom: assign highest rank to NaN values
+
+    ascending : bool, default True
+        Whether or not the elements should be ranked in ascending order.
+    pct : bool, default False
+        Whether or not to display the returned rankings in percentile
+        form.
+
+    Returns
+    -------
+    same type as caller
+        Return a Series or DataFrame with data ranks as values.
+
+    See Also
+    --------
+    core.groupby.GroupBy.rank : Rank of values within each group.
+
+    Examples
+    --------
+    >>> import maxframe.tensor as mt
+    >>> import maxframe.dataframe as md
+    >>> df = md.DataFrame(data={'Animal': ['cat', 'penguin', 'dog',
+    ...                                    'spider', 'snake'],
+    ...                         'Number_legs': [4, 2, 4, 8, mt.nan]})
+    >>> df.execute()
+        Animal  Number_legs
+    0      cat          4.0
+    1  penguin          2.0
+    2      dog          4.0
+    3   spider          8.0
+    4    snake          NaN
+
+    The following example shows how the method behaves with the above
+    parameters:
+
+    * default_rank: this is the default behaviour obtained without using
+      any parameter.
+    * max_rank: setting ``method = 'max'`` the records that have the
+      same values are ranked using the highest rank (e.g.: since 'cat'
+      and 'dog' are both in the 2nd and 3rd position, rank 3 is assigned.)
+    * NA_bottom: choosing ``na_option = 'bottom'``, if there are records
+      with NaN values they are placed at the bottom of the ranking.
+    * pct_rank: when setting ``pct = True``, the ranking is expressed as
+      percentile rank.
+
+    >>> df['default_rank'] = df['Number_legs'].rank()
+    >>> df['max_rank'] = df['Number_legs'].rank(method='max')
+    >>> df['NA_bottom'] = df['Number_legs'].rank(na_option='bottom')
+    >>> df['pct_rank'] = df['Number_legs'].rank(pct=True)
+    >>> df.execute()
+        Animal  Number_legs  default_rank  max_rank  NA_bottom  pct_rank
+    0      cat          4.0           2.5       3.0        2.5     0.625
+    1  penguin          2.0           1.0       1.0        1.0     0.250
+    2      dog          4.0           2.5       3.0        2.5     0.625
+    3   spider          8.0           4.0       4.0        4.0     1.000
+    4    snake          NaN           NaN       NaN        5.0       NaN
+    """
+    op = DataFrameRank(
+        axis=axis,
+        method=method,
+        numeric_only=numeric_only,
+        na_position=na_option,
+        ascending=ascending,
+        pct=pct,
+    )
+    return op(df)