docs: code samples for Series.{add, replace, unique, T, transpose} (#287)

Thank you for opening a Pull Request! Before submitting your PR, there are a few things you can do to make sure it goes smoothly: - [ ] Make sure to open an issue as a [bug/issue](https://togithub.com/googleapis/python-bigquery-dataframes/issues/new/choose) before writing your code! That way we can discuss the change, evaluate designs, and agree on the general idea - [ ] Ensure the tests and linter pass - [ ] Code coverage does not decrease (if any source code was changed) - [x] Appropriate docs were updated (if necessary) - `Series.add`: https://screenshot.googleplex.com/763p36yJKKvM5DY - `Series.replace`: https://screenshot.googleplex.com/9MHuQZnKakqjjJn - `Series.unique`: https://screenshot.googleplex.com/7BfuQE3bFcYASqu - `Series.T`: https://screenshot.googleplex.com/8cSYpwKXrYetsEg - `Series.transpose`: https://screenshot.googleplex.com/7mM2zBwxRiqfDUV Fixes internal issue 317297573 🦕

Author: shobsi

third_party/bigframes_vendored/pandas/core/frame.py

@@ -4371,7 +4371,7 @@ def stack(self, level=-1):
  BigQuery DataFrames does not support stack operations that would
  combine columns of different dtypes.
 
- **Example:**
+ **Examples:**
 
  >>> import bigframes.pandas as bpd
  >>> bpd.options.display.progress_bar = None
@@ -4410,7 +4410,7 @@ def unstack(self, level=-1):
  If the index is not a MultiIndex, the output will be a Series
  (the analogue of stack when the columns are not a MultiIndex).
 
- **Example:**
+ **Examples:**
 
  >>> import bigframes.pandas as bpd
  >>> bpd.options.display.progress_bar = None

third_party/bigframes_vendored/pandas/core/series.py

@@ -143,13 +143,51 @@ def name(self) -> Hashable:
 
  @property
  def T(self) -> Series:
- """Return the transpose, which is by definition self."""
+ """Return the transpose, which is by definition self.
+
+ **Examples:**
+
+ >>> import bigframes.pandas as bpd
+ >>> bpd.options.display.progress_bar = None
+
+ >>> s = bpd.Series(['Ant', 'Bear', 'Cow'])
+ >>> s
+ 0 Ant
+ 1 Bear
+ 2 Cow
+ dtype: string
+
+ >>> s.T
+ 0 Ant
+ 1 Bear
+ 2 Cow
+ dtype: string
+
+ """
  raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)
 
  def transpose(self) -> Series:
  """
  Return the transpose, which is by definition self.
 
+ **Examples:**
+
+ >>> import bigframes.pandas as bpd
+ >>> bpd.options.display.progress_bar = None
+
+ >>> s = bpd.Series(['Ant', 'Bear', 'Cow'])
+ >>> s
+ 0 Ant
+ 1 Bear
+ 2 Cow
+ dtype: string
+
+ >>> s.transpose()
+ 0 Ant
+ 1 Bear
+ 2 Cow
+ dtype: string
+
  Returns:
  Series: Series.
  """
@@ -539,6 +577,36 @@ def nunique(self) -> int:
  """
  raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)
 
+ def unique(self) -> Series:
+ """
+ Return unique values of Series object.
+
+ Uniques are returned in order of appearance. Hash table-based unique,
+ therefore does NOT sort.
+
+ **Examples:**
+
+ >>> import bigframes.pandas as bpd
+ >>> bpd.options.display.progress_bar = None
+
+ >>> s = bpd.Series([2, 1, 3, 3], name='A')
+ >>> s
+ 0 2
+ 1 1
+ 2 3
+ 3 3
+ Name: A, dtype: Int64
+ >>> s.unique()
+ 0 2
+ 1 1
+ 2 3
+ Name: A, dtype: Int64
+
+ Returns:
+ Series: The unique values returned as a Series.
+ """
+ raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)
+
  def mode(self) -> Series:
  """
  Return the mode(s) of the Series.
@@ -1405,6 +1473,77 @@ def replace(
  This differs from updating with ``.loc`` or ``.iloc``, which require
  you to specify a location to update with some value.
 
+ **Examples:**
+
+ >>> import bigframes.pandas as bpd
+ >>> bpd.options.display.progress_bar = None
+
+ >>> s = bpd.Series([1, 2, 3, 4, 5])
+ >>> s
+ 0 1
+ 1 2
+ 2 3
+ 3 4
+ 4 5
+ dtype: Int64
+
+ >>> s.replace(1, 5)
+ 0 5
+ 1 2
+ 2 3
+ 3 4
+ 4 5
+ dtype: Int64
+
+ You can replace a list of values:
+
+ >>> s.replace([1, 3, 5], -1)
+ 0 -1
+ 1 2
+ 2 -1
+ 3 4
+ 4 -1
+ dtype: Int64
+
+ You can use a replacement mapping:
+
+ >>> s.replace({1: 5, 3: 10})
+ 0 5
+ 1 2
+ 2 10
+ 3 4
+ 4 5
+ dtype: Int64
+
+ With a string Series you can use a simple string replacement or a regex
+ replacement:
+
+ >>> s = bpd.Series(["Hello", "Another Hello"])
+ >>> s.replace("Hello", "Hi")
+ 0 Hi
+ 1 Another Hello
+ dtype: string
+
+ >>> s.replace("Hello", "Hi", regex=True)
+ 0 Hi
+ 1 Another Hi
+ dtype: string
+
+ >>> s.replace("^Hello", "Hi", regex=True)
+ 0 Hi
+ 1 Another Hello
+ dtype: string
+
+ >>> s.replace("Hello$", "Hi", regex=True)
+ 0 Hi
+ 1 Another Hi
+ dtype: string
+
+ >>> s.replace("[Hh]e", "__", regex=True)
+ 0 __llo
+ 1 Anot__r __llo
+ dtype: string
+
  Args:
  to_replace (str, regex, list, int, float or None):
  How to find the values that will be replaced.
@@ -1702,6 +1841,55 @@ def add(self, other) -> Series:
  Equivalent to ``series + other``, but with support to substitute a fill_value for
  missing data in either one of the inputs.
 
+ **Examples:**
+
+ >>> import bigframes.pandas as bpd
+ >>> bpd.options.display.progress_bar = None
+
+ >>> a = bpd.Series([1, 2, 3, bpd.NA])
+ >>> a
+ 0 1.0
+ 1 2.0
+ 2 3.0
+ 3 <NA>
+ dtype: Float64
+
+ >>> b = bpd.Series([10, 20, 30, 40])
+ >>> b
+ 0 10
+ 1 20
+ 2 30
+ 3 40
+ dtype: Int64
+
+ >>> a.add(b)
+ 0 11.0
+ 1 22.0
+ 2 33.0
+ 3 <NA>
+ dtype: Float64
+
+ You can also use the mathematical operator ``+``:
+
+ >>> a + b
+ 0 11.0
+ 1 22.0
+ 2 33.0
+ 3 <NA>
+ dtype: Float64
+
+ Adding two Series with explicit indexes:
+
+ >>> a = bpd.Series([1, 2, 3, 4], index=['a', 'b', 'c', 'd'])
+ >>> b = bpd.Series([10, 20, 30, 40], index=['a', 'b', 'd', 'e'])
+ >>> a.add(b)
+ a 11
+ b 22
+ c <NA>
+ d 34
+ e <NA>
+ dtype: Int64
+
  Args:
  other (Series, or scalar value):