title: What is the difference between join and merge in Pandas?
body: <p>Suppose I have two DataFrames like so:</p>
  
  <pre><code>left = pd.DataFrame({'key1': ['foo', 'bar'], 'lval': [1, 2]})
  
  right = pd.DataFrame({'key2': ['foo', 'bar'], 'rval': [4, 5]})
  </code></pre>
  
  <p>I want to merge them, so I try something like this:</p>
  
  <pre><code>pd.merge(left, right, left_on='key1', right_on='key2')
  </code></pre>
  
  <p>And I'm happy</p>
  
  <pre><code>    key1    lval    key2    rval
  0   foo     1       foo     4
  1   bar     2       bar     5
  </code></pre>
  
  <p>But I'm trying to use the join method, which I've been lead to believe is pretty similar. </p>
  
  <pre><code>left.join(right, on=['key1', 'key2'])
  </code></pre>
  
  <p>And I get this:</p>
  
  <pre><code>//anaconda/lib/python2.7/site-packages/pandas/tools/merge.pyc in _validate_specification(self)
      406             if self.right_index:
      407                 if not ((len(self.left_on) == self.right.index.nlevels)):
  --&gt; 408                     raise AssertionError()
      409                 self.right_on = [None] * n
      410         elif self.right_on is not None:
  
  AssertionError: 
  </code></pre>
  
  <p>What am I missing?</p>