w3resource

Pandas Series: str.cat() function

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)
Pandas Series: str.cat() function

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
    
    Pandas Series: str.cat() function

    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

    

    Become a Patron!

    Follow us on Facebook and Twitter for latest update.

    It will be nice if you may share this link in any developer community or anywhere else, from where other developers may find this content. Thanks.

    https://www.w3resource.com/pandas/series/series-str-cat.php