DOC: docstring to series.unique #20474

minggli · 2018-03-23T22:08:19Z

closes DOC: Series.unique docstring can be moved to series.py #20075
tests added / passed
passes git diff upstream/master -u -- "*.py" | flake8 --diff
whatsnew entry

seems that no one has picked this up. moving _shared_doc['unique'] used by Series.unique() only to Series.unique.

################################################################################
####################### Docstring (pandas.Series.unique) #######################
################################################################################

Return unique values of Series object.

Uniques are returned in order of appearance. Hash table-based unique,
therefore does NOT sort.

Returns
-------
unique values.
  - If the input is an Index, the return is an Index
  - If the input is a Categorical dtype, the return is a Categorical
  - If the input is a Series/ndarray, the return will be an ndarray

See Also
--------
unique : return unique values of 1d array-like objects.
Index.unique : return Index with unique values from an Index object.

Examples
--------
>>> pd.Series([2, 1, 3, 3], name='A').unique()
array([2, 1, 3])

>>> pd.Series([2] + [1] * 5).unique()
array([2, 1])

>>> pd.Series([pd.Timestamp('20160101') for _ in range(3)]).unique()
array(['2016-01-01T00:00:00.000000000'], dtype='datetime64[ns]')

>>> pd.Series([pd.Timestamp('20160101', tz='US/Eastern')                        for _ in range(3)]).unique()
array([Timestamp('2016-01-01 00:00:00-0500', tz='US/Eastern')],
      dtype=object)

An unordered Categorical will return categories in the order of
appearance.

>>> pd.Series(pd.Categorical(list('baabc'))).unique()
[b, a, c]
Categories (3, object): [b, a, c]

An ordered Categorical preserves the category ordering.

>>> pd.Series(pd.Categorical(list('baabc'), categories=list('abc'),                                      ordered=True)).unique()
[b, a, c]
Categories (3, object): [a < b < c]

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.Series.unique" correct. :)

TomAugspurger · 2018-03-24T11:15:26Z

pandas/core/series.py

    def unique(self):
+        """
+        Return unique values in the object. Uniques are returned in order


This should be a single line. Can you simplify? You can use an extended summary for the bit about uniques.

broken into two lines. and minor rewording.

TomAugspurger · 2018-03-24T11:15:47Z

pandas/core/series.py

    def unique(self):
+        """
+        Return unique values in the object. Uniques are returned in order
+        of appearance, this does NOT sort. Hash table-based unique.


I'm not sure hash table-based unique will be meaningful to many users.

agree but that's the same in pandas.unique. I think it makes sense to people who understand data structure, and for people who don't understand it there is enough clarification around it. It's important to let people to know it's hash table so no sorting.

TomAugspurger · 2018-03-24T11:16:49Z

pandas/core/series.py

+        unique
+        Index.unique
+        Series.unique
+        """


Can you add examples?

aded. and removed self reference in See Also and added descriptions.

codecov · 2018-03-24T12:39:03Z

Codecov Report

Merging #20474 into master will decrease coverage by 0.02%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master   #20474      +/-   ##
==========================================
- Coverage   91.85%   91.82%   -0.03%     
==========================================
  Files         152      152              
  Lines       49231    49248      +17     
==========================================
+ Hits        45220    45224       +4     
- Misses       4011     4024      +13

Flag	Coverage Δ
#multiple	`90.21% <ø> (-0.03%)`	⬇️
#single	`41.89% <ø> (+0.05%)`	⬆️

Impacted Files	Coverage Δ
pandas/core/series.py	`93.84% <ø> (ø)`	⬆️
pandas/core/base.py	`96.79% <ø> (ø)`	⬆️
pandas/plotting/_converter.py	`65.07% <0%> (-1.74%)`	⬇️
pandas/core/arrays/categorical.py	`96.19% <0%> (-0.02%)`	⬇️
pandas/core/indexes/datetimes.py	`95.73% <0%> (-0.01%)`	⬇️
pandas/core/strings.py	`98.32% <0%> (ø)`	⬆️
pandas/core/generic.py	`95.85% <0%> (ø)`	⬆️
pandas/core/dtypes/missing.py	`91.07% <0%> (ø)`	⬆️
pandas/core/reshape/reshape.py	`100% <0%> (ø)`	⬆️
pandas/core/indexes/period.py	`92.61% <0%> (ø)`	⬆️
... and 5 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 4fb963b...4931fcf. Read the comment docs.

minggli · 2018-03-24T16:21:11Z

@TomAugspurger comments welcome 👍

jreback · 2018-03-24T22:23:51Z

pandas/core/series.py

    def unique(self):
+        """


it might be worth trying to share this doc-string with pd.unique (at least the examples) no?

good point but they have some differences:

pd.unique takes param and Series.unique doesn't take.

pd.unique handles 1d array-like objects including Index and Series.unique applies on self.

pd.unique examples contain more and Series.unique only series examples

do we have pattern somewhere in regards to conditionally show docstring lines?

https://github.com/pandas-dev/pandas/pull/20361/files is doing something similar for factorize. It's somewhat complex, since we have pd.unique, Series/Index.unique, and Categorical.unique. I'd be OK with improving the docstring here, and merging theme later.

agree, this PR is mainly about improve docstring. and should be another PR synthesising docs of all unique methods.

that's fine too

TomAugspurger · 2018-03-24T23:21:30Z

pandas/core/series.py

+
+        See Also
+        --------
+        unique : return unique values of 1d array-like objects.


