ENH:included anti join functionality

doc/source/getting_started/comparison/includes/merge.rst

@@ -15,3 +15,12 @@ data does not have to be sorted ahead of time, and different join types are acco
 
    outer_join = df1.merge(df2, on=["key"], how="outer")
    outer_join
+
+   anti_left_join = df1.merge(df2, on=["key"], how="anti_left")
+   anti_left_join
+
+   anti_right_join = df1.merge(df2, on=["key"], how="anti_right")
+   anti_right_join
+
+   anti_full_join = df1.merge(df2, on=["key"], how="anti_full")
+   anti_full_join

folder/subfolder/out.csv

@@ -0,0 +1,3 @@
+,name,mask,weapon
+0,Raphael,red,sai
+1,Donatello,purple,bo staff

pandas/core/frame.py

@@ -275,7 +275,8 @@
 ----------%s
 right : DataFrame or named Series
     Object to merge with.
-how : {'left', 'right', 'outer', 'inner', 'cross'}, default 'inner'
+how : {'left', 'right', 'outer', 'inner', 'cross', 'anti_left', \
+'anti_right', 'anti_full'}, default 'inner'
     Type of merge to be performed.
 
     * left: use only keys from left frame, similar to a SQL left outer join;
@@ -290,6 +291,15 @@
       of the left keys.
 
       .. versionadded:: 1.2.0
+    * anti_left: use only keys from left frame that are absent in right
+      frame; preserve key order.
+    * anti_right: use keys from the right frame that are absent in the
+      left frame; preserve key order.
+    * anti_full: use keys from  the right frame that are absent in the
+      left frame, and the keys in the left frame that are absent in the
+      right frame; sort keys lexicographically.
+
+      .. versionadded:: 1.4.0
 
 on : label or list
     Column or index level names to join on. These must be found in both
@@ -449,6 +459,33 @@
 1   foo      8
 2   bar      7
 3   bar      8
+
+>>> df1 = pd.DataFrame({"A": [1, 2, 3], "C": [5, 6, 7]})
+>>> df2 = pd. DataFrame({"B": [1, 2, 4], "C": [7, 8, 9]})
+>>> df1
+   A  C
+0  1  5
+1  2  6
+2  3  7
+>>> df2
+   B  C
+0  1  7
+1  2  8
+2  4  9
+>>> df1.merge(df2, on="C", how="anti_left")
+   A  C   B
+0  1  5 NaN
+1  2  6 NaN
+>>> df1.merge(df2, on="C", how="anti_right")
+    A  C  B
+0 NaN  8  2
+1 NaN  9  4
+>>> df1.merge(df2, on="C", how="anti_full")
+     A  C    B
+0  1.0  5  NaN
+1  2.0  6  NaN
+2  NaN  8  2.0
+3  NaN  9  4.0
 """
 
 

pandas/core/reshape/merge.py

@@ -690,6 +690,8 @@ def __init__(
                 cross_col,
             ) = self._create_cross_configuration(self.left, self.right)
             self.left_on = self.right_on = [cross_col]
+        elif self.how in ["anti_left", "anti_right", "anti_full"]:
+            self.left, self.right, self.how = self._anti_join_update()
         self._cross = cross_col
 
         # note this function has side effects
@@ -743,6 +745,46 @@ def get_result(self) -> DataFrame:
 
         return result.__finalize__(self, method="merge")
 
+    def _anti_join_update(self):
+        """
+        Converts `anti_left`, `anti_right` and `anti_full` configurations into `left`,
+        `right` and `outer` join configurations.
+        Calls `_anti_helper` with the indices or columns to be merged on.
+        """
+        if self.left_index and self.right_index:
+            # Merge using `right_index` and `left_index`
+            join_index_l, join_index_r, self.how = _anti_helper(
+                self.left.index, self.right.index, self.how
+            )
+        elif self.on is not None or (
+            None not in self.left_on and None not in self.right_on
+        ):
+            # Merge using `on` or `left_on` and `right_on`
+            if self.on is not None:
+                left_on = right_on = self.on
+            else:
+                left_on = self.left_on
+                right_on = self.right_on
+            join_index_l, join_index_r, self.how = _anti_helper(
+                self.left[left_on], self.right[right_on], self.how
+            )
+        elif self.left_index and self.right_on is not None:
+            # Merge using `left_index` and `right_on`
+            join_index_l, join_index_r, self.how = _anti_helper(
+                self.left.index, self.right[self.right_on], self.how
+            )
+        elif self.right_index and self.left_on is not None:
+            # Merge using `left_on` and `right_index`
+            join_index_l, join_index_r, self.how = _anti_helper(
+                self.left[self.left_on], self.right.index, self.how
+            )
+        self.left = self.left.loc[join_index_l]
+        self.right = self.right.loc[join_index_r]
+
+        # sanity check to ensure correct `how`
+        assert self.how in ["left", "right", "inner", "outer"]
+        return (self.left, self.right, self.how)
+
     def _maybe_drop_cross_column(
         self, result: DataFrame, cross_col: str | None
     ) -> None:
@@ -1450,6 +1492,59 @@ def _validate(self, validate: str) -> None:
             raise ValueError("Not a valid argument for validate")
 
 
+def _anti_helper(
+    _left: Index | DataFrame,
+    _right: Index | DataFrame,
+    _how: str,
+) -> tuple[npt.NDArray, npt.NDArray, str]:
+    """
+    Converts `anti_left`, `anti_right` and `anti_full` configurations into `left`,
+    `right` and `outer` join configurations
+
+    Parameters
+    ----------
+    _left : DataFrame, Index
+        left frame with columns if merged with `on` or `left/right_on`, else Index
+    _right : DataFrame, Index
+        right frame with columns if merged with `on` or `left/right_on`, else Index
+    _how : {'anti_left', 'anti_right', 'anti_full'}
+
+    Returns
+    -------
+    np.ndarray[bool]
+        Indexer of left_keys
+    np.ndarray[bool]
+        Indexer of right_keys
+    {"left", "right", "outer"}
+        Native join configurations
+
+    """
+
+    # If not Index. Convert the columns into Index or
+    # MultiIndex as required
+    if not isinstance(_left, Index):
+        if len(_left.columns) == 1:
+            _left = Index(_left.values.flatten(), dtype=_left.dtypes[0])
+        else:
+            _left = MultiIndex.from_frame(_left)
+    if not isinstance(_right, Index):
+        if len(_right.columns) == 1:
+            _right = Index(_right.values.flatten(), dtype=_right.dtypes[0])
+        else:
+            _right = MultiIndex.from_frame(_right)
+
+    how_dict: dict[str, str] = {
+        "anti_left": "left",
+        "anti_right": "right",
+        "anti_full": "outer",
+    }
+    _how = how_dict[_how]
+
+    join_index_l = ~_left.isin(_right)
+    join_index_r = ~_right.isin(_left)
+    return (join_index_l, join_index_r, _how)
+
+
 def get_join_indexers(
     left_keys, right_keys, sort: bool = False, how: str = "inner", **kwargs
 ) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]: