Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

depr(python): Deprecate shift_and_fill in favor of shift #11955

Merged
merged 8 commits into from
Oct 24, 2023
Merged

depr(python): Deprecate shift_and_fill in favor of shift #11955

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
a1898a0
Update Rust bindings
stinodego Oct 23, 2023
c630a87
Update Python side
stinodego Oct 23, 2023
89805df
Update tests
stinodego Oct 23, 2023
1cf5610
Update docstrings
stinodego Oct 23, 2023
525b707
Docstring update
stinodego Oct 23, 2023
827e0f0
Minor refactor
stinodego Oct 23, 2023
3faa56b
fmt
stinodego Oct 23, 2023
681bc65
Update lockfile
stinodego Oct 24, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 0 additions & 5 deletions py-polars/Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

149 changes: 78 additions & 71 deletions py-polars/polars/dataframe/frame.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7461,96 +7461,79 @@ def partition_by(
return partitions

@deprecate_renamed_parameter("periods", "n", version="0.19.11")
def shift(self, n: int = 1) -> DataFrame:
def shift(self, n: int = 1, *, fill_value: IntoExpr | None = None) -> DataFrame:
"""
Shift values by the given number of places.
Shift values by the given number of indices.

Parameters
----------
n
Number of places to shift (may be negative).
Number of indices to shift forward. If a negative value is passed, values
are shifted in the opposite direction instead.
fill_value
Fill the resulting null values with this value. Accepts expression input.
Non-expression inputs are parsed as literals.

See Also
--------
shift_and_fill
Notes
-----
This method is similar to the ``LAG`` operation in SQL when the value for ``n``
is positive. With a negative value for ``n``, it is similar to ``LEAD``.

Examples
--------
By default, values are shifted forward by one index.

>>> df = pl.DataFrame(
... {
... "foo": [1, 2, 3],
... "bar": [6, 7, 8],
... "ham": ["a", "b", "c"],
... "a": [1, 2, 3, 4],
... "b": [5, 6, 7, 8],
... }
... )
>>> df.shift(1)
shape: (3, 3)
┌──────┬──────┬──────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞══════╪══════╪══════╡
│ null ┆ null ┆ null │
│ 1 ┆ 6 ┆ a │
│ 2 ┆ 7 ┆ b │
└──────┴──────┴──────┘
>>> df.shift(-1)
shape: (3, 3)
┌──────┬──────┬──────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞══════╪══════╪══════╡
│ 2 ┆ 7 ┆ b │
│ 3 ┆ 8 ┆ c │
│ null ┆ null ┆ null │
└──────┴──────┴──────┘
>>> df.shift()
shape: (4, 2)
┌──────┬──────┐
│ a ┆ b │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞══════╪══════╡
│ null ┆ null │
│ 1 ┆ 5 │
│ 2 ┆ 6 │
│ 3 ┆ 7 │
└──────┴──────┘

"""
return self.lazy().shift(n=n).collect(_eager=True)
Pass a negative value to shift in the opposite direction instead.

@deprecate_renamed_parameter("periods", "n", version="0.19.11")
def shift_and_fill(
self,
fill_value: int | str | float,
*,
n: int = 1,
) -> DataFrame:
"""
Shift values by the given number of places and fill the resulting null values.
>>> df.shift(-2)
shape: (4, 2)
┌──────┬──────┐
│ a ┆ b │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞══════╪══════╡
│ 3 ┆ 7 │
│ 4 ┆ 8 │
│ null ┆ null │
│ null ┆ null │
└──────┴──────┘

Parameters
----------
fill_value
fill None values with this value.
n
Number of places to shift (may be negative).
Specify ``fill_value`` to fill the resulting null values.

Examples
--------
>>> df = pl.DataFrame(
... {
... "foo": [1, 2, 3],
... "bar": [6, 7, 8],
... "ham": ["a", "b", "c"],
... }
... )
>>> df.shift_and_fill(n=1, fill_value=0)
shape: (3, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 0 ┆ 0 ┆ 0 │
│ 1 ┆ 6 ┆ a │
│ 2 ┆ 7 ┆ b │
└─────┴─────┴─────┘
>>> df.shift(-2, fill_value=100)
shape: (4, 2)
┌─────┬─────┐
│ a ┆ b │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 3 ┆ 7 │
│ 4 ┆ 8 │
│ 100 ┆ 100 │
│ 100 ┆ 100 │
└─────┴─────┘

"""
return (
self.lazy().shift_and_fill(fill_value=fill_value, n=n).collect(_eager=True)
)
return self.lazy().shift(n, fill_value=fill_value).collect(_eager=True)

def is_duplicated(self) -> Series:
"""
Expand Down Expand Up @@ -10162,6 +10145,30 @@ def apply(
"""
return self.map_rows(function, return_dtype, inference_size=inference_size)

@deprecate_function("Use `shift` instead.", version="0.19.12")
@deprecate_renamed_parameter("periods", "n", version="0.19.11")
def shift_and_fill(
self,
fill_value: int | str | float,
*,
n: int = 1,
) -> DataFrame:
"""
Shift values by the given number of places and fill the resulting null values.

.. deprecated:: 0.19.12
Use :func:`shift` instead.

Parameters
----------
fill_value
fill None values with this value.
n
Number of places to shift (may be negative).

"""
return self.shift(n, fill_value=fill_value)


def _prepare_other_arg(other: Any, length: int | None = None) -> Series:
# if not a series create singleton series such that it will broadcast
Expand Down
125 changes: 77 additions & 48 deletions py-polars/polars/expr/expr.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2400,70 +2400,75 @@ def get(self, index: int | Expr) -> Self:
return self._from_pyexpr(self._pyexpr.get(index_lit))

@deprecate_renamed_parameter("periods", "n", version="0.19.11")
def shift(self, n: int = 1) -> Self:
def shift(self, n: int = 1, *, fill_value: IntoExpr | None = None) -> Self:
"""
Shift values by the given number of places.
Shift values by the given number of indices.

Parameters
----------
n
Number of places to shift (may be negative).
Number of indices to shift forward. If a negative value is passed, values
are shifted in the opposite direction instead.
fill_value
Fill the resulting null values with this value.

Notes
-----
This method is similar to the ``LAG`` operation in SQL when the value for ``n``
is positive. With a negative value for ``n``, it is similar to ``LEAD``.

Examples
--------
>>> df = pl.DataFrame({"foo": [1, 2, 3, 4]})
>>> df.with_columns(foo_shifted=pl.col("foo").shift(1))
By default, values are shifted forward by one index.

>>> df = pl.DataFrame({"a": [1, 2, 3, 4]})
>>> df.with_columns(shift=pl.col("a").shift())
shape: (4, 2)
┌─────┬─────────────┐
│ foo ┆ foo_shifted │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════════════╡
│ 1 ┆ null │
│ 2 ┆ 1 │
│ 3 ┆ 2 │
│ 4 ┆ 3 │
└─────┴─────────────┘
┌─────┬───────┐
│ a ┆ shift │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═══════╡
│ 1 ┆ null │
│ 2 ┆ 1 │
│ 3 ┆ 2 │
│ 4 ┆ 3 │
└─────┴───────┘

"""
return self._from_pyexpr(self._pyexpr.shift(n))
Pass a negative value to shift in the opposite direction instead.

@deprecate_renamed_parameter("periods", "n", version="0.19.11")
def shift_and_fill(
self,
fill_value: IntoExpr,
*,
n: int = 1,
) -> Self:
"""
Shift values by the given number of places and fill the resulting null values.
>>> df.with_columns(shift=pl.col("a").shift(-2))
shape: (4, 2)
┌─────┬───────┐
│ a ┆ shift │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═══════╡
│ 1 ┆ 3 │
│ 2 ┆ 4 │
│ 3 ┆ null │
│ 4 ┆ null │
└─────┴───────┘

Parameters
----------
fill_value
Fill None values with the result of this expression.
n
Number of places to shift (may be negative).
Specify ``fill_value`` to fill the resulting null values.

Examples
--------
>>> df = pl.DataFrame({"foo": [1, 2, 3, 4]})
>>> df.with_columns(foo_shifted=pl.col("foo").shift_and_fill("a", n=1))
>>> df.with_columns(shift=pl.col("a").shift(-2, fill_value=100))
shape: (4, 2)
┌─────┬─────────────┐
│ foo ┆ foo_shifted │
│ --- ┆ --- │
│ i64 ┆ str │
╞═════╪═════════════╡
│ 1 ┆ a │
│ 2 ┆ 1 │
│ 3 ┆ 2 │
│ 4 ┆ 3 │
└─────┴─────────────┘
┌─────┬───────┐
│ a ┆ shift │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═══════╡
│ 1 ┆ 3 │
│ 2 ┆ 4 │
│ 3 ┆ 100 │
│ 4 ┆ 100 │
└─────┴───────┘

"""
fill_value = parse_as_expression(fill_value, str_as_lit=True)
return self._from_pyexpr(self._pyexpr.shift_and_fill(n, fill_value))
if fill_value is not None:
fill_value = parse_as_expression(fill_value, str_as_lit=True)
return self._from_pyexpr(self._pyexpr.shift(n, fill_value))

def fill_null(
self,
Expand Down Expand Up @@ -9549,6 +9554,30 @@ def clip_max(
"""
return self.clip(upper_bound=upper_bound)

@deprecate_function("Use `shift` instead.", version="0.19.12")
@deprecate_renamed_parameter("periods", "n", version="0.19.11")
def shift_and_fill(
self,
fill_value: IntoExpr,
*,
n: int = 1,
) -> Self:
"""
Shift values by the given number of places and fill the resulting null values.

.. deprecated:: 0.19.12
Use :func:`shift` instead.

Parameters
----------
fill_value
Fill None values with the result of this expression.
n
Number of places to shift (may be negative).

"""
return self.shift(n, fill_value=fill_value)

def register_plugin(
self,
*,
Expand Down
Loading