Skip to content

DOC: update the Series.view docstring #20220

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
Mar 11, 2018
Merged

DOC: update the Series.view docstring #20220

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f313b79
DOC: update Series.view docstring
villasv Mar 10, 2018
cffd04b
Move comparison with numpy.ndarray.view to Notes
villasv Mar 10, 2018
4362e38
small edit in backticks
jorisvandenbossche Mar 11, 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
60 changes: 60 additions & 0 deletions pandas/core/series.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -547,6 +547,66 @@ def __len__(self):
return len(self._data)

def view(self, dtype=None):
"""
Create a new view of the Series.

This function will return a new Series with a view of the same
underlying values in memory, optionally reinterpreted with a new data
type. The new data type must preserve the same size in bytes as to not
cause index misalignment.

Series are instantiated with `dtype=float64` by default, so unlike
`numpy.array.view()` this function will not try to preserve the current
Series data type.
Copy link
Member

Choose a reason for hiding this comment

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

This part I don't fully understand. Can you try to explain more what you exactly want to say, maybe with an example? (here in the comments)

Copy link
Contributor Author

@villasv villasv Mar 10, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

It's basically what I said in the first comment of this PR. pd.Series([1,2,3], dtype='int8').view() will raise, but the equivalent in numpy would not. Maybe I should add an example in the docstring as well?

Copy link
Member

Choose a reason for hiding this comment

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

Ah, yes, thanks for the explanation. In principle, doing view without specifying a dtype is not that useful. So I would keep this explanation for the notes or so, and not include it here in the extended summary.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Notes looks like a good fit. On it.


Parameters
----------
dtype : data type
Data type object or one of their string representations.

Returns
-------
Series
A new Series object as a view of the same data in memory.

See Also
--------
numpy.ndarray.view : Return a new view of the same data in memory.
Copy link
Member

Choose a reason for hiding this comment

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

I would say in the explanation here that this is the equivalent numpy method to take a view of an array

Copy link
Contributor Author

@villasv villasv Mar 10, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

But they are not exactly equivalent because numpy is a little bit more relaxed in this operation since it doesn't need to preserve the amount of data points. But you mean that perhaps I should write:

numpy.ndarray.view : The equivalent function to create a view of an array. ?

I think the current way is more formal and clear, specially because these functions don't behave exactly alike. Perhaps:

numpy.ndarray.view : Return a new view of the array with the same data ?

This is indeed a bit closer to the original numpy short description (New view of array with the same data), though explicitly mentioning in memory helped me making people understand why those views share data changes. Simply saying "same data" leads most people think that the data is maybe just copied.

Copy link
Member

Choose a reason for hiding this comment

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

But you mean that perhaps I should write:

numpy.ndarray.view : The equivalent function to create a view of an array. ?

Yes, that is what I meant (I would say "equivalent numpy function" though).
I think a see also should also give a sense of why we mention the other function. And in this case, because it is the equivalent function of numpy (yes, they don't behave completely the same, but I would keep this for the notes)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Makes sense. I'll try to be a bit more explicit on the difference between them in the Notes section.


Examples
--------
>>> s = pd.Series([-2, -1, 0, 1, 2], dtype='int8')
>>> s
0 -2
1 -1
2 0
3 1
4 2
dtype: int8

The 8 bit signed integer representation of `-1` is `0b10000001`, but
the same bytes represent 255 if read as an 8 bit unsigned integer:

>>> us = s.view('uint8')
>>> us
0 254
1 255
2 0
3 1
4 2
dtype: uint8

The views share the same underlying values:

>>> us[0] = 128
>>> s
0 -128
1 -1
2 0
3 1
4 2
dtype: int8
"""
return self._constructor(self._values.view(dtype),
index=self.index).__finalize__(self)

Expand Down