Expose options to Series' cut and qcut

[philss]

Closes: #1006

[philss]

I don't know how to explain these two new options - left_close and include_breaks, so I left out of docs. But if you have something in mind, feel free to suggest :)

[billylanchantin]

From the Python docs:

• left_closed
  • Set the intervals to be left-closed instead of right-closed.
• include_breaks
  • Include a column with the right endpoint of the bin each observation falls in. This will change the data type of the output from a Categorical to a Struct.

It's probably fine if we just forward their documentation. Here's a more in depth explanation:

left_closed

The cuts which are the main argument to this function divide the real line into discrete bins. E.g. if we passed cuts [-1, 1], we'd break up the real line into 3 bins like this (call them A, B, and C):

   A       B       C 
-------|-------|-------
      -1       1

This is a bit ambiguous though. We need to decide which bins the cuts themselves belong to. Is -1 in A or B?

By default, the bins are "right closed", meaning the bins contain their right cut but not their left. So -1 $\in$ A and 1 $\in$ B.

Including the left_closed argument flips this. Now the bins contain their left cut but not their right. So -1 $\in$ B and 1 $\in$ C.

include_breaks

This argument changes the return of the overall function. Instead of just mapping each value to the bin it's in, it also returns metadata about the bin it was mapped to. So you get a series of structs back instead of a category.

See their docs for an example of the structs returned.

[philss]

oh, thank you @billylanchantin!! :D
I will add these short descriptions :)