From 7982f691f00b951bce8229299cd6dbf9aa7abc67 Mon Sep 17 00:00:00 2001 From: "H. Vetinari" Date: Thu, 15 Nov 2018 09:09:28 +0100 Subject: [PATCH 1/5] DOC: update str.cat example --- doc/source/text.rst | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/doc/source/text.rst b/doc/source/text.rst index d01c48695d0d6..f6891bf773344 100644 --- a/doc/source/text.rst +++ b/doc/source/text.rst @@ -306,21 +306,24 @@ The same alignment can be used when ``others`` is a ``DataFrame``: Concatenating a Series and many objects into a Series ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -All one-dimensional list-likes can be combined in a list-like container (including iterators, ``dict``-views, etc.): +Several items can be combined a list-like container (including iterators, ``dict``-views, etc.), which may contain ``Series``, ``Index`` and ``np.ndarray``. +Note that ``Index`` will align as well, so we change the indexes of ``s`` and ``u`` to strings for the purpose of this example: .. ipython:: python - s - u - s.str.cat([u.values, - u.index.astype(str).values], na_rep='-') + s2 = s.set_axis(['a', 'b', 'c', 'd'], inplace=False) + s2 + u2 = u.set_axis(['b', 'd', 'a', 'c'], inplace=False) + u2 + s2.str.cat([pd.Index(['d', 'c', 'b', 'a']), u2, u2.values], na_rep='-', join='left') -All elements must match in length to the calling ``Series`` (or ``Index``), except those having an index if ``join`` is not None: +All ``np.ndarrays`` within the passed list-like must match in length to the calling ``Series`` (or ``Index``), +but ``Series`` and ``Index`` may have arbitrary length (as long as alignment is not disabled with ``join is not None``): .. ipython:: python v - s.str.cat([u, v], join='outer', na_rep='-') + s.str.cat([v, u, u.values], join='outer', na_rep='-') If using ``join='right'`` on a list of ``others`` that contains different indexes, the union of these indexes will be used as the basis for the final concatenation: From 75ef297901afef9d7a1107486678e91199cb6061 Mon Sep 17 00:00:00 2001 From: "H. Vetinari" Date: Sun, 18 Nov 2018 13:15:39 +0100 Subject: [PATCH 2/5] Review (jreback & WillAyd) --- doc/source/text.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/source/text.rst b/doc/source/text.rst index f6891bf773344..bac4c74a6f4e4 100644 --- a/doc/source/text.rst +++ b/doc/source/text.rst @@ -311,11 +311,13 @@ Note that ``Index`` will align as well, so we change the indexes of ``s`` and `` .. ipython:: python - s2 = s.set_axis(['a', 'b', 'c', 'd'], inplace=False) + s_values = np.array(['a', 'b', 'c', 'd'], dtype=object) # same as s.values + s2 = pd.Series(s_values, index=s_values) s2 - u2 = u.set_axis(['b', 'd', 'a', 'c'], inplace=False) + u_values = np.array(['b', 'd', 'a', 'c'], dtype=object) # same as u.values + u2 = pd.Series(u_values, index=u_values) u2 - s2.str.cat([pd.Index(['d', 'c', 'b', 'a']), u2, u2.values], na_rep='-', join='left') + s2.str.cat([pd.Index(['d', 'c', 'b', 'a']), u2, u_values], na_rep='-', join='left') All ``np.ndarrays`` within the passed list-like must match in length to the calling ``Series`` (or ``Index``), but ``Series`` and ``Index`` may have arbitrary length (as long as alignment is not disabled with ``join is not None``): @@ -323,7 +325,7 @@ but ``Series`` and ``Index`` may have arbitrary length (as long as alignment is .. ipython:: python v - s.str.cat([v, u, u.values], join='outer', na_rep='-') + s.str.cat([v, u, u_values], join='outer', na_rep='-') If using ``join='right'`` on a list of ``others`` that contains different indexes, the union of these indexes will be used as the basis for the final concatenation: From f7440525bd0c254846fcaa1e244f2d6a82fc646a Mon Sep 17 00:00:00 2001 From: "H. Vetinari" Date: Mon, 19 Nov 2018 07:47:54 +0100 Subject: [PATCH 3/5] Review (WillAyd & jreback) --- doc/source/text.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/doc/source/text.rst b/doc/source/text.rst index bac4c74a6f4e4..9ec49fecac2db 100644 --- a/doc/source/text.rst +++ b/doc/source/text.rst @@ -307,17 +307,19 @@ Concatenating a Series and many objects into a Series ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Several items can be combined a list-like container (including iterators, ``dict``-views, etc.), which may contain ``Series``, ``Index`` and ``np.ndarray``. -Note that ``Index`` will align as well, so we change the indexes of ``s`` and ``u`` to strings for the purpose of this example: +Note that ``Index`` will align as well, so for the purpose of this example, we change ``s`` and ``u`` from above to also have a string index: .. ipython:: python - s_values = np.array(['a', 'b', 'c', 'd'], dtype=object) # same as s.values + s_values = np.array(['a', 'b', 'c', 'd'], dtype=object) s2 = pd.Series(s_values, index=s_values) s2 - u_values = np.array(['b', 'd', 'a', 'c'], dtype=object) # same as u.values + u_values = np.array(['b', 'd', 'a', 'c'], dtype=object) u2 = pd.Series(u_values, index=u_values) u2 - s2.str.cat([pd.Index(['d', 'c', 'b', 'a']), u2, u_values], na_rep='-', join='left') + idx = pd.Index(['d', 'c', 'b', 'a']) + idx + s2.str.cat([u2, idx, u_values], join='left') All ``np.ndarrays`` within the passed list-like must match in length to the calling ``Series`` (or ``Index``), but ``Series`` and ``Index`` may have arbitrary length (as long as alignment is not disabled with ``join is not None``): @@ -327,7 +329,7 @@ but ``Series`` and ``Index`` may have arbitrary length (as long as alignment is v s.str.cat([v, u, u_values], join='outer', na_rep='-') -If using ``join='right'`` on a list of ``others`` that contains different indexes, +If using ``join='right'`` on a list-like of ``others`` that contains different indexes, the union of these indexes will be used as the basis for the final concatenation: .. ipython:: python From fc1d2ddc79c70469cdd11088297176d20993b2cc Mon Sep 17 00:00:00 2001 From: "H. Vetinari" Date: Thu, 3 Jan 2019 11:45:40 +0100 Subject: [PATCH 4/5] Review (WillAyd) --- 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 282cb600f23ac..43e3da9f973db 100644 --- a/doc/source/text.rst +++ b/doc/source/text.rst @@ -303,7 +303,7 @@ The same alignment can be used when ``others`` is a ``DataFrame``: Concatenating a Series and many objects into a Series ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Several items can be combined a list-like container (including iterators, ``dict``-views, etc.), which may contain ``Series``, ``Index``, ``PandasArray`` and ``np.ndarray``. +Several items (specifically: ``Series``, ``Index``, ``PandasArray`` and ``np.ndarray``) can be combined in a list-like container (including iterators, ``dict``-views, etc.). .. ipython:: python From b75c4159b5e2b7b8e9a2ce0ea1856c28b802015f Mon Sep 17 00:00:00 2001 From: "H. Vetinari" Date: Thu, 3 Jan 2019 21:34:36 +0100 Subject: [PATCH 5/5] Review (jreback) --- doc/source/text.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/source/text.rst b/doc/source/text.rst index 43e3da9f973db..e4f60a761750d 100644 --- a/doc/source/text.rst +++ b/doc/source/text.rst @@ -303,15 +303,16 @@ The same alignment can be used when ``others`` is a ``DataFrame``: Concatenating a Series and many objects into a Series ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Several items (specifically: ``Series``, ``Index``, ``PandasArray`` and ``np.ndarray``) can be combined in a list-like container (including iterators, ``dict``-views, etc.). +Several array-like items (specifically: ``Series``, ``Index``, and 1-dimensional variants of ``np.ndarray``) +can be combined in a list-like container (including iterators, ``dict``-views, etc.). .. ipython:: python s u - s.str.cat([u, u.array, u.to_numpy()], join='left') + s.str.cat([u, u.to_numpy()], join='left') -All elements without an index (e.g. ``PandasArray`` and ``np.ndarray``) within the passed list-like must match in length to the calling ``Series`` (or ``Index``), +All elements without an index (e.g. ``np.ndarray``) within the passed list-like must match in length to the calling ``Series`` (or ``Index``), but ``Series`` and ``Index`` may have arbitrary length (as long as alignment is not disabled with ``join=None``): .. ipython:: python