DOC: clarify the behavior of the .as_matrix method

[clham]

When using df.as_matrix() method, rows and columns do not render as 1xN or Nx1 matricies, rather as 1xN arrays.

In [4]: df.ix['foo']=[5,3]

In [5]: df.ix['bar']=[2,6]

In [6]: df
Out[6]:
     A  B
foo  5  3
bar  2  6

[2 rows x 2 columns]

In [7]: df['A'].as_matrix()
Out[7]: array([ 5.,  2.])

In [8]: df.ix['foo'].as_matrix()
Out[8]: array([ 5.,  3.])

Expected :

In [9]: np.matrix('5; 2')
Out[9]:
matrix([[5],
        [2]])

[cpcloud]

This is a poorly named method. It's doing what it's intended to do, and for back compat reasons we can't change it. This corresponds to and I think is the implementation of the .values attribute of all pandas objects that carry the attribute. If you want a matrix you'll have to do np.matrix(df.A.values). I could potentially see a to_matrix() method, but seeing as there's not much you can do with a matrix that you can't do with an array I'd say that that's a bit overkill when you can just use the matrix constructor.

[clham]

That's a bummer... I wanted to be able to do math on them elegantly. I'll see if I can clear that up in the docs.

[cpcloud]

@clham Great! I'll reopen to track the doc issue.

[jreback]

see long discussion on np.matrix here: http://comments.gmane.org/gmane.comp.python.numeric.general/56494

[clham]

Thanks @jreback, My head exploded about halfway through that thread. Based on what I got through however, I'm guessing the consensus here is to frame the docs to reflect that as_matrix should generally be avoided, and .values should be used in its place, both for clarity of code, and the (distant) possibility of depreciation?

[cpcloud]

whew wow that thread was interesting, thanks @jreback. personally, i've never once thought: "oh, i'll use np.matrix here", usually for linalg i just use the dot method.