From d543b629f44eabb8fe165f0228244d1ad1496daf Mon Sep 17 00:00:00 2001 From: Bidek56 Date: Sat, 21 Sep 2024 15:08:10 -0400 Subject: [PATCH 1/2] Replacing reverse with descending --- README.md | 2 +- __tests__/dataframe.test.ts | 8 ++--- __tests__/expr.test.ts | 22 ++++++------ __tests__/lazyframe.test.ts | 4 +-- __tests__/series.test.ts | 6 ++-- polars/dataframe.ts | 25 +++++++------ polars/lazy/dataframe.ts | 18 +++++----- polars/lazy/expr/index.ts | 70 ++++++++++++++++++++----------------- polars/lazy/expr/list.ts | 8 ++--- polars/series/index.ts | 34 ++++++++++-------- polars/series/list.ts | 8 ++--- polars/shared_traits.ts | 4 +-- src/lazy/dsl.rs | 4 +-- src/series.rs | 4 +-- 14 files changed, 116 insertions(+), 101 deletions(-) diff --git a/README.md b/README.md index bfbdb24ae..745d747d2 100644 --- a/README.md +++ b/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] [ diff --git a/__tests__/dataframe.test.ts b/__tests__/dataframe.test.ts index 39e0c1917..ca1b30123 100644 --- a/__tests__/dataframe.test.ts +++ b/__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], }); diff --git a/__tests__/expr.test.ts b/__tests__/expr.test.ts index 760f325fc..c1237aa81 100644 --- a/__tests__/expr.test.ts +++ b/__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]); diff --git a/__tests__/lazyframe.test.ts b/__tests__/lazyframe.test.ts index 571bf3246..acd4cbb36 100644 --- a/__tests__/lazyframe.test.ts +++ b/__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], diff --git a/__tests__/series.test.ts b/__tests__/series.test.ts index 2af7df72c..4db2ab2d9 100644 --- a/__tests__/series.test.ts +++ b/__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)} diff --git a/polars/dataframe.ts b/polars/dataframe.ts index 1ba053bac..e1af2dde5 100644 --- a/polars/dataframe.ts +++ b/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(); diff --git a/polars/lazy/dataframe.ts b/polars/lazy/dataframe.ts index 86d663d28..5c10ca766 100644 --- a/polars/lazy/dataframe.ts +++ b/polars/lazy/dataframe.ts @@ -416,14 +416,14 @@ export interface LazyDataFrame extends Serialize, GroupByOps { sort( by: ColumnsOrExpr, descending?: ValueOrArray, - nulls_last?: boolean, - maintain_order?: boolean, + nullsLast?: boolean, + maintainOrder?: boolean, ): LazyDataFrame; sort(opts: { by: ColumnsOrExpr; descending?: ValueOrArray; - 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()); diff --git a/polars/lazy/expr/index.ts b/polars/lazy/expr/index.ts index 5827a629a..3fcf84aa8 100644 --- a/polars/lazy/expr/index.ts +++ b/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()); diff --git a/polars/lazy/expr/list.ts b/polars/lazy/expr/list.ts index abe69affc..d265560e3 100644 --- a/polars/lazy/expr/list.ts +++ b/polars/lazy/expr/list.ts @@ -110,10 +110,10 @@ export const ExprListFunctions = (_expr: any): ExprList => { exprToLitOrExpr(length)._expr, ); }, - sort(reverse: any = false) { - return typeof reverse === "boolean" - ? wrap("listSort", reverse) - : wrap("listSort", reverse.reverse); + sort(descending: any = false) { + return typeof descending === "boolean" + ? wrap("listSort", descending) + : wrap("listSort", descending.descending); }, sum() { return wrap("listSum"); diff --git a/polars/series/index.ts b/polars/series/index.ts index 4f49fb357..e1febf874 100644 --- a/polars/series/index.ts +++ b/polars/series/index.ts @@ -125,14 +125,18 @@ export interface Series */ argUnique(): Series; /** - * Index location of the sorted variant of this Series. + * Get the index values that would sort this Series. * ___ - * @param reverse + * @param descending - Sort in descending order. + * @param nullsLast - Place null values last instead of first. * @return {SeriesType} indexes - Indexes that can be used to sort this array. */ argSort(): Series; - argSort(reverse: boolean): Series; - argSort({ reverse }: { reverse: boolean }): Series; + argSort(descending?: boolean, nullsLast?: boolean): Series; + argSort({ + descending, + nullsLast, + }: { descending?: boolean; nullsLast?: boolean }): Series; /** * __Rename this Series.__ * @@ -713,6 +717,7 @@ export interface Series * Assign ranks to data, dealing with ties appropriately. * @param method * The method used to assign ranks to tied elements. + * @param method: {'average', 'min', 'max', 'dense', 'ordinal', 'random'} * The following methods are available: _default is 'average'_ * * * __'average'__: The average of the ranks that would have been assigned to @@ -729,8 +734,9 @@ export interface Series * the order that the values occur in `a`. * * __'random'__: Like 'ordinal', but the rank for ties is not dependent * on the order that the values occur in `a`. + * @param descending - Rank in descending order. */ - rank(method?: RankMethod): Series; + rank(method?: RankMethod, descending?: boolean): Series; rechunk(): Series; rechunk(inPlace: true): Series; rechunk(inPlace: false): void; @@ -1216,23 +1222,23 @@ export function _Series(_s: any): Series { return _s.argMin(); }, argSort( - reverse: any = false, + descending: any = false, nullsLast = true, multithreaded = true, maintainOrder = false, ) { - if (typeof reverse === "boolean") { + if (typeof descending === "boolean") { return _Series( - _s.argsort(reverse, nullsLast, multithreaded, maintainOrder), + _s.argsort(descending, nullsLast, multithreaded, maintainOrder), ); } return _Series( _s.argsort( - reverse.reverse, - reverse.nullsLast ?? nullsLast, - reverse.multithreaded ?? multithreaded, - reverse.maintainOrder ?? maintainOrder, + descending.descending, + descending.nullsLast ?? nullsLast, + descending.multithreaded ?? multithreaded, + descending.maintainOrder ?? maintainOrder, ), ); }, @@ -1590,8 +1596,8 @@ export function _Series(_s: any): Series { quantile(quantile, interpolation = "nearest") { return _s.quantile(quantile, interpolation); }, - rank(method = "average", reverse = false) { - return wrap("rank", method, reverse); + rank(method = "average", descending = false) { + return wrap("rank", method, descending); }, rechunk(inPlace = false) { return wrap("rechunk", inPlace); diff --git a/polars/series/list.ts b/polars/series/list.ts index d39d62df2..c2a15232b 100644 --- a/polars/series/list.ts +++ b/polars/series/list.ts @@ -77,10 +77,10 @@ export const SeriesListFunctions = (_s): ListFunctions => { slice(offset, length) { return wrap("slice", offset, length); }, - sort(reverse: any = false) { - return typeof reverse === "boolean" - ? wrap("sort", reverse) - : wrap("sort", reverse.reverse); + sort(descending: any = false) { + return typeof descending === "boolean" + ? wrap("sort", descending) + : wrap("sort", descending.descending); }, sum() { return wrap("sum"); diff --git a/polars/shared_traits.ts b/polars/shared_traits.ts index 3ef3cc956..6c257dce4 100644 --- a/polars/shared_traits.ts +++ b/polars/shared_traits.ts @@ -717,8 +717,8 @@ export interface ListFunctions { * @param reverse - Sort in reverse order. * @category List */ - sort(reverse?: boolean): T; - sort(opt: { reverse: boolean }): T; + sort(descending?: boolean): T; + sort(opt: { descending: boolean }): T; /** * Sum all elements of the sublists. * @category List diff --git a/src/lazy/dsl.rs b/src/lazy/dsl.rs index 51db6a20f..802b08c5b 100644 --- a/src/lazy/dsl.rs +++ b/src/lazy/dsl.rs @@ -1357,13 +1357,13 @@ impl JsExpr { .into() } #[napi(catch_unwind)] - pub fn rank(&self, method: Wrap, reverse: bool, seed: Option>) -> JsExpr { + pub fn rank(&self, method: Wrap, descending: bool, seed: Option>) -> JsExpr { // Safety: // Wrap is transparent. let seed: Option = unsafe { std::mem::transmute(seed) }; let options = RankOptions { method: method.0, - descending: reverse, + descending, }; self.inner.clone().rank(options, seed).into() } diff --git a/src/series.rs b/src/series.rs index 66da7f496..a85c4aa8a 100644 --- a/src/series.rs +++ b/src/series.rs @@ -526,14 +526,14 @@ impl JsSeries { #[napi] pub fn argsort( &self, - reverse: bool, + descending: bool, nulls_last: bool, multithreaded: bool, maintain_order: bool, ) -> JsSeries { self.series .arg_sort(SortOptions { - descending: reverse, + descending, nulls_last, multithreaded, maintain_order, From 975728a6088296e19d7ad7d1abc08d392bcc9f37 Mon Sep 17 00:00:00 2001 From: Bidek56 Date: Sat, 28 Sep 2024 19:38:11 -0400 Subject: [PATCH 2/2] Deprecating reverse sort option --- __tests__/dataframe.test.ts | 9 ++++++++- __tests__/expr.test.ts | 1 + polars/dataframe.ts | 13 ++++++++++++- polars/lazy/expr/index.ts | 24 +++++++++++++++++++++--- polars/series/index.ts | 17 +++++++++++++++-- polars/series/list.ts | 2 +- polars/shared_traits.ts | 5 ++++- 7 files changed, 62 insertions(+), 9 deletions(-) diff --git a/__tests__/dataframe.test.ts b/__tests__/dataframe.test.ts index ca1b30123..d4bb9a865 100644 --- a/__tests__/dataframe.test.ts +++ b/__tests__/dataframe.test.ts @@ -1009,7 +1009,7 @@ describe("dataframe", () => { expect(actual).toFrameEqual(expected); }); test("sort:named", () => { - const actual = pl + let actual = pl .DataFrame({ foo: [1, 2, 3, 1], bar: [6, 7, 8, 1], @@ -1020,6 +1020,13 @@ describe("dataframe", () => { bar: [8, 7, 6, 1], }); expect(actual).toFrameEqual(expected); + actual = pl + .DataFrame({ + foo: [1, 2, 3, 1], + bar: [6, 7, 8, 1], + }) + .sort({ by: "bar", reverse: true }); // deprecated + expect(actual).toFrameEqual(expected); }); test("sort:multi-args", () => { const actual = pl diff --git a/__tests__/expr.test.ts b/__tests__/expr.test.ts index c1237aa81..49cd9ba84 100644 --- a/__tests__/expr.test.ts +++ b/__tests__/expr.test.ts @@ -75,6 +75,7 @@ describe("expr", () => { ${undefined} | ${[1, 0, 3, 2]} ${true} | ${[2, 3, 0, 1]} ${{ descending: true }} | ${[2, 3, 0, 1]} + ${{ reverse: true }} | ${[2, 3, 0, 1]} `("argSort", ({ args, expectedSort }) => { const df = pl.DataFrame({ a: [1, 0, 2, 1.5] }); const expected = pl.DataFrame({ argSort: expectedSort }); diff --git a/polars/dataframe.ts b/polars/dataframe.ts index 5b26e0931..2b398c014 100644 --- a/polars/dataframe.ts +++ b/polars/dataframe.ts @@ -1358,6 +1358,7 @@ export interface DataFrame * Sort the DataFrame by column. * ___ * @param by - Column(s) to sort by. Accepts expression input, including selectors. Strings are parsed as column names. + * @deprecated *since 0.16.0* @use descending * @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. @@ -1369,6 +1370,16 @@ export interface DataFrame nullsLast?: boolean, maintainOrder?: boolean, ): DataFrame; + sort({ + by, + reverse, // deprecated + maintainOrder, + }: { + by: ColumnsOrExpr; + reverse?: boolean; // deprecated + nullsLast?: boolean; + maintainOrder?: boolean; + }): DataFrame; sort({ by, descending, @@ -2363,7 +2374,7 @@ export const _DataFrame = (_df: any): DataFrame => { if (arg?.by !== undefined) { return this.sort( arg.by, - arg.descending, + arg.descending ?? arg.reverse ?? false, arg.nullsLast, arg.maintainOrder, ); diff --git a/polars/lazy/expr/index.ts b/polars/lazy/expr/index.ts index 3fcf84aa8..ebc3e073f 100644 --- a/polars/lazy/expr/index.ts +++ b/polars/lazy/expr/index.ts @@ -257,12 +257,18 @@ export interface Expr argMin(): Expr; /** * Get the index values that would sort this column. + * @deprecated *since 0.16.0* @use descending + * @param reverse - Reverse/descending sort. * @param descending * - false -> order from small to large. * - true -> order from large to small. * @returns UInt32 Series */ argSort(descending?: boolean, maintainOrder?: boolean): Expr; + argSort({ + reverse, // deprecated + maintainOrder, + }: { reverse?: boolean; maintainOrder?: boolean }): Expr; argSort({ descending, maintainOrder, @@ -1034,6 +1040,8 @@ export interface Expr }: { offset: number | Expr; length: number | Expr }): Expr; /** * Sort this column. In projection/ selection context the whole column is sorted. + * @deprecated *since 0.16.0* @use descending + * @param reverse - Reverse/descending sort. * @param descending * * false -> order from small to large. * * true -> order from large to small. @@ -1044,6 +1052,10 @@ export interface Expr descending, nullsLast, }: { descending?: boolean; nullsLast?: boolean }): Expr; + sort({ + reverse, // deprecated + nullsLast, + }: { reverse?: 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. @@ -1052,6 +1064,8 @@ export interface Expr Parameters ---------- @param by The column(s) used for sorting. + @deprecated *since 0.16.0* @use descending + @param reverse - Reverse/descending sort. @param descending false -> order from small to large. true -> order from large to small. @@ -1064,6 +1078,10 @@ export interface Expr by: ExprOrString[] | ExprOrString; descending?: boolean | boolean[]; }): Expr; + sortBy(options: { + by: ExprOrString[] | ExprOrString; + reverse?: boolean | boolean[]; + }): Expr; /** Get standard deviation. */ std(): Expr; /** Add a suffix the to root column name of the expression. */ @@ -1235,7 +1253,7 @@ export const _Expr = (_expr: any): Expr => { return _Expr(_expr.argMin()); }, argSort(descending: any = false, maintainOrder?: boolean) { - descending = descending?.descending ?? descending; + descending = descending?.descending ?? descending?.reverse ?? descending; maintainOrder = descending?.maintainOrder ?? maintainOrder; return _Expr(_expr.argSort(descending, false, false, maintainOrder)); }, @@ -1778,7 +1796,7 @@ export const _Expr = (_expr: any): Expr => { return wrap( "sortWith", - descending?.descending ?? false, + descending?.descending ?? descending?.reverse ?? false, descending?.nullsLast ?? nullsLast, false, descending?.maintainOrder ?? maintainOrder, @@ -1786,7 +1804,7 @@ export const _Expr = (_expr: any): Expr => { }, sortBy(arg, descending = false) { if (arg?.by !== undefined) { - return this.sortBy(arg.by, arg.descending); + return this.sortBy(arg.by, arg.descending ?? arg.reverse ?? false); } descending = Array.isArray(descending) diff --git a/polars/series/index.ts b/polars/series/index.ts index 29092eccc..8f7e4b15b 100644 --- a/polars/series/index.ts +++ b/polars/series/index.ts @@ -127,6 +127,8 @@ export interface Series /** * Get the index values that would sort this Series. * ___ + * @deprecated *since 0.16.0* @use descending + * @param reverse - Reverse/descending sort. * @param descending - Sort in descending order. * @param nullsLast - Place null values last instead of first. * @return {SeriesType} indexes - Indexes that can be used to sort this array. @@ -137,6 +139,10 @@ export interface Series descending, nullsLast, }: { descending?: boolean; nullsLast?: boolean }): Series; + argSort({ + reverse, // deprecated + nullsLast, + }: { reverse?: boolean; nullsLast?: boolean }): Series; /** * __Rename this Series.__ * @@ -877,6 +883,8 @@ export interface Series slice(start: number, length?: number): Series; /** * __Sort this Series.__ + * @deprecated *since 0.16.0* @use descending + * @param reverse - Reverse/descending sort. * @param descending - Sort in descending order. * @param nullsLast - Place nulls at the end. * @example @@ -904,6 +912,7 @@ export interface Series */ sort(): Series; sort(options: { descending?: boolean; nullsLast?: boolean }): Series; + sort(options: { reverse?: boolean; nullsLast?: boolean }): Series; /** * Reduce this Series to the sum value. * @example @@ -1235,7 +1244,7 @@ export function _Series(_s: any): Series { return _Series( _s.argsort( - descending.descending, + descending.descending ?? descending.reverse ?? false, descending.nullsLast ?? nullsLast, descending.multithreaded ?? multithreaded, descending.maintainOrder ?? maintainOrder, @@ -1747,7 +1756,11 @@ export function _Series(_s: any): Series { }, sort(options?) { options = { descending: false, nullsLast: false, ...(options ?? {}) }; - return wrap("sort", options.descending, options.nullsLast); + return wrap( + "sort", + options.descending ?? options.reverse ?? false, + options.nullsLast, + ); }, sub(field) { return dtypeWrap("Sub", field); diff --git a/polars/series/list.ts b/polars/series/list.ts index c2a15232b..bcbea3ede 100644 --- a/polars/series/list.ts +++ b/polars/series/list.ts @@ -80,7 +80,7 @@ export const SeriesListFunctions = (_s): ListFunctions => { sort(descending: any = false) { return typeof descending === "boolean" ? wrap("sort", descending) - : wrap("sort", descending.descending); + : wrap("sort", descending.descending ?? descending.reverse ?? false); }, sum() { return wrap("sum"); diff --git a/polars/shared_traits.ts b/polars/shared_traits.ts index 6c257dce4..cd7804702 100644 --- a/polars/shared_traits.ts +++ b/polars/shared_traits.ts @@ -714,11 +714,14 @@ export interface ListFunctions { slice(offset: number, length: number): T; /** * Sort the sublists. - * @param reverse - Sort in reverse order. + * @deprecated *since 0.16.0* @use descending + * @param reverse - Reverse/descending sort. + * @param descending - Sort in reverse order. * @category List */ sort(descending?: boolean): T; sort(opt: { descending: boolean }): T; + sort(opt: { reverse: boolean }): T; /** * Sum all elements of the sublists. * @category List