ENH: add nlargest nsmallest to Series
State: closed

closes #3960
xref: #5534


Labels:
name: Enhancement
name: API Design
name: Numeric Operations
description: Arithmetic, Comparison, and Logical operations

Comments:
and pls do a vbench to verify these don't really change anything else

I think @hayd had an optimization for these methods somewhere, but push that off to another version (and they may be fine anyhow)

sure thing

there was discussion of `topk` in #3960 , but `nlargest` and `nsmallest` are consistent with the `heapq` module. i think it would be nice to keep that consistency

that's cool..fine with the names

vbench 

```
eval_frame_mult_python                       |  13.9356 |  12.7607 |   1.0921 |
query_store_table                            |   5.0490 |   4.5670 |   1.1055 |
frame_ctor_dtindex_BusinessDayx1             |   1.3620 |   1.2143 |   1.1216 |
reindex_frame_level_reindex                  |   0.7103 |   0.6084 |   1.1676 |
frame_add_no_ne                              |   4.6510 |   3.9537 |   1.1764 |
timeseries_large_lookup_value                |   0.0287 |   0.0243 |   1.1797 |
concat_empty_frames2                         |   1.0597 |   0.7667 |   1.3822 |
-------------------------------------------------------------------------------
Test name                                    | head[ms] | base[ms] |  ratio   |
-------------------------------------------------------------------------------
```

i was running some other things at the same time ... @jreback are these okay?

yep

@jreback @jorisvandenbossche any more comments? will squash and then can merge

g2g

@cpcloud pls squash down a bit and looks good 2 go

maybe a small doc mention here? http://pandas-docs.github.io/pandas-docs-travis/basics.html#sorting-by-index-and-value

@jreback doc and squish ok?

yep go 4 it

@cpcloud 

seems some of the complex dtypes don't exist on some arch's (windows even though this is 2.7-64 bit). so need to test that numpy can create before testing that they raise.

```
(Pdb) u
> c:\users\jeff reback\documents\github\pandas\build\lib.win-amd64-2.7\pandas\core\series.py(152)__init__()
-> dtype = self._validate_dtype(dtype)
(Pdb) l
147                     index = _ensure_index(index)
148
149                 if data is None:
150                     data = {}
151                 if dtype is not None:
152  ->                 dtype = self._validate_dtype(dtype)
153
154                 if isinstance(data, MultiIndex):
155                     raise NotImplementedError
156                 elif isinstance(data, Index):
157                     # need to copy to avoid aliasing issues
(Pdb) u
> c:\users\jeff reback\documents\github\pandas\build\lib.win-amd64-2.7\pandas\tests\test_series.py(4025)test_nsmallest_nlargest()
-> Series([3., 2, 1, 2, 5], dtype='complex256'),
(Pdb) l
4020            ]
4021
4022            raising = [
4023                Series([3., 2, 1, 2, '5'], dtype='object'),
4024                Series([3., 2, 1, 2, 5], dtype='object'),
4025 ->             Series([3., 2, 1, 2, 5], dtype='complex256'),
4026                Series([3., 2, 1, 2, 5], dtype='complex128'),
4027            ]
4028
4029            for r in raising:
4030                dt = r.dtype
(Pdb) p np.dtype('complex128')
dtype('complex128')
(Pdb) p np.dtype('complex256')
*** TypeError: TypeError('data type "complex256" not understood',)
(Pdb)
```

or could just totally skip the complex256 I think (easier)

easy enough just to take it out: https://github.com/pydata/pandas/commit/15334807345ae717196075e142dc34dabf2fe3a4

ok sorry about this ... i'll take it out since 128 is enough... really just there to test that the dtype check in select_n fails for the types that cannot be "sanely" sorted

oh i see... you've already done it

thanks!

@cpcloud thanks for picking up the ball here!

@hayd absolutely np!

ha! graphlab call this topk.