Skip to content

Commit

Permalink
docs[python] more docstrings (#4825)
Browse files Browse the repository at this point in the history
  • Loading branch information
@moritzwilksch
moritzwilksch committed Sep 12, 2022
1 parent d52dff7 commit 8ee9fd2
Show file tree
Hide file tree
Showing 3 changed files with 226 additions and 91 deletions.
103 changes: 66 additions & 37 deletions py-polars/polars/internals/dataframe/frame.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1487,6 +1487,20 @@ def to_arrow(self) -> pa.Table:
Data types that do copy:
- CategoricalType
Examples
--------
>>> df = pl.DataFrame(
... {"foo": [1, 2, 3, 4, 5, 6], "bar": ["a", "b", "c", "d", "e", "f"]}
... )
>>> df.to_arrow()
pyarrow.Table
foo: int64
bar: large_string
----
foo: [[1,2,3,4,5,6]]
bar: [["a","b","c","d","e","f"]]
"""
if not _PYARROW_AVAILABLE: # pragma: no cover
raise ImportError(
Expand Down Expand Up @@ -2758,6 +2772,27 @@ def limit(self: DF, n: int = 5) -> DF:
n
Number of rows to return.
Examples
--------
>>> df = pl.DataFrame(
... {"foo": [1, 2, 3, 4, 5, 6], "bar": ["a", "b", "c", "d", "e", "f"]}
... )
>>> df.limit(4)
shape: (4, 2)
┌─────┬─────┐
│ foo ┆ bar │
│ --- ┆ --- │
│ i64 ┆ str │
╞═════╪═════╡
│ 1 ┆ a │
├╌╌╌╌╌┼╌╌╌╌╌┤
│ 2 ┆ b │
├╌╌╌╌╌┼╌╌╌╌╌┤
│ 3 ┆ c │
├╌╌╌╌╌┼╌╌╌╌╌┤
│ 4 ┆ d │
└─────┴─────┘
"""
return self.head(n)

Expand Down Expand Up @@ -4487,54 +4522,48 @@ def explode(
--------
>>> df = pl.DataFrame(
... {
... "letters": ["c", "c", "a", "c", "a", "b"],
... "nrs": [[1, 2], [1, 3], [4, 3], [5, 5, 5], [6], [2, 1, 2]],
... "letters": ["a", "a", "b", "c"],
... "numbers": [[1], [2, 3], [4, 5], [6, 7, 8]],
... }
... )
>>> df
shape: (6, 2)
shape: (4, 2)
┌─────────┬───────────┐
│ letters ┆ nrs │
│ letters ┆ numbers │
│ --- ┆ --- │
│ str ┆ list[i64] │
╞═════════╪═══════════╡
│ c ┆ [1, 2] │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
│ c ┆ [1, 3] │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
│ a ┆ [4, 3] │
│ a ┆ [1] │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
│ c ┆ [5, 5, 5] │
│ a ┆ [2, 3] │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
│ a ┆ [6] │
│ b ┆ [4, 5] │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
│ b ┆ [2, 1, 2] │
│ c ┆ [6, 7, 8] │
└─────────┴───────────┘
>>> df.explode("nrs")
shape: (13, 2)
┌─────────┬─────┐
│ letters ┆ nrs │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════════╪═════╡
│ c ┆ 1 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌┤
│ c ┆ 2 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌┤
│ c ┆ 1 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌┤
│ c ┆ 3 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌┤
│ ... ┆ ... │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌┤
│ a ┆ 6 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌┤
│ b ┆ 2 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌┤
│ b ┆ 1 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌┤
│ b ┆ 2 │
└─────────┴─────┘
>>> df.explode("numbers")
shape: (8, 2)
┌─────────┬─────────┐
│ letters ┆ numbers │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════════╪═════════╡
│ a ┆ 1 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ a ┆ 2 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ a ┆ 3 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ b ┆ 4 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ b ┆ 5 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ c ┆ 6 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ c ┆ 7 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ c ┆ 8 │
└─────────┴─────────┘
"""
return self.lazy().explode(columns).collect(no_optimization=True)
Expand Down
212 changes: 158 additions & 54 deletions py-polars/polars/internals/lazyframe/frame.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2045,31 +2045,143 @@ def fill_nan(self: LDF, fill_value: int | str | float | pli.Expr | None) -> LDF:
return self._from_pyldf(self._ldf.fill_nan(fill_value._pyexpr))

def std(self: LDF, ddof: int = 1) -> LDF:
"""Aggregate the columns in the DataFrame to their standard deviation value."""
"""
Aggregate the columns in the DataFrame to their standard deviation value.
Examples
--------
>>> df = pl.DataFrame({"a": [1, 2, 3, 4], "b": [1, 2, 1, 1]}).lazy()
>>> df.std().collect()
shape: (1, 2)
┌──────────┬─────┐
│ a ┆ b │
│ --- ┆ --- │
│ f64 ┆ f64 │
╞══════════╪═════╡
│ 1.290994 ┆ 0.5 │
└──────────┴─────┘
"""
return self._from_pyldf(self._ldf.std(ddof))

def var(self: LDF, ddof: int = 1) -> LDF:
"""Aggregate the columns in the DataFrame to their variance value."""
"""
Aggregate the columns in the DataFrame to their variance value.
Examples
--------
>>> df = pl.DataFrame({"a": [1, 2, 3, 4], "b": [1, 2, 1, 1]}).lazy()
>>> df.var().collect()
shape: (1, 2)
┌──────────┬──────┐
│ a ┆ b │
│ --- ┆ --- │
│ f64 ┆ f64 │
╞══════════╪══════╡
│ 1.666667 ┆ 0.25 │
└──────────┴──────┘
"""
return self._from_pyldf(self._ldf.var(ddof))

def max(self: LDF) -> LDF:
"""Aggregate the columns in the DataFrame to their maximum value."""
"""
Aggregate the columns in the DataFrame to their maximum value.
Examples
--------
>>> df = pl.DataFrame({"a": [1, 2, 3, 4], "b": [1, 2, 1, 1]}).lazy()
>>> df.max().collect()
shape: (1, 2)
┌─────┬─────┐
│ a ┆ b │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 4 ┆ 2 │
└─────┴─────┘
"""
return self._from_pyldf(self._ldf.max())

def min(self: LDF) -> LDF:
"""Aggregate the columns in the DataFrame to their minimum value."""
"""
Aggregate the columns in the DataFrame to their minimum value.
Examples
--------
>>> df = pl.DataFrame({"a": [1, 2, 3, 4], "b": [1, 2, 1, 1]}).lazy()
>>> df.min().collect()
shape: (1, 2)
┌─────┬─────┐
│ a ┆ b │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1 ┆ 1 │
└─────┴─────┘
"""
return self._from_pyldf(self._ldf.min())

def sum(self: LDF) -> LDF:
"""Aggregate the columns in the DataFrame to their sum value."""
"""
Aggregate the columns in the DataFrame to their sum value.
Examples
--------
>>> df = pl.DataFrame({"a": [1, 2, 3, 4], "b": [1, 2, 1, 1]}).lazy()
>>> df.sum().collect()
shape: (1, 2)
┌─────┬─────┐
│ a ┆ b │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 10 ┆ 5 │
└─────┴─────┘
"""
return self._from_pyldf(self._ldf.sum())

def mean(self: LDF) -> LDF:
"""Aggregate the columns in the DataFrame to their mean value."""
"""
Aggregate the columns in the DataFrame to their mean value.
Examples
--------
>>> df = pl.DataFrame({"a": [1, 2, 3, 4], "b": [1, 2, 1, 1]}).lazy()
>>> df.mean().collect()
shape: (1, 2)
┌─────┬──────┐
│ a ┆ b │
│ --- ┆ --- │
│ f64 ┆ f64 │
╞═════╪══════╡
│ 2.5 ┆ 1.25 │
└─────┴──────┘
"""
return self._from_pyldf(self._ldf.mean())

def median(self: LDF) -> LDF:
"""Aggregate the columns in the DataFrame to their median value."""
"""
Aggregate the columns in the DataFrame to their median value.
Examples
--------
>>> df = pl.DataFrame({"a": [1, 2, 3, 4], "b": [1, 2, 1, 1]}).lazy()
>>> df.median().collect()
shape: (1, 2)
┌─────┬─────┐
│ a ┆ b │
│ --- ┆ --- │
│ f64 ┆ f64 │
╞═════╪═════╡
│ 2.5 ┆ 1.0 │
└─────┴─────┘
"""
return self._from_pyldf(self._ldf.median())

def quantile(
Expand All @@ -2085,6 +2197,19 @@ def quantile(
interpolation : {'nearest', 'higher', 'lower', 'midpoint', 'linear'}
Interpolation method.
Examples
--------
>>> df = pl.DataFrame({"a": [1, 2, 3, 4], "b": [1, 2, 1, 1]}).lazy()
>>> df.quantile(0.7).collect()
shape: (1, 2)
┌─────┬─────┐
│ a ┆ b │
│ --- ┆ --- │
│ f64 ┆ f64 │
╞═════╪═════╡
│ 3.0 ┆ 1.0 │
└─────┴─────┘
"""
return self._from_pyldf(self._ldf.quantile(quantile, interpolation))

Expand All @@ -2099,54 +2224,33 @@ def explode(
--------
>>> df = pl.DataFrame(
... {
... "letters": ["c", "c", "a", "c", "a", "b"],
... "nrs": [[1, 2], [1, 3], [4, 3], [5, 5, 5], [6], [2, 1, 2]],
... "letters": ["a", "a", "b", "c"],
... "numbers": [[1], [2, 3], [4, 5], [6, 7, 8]],
... }
... )
>>> df
shape: (6, 2)
┌─────────┬───────────┐
│ letters ┆ nrs │
│ --- ┆ --- │
│ str ┆ list[i64] │
╞═════════╪═══════════╡
│ c ┆ [1, 2] │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
│ c ┆ [1, 3] │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
│ a ┆ [4, 3] │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
│ c ┆ [5, 5, 5] │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
│ a ┆ [6] │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
│ b ┆ [2, 1, 2] │
└─────────┴───────────┘
>>> df.explode("nrs")
shape: (13, 2)
┌─────────┬─────┐
│ letters ┆ nrs │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════════╪═════╡
│ c ┆ 1 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌┤
│ c ┆ 2 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌┤
│ c ┆ 1 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌┤
│ c ┆ 3 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌┤
│ ... ┆ ... │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌┤
│ a ┆ 6 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌┤
│ b ┆ 2 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌┤
│ b ┆ 1 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌┤
│ b ┆ 2 │
└─────────┴─────┘
... ).lazy()
>>> df.explode("numbers").collect()
shape: (8, 2)
┌─────────┬─────────┐
│ letters ┆ numbers │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════════╪═════════╡
│ a ┆ 1 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ a ┆ 2 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ a ┆ 3 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ b ┆ 4 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ b ┆ 5 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ c ┆ 6 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ c ┆ 7 │
├╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ c ┆ 8 │
└─────────┴─────────┘
"""
columns = pli.selection_to_pyexpr_list(columns)
Expand Down
2 changes: 2 additions & 0 deletions py-polars/polars/internals/series/series.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3777,6 +3777,8 @@ def pct_change(self, n: int = 1) -> Series:
n
periods to shift for forming percent change.
Examples
--------
>>> pl.Series(range(10)).pct_change()
shape: (10,)
Series: '' [f64]
Expand Down

0 comments on commit 8ee9fd2

Please sign in to comment.