Skip to content

Commit

Permalink
depr(python): Deprecate shift_and_fill in favor of shift (#11955)
Browse files Browse the repository at this point in the history
  • Loading branch information
@stinodego
stinodego authored Oct 24, 2023
1 parent 21146be commit ca160cf
Show file tree
Hide file tree
Showing 19 changed files with 477 additions and 357 deletions.
5 changes: 0 additions & 5 deletions py-polars/Cargo.lock
View file

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
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
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

0 comments on commit ca160cf

Please sign in to comment.