From bd9a36197a020d0a7f1db41ac417c177a7ac31b1 Mon Sep 17 00:00:00 2001 From: Axel Obermeier Date: Mon, 23 Apr 2018 07:53:58 +0200 Subject: [PATCH 1/6] add concat-section to text.rst --- doc/source/text.rst | 69 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/doc/source/text.rst b/doc/source/text.rst index da8e40892716e..c5ccc9172e1ba 100644 --- a/doc/source/text.rst +++ b/doc/source/text.rst @@ -199,6 +199,75 @@ regular expression object will raise a ``ValueError``. --------------------------------------------------------------------------- ValueError: case and flags cannot be set when pat is a compiled regex +.. _text.concatenate: + +Concatenation +------------- + +There are several ways to concatenate a ``Series`` or ``Index``, either with itself or others, all based on :meth:`~Series.str.cat`, +resp. ``Index.str.cat``. + +Concatenating a single Series into a string +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The content of a ``Series`` can be concatenated: + +.. ipython:: python + + s = pd.Series(['a', 'b', 'c', 'd']) + s.str.cat(sep=',') + +If not specified, the keyword ``sep`` for the separator defaults to the empty string, ``sep=''``: + +.. ipython:: python + + s.str.cat() + +By default, missing values are ignored. Using ``na_rep``, they can be given a representation: + +.. ipython:: python + + t = pd.Series(['a', 'b', np.nan, 'd']) + t.str.cat(sep=',') + t.str.cat(sep=',', na_rep='-') + +Concatenating a Series and something list-like into a Series +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The first argument to :meth:`~Series.str.cat` can be a list-like object, provided that it matches the length of the calling ``Series``. + +.. ipython:: python + + s.str.cat(['A', 'B', 'C', 'D']) + +Missing values on either side will result in missing values in the result as well, *unless* ``na_rep`` is specified: + +.. ipython:: python + + s.str.cat(t) + s.str.cat(t, na_rep='-') + +Series are *not* aligned on their index before concatenation: + +.. ipython:: python + + u = pd.Series(['b', 'd', 'a', 'c'], index=[1, 3, 0, 2]) + # without alignment + s.str.cat(u) + # manual alignment + t, v = s.align(u) + t.str.cat(v) + +Concatenating a Series and many objects into a Series +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +List-likes (excluding iterators, ``dict``-views, etc.) can be arbitrarily combined in a list. +All elements of the list must match in length to the calling ``Series``: + +.. ipython:: python + + t = pd.Series([1, 2, 3, 4], index=['A', 'B', 'C', 'D']) + s.str.cat([['A', 'B', 'C', 'D'], s, s.values, t.index]) Indexing with ``.str`` ---------------------- From 03fa01d6c6e1ea01bbf55e4c4173e79a15c6ff1c Mon Sep 17 00:00:00 2001 From: Axel Obermeier Date: Mon, 23 Apr 2018 07:58:37 +0200 Subject: [PATCH 2/6] Fix variable names --- doc/source/text.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/source/text.rst b/doc/source/text.rst index c5ccc9172e1ba..767c92e3fcd36 100644 --- a/doc/source/text.rst +++ b/doc/source/text.rst @@ -255,8 +255,8 @@ Series are *not* aligned on their index before concatenation: # without alignment s.str.cat(u) # manual alignment - t, v = s.align(u) - t.str.cat(v) + v, w = s.align(u) + v.str.cat(w) Concatenating a Series and many objects into a Series ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -266,8 +266,8 @@ All elements of the list must match in length to the calling ``Series``: .. ipython:: python - t = pd.Series([1, 2, 3, 4], index=['A', 'B', 'C', 'D']) - s.str.cat([['A', 'B', 'C', 'D'], s, s.values, t.index]) + x = pd.Series([1, 2, 3, 4], index=['A', 'B', 'C', 'D']) + s.str.cat([['A', 'B', 'C', 'D'], s, s.values, x.index]) Indexing with ``.str`` ---------------------- From c5a52e6f5e9027f4c5b84ed411e17b8a03f879e4 Mon Sep 17 00:00:00 2001 From: Axel Obermeier Date: Mon, 23 Apr 2018 08:12:21 +0200 Subject: [PATCH 3/6] Add doc-string to _get_array_list --- pandas/core/strings.py | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/pandas/core/strings.py b/pandas/core/strings.py index 23c891ec4fcd0..47c212d9a0345 100644 --- a/pandas/core/strings.py +++ b/pandas/core/strings.py @@ -36,6 +36,22 @@ def _get_array_list(arr, others): + """ + Auxiliary function for :func:`str_cat` + + Parameters + ---------- + arr : ndarray + The left-most ndarray of the concatenation + others : list, ndarray, Series + The rest of the content to concatenate. If list of list-likes, + all elements must be passable to ``np.asarray``. + + Returns + ------- + list + List of all necessary arrays + """ from pandas.core.series import Series if len(others) and isinstance(com._values_from_object(others)[0], From be46e38d2f4a1e198a20b186f709de41a7b5dbac Mon Sep 17 00:00:00 2001 From: Axel Obermeier Date: Mon, 23 Apr 2018 09:34:08 +0200 Subject: [PATCH 4/6] Fix na_rep in align example --- doc/source/text.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/text.rst b/doc/source/text.rst index 767c92e3fcd36..15b96d4d6ecad 100644 --- a/doc/source/text.rst +++ b/doc/source/text.rst @@ -256,7 +256,7 @@ Series are *not* aligned on their index before concatenation: s.str.cat(u) # manual alignment v, w = s.align(u) - v.str.cat(w) + v.str.cat(w, na_rep='-') Concatenating a Series and many objects into a Series ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 20b69be6ca9d68ef687473d8ad5b30a2f6c7fc7e Mon Sep 17 00:00:00 2001 From: Axel Obermeier Date: Mon, 23 Apr 2018 15:01:56 +0200 Subject: [PATCH 5/6] Modifications after review --- doc/source/text.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/source/text.rst b/doc/source/text.rst index 15b96d4d6ecad..143507cc514dc 100644 --- a/doc/source/text.rst +++ b/doc/source/text.rst @@ -210,7 +210,7 @@ resp. ``Index.str.cat``. Concatenating a single Series into a string ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The content of a ``Series`` can be concatenated: +The content of a ``Series`` (or ``Index``) can be concatenated: .. ipython:: python @@ -234,7 +234,7 @@ By default, missing values are ignored. Using ``na_rep``, they can be given a re Concatenating a Series and something list-like into a Series ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The first argument to :meth:`~Series.str.cat` can be a list-like object, provided that it matches the length of the calling ``Series``. +The first argument to :meth:`~Series.str.cat` can be a list-like object, provided that it matches the length of the calling ``Series`` (or ``Index``). .. ipython:: python @@ -254,7 +254,7 @@ Series are *not* aligned on their index before concatenation: u = pd.Series(['b', 'd', 'a', 'c'], index=[1, 3, 0, 2]) # without alignment s.str.cat(u) - # manual alignment + # with separate alignment v, w = s.align(u) v.str.cat(w, na_rep='-') @@ -262,7 +262,7 @@ Concatenating a Series and many objects into a Series ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ List-likes (excluding iterators, ``dict``-views, etc.) can be arbitrarily combined in a list. -All elements of the list must match in length to the calling ``Series``: +All elements of the list must match in length to the calling ``Series`` (resp. ``Index``): .. ipython:: python From 4ae91965d063f5c6b6586a893274f64491244a38 Mon Sep 17 00:00:00 2001 From: Axel Obermeier Date: Mon, 23 Apr 2018 15:11:29 +0200 Subject: [PATCH 6/6] Further fix to alignment example --- doc/source/text.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/text.rst b/doc/source/text.rst index 143507cc514dc..bcbf7f0ef78d7 100644 --- a/doc/source/text.rst +++ b/doc/source/text.rst @@ -251,7 +251,7 @@ Series are *not* aligned on their index before concatenation: .. ipython:: python - u = pd.Series(['b', 'd', 'a', 'c'], index=[1, 3, 0, 2]) + u = pd.Series(['b', 'd', 'e', 'c'], index=[1, 3, 4, 2]) # without alignment s.str.cat(u) # with separate alignment