More polish

plugins/plotly-express/docs/area.md

@@ -14,7 +14,7 @@ Area plots are appropriate when the data contain a continuous response variable
 
 ### A basic area plot
 
-Visualize the relationship between two variables. In this case, an area plot is similar to a line plot.
+Visualize the relationship between two variables by passing each variable to the `x` and `y` arguments.
 
 ```python order=area_plot,usa_population
 import deephaven.plot.express as dx
@@ -23,23 +23,22 @@ gapminder = dx.data.gapminder()
 # subset to get a specific group
 usa_population = gapminder.where("country == `United States`")
 
-# create a basic area plot that tracks the trend of US population over time
 area_plot = dx.area(usa_population, x="year", y="pop")
 ```
 
 ### Color by group
 
 Area plots are unique in that the y-axis demonstrates each groups' total contribution to the whole. Use the `by` argument to specify a grouping column.
 
-```python order=area_plot_multi,large_countries_population
+```python order=area_plot_group,large_countries_population
 import deephaven.plot.express as dx
 gapminder = dx.data.gapminder()
 
 # subset to get several countries to compare
 large_countries_population = gapminder.where("country in `United States`, `India`, `China`")
 
-# pass a grouping column to `by` to create a plot of cumulative population trend showing contribution from each country
-area_plot_multi = dx.area(large_countries_population, x="year", y="pop", by="country")
+# cumulative trend showing contribution from each group
+area_plot_group = dx.area(large_countries_population, x="year", y="pop", by="country")
 ```
 
 ## API Reference

plugins/plotly-express/docs/bar.md

@@ -14,17 +14,16 @@ Bar plots are appropriate when the data contain a continuous response variable t
 
 ### A basic bar plot
 
-Visualize the relationship between a continuous variable and a categorical or discrete variable.
+Visualize the relationship between a continuous variable and a categorical or discrete variable by passing each to the `x` and `y` arguments.
 
 ```python order=bar_plot,tips
 import deephaven.plot.express as dx
 tips = dx.data.tips()
 
-# create a basic bar plot by specifying columns for the `x` and `y` axes
 bar_plot = dx.bar(tips, x="day", y="total_bill")
 ```
 
-Change the x-axis order by sorting the dataset by the categorical variable.
+Change the x-axis ordering by sorting the dataset by the categorical variable.
 
 ```python order=ordered_bar_plot,tips
 import deephaven.plot.express as dx
@@ -44,10 +43,10 @@ tips = dx.data.tips() # import a ticking version of the Tips dataset
 
 sorted_tips = tips.sort("day")
 
-# partition bars by smoker / non-smoker
+# group by smoker / non-smoker
 bar_plot_smoke = dx.bar(sorted_tips, x="day", y="total_bill", by="smoker")
 
-# partition bars by male / female
+# group by male / female
 bar_plot_sex = dx.bar(sorted_tips, x="day", y="total_bill", by="sex")
 ```
 

plugins/plotly-express/docs/box.md

@@ -14,29 +14,28 @@ Box plots are appropriate when the data have a continuous variable of interest.
 
 ### A basic box plot
 
-Visualize the distribution of a single continuous variable using a box plot. Data points displayed as dots are candidates for being outliers.
+Visualize the distribution of a single variable by passing the column name to `x` or `y`.
 
-```python order=total_bill_plot,tips
+```python order=box_plot,tips
 import deephaven.plot.express as dx
 tips = dx.data.tips()
 
-# create a basic box plot by specifying the variable of interest with `y`
-total_bill_plot = dx.box(tips, y="total_bill")
+box_plot = dx.box(tips, y="total_bill")
 ```
 
 ### Distributions for multiple groups
 
 Box plots are useful for comparing the distributions of two or more groups of data. Use the `by` argument to specify a grouping column.
 
-```python order=total_bill_smoke,total_bill_sex,tips
+```python order=box_plot_group_1,box_plot_group_2,tips
 import deephaven.plot.express as dx
 tips = dx.data.tips()
 
 # total bill distribution by smoker / non-smoker
-total_bill_smoke = dx.box(tips, y="total_bill", by="smoker")
+box_plot_group_1 = dx.box(tips, y="total_bill", by="smoker")
 
 # total bill distribution by male / female
