API, DOC: SparseArray Interface and Documentation is Confusing

[gfyoung]

1. SparseArray inherits from np.ndarray, but it doesn't seem like the instance itself can take on more than one dimension? Documentation doesn't make that super clear IMO.

2. If having 1-D sparse arrays is the intention, then I think there should be stronger checks against multi-dimensional data inputs. For example, if I pass in a multi-dimensional ndarray into SparseArray, I get a not so helpful error message that it does not have an sp_index.

[jreback]

SparseArray is an implementation detail. Its not user facing.

[gfyoung]

What do you mean by not "user-facing"?

[jreback]

exactly what I mean. Its a detail that is hidden away from the user. Its the .values of the SparseSeries. In theory it could be swapped for another implementation (e.g. from scipy or whatever). Its not needed by the user and is a sub-class of a numpy-array. So if anything you can simply update the docs to reflect this.

[kawochen]

Doc already says 1D though.

[gfyoung]

I couldn't find anything that explicitly says that in array.py AFAICT

[jreback]

@gfyoung you can certainly document it more if you want.

[gfyoung]

@jreback : Sure thing. It was just another thing I noticed as I have been squashing fromnumeric.py compat issues (same with the Categorical issue).

[kawochen]

http://pandas.pydata.org/pandas-docs/stable/sparse.html#sparsearray

[gfyoung]

@kawochen : Fair enough, but I think the documentation internally should nevertheless reflect that as well. Perhaps it may not be for user eyes, but for developer eyes, more info is better.

[kawochen]

I agree.

[gfyoung]

@jreback : Made the doc changes in my massive PR #12810 as I was addressing incompatibilities in pandas.sparse, so I think this issue can allotted to v0.18.1.

[jreback]

@gfyoung can you split this one off.

[gfyoung]

@jreback : My computer has been acting a little weird recently, which is why I have been somewhat inactive (answering on phone ATM). I'll get to this ASAP once I get my computer checked out.