DOC: add nlargest/nsmallest to API.rst

[RomanPekar]

At the moment there's no easy way to partially sort the DataFrame to get top N rows, could be useful feature.

There's partial sorting available for numpy within the bottleneck library.

Here's link to SO question about numpy partial sort - http://stackoverflow.com/questions/10337533/a-fast-way-to-find-the-largest-n-elements-in-an-numpy-array

[jreback]

http://pandas.pydata.org/pandas-docs/stable/basics.html?highlight=nlargest#smallest-largest-values

(this is even faster than partsort as its grabbing the top values)

though these are not mentioned in API.rst. want to do a PR to add them?

[RomanPekar]

Ok, but this one is for Series, my issue was about getting top N rows from DataFrame ordered by columns I want, similar to SQL select top (@N) * from <Table> order by <col1> asc, <col2> desc without actually sorting the whole dataset

[jreback]

df.apply(Series.nlargest)

[RomanPekar]

Thanks again, but it still will not work if I want to sort by several columns. As an example - suppose I have this dataset:

    A   B
0   1   5
1   2   5
2   2   4
3   2   3
4   3   2
5   3   1

And I want to take top 4 records ordered by A desc, B desc (rows 5, 4, 1, 2)

[jreback]

In [42]: df.sort(['A','B'],ascending=[0,0])
Out[42]: 
   A  B
4  3  2
5  3  1
1  2  5
2  2  4
3  2  3
0  1  5

I don't think there is an easy way to do this w/o a full-sort. partsort (and most other algos operate on a 1-d array).