docs: MVP plotly-express docs

plugins/plotly-express/docs/area.md

@@ -26,7 +26,7 @@ usa_population = gapminder.where("Country == `United States`")
 area_plot = dx.area(usa_population, x="Year", y="Pop")
 ```
 
-### Color by group
+### Area by group
 
 Area plots are unique in that the y-axis demonstrates each groups' total contribution to the whole. Pass the name of the grouping column(s) to the `by` argument.
 

plugins/plotly-express/docs/box.md

@@ -16,11 +16,13 @@ Box plots are appropriate when the data have a continuous variable of interest.
 
 Visualize the distribution of a single variable by passing the column name to `x` or `y`.
 
-```python order=box_plot,tips
+```python order=box_plot_x,box_plot_y,tips
 import deephaven.plot.express as dx
 tips = dx.data.tips()
 
-box_plot = dx.box(tips, y="TotalBill")
+# control the plot orientation using `x` or `y`
+box_plot_x = dx.box(tips, x="TotalBill")
+box_plot_y = dx.box(tips, y="TotalBill")
 ```
 
 ### Distributions for multiple groups

plugins/plotly-express/docs/histogram.md

@@ -16,14 +16,16 @@ Histograms are appropriate when the data contain a continuous variable of intere
 
 Visualize the distribution of a single variable by passing the column name to the `x` or `y` arguments.
 
-```python order=hist_plot,setosa,iris
+```python order=hist_plot_x,hist_plot_y,setosa,iris
 import deephaven.plot.express as dx
 iris = dx.data.iris()
 
 # subset to get specific species
 setosa = iris.where("Species == `setosa`")
 
-hist_plot = dx.histogram(setosa, x="SepalLength")
+# control the plot orientation using `x` or `y`
+hist_plot_x = dx.histogram(setosa, x="SepalLength")
+hist_plot_y = dx.histogram(setosa, y="SepalLength")
 ```
 
 Modify the bin size by setting `nbins` equal to the number of desired bins.

plugins/plotly-express/docs/line.md

@@ -26,7 +26,7 @@ dog_prices = my_table.where("Sym = `DOG`")
 line_plot = dx.line(dog_prices, x="Timestamp", y="Price")
 ```
 
-### Color line plot by group
+### Line by group
 
 Create a line with a unique color for each group in the dataset by passing the grouping column name to the `by` argument.
 

plugins/plotly-express/docs/multiple-axes.md

@@ -10,22 +10,35 @@ When two or more response variables appear in separate columns, pass their colum
 
 ```python order=line_plot_multi,brazil,gapminder
 import deephaven.plot.express as dx
-gapminder = dx.data.gapminder() # import a ticking version of the Gapminder dataset
+gapminder = dx.data.gapminder()
 
 # get a specific country
 brazil = gapminder.where("Country == `Brazil`")
 
-# specify multiple y-axis columns and order axes left to right with yaxis_sequence
+# specify multiple y-axis columns and split axes with yaxis_sequence
 line_plot_multi = dx.line(brazil, x="Year", y=["Pop", "GdpPerCap"], yaxis_sequence=[1, 2])
 ```
 
+If `xaxis_sequence` or `yaxis_sequence` are not specified, the series will share an axis, which may or may not be useful depending on the units and scale of the data.
+
+```python order=line_plot_shared,brazil,gapminder
+import deephaven.plot.express as dx
+gapminder = dx.data.gapminder()
+
+# get a specific country
+brazil = gapminder.where("Country == `Brazil`")
+
+# population and per capita gdp have very different scales and units
+line_plot_shared = dx.line(brazil, x="Year", y=["Pop", "GdpPerCap"])
+```
+
 ### Use `by` with multiple axes
 
 When a single response variable has observations from several groups of data, use the `by` parameter to specify the grouping column.
 
 ```python order=line_plot_by,cat_dog,stocks
 import deephaven.plot.express as dx
-stocks = dx.data.stocks() # import the example stock market data set
+stocks = dx.data.stocks()
 
 # subset to get two symbols
 cat_dog = stocks.where("Sym in `CAT`, `DOG`")
@@ -40,7 +53,7 @@ Finally, plots can be layered to achieve multiple axes. Use the `dx.layer` funct
 
 ```python order=line_plot_layered,fish,bird,stocks
 import deephaven.plot.express as dx
-stocks = dx.data.stocks() # import the example stock market data set
+stocks = dx.data.stocks()
 
 # subset to get two tables with a shared x-axis
 fish = stocks.where("Sym == `FISH`")

plugins/plotly-express/docs/plot-by.md

@@ -2,6 +2,8 @@
 
 To plot multiple series from a table into a single chart, use the `by` parameter. This parameter accepts a column name or a list of column names denoting other variables of interest in the dataset. The chart will be partitioned by the values in the specified column(s), with one series for each unique value. Other parameters, such as `color` (for which `by` is an alias), `symbol`, `size`, `width`, and `line_dash` can also be used to partition the chart.
 
+Under the hood, the Deephaven query engine performs a `parition_by` table operation on the given color column to create each series. This efficient implementation means that plots with multiple groups can easily scale to tens of millions or billions of rows with ease.
+
 ## Examples
 
 ### Scatter plot by a categorical variable

plugins/plotly-express/docs/scatter.md

@@ -85,7 +85,7 @@ custom_colors_3 = dx.scatter(
     y="SepalLength",
     by="example_colors",
     # When set to `identity`, the column data passed to the
-    # color parameter will used as the actual color
+    # grouping/color parameter will be used as the actual color
     color_discrete_map="identity"
 )
 ```

plugins/plotly-express/docs/sidebar.json

@@ -133,10 +133,6 @@
           {
             "label": "Multiple axes",
             "path": "multiple-axes.md"
-          },
-          {
-            "label": "Titles and legends",
-            "path": "other.md"
           }
         ]
       }

plugins/plotly-express/docs/violin.md

@@ -16,14 +16,16 @@ Violin plots are appropriate when the data contain a continuous variable of inte
 
 Visualize the distribution of a single variable by passing the column name to the `x` or `y` arguments.
 
-```python order=violin_plot,versicolor
+```python order=violin_plot_x,violin_plot_y,versicolor
 import deephaven.plot.express as dx
 iris = dx.data.iris()
 
 # subset to get a specific group
 versicolor = iris.where("Species == `versicolor`")
 
-violin_plot = dx.violin(versicolor, x="SepalLength")
+# control the plot orientation using `x` or `y`
+violin_plot_x = dx.violin(versicolor, x="SepalLength")
+violin_plot_y = dx.violin(versicolor, y="SepalLength")
 ```
 
 ### Distributions for multiple groups