Pandas DataFrame.combine() method: A complete guide

Updated: February 19, 2024 By: Guest Contributor Post a comment


The pandas library in Python is an essential tool for data scientists and analysts due to its powerful data manipulation capabilities. Among its various functionalities, the combine() method stands out for its ability to efficiently combine two DataFrame objects. This tutorial provides an in-depth look at using combine(), complete with step-by-step examples ranging from basic to advanced applications.

The Fundamentals of the combine() Method

DataFrame.combine() is a method designed for the element-wise combining of two DataFrame objects. This method is particularly useful when you want to merge two DataFrames using a custom function to determine what values should be retained. The general syntax is:

DataFrame.combine(other, func, fill_value=None, overwrite=True)


  • other is the other DataFrame you wish to combine with.
  • func is a function that defines how the merging happens. It takes two arguments (one from each DataFrame being combined) and returns the result of the combination.
  • fill_value is used to fill missing values in the DataFrames before combining.
  • overwrite determines whether the combination should overwrite existing values or only fill in missing ones.

Basic Example

Let’s start with a simple example where we combine two DataFrames based on their index:

import pandas as pd

# Creating first DataFrame
df1 = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]})
# Creating second DataFrame
df2 = pd.DataFrame({'A': [10, 20, 30], 'B': [40, 50, 60]})

# Defining our custom function
def custom_combiner(s1, s2):
    return s1 if s1.sum() > s2.sum() else s2

# Combining the DataFrames
combined_df = df1.combine(df2, custom_combiner)

This will output:

    A   B
0  10  40
1  20  50
2  30  60

In this example, since the sum of the elements in each column of df2 is greater than that of df1, df2‘s values are retained in the combined DataFrame.

Handling Missing Values

One common issue when combining DataFrames is the handling of missing values. The combine() method allows you to specify a fill_value to deal with this. Here’s how you can apply it:

df1 = pd.DataFrame({'A': [1, None, 3], 'B': [4, 5, None]})
df2 = pd.DataFrame({'A': [None, 20, 30], 'B': [40, 50, 60]})
def custom_combiner(s1, s2):
    if s1.isnull().all():
        return s2
    elif s2.isnull().all():
        return s1
        return s1.fillna(0) + s2.fillna(0)
combined_df = df1.combine(df2, custom_combiner, fill_value=0)

This outputs:

      A     B
0   1.0  44.0
1  20.0  55.0
2  33.0  60.0

In this example, missing values are filled with 0 before combining, resulting in a seamless merging process without any NaN values.

Advanced Usage

As you become more comfortable with the combine() method, you can explore more complex operations. For instance, consider the scenario where you want to combine DataFrames based on a more sophisticated business logic, such as prioritizing one DataFrame’s values but only under certain conditions. This is where the power of combine() truly shines. Here is an advanced example:

# Assume df1 and df2 are defined as before
def advanced_combiner(s1, s2):
    if s1.mean() > 15:
        return s1
        return max(s1.max(), s2.max())

combined_df = df1.combine(df2, advanced_combiner)

In this sophisticated scenario, the combination logic is not merely about summing or replacing values but involves conditional logic with respect to the data’s characteristics.


The combine() method in pandas offers a flexible way to merge DataFrames based on custom logic. From handling missing values to implementing complex merging rules, combine() provides the functionality needed to efficiently combine datasets. By mastering combine(), you can take your data manipulation tasks to the next level, ensuring your analyses are both robust and insightful.