Skip to content

DOC: update the pandas.DataFrame.to_sparse docstring #20193

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 10, 2018
Merged

DOC: update the pandas.DataFrame.to_sparse docstring #20193

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
087f441
Updates the documentation for pandas.DataFrame.to_sparse.
Mar 10, 2018
ae0e96e
Merge remote-tracking branch 'upstream/master' into gioiab-master
datapythonista Jul 9, 2018
dcdf0bb
Minor fixes and adding more real world examples
datapythonista Jul 10, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 29 additions & 1 deletion pandas/core/frame.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1570,16 +1570,44 @@ def from_csv(cls, path, header=0, sep=',', index_col=0, parse_dates=True,

def to_sparse(self, fill_value=None, kind='block'):
"""
Convert to SparseDataFrame
Convert to SparseDataFrame.

Implement the sparse version of the DataFrame meaning that any data
matching a specific value it's omitted in the representation.
The sparse DataFrame allows for a more efficient storage.

Parameters
----------
fill_value : float, default NaN
The specific value that should be omitted in the representation.
kind : {'block', 'integer'}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The default is missing.

The kind of the SparseIndex tracking where data is not equal to
the fill value:

- 'block' tracks only the locations and sizes of blocks of data;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if the semi-colon at the end is intentional. If you find another docstring with a list, I'd use the same convention.

- 'integer' keeps an array with all the locations of the data.

The kind 'block' is recommended since it's more memory efficient.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd say the same, but in a way that doesn't sound like 'block' is always better. Something like "In most cases, the default 'block' is preferred for being more memory efficient.".

Not a big difference, but I'd prefer to avoid giving the idea that 'integer' is never the best option, which is not true.


Returns
-------
y : SparseDataFrame
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can get rid of the y and just leave the type. Also, may be it's a bit redundant in this case, but for consistency I'd add the description of what is returned.


See Also
--------
DataFrame.to_dense :
converts the DataFrame back to the its dense form
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you capitalize the first letter and add a period at the end?

I think the description should start in the same line as to_dense and continue to the next line indented when it doesn't fit.


Examples
--------

Compressing on the zero value.

>>> df = pd.DataFrame(np.random.randn(1000, 4))
>>> df.iloc[:995] = 0.
>>> sdf = df.to_sparse(fill_value=0.)
>>> sdf.density
0.005
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice example. It's just an opinion, feel free to leave it like this, if you think that being somehow more realistic is better, but I'd have something like: pd.DataFrame([np.nan, np.nan, 1., np.nan]). You can make it sparse with default arguments, then create another example with zeros instead of NaN and use fill_value. And if you find a nice way to illustrate the difference, I'd add an example with kind='integer'.

"""
from pandas.core.sparse.frame import SparseDataFrame
return SparseDataFrame(self._series, index=self.index,
Expand Down