pandas.Series.str.cat#

Series.str.cat(others=None, sep=None, na_rep=None, join='left')[source]#

Concatenate strings in the Series/Index with given separator.

If others is specified, this function concatenates the Series/Index and elements of others element-wise. If others is not passed, then all values in the Series/Index are concatenated into a single string with a given sep.

Parameters:
othersSeries, Index, DataFrame, np.ndarray or list-like

Series, Index, DataFrame, np.ndarray (one- or two-dimensional) and other list-likes of strings must have the same length as the calling Series/Index, with the exception of indexed objects (i.e. Series/Index/DataFrame) if join is not None.

If others is a list-like that contains a combination of Series, Index or np.ndarray (1-dim), then all elements will be unpacked and must satisfy the above criteria individually.

If others is None, the method returns the concatenation of all strings in the calling Series/Index.

sepstr, default ‘’

The separator between the different elements/columns. By default the empty string ‘’ is used.

na_repstr or None, default None

Representation that is inserted for all missing values:

  • If na_rep is None, and others is None, missing values in the Series/Index are omitted from the result.

  • If na_rep is None, and others is not None, a row containing a missing value in any of the columns (before concatenation) will have a missing value in the result.

join{‘left’, ‘right’, ‘outer’, ‘inner’}, default ‘left’

Determines the join-style between the calling Series/Index and any Series/Index/DataFrame in others (objects without an index need to match the length of the calling Series/Index). To disable alignment, use .values on any Series/Index/DataFrame in others. Note: when the caller is an Index, its values are used as the index for alignment, so a Series or DataFrame in others is aligned against those values rather than positionally. An Index or np.ndarray in others has no index of its own and is always used positionally.

Returns:
str, Series or Index

If others is None, str is returned, otherwise a Series/Index (same type as caller) of objects is returned.

See also

split

Split each string in the Series/Index.

join

Join lists contained as elements in the Series/Index.

Examples

When not passing others, all values are concatenated into a single string:

>>> s = pd.Series(["a", "b", np.nan, "d"])
>>> s.str.cat(sep=" ")
'a b d'

By default, NA values in the Series are ignored. Using na_rep, they can be given a representation:

>>> s.str.cat(sep=" ", na_rep="?")
'a b ? d'

If others is specified, corresponding values are concatenated with the separator. Result will be a Series of strings.

>>> s.str.cat(["A", "B", "C", "D"], sep=",")
0    a,A
1    b,B
2    NaN
3    d,D
dtype: str

Missing values will remain missing in the result, but can again be represented using na_rep

>>> s.str.cat(["A", "B", "C", "D"], sep=",", na_rep="-")
0    a,A
1    b,B
2    -,C
3    d,D
dtype: str

If sep is not specified, the values are concatenated without separation.

>>> s.str.cat(["A", "B", "C", "D"], na_rep="-")
0    aA
1    bB
2    -C
3    dD
dtype: str

Series with different indexes can be aligned before concatenation. The join-keyword works as in other methods.

>>> t = pd.Series(["d", "a", "e", "c"], index=[3, 0, 4, 2])
>>> s.str.cat(t, join="left", na_rep="-")
0    aa
1    b-
2    -c
3    dd
dtype: str
>>>
>>> s.str.cat(t, join="outer", na_rep="-")
0    aa
1    b-
2    -c
3    dd
4    -e
dtype: str
>>>
>>> s.str.cat(t, join="inner", na_rep="-")
0    aa
2    -c
3    dd
dtype: str
>>>
>>> s.str.cat(t, join="right", na_rep="-")
3    dd
0    aa
4    -e
2    -c
dtype: str

When the caller is an Index, alignment uses the values of that Index, so concatenating with a Series whose index is unrelated gives missing values:

>>> idx = pd.Index(["a", "b", "c"])
>>> idx.str.cat(pd.Series(["x", "y", "z"]))
Index([nan, nan, nan], dtype='object')

Use .to_numpy() (or .values) to concatenate positionally:

>>> idx.str.cat(pd.Series(["x", "y", "z"]).to_numpy())
Index(['ax', 'by', 'cz'], dtype='str')

For more examples, see here.

On this page