Replacing reverse with descending

README.md

@@ -42,7 +42,7 @@ const pl = require('nodejs-polars');
 // a lot operations support both positional and named arguments
 // you can see the full specs in the docs or the type definitions
 > fooSeries.sort(true)
-> fooSeries.sort({reverse: true})
+> fooSeries.sort({descending: true})
 shape: (3,)
 Series: 'foo' [f64]
 [

__tests__/dataframe.test.ts

@@ -1038,23 +1038,23 @@ describe("dataframe", () => {
     });
     expect(actual).toFrameEqual(expected);
   });
-  test("sort:nulls_last:false", () => {
+  test("sort:nullsLast:false", () => {
     const actual = pl
       .DataFrame({
         foo: [1, null, 2, 3],
       })
-      .sort({ by: "foo", nulls_last: false });
+      .sort({ by: "foo", nullsLast: false });
     const expected = pl.DataFrame({
       foo: [null, 1, 2, 3],
     });
     expect(actual).toFrameEqual(expected);
   });
-  test("sort:nulls_last:true", () => {
+  test("sort:nullsLast:true", () => {
     const actual = pl
       .DataFrame({
         foo: [1, null, 2, 3],
       })
-      .sort({ by: "foo", nulls_last: true });
+      .sort({ by: "foo", nullsLast: true });
     const expected = pl.DataFrame({
       foo: [1, 2, 3, null],
     });

__tests__/expr.test.ts

@@ -71,10 +71,10 @@ describe("expr", () => {
     expect(actual).toStrictEqual(0);
   });
   test.each`
-    args                 | expectedSort
-    ${undefined}         | ${[1, 0, 3, 2]}
-    ${true}              | ${[2, 3, 0, 1]}
-    ${{ reverse: true }} | ${[2, 3, 0, 1]}
+    args                    | expectedSort
+    ${undefined}            | ${[1, 0, 3, 2]}
+    ${true}                 | ${[2, 3, 0, 1]}
+    ${{ descending: true }} | ${[2, 3, 0, 1]}
   `("argSort", ({ args, expectedSort }) => {
     const df = pl.DataFrame({ a: [1, 0, 2, 1.5] });
     const expected = pl.DataFrame({ argSort: expectedSort });
@@ -845,16 +845,16 @@ describe("expr", () => {
     const b = col("b");
     const actual = df.select(
       a.sort().as("a_sorted_default"),
-      a.sort({ reverse: true }).as("a_sorted_reverse"),
+      a.sort({ descending: true }).as("a_sorted_reverse"),
       a.sort({ nullsLast: true }).as("a_sorted_nulls_last"),
       a
-        .sort({ reverse: true, nullsLast: true })
+        .sort({ descending: true, nullsLast: true })
         .as("a_sorted_reverse_nulls_last"),
       b.sort().as("b_sorted_default"),
-      b.sort({ reverse: true }).as("b_sorted_reverse"),
+      b.sort({ descending: true }).as("b_sorted_reverse"),
       b.sort({ nullsLast: true }).as("b_sorted_nulls_last"),
       b
-        .sort({ reverse: true, nullsLast: true })
+        .sort({ descending: true, nullsLast: true })
         .as("b_sorted_reverse_nulls_last"),
     );
     expect(actual).toFrameEqual(expected);
@@ -903,7 +903,7 @@ describe("expr", () => {
     const actual = df.withColumns(
       pl
         .col(["name", "value"])
-        .sortBy({ by: [pl.col("value")], reverse: [true] })
+        .sortBy({ by: [pl.col("value")], descending: [true] })
         .last()
         .over("label")
         .suffix("_min"),
@@ -1829,12 +1829,12 @@ describe("expr.lst", () => {
     });
     const actual = df.select(
       col("a").lst.sort().as("sort"),
-      col("a").lst.sort({ reverse: true }).as("sort:reverse"),
+      col("a").lst.sort({ descending: true }).as("sort:reverse"),
     );
     const sortSeries = df.getColumn("a").lst.sort().rename("sort");
     const sortReverseSeries = df
       .getColumn("a")
-      .lst.sort({ reverse: true })
+      .lst.sort({ descending: true })
       .rename("sort:reverse");
 
     const actualFromSeries = pl.DataFrame([sortSeries, sortReverseSeries]);

__tests__/lazyframe.test.ts

@@ -1011,7 +1011,7 @@ describe("lazyframe", () => {
         foo: [1, null, 2, 3],
       })
       .lazy()
-      .sort({ by: "foo", nulls_last: false })
+      .sort({ by: "foo", nullsLast: false })
       .collectSync();
     const expected = pl.DataFrame({
       foo: [null, 1, 2, 3],
@@ -1024,7 +1024,7 @@ describe("lazyframe", () => {
         foo: [1, null, 2, 3],
       })
       .lazy()
-      .sort({ by: "foo", nulls_last: true })
+      .sort({ by: "foo", nullsLast: true })
       .collectSync();
     const expected = pl.DataFrame({
       foo: [1, 2, 3, null],

__tests__/series.test.ts

@@ -430,8 +430,8 @@ describe("series", () => {
     ${numSeries()}  | ${"sort"}            | ${[]}
     ${numSeries()}  | ${"sort"}            | ${[false]}
     ${numSeries()}  | ${"sort"}            | ${[true]}
-    ${numSeries()}  | ${"sort"}            | ${[{ reverse: true }]}
-    ${numSeries()}  | ${"sort"}            | ${[{ reverse: false }]}
+    ${numSeries()}  | ${"sort"}            | ${[{ descending: true }]}
+    ${numSeries()}  | ${"sort"}            | ${[{ descending: false }]}
     ${numSeries()}  | ${"sum"}             | ${[]}
     ${numSeries()}  | ${"tail"}            | ${[]}
     ${numSeries()}  | ${"gather"}          | ${[[1, 2]]}
@@ -462,7 +462,7 @@ describe("series", () => {
     ${"argMax"}          | ${pl.Series([1, 2, 3]).argMax()}                                                       | ${2}
     ${"argMin"}          | ${pl.Series([1, 2, 3]).argMin()}                                                       | ${0}
     ${"argSort"}         | ${pl.Series([3, 2, 1]).argSort()}                                                      | ${pl.Series([2, 1, 0])}
-    ${"argSort"}         | ${pl.Series([null, 3, 2, 1]).argSort({ reverse: true })}                               | ${pl.Series([1, 2, 3, 0])}
+    ${"argSort"}         | ${pl.Series([null, 3, 2, 1]).argSort({ descending: true })}                            | ${pl.Series([1, 2, 3, 0])}
     ${"argTrue"}         | ${pl.Series([true, false]).argTrue()}                                                  | ${pl.Series([0])}
     ${"argUnique"}       | ${pl.Series([1, 1, 2]).argUnique()}                                                    | ${pl.Series([0, 2])}
     ${"cast-Int16"}      | ${pl.Series("", [1, 1, 2]).cast(pl.Int16)}                                             | ${pl.Series("", [1, 1, 2], pl.Int16)}

polars/dataframe.ts

@@ -1351,24 +1351,27 @@ export interface DataFrame
   /**
    * Sort the DataFrame by column.
    * ___
-   * @param by - By which columns to sort. Only accepts string.
+   * @param by - Column(s) to sort by. Accepts expression input, including selectors. Strings are parsed as column names.
    * @param reverse - Reverse/descending sort.
+   * @param descending - Sort in descending order. When sorting by multiple columns, can be specified per column by passing a sequence of booleans.
+   * @param nullsLast - Place null values last; can specify a single boolean applying to all columns or a sequence of booleans for per-column control.
+   * @param maintainOrder - Whether the order should be maintained if elements are equal.
    */
   sort(
     by: ColumnsOrExpr,
     descending?: boolean,
-    nulls_last?: boolean,
-    maintain_order?: boolean,
+    nullsLast?: boolean,
+    maintainOrder?: boolean,
   ): DataFrame;
   sort({
     by,
     descending,
-    maintain_order,
+    maintainOrder,
   }: {
     by: ColumnsOrExpr;
     descending?: boolean;
-    nulls_last?: boolean;
-    maintain_order?: boolean;
+    nullsLast?: boolean;
+    maintainOrder?: boolean;
   }): DataFrame;
   /**
    * Aggregate the columns of this DataFrame to their standard deviation value.
@@ -2350,22 +2353,22 @@ export const _DataFrame = (_df: any): DataFrame => {
       }
       return wrap("slice", opts.offset, opts.length);
     },
-    sort(arg, descending = false, nulls_last = false, maintain_order = false) {
+    sort(arg, descending = false, nullsLast = false, maintainOrder = false) {
       if (arg?.by !== undefined) {
         return this.sort(
           arg.by,
           arg.descending,
-          arg.nulls_last,
-          arg.maintain_order,
+          arg.nullsLast,
+          arg.maintainOrder,
         );
       }
       if (Array.isArray(arg) || Expr.isExpr(arg)) {
         return _DataFrame(_df)
           .lazy()
-          .sort(arg, descending, nulls_last, maintain_order)
+          .sort(arg, descending, nullsLast, maintainOrder)
           .collectSync({ noOptimization: true });
       }
-      return wrap("sort", arg, descending, nulls_last, maintain_order);
+      return wrap("sort", arg, descending, nullsLast, maintainOrder);
     },
     std() {
       return this.lazy().std().collectSync();

polars/lazy/dataframe.ts

@@ -416,14 +416,14 @@ export interface LazyDataFrame extends Serialize, GroupByOps<LazyGroupBy> {
   sort(
     by: ColumnsOrExpr,
     descending?: ValueOrArray<boolean>,
-    nulls_last?: boolean,
-    maintain_order?: boolean,
+    nullsLast?: boolean,
+    maintainOrder?: boolean,
   ): LazyDataFrame;
   sort(opts: {
     by: ColumnsOrExpr;
     descending?: ValueOrArray<boolean>;
-    nulls_last?: boolean;
-    maintain_order?: boolean;
+    nullsLast?: boolean;
+    maintainOrder?: boolean;
   }): LazyDataFrame;
   /**
    * @see {@link DataFrame.std}
@@ -1022,20 +1022,20 @@ export const _LazyDataFrame = (_ldf: any): LazyDataFrame => {
       }
       return _LazyDataFrame(_ldf.slice(opt, len));
     },
-    sort(arg, descending = false, nulls_last = false, maintain_order = false) {
+    sort(arg, descending = false, nullsLast = false, maintainOrder = false) {
       if (arg?.by !== undefined) {
         return this.sort(
           arg.by,
           arg.descending,
-          arg.nulls_last,
-          arg.maintain_order,
+          arg.nullsLast,
+          arg.maintainOrder,
         );
       }
       if (typeof arg === "string") {
-        return wrap("sort", arg, descending, nulls_last, maintain_order);
+        return wrap("sort", arg, descending, nullsLast, maintainOrder);
       }
       const by = selectionToExprList(arg, false);
-      return wrap("sortByExprs", by, descending, nulls_last, maintain_order);
+      return wrap("sortByExprs", by, descending, nullsLast, maintainOrder);
     },
     std() {
       return _LazyDataFrame(_ldf.std());

polars/lazy/expr/index.ts

@@ -87,7 +87,7 @@ export interface Expr
     ...         "value": [94, 95, 96, 97, 97, 99],
     ...     }
     ... )
-    >>> df.group_by("group", maintain_order=True).agg(pl.col("value").aggGroups())
+    >>> df.group_by("group", maintainOrder=True).agg(pl.col("value").aggGroups())
     shape: (2, 2)
     ┌───────┬───────────┐
     │ group ┆ value     │
@@ -257,16 +257,16 @@ export interface Expr
   argMin(): Expr;
   /**
    * Get the index values that would sort this column.
-   * @param reverse
+   * @param descending
    *     - false -> order from small to large.
    *     - true -> order from large to small.
    * @returns UInt32 Series
    */
-  argSort(reverse?: boolean, maintain_order?: boolean): Expr;
+  argSort(descending?: boolean, maintainOrder?: boolean): Expr;
   argSort({
-    reverse,
-    maintain_order,
-  }: { reverse?: boolean; maintain_order?: boolean }): Expr;
+    descending,
+    maintainOrder,
+  }: { descending?: boolean; maintainOrder?: boolean }): Expr;
   /** Get index of first unique value. */
   argUnique(): Expr;
   /** @see {@link Expr.alias} */
@@ -730,9 +730,13 @@ export interface Expr
   prefix(prefix: string): Expr;
   /** Get quantile value. */
   quantile(quantile: number | Expr): Expr;
-  /** Assign ranks to data, dealing with ties appropriately. */
-  rank(method?: RankMethod): Expr;
-  rank({ method }: { method: string }): Expr;
+  /**
+   * Assign ranks to data, dealing with ties appropriately.
+   * @param - method : {'average', 'min', 'max', 'dense', 'ordinal', 'random'}
+   * @param - descending - Rank in descending order.
+   * */
+  rank(method?: RankMethod, descending?: boolean): Expr;
+  rank({ method, descending }: { method: string; descending: boolean }): Expr;
   reinterpret(signed?: boolean): Expr;
   reinterpret({ signed }: { signed: boolean }): Expr;
   /**
@@ -1030,16 +1034,16 @@ export interface Expr
   }: { offset: number | Expr; length: number | Expr }): Expr;
   /**
    * Sort this column. In projection/ selection context the whole column is sorted.
-   * @param reverse
+   * @param descending
    * * false -> order from small to large.
    * * true -> order from large to small.
    * @param nullsLast If true nulls are considered to be larger than any valid value
    */
-  sort(reverse?: boolean, nullsLast?: boolean): Expr;
+  sort(descending?: boolean, nullsLast?: boolean): Expr;
   sort({
-    reverse,
+    descending,
     nullsLast,
-  }: { reverse?: boolean; nullsLast?: boolean }): Expr;
+  }: { descending?: boolean; nullsLast?: boolean }): Expr;
   /**
    * Sort this column by the ordering of another column, or multiple other columns.
       In projection/ selection context the whole column is sorted.
@@ -1048,17 +1052,17 @@ export interface Expr
       Parameters
       ----------
       @param by The column(s) used for sorting.
-      @param reverse
+      @param descending
           false -> order from small to large.
           true -> order from large to small.
    */
   sortBy(
     by: ExprOrString[] | ExprOrString,
-    reverse?: boolean | boolean[],
+    descending?: boolean | boolean[],
   ): Expr;
   sortBy(options: {
     by: ExprOrString[] | ExprOrString;
-    reverse?: boolean | boolean[];
+    descending?: boolean | boolean[];
   }): Expr;
   /** Get standard deviation. */
   std(): Expr;
@@ -1230,10 +1234,10 @@ export const _Expr = (_expr: any): Expr => {
     argMin() {
       return _Expr(_expr.argMin());
     },
-    argSort(reverse: any = false, maintain_order?: boolean) {
-      reverse = reverse?.reverse ?? reverse;
-      maintain_order = reverse?.maintain_order ?? maintain_order;
-      return _Expr(_expr.argSort(reverse, false, false, maintain_order));
+    argSort(descending: any = false, maintainOrder?: boolean) {
+      descending = descending?.descending ?? descending;
+      maintainOrder = descending?.maintainOrder ?? maintainOrder;
+      return _Expr(_expr.argSort(descending, false, false, maintainOrder));
     },
     argUnique() {
       return _Expr(_expr.argUnique());
@@ -1621,9 +1625,9 @@ export const _Expr = (_expr: any): Expr => {
 
       return _Expr(_expr.quantile(quantile, interpolation));
     },
-    rank(method: any = "average", reverse = false) {
+    rank(method: any = "average", descending = false) {
       return _Expr(
-        _expr.rank(method?.method ?? method, method?.reverse ?? reverse),
+        _expr.rank(method?.method ?? method, method?.descending ?? descending),
       );
     },
     reinterpret(signed: any = true) {
@@ -1767,28 +1771,30 @@ export const _Expr = (_expr: any): Expr => {
 
       return wrap("slice", pli.lit(arg.offset), pli.lit(arg.length));
     },
-    sort(reverse: any = false, nullsLast = false, maintain_order = false) {
-      if (typeof reverse === "boolean") {
-        return wrap("sortWith", reverse, nullsLast, false, maintain_order);
+    sort(descending: any = false, nullsLast = false, maintainOrder = false) {
+      if (typeof descending === "boolean") {
+        return wrap("sortWith", descending, nullsLast, false, maintainOrder);
       }
 
       return wrap(
         "sortWith",
-        reverse?.reverse ?? false,
-        reverse?.nullsLast ?? nullsLast,
+        descending?.descending ?? false,
+        descending?.nullsLast ?? nullsLast,
         false,
-        reverse?.maintain_order ?? maintain_order,
+        descending?.maintainOrder ?? maintainOrder,
       );
     },
-    sortBy(arg, reverse = false) {
+    sortBy(arg, descending = false) {
       if (arg?.by !== undefined) {
-        return this.sortBy(arg.by, arg.reverse);
+        return this.sortBy(arg.by, arg.descending);
       }
 
-      reverse = Array.isArray(reverse) ? reverse.flat() : ([reverse] as any);
+      descending = Array.isArray(descending)
+        ? descending.flat()
+        : ([descending] as any);
       const by = selectionToExprList(arg, false);
 
-      return wrap("sortBy", by, reverse);
+      return wrap("sortBy", by, descending);
     },
     std() {
       return _Expr(_expr.std());