# Annotated Chart

This chart allows users to interactively change their data across a timeline. In the frontend, users can click inside the chart to display a modal with options to add a point or two to the timeline, as well as add an annotation for that point.

The chart requires a separate dataset for each series to plot, and it needs the y-field-name specified for each of them. All datasets must have the same name for the x-field and for the annotations field. The x-field values must be of type Date or convertible to it, the y-field must be integers, and the annotation field values must be strings. 

The modal that appears includes a slider to select the value that the user wants to add. This can be configured with the `slider_config` parameter, where the `max` value can be defined, and also the `defaultValue`. Labels can be added to the slider values using the `slider_marks` parameter.

## The Method To Use <a href="#the-method-to-use" id="the-method-to-use"></a>

The method is `s.plt.annotated_chart()`

It must contain the following input variables:

```python
data: Union[List[DataFrame], List[List[Dict]]]
order: int
x: str 
y: List[str] 
```

Accepts the following input variables as optional:

```python
annotations: str
rows_size: Optional[int]
cols_size: Optional[int]
padding: Optional[str]
title: Optional[str]
y_axis_name: Optional[str]
slider_config: Optional[Dict]
slider_marks: Optional[Dict]
```

## Examples <a href="#examples" id="examples"></a>

An example on how to use it would be:&#x20;

```python
data1 = [
    {'date': '2022-01-01', 'Value [1]': 3},
    {'date': '2022-03-01', 'Value [1]': 7, 'Annotation': 'Value [1] rapid increase'},
    {'date': '2022-04-01', 'Value [1]': 7},
    {'date': '2022-07-01', 'Value [1]': 8},
    {'date': '2022-08-01', 'Value [1]': 9},
    {'date': '2022-12-01', 'Value [1]': 5},
]
data2 = [
    {'date': '2021-12-31', 'Value [2]': 6},
    {'date': '2022-01-02', 'Value [2]': 9},
    {'date': '2022-02-01', 'Value [2]': 7},
    {'date': '2022-03-01', 'Value [2]': 8},
    {'date': '2022-04-01', 'Value [2]': 9},
    {'date': '2022-05-01', 'Value [2]': 7},
    {'date': '2022-06-01', 'Value [2]': 8, 'Annotation': 'Value [2] oscillation'},
    {'date': '2022-07-01', 'Value [2]': 9},
    {'date': '2022-08-01', 'Value [2]': 8},
]

s.plt.annotated_chart(
    order=0, x='date', y=['Value [1]', 'Value [2]'], annotations='Annotation',
    data=[data1, data2], slider_config={'max': 100, 'defaultValue': 50},
    slider_marks=[('Low', 15), ('Medium', 50), ('High', 85)]
)
```

<figure><img src="/files/y3zPTYtwcH9qg1A1aywA" alt=""><figcaption><p>Annotated chart with two datasets</p></figcaption></figure>

When clicking in the chart the modal appears like so:

<figure><img src="/files/OoLtIFEcTnpNwLyq7Dq0" alt=""><figcaption><p>Annotation modal</p></figcaption></figure>

It lets the user select a date range and the value of the point. Also it lets the user write an annotation in the bottom text field.

If we use the following values:&#x20;

<figure><img src="/files/8LNyDqlykWhg0GAb9yHK" alt=""><figcaption><p>Form ready to send</p></figcaption></figure>

The result in the chart is:

<figure><img src="/files/PJskL3Iwk8bcwi8Vz1WM" alt=""><figcaption><p>Annotation added</p></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.shimoku.com/dev/elements/charts/annotated-chart.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.