DOCSP-12756: [Charts] regex bins (#430)

Author: steveren

source/bin-data.txt

@@ -256,20 +256,33 @@ start date.
       - A dataset on various artists throughout history that you want to
         group by artistic period (for example, Renaissance, Romantic, Modern).
 
+      - A dataset containing fine-grained version numbers (e.g. ``2.3.0``,
+        ``2.3.1``, ``2.3.2-rc1``, ``2.4.0``) which you'd like to analyze
+        in coarser-grained groups (e.g. ``2.3``, ``2.4``).
+
       Create a Bin from String Values
       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-      To create a bin from selected category strings:
-
       1. Drag a string field to a :guilabel:`Category` encoding channel.
 
       #. Toggle :guilabel:`Binning` for the field to :guilabel:`On`.
 
       #. Click :guilabel:`Add Bin`.
 
-      #. In the :guilabel:`Add Bin` window, give your bin a title and
-         select the categories to include in your bin.
+      #. In the :guilabel:`Add Bin` window, give your bin a title.
+
+      At this point you can either create a bin from a list of category
+      strings or define a regular expression to match string values.
+      You can use the list of category strings if you want to choose the
+      exact values for each bin. A regular expression is a better choice
+      if you want to pattern-match a larger range of potential values.
+
+      To create a bin from selected category strings:
+
+      1. Click the :guilabel:`Select` radio button.
 
+      #. Select the categories to include in your bin. 
+         
       #. Click :guilabel:`Save`. The :guilabel:`Bins` window shows the
          bins you have created and how many categories belong to each
          bin.
@@ -284,6 +297,47 @@ start date.
            data and may not include every value that exists in the data.
            You can manually add additional values to the list.
 
+      To create a bin from a regular expression:
+
+      1. Click the :guilabel:`Regex` radio button. 
+
+      #. Enter a regular expression in the :guilabel:`Insert regex` text
+         box.
+
+      #. Select any desired flags from the dropdown menu to the right of
+         the text box. You can use any combination of the four available
+         flags:
+
+         .. list-table::
+            :header-rows: 1
+            :widths: 20 80
+
+            * - Flag
+              - Description
+
+            * - ``i``
+              - Case insensitive search
+
+            * - ``m``
+              - Multiline mode
+
+            * - ``x``
+              - Extended mode
+
+            * - ``s``
+              - Single line mode
+
+      #. A sample of matching documents appears. If there are no matching
+         documents, you can still save the bin.
+
+      #. Click :guilabel:`Save`. The :guilabel:`Bins` window shows the
+         bins you have created. Bins created from a regular expression
+         are noted with a :guilabel:`.*` icon.
+
+      You can add another bin by clicking the :guilabel:`Add Bin` link,
+      or close the :guilabel:`Bins` window by clicking the :guilabel:`X`
+      in the upper right corner.
+
       Edit and Remove Existing Bins
       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -301,8 +355,8 @@ start date.
 
       To remove a bin, click the :guilabel:`Trash` icon.
 
-      Example
-      ~~~~~~~
+      Examples
+      ~~~~~~~~
 
       The following chart groups genres from the
       :ref:`Movies Sample Data <sample-data>` into broader bins:
@@ -327,17 +381,34 @@ start date.
          :figwidth: 700px
          :alt: Chart containing binned category data
 
+      The following chart looks through the ``description`` field of the
+      ``sample_airbnb.listingsAndReviews`` collection for certain words
+      and compares the mean prices. It uses bins to group documents based
+      on whether the ``description`` field contains a string matching the
+      pattern specified by the regular expression.
+      
+      .. figure:: /images/charts/nominal-binning-regex.png
+         :figwidth: 700px
+         :alt: Chart containing binned description data
+
       Behavior
       ~~~~~~~~
 
-      - A single category cannot belong to multiple bins.
+      - Values can only belong to only one category bin, but they can belong
+        to any number of regex bins.
 
       - Any values shown on the chart that have not been added to any
         bins are automatically added to a default bin called
         :guilabel:`Other Values`.
 
-      - The order in which bins appear in the :guilabel:`Bins` window
-        does not have any effect on the chart.
+      - The order in which bins appear in the :guilabel:`Bins` window is
+        significant. Each value is rendered in the chart as part of the
+        highest-ranked bin it appears in.
+
+        .. note::
+
+           You can reorder your bins by dragging and dropping them in the
+           :guilabel:`Bins` window.
 
 .. _charts-sort-data:
 
@@ -424,3 +495,4 @@ difficult to create a meaningful chart.
    .. figure:: /images/charts/charts-movie-ratings-by-country-limited.png
       :figwidth: 720px
       :alt: Movie ratings by country limited
+