diff --git a/doc/python/dropdowns.md b/doc/python/dropdowns.md index 222b794e804..c43103a630f 100644 --- a/doc/python/dropdowns.md +++ b/doc/python/dropdowns.md @@ -365,27 +365,27 @@ fig.add_trace( go.Scatter(x=list(df.Date), y=list(df.High), name="High", - line=dict(color="#33CFA5"))) + line=dict(color="DarkBlue"))) fig.add_trace( go.Scatter(x=list(df.Date), y=[df.High.mean()] * len(df.index), name="High Average", visible=False, - line=dict(color="#33CFA5", dash="dash"))) + line=dict(color="DarkBlue", dash="dash"))) fig.add_trace( go.Scatter(x=list(df.Date), y=list(df.Low), name="Low", - line=dict(color="#F06A6A"))) + line=dict(color="Crimson"))) fig.add_trace( go.Scatter(x=list(df.Date), y=[df.Low.mean()] * len(df.index), name="Low Average", visible=False, - line=dict(color="#F06A6A", dash="dash"))) + line=dict(color="Crimson", dash="dash"))) # Add Annotations and Buttons high_annotations = [dict(x="2016-03-01", diff --git a/doc/python/facet-plots.md b/doc/python/facet-plots.md index 5d0f629b2ea..7a79ea06c2d 100644 --- a/doc/python/facet-plots.md +++ b/doc/python/facet-plots.md @@ -54,6 +54,8 @@ fig.show() ### Bar Chart Row Facets +There is a more presentation-ready horizontal, faceted bar chart in the [horizontal bar documentation](/python/horizontal-bar-charts/#Small-multiple-horizontal-bar-charts-show-each-component's-size-more-clearly-than-a-stacked-bar) + ```python import plotly.express as px df = px.data.tips() diff --git a/doc/python/graph-objects.md b/doc/python/graph-objects.md index 936ea6d6960..878b36d6bfc 100644 --- a/doc/python/graph-objects.md +++ b/doc/python/graph-objects.md @@ -68,7 +68,9 @@ Note that the figures produced by Plotly Express **in a single function-call** a The figures produced by Plotly Express can always be built from the ground up using graph objects, but this approach typically takes **5-100 lines of code rather than 1**. -Here is a simple example of how to produce the same figure object from the same data, once with Plotly Express and once without. The data in this example is in "long form" but [Plotly Express also accepts data in "wide form"](/python/wide-form/) and the line-count savings from Plotly Express over graph objects are comparable. More complex figures such as [sunbursts](/python/sunburst-charts/), [parallel coordinates](/python/parallel-coordinates-plot/), [facet plots](/python/facet-plots/) or [animations](/python/animations/) require many more lines of figure-specific graph objects code, whereas switching from one representation to another with Plotly Express usually involves changing just a few characters. +Here is a simple example of how to produce the same figure object from the same data, once with Plotly Express and once without. Note that [Plotly Express functions](/python-api-reference/plotly.express.html) like [`px.bar()`](/python/bar-charts/) can accept a DataFrame as their first argument with column names passed to the `x` and `y` arguments, while [Graph Objects functions](/python-api-reference/plotly.graph_objects.html) like [`go.Bar()`](/python/bar-charts/#basic-bar-charts-with-plotlygraphobjects) require the data values to be passed directly to the `x` and `y` arguments as a tuple, list, NumPy array, or Pandas Series. + +The data in this example is in "long form" but [Plotly Express also accepts data in "wide form"](/python/wide-form/) and the line-count savings from Plotly Express over graph objects are comparable. More complex figures such as [sunbursts](/python/sunburst-charts/), [parallel coordinates](/python/parallel-coordinates-plot/), [facet plots](/python/facet-plots/) or [animations](/python/animations/) require many more lines of figure-specific graph objects code, whereas switching from one representation to another with Plotly Express usually involves changing just a few characters. ```python import pandas as pd diff --git a/doc/python/horizontal-bar-charts.md b/doc/python/horizontal-bar-charts.md index 3a5070f9bc8..274e53010bb 100644 --- a/doc/python/horizontal-bar-charts.md +++ b/doc/python/horizontal-bar-charts.md @@ -107,6 +107,49 @@ fig.add_trace(go.Bar( )) fig.update_layout(barmode='stack') +fig.show() +``` +### Small multiple horizontal bar charts show each component's size more clearly than a stacked bar + +Bar charts with multiple components pose a fundamental trade off between presenting the total clearly and presenting the component values clearly. This small multiples approach shows the component magnitudes clearly at the cost of slightly obscuring the totals. A stacked bar does the opposite. Small multiple bar charts often work better in a horizontal orientation; and are easy to create with the px.bar orientation and facet_col parameters. +``` +import pandas as pd +import plotly.express as px + +data = { + "Quarter": ["Q1", "Q2", "Q3", "Q4"] * 3, + "Region": ["North", "North", "North", "North", "South", "South", "South", "South", "West", "West", "West", "West"], + "Outcome": [150, 200, 250, 300, 120, 180, 240, 310, 100, 150, 220, 280] +} +df = pd.DataFrame(data) + + +fig = px.bar( + df, + x="Outcome", + y="Region", + orientation="h", + facet_col="Quarter", + title="Number of Patients Served by Region and Quarter", + labels={"Outcome": "Patients Served", "Region": "Region"} +) + +## the section below is optional clean up to make this presentation ready + +fig.update_layout( + height=400, #the Plotly default makes the bars awkwardly large; setting a height improves the display + showlegend=False, # the legend does not add anything +) + +# remove the default "facet_variable =" text from the title of each facet graph +fig.for_each_annotation(lambda a: a.update(text=a.text.split("=")[-1])) + +# Remove duplicate axis labels +fig.for_each_yaxis(lambda axis: axis.update(title=None)) +fig.for_each_xaxis(lambda axis: axis.update(title=None)) +# add the one valuable axis label back in +fig.update_xaxes(title="Count", row=1, col=1) + fig.show() ``` diff --git a/plotly/express/_doc.py b/plotly/express/_doc.py index 8754e5265b3..59faac4c0b3 100644 --- a/plotly/express/_doc.py +++ b/plotly/express/_doc.py @@ -612,7 +612,12 @@ def make_docstring(fn, override_dict=None, append_dict=None): override_dict = {} if override_dict is None else override_dict append_dict = {} if append_dict is None else append_dict - tw = TextWrapper(width=75, initial_indent=" ", subsequent_indent=" ") + tw = TextWrapper( + width=75, + initial_indent=" ", + subsequent_indent=" ", + break_on_hyphens=False, + ) result = (fn.__doc__ or "") + "\nParameters\n----------\n" for param in getfullargspec(fn)[0]: if override_dict.get(param):