-total_bill_sex = dx.box(tips, y="total_bill", by="sex")
+box_plot_group_2 = dx.box(tips, y="total_bill", by="sex")
 ```
 
 ## API Reference

plugins/plotly-express/docs/candlestick.md

@@ -16,7 +16,7 @@ In a bullish (upward, typically shown as green) candlestick, the open is typical
 
 ### A basic candlestick plot
 
-Visualize the key summary statistics of a stock price as it evolves.
+Visualize the key summary statistics of a stock price as it evolves. Specify the instrument of interest with `x`, and pass the `open`, `high`, `low`, and `close` arguments the appropriate column names.
 
 ```python order=candlestick_plot,stocks_1min_ohlc,stocks
 import deephaven.plot.express as dx
@@ -36,7 +36,6 @@ stocks_1min_ohlc = stocks.update_view(
     by=["sym", "binnedTimestamp"],
 )
 
-# create a basic candlestick plot - the `open`, `high`, `low`, and `close` arguments must be specified
 candlestick_plot = dx.candlestick(
     stocks_1min_ohlc.where("sym == `DOG`"),
     x="binnedTimestamp",

plugins/plotly-express/docs/funnel-area.md

@@ -16,14 +16,14 @@ Funnel area plots are appropriate when the data contain a categorical variable w
 
 ### A basic funnel plot
 
-Visualize the trend in consecutive stages of a categorical variable.
+Visualize the trend in consecutive stages of a categorical variable by specifying the `names` and `values` arguments.
 
-```python order=marking_trend_percentage,marketing
+```python order=funnel_area_plot,marketing
 import deephaven.plot.express as dx
 marketing = dx.data.marketing()
 
-# create a basic funnel plot by specifying column names for `names` and `values`
-marketing_trend_percentage = dx.funnel_area(marketing, names="Stage", values="Count")
+# `Count` is the frequency/value column, and `Stage` is the category column
+funnel_area_plot = dx.funnel_area(marketing, names="Stage", values="Count")
 ```
 
 ## API Reference

plugins/plotly-express/docs/funnel.md

@@ -16,14 +16,14 @@ Funnel plots are appropriate when the data contain a categorical variable where
 
 ### A basic funnel plot
 
-Visualize the trend in consecutive stages of a categorical variable.
+Visualize the trend in consecutive stages of a categorical variable by specifying the `x` and `y` arguments.
 
-```python order=marketing_trend,marketing
+```python order=funnel_plot,marketing
 import deephaven.plot.express as dx
 marketing = dx.data.marketing()
 
-# create a basic funnel plot by specifying column names for `x` and `y`
-marketing_trend = dx.funnel(marketing, x="Count", y="Stage")
+# `Count` is the frequency/value column, and `Stage` is the category column
+funnel_plot = dx.funnel(marketing, x="Count", y="Stage")
 ```
 
 ## API Reference

plugins/plotly-express/docs/histogram.md

@@ -14,51 +14,50 @@ Histograms are appropriate when the data contain a continuous variable of intere
 
 ### A basic histogram
 
-Visualize the distribution of a single continuous variable.
+Visualize the distribution of a single variable by passing the variable's name to the `x` or `y` arguments.
 
-```python order=setosa_sep_length,setosa,iris
+```python order=hist_plot,setosa,iris
 import deephaven.plot.express as dx
 iris = dx.data.iris()
 
 # subset to get specific species
 setosa = iris.where("species == `setosa`")
 
-# create a basic histogram by passing the column of interest to `x`
-setosa_sep_length = dx.histogram(setosa, x="sepal_length")
+hist_plot = dx.histogram(setosa, x="sepal_length")
 ```
 
 Modify the bin size by setting `nbins` equal to the number of desired bins.
 
-```python order=setosa_sep_length,setosa,iris
+```python order=hist_20_bins,hist_3_bins,hist_8_bins,virginica,iris
 import deephaven.plot.express as dx
 iris = dx.data.iris()
 
 # subset to get specific species
 virginica = iris.where("species == `virginica`")
 
 # too many bins will produce jagged, disconnected histograms
-virginica_20_bins = dx.histogram(setosa, x="sepal_length", nbins=20)
+hist_20_bins = dx.histogram(setosa, x="sepal_length", nbins=20)
 
 # too few bins will mask distributional information
-virginica_3_bins = dx.histogram(setosa, x="sepal_length", nbins=3)
+hist_3_bins = dx.histogram(setosa, x="sepal_length", nbins=3)
 
 # play with the `nbins` parameter to get a good visualization
-virginica_8_bins = dx.histogram(setosa, x="sepal_length", nbins=8)
+hist_8_bins = dx.histogram(setosa, x="sepal_length", nbins=8)
 ```
 
 ### Distributions of several groups
 
-Histograms can also be used to compare the distributional properties of different groups of data, though they may be a little harder to read than box plots or violin plots.
+Histograms can also be used to compare the distributional properties of different groups of data, though they may be a little harder to read than box plots or violin plots. Use the `by` argument to specify a grouping column.
 
-```python order=sep_length_multi,sep_length_multi_overlay,iris
+```python order=stacked_hist,overlay_hist,iris
 import deephaven.plot.express as dx
 iris = dx.data.iris()
 
 # each bin may be stacked side-by-side for each group
-sep_length_multi = dx.histogram(iris, x="sepal_length", by="species")
+stacked_hist = dx.histogram(iris, x="sepal_length", by="species")
 
 # or, each bin may be overlaid with the others
-sep_length_multi_overlay = dx.histogram(iris, x="sepal_length", by="species", barmode="overlay")
+overlay_hist = dx.histogram(iris, x="sepal_length", by="species", barmode="overlay")
 ```
 
 ## API Reference

plugins/plotly-express/docs/icicle.md

@@ -14,9 +14,9 @@ Icicle plots are appropriate when the data have a hierarchical structure. Each l
 
 ### A basic icicle plot
 
-Visualize a hierarchical dataset as nested rectangles, with categories displayed left-to-right, and the size of each category displayed top-to-bottom.
+Visualize a hierarchical dataset as nested rectangles, with categories displayed left-to-right, and the size of each category displayed top-to-bottom. Use the `names` argument to specify the labels for each group, the `values` argument to specify the value column for each group, and the `parents` column to specify the root category of the chart.
 
-```python order=continent_population,gapminder_recent,gapminder
+```python order=icicle_plot,gapminder_recent,gapminder
 import deephaven.plot.express as dx
 gapminder = dx.data.gapminder()
 
@@ -26,10 +26,10 @@ gapminder_recent = (
     .last_by("country")
     .view(["continent", "pop"])
     .sum_by("continent")
+    .update("world = `world`")
 )
 
-# create a basic icicle plot by specifying the categories, the values of interest, and a single root 'world'
-continent_population = dx.icicle(gapminder_recent.update("world = `world`"), names="continent", values="pop", parents="world")
+icicle_plot = dx.icicle(gapminder_recent, names="continent", values="pop", parents="world")
 ```
 
 ## API Reference

plugins/plotly-express/docs/line-3d.md

@@ -19,9 +19,9 @@ Alternatives to 3D line plots include:
 
 ### A basic 3D line plot
 
-Visualize the relationship between three variables by specifying each spatial component. Click and drag on the resulting chart to rotate it for new perspectives.
+Visualize the relationship between three variables by specifying the `x`, `y`, and `z` arguments. Click and drag on the resulting chart to rotate it for new perspectives.
 
-```python order=spiral_plot,spiral
+```python order=line_plot_3D,spiral
 import deephaven.plot.express as dx
 from deephaven import time_table
 
@@ -30,8 +30,7 @@ spiral = time_table("PT0.01s").update_view(
     ["X = sin(ii / 100)", "Y = cos(ii / 100)", "Z = 4 * ii / 100"]
 )
 
-# create a basic 3d line plot by specifying `x`, `y`, and `z`
-spiral_plot = dx.line_3d(spiral, x="X", y="Y", z="Z")
+line_plot_3D = dx.line_3d(spiral, x="X", y="Y", z="Z")
 ```
 
 ## API Reference

plugins/plotly-express/docs/line-polar.md

@@ -14,12 +14,14 @@ Polar line plots are appropriate when the data contain a continuous variable rep
 
 ### A basic polar line plot
 
-```python order=wind_line,wind
+Visualize a dataset in polar coordinates by providing the `r` and `theta` arguments. `theta` may be passed as a string of cardinal directions, as in this case. `theta` also supports the use of numeric types that may represent radians or degrees, depending on how the `range_theta` argument is supplied.
+
+```python order=polar_line_plot,wind
 import deephaven.plot.express as dx
 wind = dx.data.wind()
 
-# create a polar line plot by specifying `r` and `theta`. `by` is used to separate data by groups
-wind_line = dx.line_polar(wind, r="frequency", theta="direction", by="strength")
+# `by` is used to separate data by groups
+polar_line_plot = dx.line_polar(wind, r="frequency", theta="direction", by="strength")
 ```
 
 ## API Reference

plugins/plotly-express/docs/line-ternary.md

@@ -14,12 +14,13 @@ Ternary line plots are appropriate when the data contain three interrelated mutu
 
 ### A basic ternary line plot
 
-```python order=election_line,election
+Visualize a ternary dataset by passing categorical variables to each of the `a`, `b`, and `c` arguments.
+
+```python order=ternary_line_plot,election
 import deephaven.plot.express as dx
 election = dx.data.election()
 
-# create a ternary line plot by passing the column names for the three points of the triangle to `a`, `b`, and `c`
-election_line = dx.line_ternary(election, a="Joly", b="Coderre", c="Bergeron")
+ternary_line_plot = dx.line_ternary(election, a="Joly", b="Coderre", c="Bergeron")
 ```
 
 ## API Reference

plugins/plotly-express/docs/line.md

@@ -14,7 +14,7 @@ Line plots are appropriate when the data contain a continuous response variable
 
 ### A basic line plot
 
-Visualize the relationship between two variables. Column names are passed in directly as `x` and `y`.
+Visualize the relationship between two variables by passing each variable to the `x` and `y` arguments.
 
 ```python order=line_plot,my_table
 import deephaven.plot.express as dx
@@ -23,20 +23,19 @@ my_table = dx.data.stocks()
 # subset data for just DOG transactions
 dog_prices = my_table.where("sym = `DOG`")
 
-# create a basic line plot by specifying the x and y column
 line_plot = dx.line(dog_prices, x="timestamp", y="price")
 ```
 
 ### Color line plot by group
 
-Create a line with a unique color for each group in the dataset.
+Create a line with a unique color for each group in the dataset using the `by` argument.
 
 ```python order=line_plot,mytable
 import deephaven.plot.express as dx
 my_table = dx.data.stocks()
 
 # each line represents a group and has a unique color
-line_plot = dx.line(my_table, x="timestamp", y="price", color="sym")
+line_plot = dx.line(my_table, x="timestamp", y="price", by="sym")
 ```
 
 ## API Reference

plugins/plotly-express/docs/ohlc.md

@@ -14,7 +14,7 @@ In OHLC plots, each bar consists of a vertical line with small horizontal lines
 
 ### A basic OHLC plot
 
-Visualize the key summary statistics of a stock price as it evolves.
+Visualize the key summary statistics of a stock price as it evolves. Specify the instrument of interest with `x`, and pass the `open`, `high`, `low`, and `close` arguments the appropriate column names.
 
 ```python order=ohlc_plot,stocks_1min_ohlc,stocks
 import deephaven.plot.express as dx

plugins/plotly-express/docs/pie.md

@@ -15,21 +15,21 @@ Pie plots do have some limitations. They become less effective when dealing with
 
 # A basic pie plot
 
-Visualize the contribution of each part to the whole, arranged clockwise from greatest to least contribution.
+Visualize the contribution of each part to the whole, arranged clockwise from greatest to least contribution. Pass the label column to the `names` argument, and the value column to the `values` argument.
 
-```python order=continent_population,gapminder_recent_pop,gapminder
+```python order=pie_plot,gapminder_recent_pop,gapminder
 import deephaven.plot.express as dx
 gapminder = dx.data.gapminder()
 
+# get table of most recent total population per continent
 gapminder_recent_pop = (
     gapminder
     .last_by("country")
     .drop_columns(["country", "lifeExp", "gdpPercap"])
     .sum_by(["year", "month", "continent"])
 )
 
-# specify the labels for each slice with `names`, and the value corresponding to that label with `values`
-continent_population = dx.pie(gapminder_recent_pop, names="continent", values="pop")
+pie_plot = dx.pie(gapminder_recent_pop, names="continent", values="pop")
 ```
 
 ## API Reference