DOC: Document scipy sparse matrix accepted in SparseSeries constructor

Author: kernc

doc/source/sparse.rst

@@ -213,9 +213,28 @@ To convert a ``SparseDataFrame`` back to sparse SciPy matrix in COO format, you
 
    sdf.to_coo()
 
+.. _sparse.scipysparse_series:
+
 SparseSeries
 ~~~~~~~~~~~~
 
+.. versionadded:: 0.20.2
+
+``SparseSeries``, ``SparseArray`` can be constructed from ``scipy.sparse.spmatrix`` objects of shape ``(1, n)`` or ``(n, 1)``.
+SciPy sparse matrices can also be assigned directly to a ``SparseDataFrame`` with an index.
+
+.. ipython:: python
+
+   sa = pd.SparseSeries(sp_arr[:, 5])
+   sa
+
+   sdf['x'] = sa
+   sdf['y'] = sp_arr[:, 6]
+   sdf[['z', 'w']] = sp_arr[:, [7, 8]]
+   sdf.iloc[:, -5:]
+
+Below interface is deprecated.
+
 .. versionadded:: 0.16.0
 
 A :meth:`SparseSeries.to_coo` method is implemented for transforming a ``SparseSeries`` indexed by a ``MultiIndex`` to a ``scipy.sparse.coo_matrix``.

doc/source/whatsnew/v0.20.2.txt

@@ -25,6 +25,9 @@ Enhancements
   has been added to return the group order (:issue:`11642`); see
   :ref:`here <groupby.ngroup>`.
 
+
+- ``SparseSeries`` and ``SparseArray`` now support 1d ``scipy.sparse.spmatrix`` in constructor. Additionally, ``SparseDataFrame`` can be assigned columns of ``scipy.sparse.spmatrix``; see :ref:`here <sparse.scipysparse_series>`. (:issue:`15634`)
+
 .. _whatsnew_0202.performance:
 
 Performance Improvements

pandas/core/sparse/series.py

@@ -726,6 +726,9 @@ def combine_first(self, other):
 
     def to_coo(self, row_levels=(0, ), column_levels=(1, ), sort_labels=False):
         """
+        DEPRECATED; instead, make a SparseSeries with a two-level index,
+        unstack it, then use .to_coo() on the resulting SparseDataFrame.
+
         Create a scipy.sparse.coo_matrix from a SparseSeries with MultiIndex.
 
         Use row_levels and column_levels to determine the row and column
@@ -783,6 +786,9 @@ def to_coo(self, row_levels=(0, ), column_levels=(1, ), sort_labels=False):
     @classmethod
     def from_coo(cls, A, dense_index=False):
         """
+        DEPRECATED; instead, pass 1d scipy.sparse matrices directly into
+        SparseSeries constructor, and 2d into SparseDataFrame constructor.
+
         Create a SparseSeries from a scipy.sparse.coo_matrix.
 
         .. versionadded:: 0.16.0