Repository: vega/altair

Issue:
`selection_interval` docs describe unusable `"fields"` parameter
I'm not sure whether this is just a documentation bug or an actual bug, as I've only been using `altair` for one day.
I am using version `"5.0.0rc1"`.

The `altair.selection_interval` [docs](https://altair-viz.github.io/user_guide/generated/api/altair.selection_interval.html) include a description of a `fields` parameter, but attempting to use it:
``` python
import altair as alt
alt.selection_interval(fields=["iid"])
``` 
elicits:
``` python
SchemaValidationError: `IntervalSelectionConfig` has no parameter named 'fields'
```

#2365 suggests that this is indeed just a documentation bug. Perhaps it arose in #2908?

Thanks!



Discussion:
Thanks for reporting and welcome to the Altair community! You're correct that `selection_interval` should not list `fields` in the docstring (it seems like the signature is correct). @ChristopherDavisUCI , I think it would be enough to just delete this section, does that seem correct to you?

https://github.com/altair-viz/altair/blob/37e91ec2174fe6716c7c8372b0bbdb1800340d31/altair/vegalite/v5/api.py#L492-L494
OK, thanks for confirming and for the quick response!
Thank you!  I will take a look today.  My first impression is that this `fields` parameter should be usable, but I'll have to look more closely.
Great, thank you. My understanding is that it is only usable for point selection but not for intervals as per https://vega.github.io/vega-lite/docs/selection.html#current-limitations so maybe the docstring from point selection was just copied over? 
Ah, thanks @joelostblom, the reason I thought `fields` was usable was because it is listed here: https://vega.github.io/vega-lite/docs/selection.html#selection-props

You seem to be right though, so please go ahead with the change you mentioned https://github.com/altair-viz/altair/issues/3000#issuecomment-1485982775
Sounds good! @dpoznik Since you reported this initially, are you interested in contributing by removing the lines I linked above in a PR? No worries if not, I can do it too. 
@joelostblom, sure I'd be happy to contribute. Will do!

Could I ask a question though? Since I am brand new to this package, I'll take no offense at a response along the lines of ~"read the docs" :)

When I saw the `fields` parameters in the `selection_interval` docs, it seemed perfectly suited to my needs. Would you be willing to point me to the "right" way to accomplish the following?

I've got a dataframe, `df`, with columns: `["id", "x", "y", "a", "b", "c"]`, where `"id"` is an identifier, and the other columns are `float` measurements for the given ID. I would like to generate a scatter plot of `"y"` vs. `"x"` and, for a given interval selection on the scatter plot, view the distributions of `"a"`, `"b"`, and `"c"` as violins.

Having seen the `fields` parameter in the docs, my initial attempt was to melt `df` into `melted_df` with columns `["id", "category", "value"]`, where `"category"` takes values `{"a", "b", "c"}` and then do something like:

``` python
selection = alt.selection_interval(fields=["id"])

points = (
    alt.Chart(df)
    .mark_point(...)
    .encode(...)
    .add_params(selection)
    .properties(...)
)

violins = (
    alt.Chart(melted_df)
    .transform_density(...)
    .mark_area(...)
    .encode(...)
    .properties(...)
    .transform_filter(selection)
)

points & violins
```

Thanks!

Resolving patch:
diff --git a/altair/vegalite/v5/api.py b/altair/vegalite/v5/api.py
--- a/altair/vegalite/v5/api.py
+++ b/altair/vegalite/v5/api.py
@@ -323,12 +323,12 @@ def param(
     name : string (optional)
         The name of the parameter. If not specified, a unique name will be
         created.
-    bind : :class:`Binding` (optional)
-        Binds the parameter to an external input element such as a slider,
-        selection list or radio button group.
     value : any (optional)
         The default value of the parameter. If not specified, the parameter
         will be created without a default value.
+    bind : :class:`Binding` (optional)
+        Binds the parameter to an external input element such as a slider,
+        selection list or radio button group.
     empty : boolean (optional)
         For selection parameters, the predicate of empty selections returns
         True by default. Override this behavior, by setting this property
@@ -472,12 +472,12 @@ def selection_interval(
     name : string (optional)
         The name of the parameter. If not specified, a unique name will be
         created.
-    bind : :class:`Binding` (optional)
-        Binds the parameter to an external input element such as a slider,
-        selection list or radio button group.
     value : any (optional)
         The default value of the parameter. If not specified, the parameter
         will be created without a default value.
+    bind : :class:`Binding` (optional)
+        Binds the parameter to an external input element such as a slider,
+        selection list or radio button group.
     empty : boolean (optional)
         For selection parameters, the predicate of empty selections returns
         True by default. Override this behavior, by setting this property
@@ -489,9 +489,6 @@ def selection_interval(
     encodings : List[str] (optional)
         A list of encoding channels. The corresponding data field values
         must match for a data tuple to fall within the selection.
-    fields : List[str] (optional)
-        A list of field names whose values must match for a data tuple to
-        fall within the selection.
     on : string (optional)
         A Vega event stream (object or selector) that triggers the selection.
         For interval selections, the event stream must specify a start and end.
@@ -540,7 +537,7 @@ def selection_interval(
         default allows users to use the mouse wheel to resize an interval
         selection.
     **kwds :
-        additional keywords to control the selection.
+        Additional keywords to control the selection.
 
     Returns
     -------
@@ -572,6 +569,7 @@ def selection_point(
     empty=Undefined,
     expr=Undefined,
     encodings=Undefined,
+    fields=Undefined,
     on=Undefined,
     clear=Undefined,
     resolve=Undefined,
@@ -586,12 +584,12 @@ def selection_point(
     name : string (optional)
         The name of the parameter. If not specified, a unique name will be
         created.
-    bind : :class:`Binding` (optional)
-        Binds the parameter to an external input element such as a slider,
-        selection list or radio button group.
     value : any (optional)
         The default value of the parameter. If not specified, the parameter
         will be created without a default value.
+    bind : :class:`Binding` (optional)
+        Binds the parameter to an external input element such as a slider,
+        selection list or radio button group.
     empty : boolean (optional)
         For selection parameters, the predicate of empty selections returns
         True by default. Override this behavior, by setting this property
@@ -655,7 +653,7 @@ def selection_point(
         data values must be interacted with directly (e.g., clicked on)
         to be added to the selection.
     **kwds :
-        additional keywords to control the selection.
+        Additional keywords to control the selection.
 
     Returns
     -------
@@ -670,6 +668,7 @@ def selection_point(
         empty=empty,
         expr=expr,
         encodings=encodings,
+        fields=fields,
         on=on,
         clear=clear,
         resolve=resolve,


Test patch: