Pandas Series: str.cat() function

Last update on September 15 2022 12:57:29 (UTC/GMT +8 hours)

Series-str.cat() function

The str.cat() function is used to 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.

Syntax:

Series.str.cat(self, others=None, sep=None, na_rep=None, join=None)

Parameters:

Name	Description	Type/Default Value	Required / Optional
others	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.	Series, Index, DataFrame, np.ndarray or list-like	Required
sep	The separator between the different elements/columns. By default the empty string '' is used.	str, default ''	Required
na_rep	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.	str or None Default Value: None	Required
join	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). If None, alignment is disabled, but this option will be removed in a future version of pandas and replaced with a default of 'left'. To disable alignment, use .values on any Series/Index/DataFrame in others.	{'left', 'right', 'outer', 'inner'} Default Value: None	Required

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

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

Python-Pandas Code:

import numpy as np
import pandas as pd
s = pd.Series(['p', 'q', np.nan, 's'])
s.str.cat(sep=' ')

Output:

'p q s'

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

Python-Pandas Code:

import numpy as np
import pandas as pd
s = pd.Series(['p', 'q', np.nan, 's'])
s.str.cat(sep=' ', na_rep='?')

Output:

'p q ? s'

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

Python-Pandas Code:

import numpy as np
import pandas as pd
s = pd.Series(['p', 'q', np.nan, 's'])
s.str.cat(['P', 'Q', 'R', 'S'], sep=',')

Output:

0    p,P
1    q,Q
2    NaN
3    s,S
dtype: object

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

Python-Pandas Code:

import numpy as np
import pandas as pd
s = pd.Series(['p', 'q', np.nan, 's'])
s.str.cat(['P', 'Q', 'R', 'S'], sep=',', na_rep='-')

Output:

0    p,P
1    q,Q
2    -,R
3    s,S
dtype: object

Example - If sep is not specified, the values are concatenated without separation:

Python-Pandas Code:

import numpy as np
import pandas as pd
s = pd.Series(['p', 'q', np.nan, 's'])
s.str.cat(['P', 'Q', 'R', 'S'], na_rep='-')

Output:

0    pP
1    qQ
2    -R
3    sS
dtype: object

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

Python-Pandas Code:

import numpy as np
import pandas as pd
s = pd.Series(['p', 'q', np.nan, 's'])
t = pd.Series(['s', 'p', 't', 'r'], index=[2, 0, 4, 3])
s.str.cat(t, join='left', na_rep='-')

Output:

0    pp
1    q-
2    -s
3    sr
dtype: object

Python-Pandas Code:

import numpy as np
import pandas as pd
s = pd.Series(['p', 'q', np.nan, 's'])
t = pd.Series(['s', 'p', 't', 'r'], index=[2, 0, 4, 3])
s.str.cat(t, join='outer', na_rep='-')

Output:

0    pp
1    q-
2    -s
3    sr
4    -t
dtype: object

Python-Pandas Code:

import numpy as np
import pandas as pd
s = pd.Series(['p', 'q', np.nan, 's'])
t = pd.Series(['s', 'p', 't', 'r'], index=[2, 0, 4, 3])
s.str.cat(t, join='inner', na_rep='-')

Output:

0    pp
2    -s
3    sr
dtype: object

Python-Pandas Code:

import numpy as np
import pandas as pd
s = pd.Series(['p', 'q', np.nan, 's'])
t = pd.Series(['s', 'p', 't', 'r'], index=[2, 0, 4, 3])
s.str.cat(t, join='right', na_rep='-')

Output:

2    -s
0    pp
4    -t
3    sr
dtype: object

Previous: Series-str.casefold() function
Next: Series-str.contains() function