Can you include pandas. for this one. Otherwise it's unclear what's being referenced. The explanation can say "Top-level unique method for any 1-d array-like object."

TomAugspurger · 2018-03-24T23:22:08Z

pandas/core/series.py

+
+        An ordered Categorical preserves the category ordering.
+
+        >>> pd.Series(pd.Categorical(list('baabc'), categories=list('abc'), \


Remove the \ here, and start the line with ...

TomAugspurger · 2018-03-24T23:22:17Z

pandas/core/series.py

+        >>> pd.Series([pd.Timestamp('20160101') for _ in range(3)]).unique()
+        array(['2016-01-01T00:00:00.000000000'], dtype='datetime64[ns]')
+
+        >>> pd.Series([pd.Timestamp('20160101', tz='US/Eastern') \


Remove the \ here, and start the line with ...

jorisvandenbossche · 2018-03-26T08:52:59Z

pandas/core/series.py

+        Returns
+        -------
+        unique values.
+          - If the input is an Index, the return is an Index


This part can be simplified, since it is now only the docstring of Series.unique.
So there is also no "input"

In this case it is always an array, except for categorical dtype.

minggli · 2018-03-27T13:19:58Z

@jorisvandenbossche does it look good?

jorisvandenbossche · 2018-03-27T13:55:31Z

pandas/core/series.py

+
+        Returns
+        -------
+        unique values : Series or Categorical


It's never a Series, only an numpy array or Categorical. I would also include something about that like

ndarray or Categorical The unique values returned as a NumPy array. In case of categorical data type, returned as a Categorical

jorisvandenbossche · 2018-03-27T20:56:24Z

@minggli Thanks a lot!

minggli · 2018-03-27T21:39:46Z

Thanks @jorisvandenbossche

remove _shared_docs and add doctring to series.unique

0a8ba45

minggli changed the title ~~remove _shared_docs and add doctring to series.unique~~ DOC: docstring to series.unique Mar 23, 2018

TomAugspurger reviewed Mar 24, 2018

View reviewed changes

Merge branch 'master' into doc/unique

fc7049b

minggli added 4 commits March 24, 2018 13:28

add examples and wording

308b279

line break in example docstrings

fb86b7f

descriptions in See Also

10d940d

minor changes

93b1ffd

jreback added the Docs label Mar 24, 2018

jreback requested changes Mar 24, 2018

View reviewed changes

TomAugspurger reviewed Mar 24, 2018

View reviewed changes

minggli added 2 commits March 25, 2018 22:52

remove backward slash

2dff831

rephrase See Also section

e024635

jorisvandenbossche reviewed Mar 26, 2018

View reviewed changes

jreback added this to the 0.23.0 milestone Mar 26, 2018

simpler return description.

e325fef

jorisvandenbossche reviewed Mar 27, 2018

View reviewed changes

minggli and others added 2 commits March 27, 2018 16:25

rephase return description

bd1f114

Update series.py

4931fcf

jorisvandenbossche approved these changes Mar 27, 2018

View reviewed changes

jorisvandenbossche merged commit 23cf851 into pandas-dev:master Mar 27, 2018

minggli deleted the doc/unique branch March 27, 2018 20:51

jorisvandenbossche pushed a commit that referenced this pull request Mar 27, 2018

DOC: docstring to series.unique (#20474)

cdfce2b

javadnoorb pushed a commit to javadnoorb/pandas that referenced this pull request Mar 29, 2018

DOC: docstring to series.unique (pandas-dev#20474)

3e91555

dworvos pushed a commit to dworvos/pandas that referenced this pull request Apr 2, 2018

DOC: docstring to series.unique (pandas-dev#20474)

a303326

kornilova203 pushed a commit to kornilova203/pandas that referenced this pull request Apr 23, 2018

DOC: docstring to series.unique (pandas-dev#20474)

48c97b5

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: docstring to series.unique #20474

DOC: docstring to series.unique #20474

minggli commented Mar 23, 2018 •

edited

Loading

TomAugspurger Mar 24, 2018

minggli Mar 24, 2018

TomAugspurger Mar 24, 2018

minggli Mar 24, 2018

TomAugspurger Mar 24, 2018

minggli Mar 24, 2018

codecov bot commented Mar 24, 2018 •

edited

Loading

minggli commented Mar 24, 2018

jreback Mar 24, 2018

minggli Mar 24, 2018

TomAugspurger Mar 24, 2018

minggli Mar 25, 2018

jreback Mar 26, 2018

TomAugspurger Mar 24, 2018

minggli Mar 25, 2018

TomAugspurger Mar 24, 2018

minggli Mar 25, 2018

TomAugspurger Mar 24, 2018

minggli Mar 25, 2018

jorisvandenbossche Mar 26, 2018

minggli Mar 26, 2018

minggli commented Mar 27, 2018

jorisvandenbossche Mar 27, 2018

minggli Mar 27, 2018

jorisvandenbossche commented Mar 27, 2018

minggli commented Mar 27, 2018


		An ordered Categorical preserves the category ordering.

		>>> pd.Series(pd.Categorical(list('baabc'), categories=list('abc'), \

DOC: docstring to series.unique #20474

DOC: docstring to series.unique #20474

Conversation

minggli commented Mar 23, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Mar 24, 2018 • edited Loading

Codecov Report

minggli commented Mar 24, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

minggli commented Mar 27, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jorisvandenbossche commented Mar 27, 2018

minggli commented Mar 27, 2018

minggli commented Mar 23, 2018 •

edited

Loading

codecov bot commented Mar 24, 2018 •

edited

Loading