Skip to content

Commit

Permalink
Chart annotation and dataframe selection tutorials (#1080)
Browse files Browse the repository at this point in the history 
* Move altair annotations to tutorial sections

* Remove mention of selections

* Migrate row selections KB

* Add dataframe row-selections example

* Finish draft of dataframe row selections

* Update old row selection example to mention new one

* Grammar and typo check

* Update st.dataframe tip

* Update dataframe tip
  • Loading branch information
@sfc-gh-dmatthews
sfc-gh-dmatthews authored Jun 12, 2024
1 parent 22277ca commit ccff79b
Show file tree
Hide file tree
Showing 14 changed files with 986 additions and 167 deletions.
146 changes: 0 additions & 146 deletions content/develop/api-reference/charts/altair_chart.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -124,149 +124,3 @@ Notice how the custom colors are still reflected in the chart, even when the Str
<Cloud name="doc-altair-custom-colors" height="675px" />

For many more examples of Altair charts with and without the Streamlit theme, check out the [altair.streamlit.app](https://altair.streamlit.app).

## Annotating charts

Altair also allows you to annotate your charts with text, images, and emojis. You can do this by creating [layered charts](https://altair-viz.github.io/user_guide/compound_charts.html#layered-charts), which let you overlay two different charts on top of each other. The idea is to use the first chart to show the data, and the second chart to show the annotations. The second chart can then be overlaid on top of the first chart using the `+` operator to create a layered chart.

Let's walk through an example of annotating a time-series chart with text and an emoji.

### Step 1: Create the base chart

In this example, we create a time-series chart to track the evolution of stock prices. The chart is interactive and contains a multi-line tooltip. Click [here](https://altair-viz.github.io/gallery/multiline_tooltip.html) to learn more about multi-line tooltips in Altair.

First, we import the required libraries and load the example stocks dataset using the [`vega_datasets`](https://pypi.org/project/vega-datasets/) package:

```python
import altair as alt
import pandas as pd
import streamlit as st
from vega_datasets import data

# We use @st.cache_data to keep the dataset in cache
@st.cache_data
def get_data():
source = data.stocks()
source = source[source.date.gt("2004-01-01")]
return source

source = get_data()
```

Next, we define a function `get_chart()` to create the interactive time-series chart of the stock prices with a multi-line tooltip. The x-axis represents the date, and the y-axis represents the stock price.

We then invoke `get_chart()` that takes the stock prices dataframe as an input and returns a chart object. This is going to be our base chart on which we will overlay the annotations in [Step 2](/develop/api-reference/charts/st.altair_chart#step-2-annotate-the-chart).

```python
# Define the base time-series chart.
def get_chart(data):
hover = alt.selection_single(
fields=["date"],
nearest=True,
on="mouseover",
empty="none",
)

lines = (
alt.Chart(data, title="Evolution of stock prices")
.mark_line()
.encode(
x="date",
y="price",
color="symbol",
)
)

# Draw points on the line, and highlight based on selection
points = lines.transform_filter(hover).mark_circle(size=65)

# Draw a rule at the location of the selection
tooltips = (
alt.Chart(data)
.mark_rule()
.encode(
x="yearmonthdate(date)",
y="price",
opacity=alt.condition(hover, alt.value(0.3), alt.value(0)),
tooltip=[
alt.Tooltip("date", title="Date"),
alt.Tooltip("price", title="Price (USD)"),
],
)
.add_selection(hover)
)
return (lines + points + tooltips).interactive()

chart = get_chart(source)
```

### Step 2: Annotate the chart

Now that we have our first chart that shows the data, we can annotate it with text and an emoji. Let's overlay the ⬇ emoji on top of the time-series chart at specifc points of interest. We want users to hover over the ⬇ emoji to see the associated annotation text.

For simplicity, let's annotate four specific dates and set the height of the annotations at constant value of `10`.

<Tip>

You can vary the horizontal and vertical postions of the annotations by replacing the hard-coded values with the output of Streamlit widgets! Click [here](/develop/api-reference/charts/st.altair_chart#interactive-example) to jump to a live example below, and develop an intuition for the ideal horizontal and vertical positions of the annotations by playing with Streamlit widgets.

</Tip>

To do so, we create a dataframe `annotations_df` containing the dates, annotation text, and the height of the annotations:

```python
# Add annotations
ANNOTATIONS = [
("Mar 01, 2008", "Pretty good day for GOOG"),
("Dec 01, 2007", "Something's going wrong for GOOG & AAPL"),
("Nov 01, 2008", "Market starts again thanks to..."),
("Dec 01, 2009", "Small crash for GOOG after..."),
]
annotations_df = pd.DataFrame(ANNOTATIONS, columns=["date", "event"])
annotations_df.date = pd.to_datetime(annotations_df.date)
annotations_df["y"] = 10
```

Using this dataframe, we create a scatter plot with the x-axis representing the date, and the y-axis representing the height of the annotation. The data point at the specific date and height is represented by the ⬇ emoji, using Altair's `mark_text()` [mark](https://altair-viz.github.io/user_guide/marks.html).

The annotation text is displayed as a tooltip when users hover over the ⬇ emoji. This is achieved using Altair's `encode()` method to map the `event` column containing the annotation text to the visual attribute ⬇ of the plot.

```python
annotation_layer = (
alt.Chart(annotations_df)
.mark_text(size=20, text="⬇", dx=-8, dy=-10, align="left")
.encode(
x="date:T",
y=alt.Y("y:Q"),
tooltip=["event"],
)
.interactive()
)
```

Finally, we overlay the annotations on top of the base chart using the `+` operator to create the final layered chart! 🎈

```python
st.altair_chart(
(chart + annotation_layer).interactive(),
use_container_width=True
)
```

<Image src="/images/api/altair-annotation.png" />

To use images instead of emojis, replace the line containing `.mark_text()` with `.mark_image()`, and replace `image_url` below with the URL of the image:

```python
.mark_image(
width=12,
height=12,
url="image_url",
)
```

### Interactive example

Now that you've learned how to annotate charts, the sky's the limit! We've extended the above example to let you interactively paste your favorite emoji and set its position on the chart with Streamlit widgets. 👇

<Cloud name="example-time-series-annotation" height="700px" />
2 changes: 1 addition & 1 deletion content/develop/api-reference/data/dataframe.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ description: st.dataframe displays a dataframe as an interactive table.

<Tip>

This page only contains information on the `st.dataframe` API. For an overview of working with dataframes read [Dataframes](/develop/concepts/design/dataframes). If you want to let users interactively edit dataframes, check out [`st.data_editor`](/develop/api-reference/data/st.data_editor).
Learn more in our [Dataframes](/develop/concepts/design/dataframes) guide and check out our tutorial, [Get dataframe row-selections from users](/develop/tutorials/elements/dataframe-row-selections).

</Tip>

Expand Down
4 changes: 4 additions & 0 deletions content/develop/tutorials/elements/_index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
title: Work with Streamlit elements
slug: /develop/tutorials/elements
---
Loading

0 comments on commit ccff79b

Please sign in to comment.