pandas.concat#

pandas.concat(objs,*,axis=0,join='outer',ignore_index=False,keys=None,levels=None,names=None,verify_integrity=False,sort=False,copy=None)[source]#

Concatenate pandas objects along a particular axis.

Allows optional set logic along the other axes.

Can also add a layer of hierarchical indexing on the concatenation axis,which may be useful if the labels are the same (or overlapping) onthe passed axis number.

Parameters:

objsa sequence or mapping of Series or DataFrame objects

If a mapping is passed, the sorted keys will be used as thekeysargument, unless it is passed, in which case the values will beselected (see below). Any None objects will be dropped silently unlessthey are all None in which case a ValueError will be raised.

axis{0/’index’, 1/’columns’}, default 0

The axis to concatenate along.

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

How to handle indexes on other axis (or axes).

ignore_indexbool, default False

If True, do not use the index values along the concatenation axis. Theresulting axis will be labeled 0, …, n - 1. This is useful if you areconcatenating objects where the concatenation axis does not havemeaningful indexing information. Note the index values on the otheraxes are still respected in the join.

keyssequence, default None

If multiple levels passed, should contain tuples. Constructhierarchical index using the passed keys as the outermost level.

levelslist of sequences, default None

Specific levels (unique values) to use for constructing aMultiIndex. Otherwise they will be inferred from the keys.

nameslist, default None

Names for the levels in the resulting hierarchical index.

verify_integritybool, default False

Check whether the new concatenated axis contains duplicates. This canbe very expensive relative to the actual data concatenation.

sortbool, default False

Sort non-concatenation axis if it is not already aligned. One exception tothis is when the non-concatentation axis is a DatetimeIndex and join=’outer’and the axis is not already aligned. In that case, the non-concatenationaxis is always sorted lexicographically.

copybool, default True

If False, do not copy data unnecessarily.

Returns:

object, type of objs

When concatenating allSeries along the index (axis=0), aSeries is returned. Whenobjs contains at least oneDataFrame, aDataFrame is returned. When concatenating alongthe columns (axis=1), aDataFrame is returned.

See also

DataFrame.join

Join DataFrames using indexes.

DataFrame.merge

Merge DataFrames by indexes or columns.

Notes

The keys, levels, and names arguments are all optional.

A walkthrough of how this method fits in with other tools for combiningpandas objects can be foundhere.

It is not recommended to build DataFrames by adding single rows in afor loop. Build a list of rows and make a DataFrame in a single concat.

Examples

Combine twoSeries.

>>>s1=pd.Series(['a','b'])>>>s2=pd.Series(['c','d'])>>>pd.concat([s1,s2])0    a1    b0    c1    ddtype: object

Clear the existing index and reset it in the resultby setting theignore_index option toTrue.

>>>pd.concat([s1,s2],ignore_index=True)0    a1    b2    c3    ddtype: object

Add a hierarchical index at the outermost level ofthe data with thekeys option.

>>>pd.concat([s1,s2],keys=['s1','s2'])s1  0    a    1    bs2  0    c    1    ddtype: object

Label the index keys you create with thenames option.

>>>pd.concat([s1,s2],keys=['s1','s2'],...names=['Series name','Row ID'])Series name  Row IDs1           0         a             1         bs2           0         c             1         ddtype: object

Combine twoDataFrame objects with identical columns.

>>>df1=pd.DataFrame([['a',1],['b',2]],...columns=['letter','number'])>>>df1  letter  number0      a       11      b       2>>>df2=pd.DataFrame([['c',3],['d',4]],...columns=['letter','number'])>>>df2  letter  number0      c       31      d       4>>>pd.concat([df1,df2])  letter  number0      a       11      b       20      c       31      d       4

CombineDataFrame objects with overlapping columnsand return everything. Columns outside the intersection willbe filled withNaN values.

>>>df3=pd.DataFrame([['c',3,'cat'],['d',4,'dog']],...columns=['letter','number','animal'])>>>df3  letter  number animal0      c       3    cat1      d       4    dog>>>pd.concat([df1,df3],sort=False)  letter  number animal0      a       1    NaN1      b       2    NaN0      c       3    cat1      d       4    dog

CombineDataFrame objects with overlapping columnsand return only those that are shared by passinginner tothejoin keyword argument.

>>>pd.concat([df1,df3],join="inner")  letter  number0      a       11      b       20      c       31      d       4

CombineDataFrame objects horizontally along the x axis bypassing inaxis=1.

>>>df4=pd.DataFrame([['bird','polly'],['monkey','george']],...columns=['animal','name'])>>>pd.concat([df1,df4],axis=1)  letter  number  animal    name0      a       1    bird   polly1      b       2  monkey  george

Prevent the result from including duplicate index values with theverify_integrity option.

>>>df5=pd.DataFrame([1],index=['a'])>>>df5   0a  1>>>df6=pd.DataFrame([2],index=['a'])>>>df6   0a  2>>>pd.concat([df5,df6],verify_integrity=True)Traceback (most recent call last):...ValueError:Indexes have overlapping values: ['a']

Append a single row to the end of aDataFrame object.

>>>df7=pd.DataFrame({'a':1,'b':2},index=[0])>>>df7    a   b0   1   2>>>new_row=pd.Series({'a':3,'b':4})>>>new_rowa    3b    4dtype: int64>>>pd.concat([df7,new_row.to_frame().T],ignore_index=True)    a   b0   1   21   3   4