# v.0.18

{% hint style="danger" %}
The package shimoku-api-python is no longer maintained
{% endhint %}

{% hint style="info" %}
To get the new version 🦾
{% endhint %}

```
pip install --upgrade shimoku-api-python
```

This version expands massively the charts catalog as well as bringing a new navigation tool!

## Fixes

Horizontal indicators group now occupies all available columns given. Previously, if the number of indicators didn't divide the number of columns, sometimes the sum of the sizes of the indicators didn't equal the number of given columns. The remaining space is now filled with `padding`.

<figure><img src="https://3782181538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUlHTfmIZY46Z1EDfyGMz%2Fuploads%2F3zQUtBtzjmd0aScaVAUA%2Fimatge.png?alt=media&#x26;token=8f8e6925-c60d-411e-8703-8d1378b5ca72" alt=""><figcaption><p>Padding applied automatically to a row of 5 indicators</p></figcaption></figure>

## Improvements&#x20;

* ### New HTML Component

  A new component has been added to the shimoku\_components\_catalog library! It is an iteration on the previous title component, it brings a lot more features and customization options:

  ```python
  def create_h1_title_with_modal(
      title: str, 
      subtitle: str, 
      # This will be the title shown in the modal, if the value is None, the 
      # information icon will not be shown, and the modal will not be available
      modal_title: Optional[str] = None,
      # Information icon
      icon_url: str = 'https://uploads-ssl.webflow.com/619f9fe98661d321dc3beec7/63594ccf3f311a98d72faff7_suite-customer-b.svg',
      # Text shown in the modal
      modal_text: str = "You can click the X in the corner or click the overlay to close this modal. "
  		      "This is a nice way to show additional information.",
      # Main title color
      text_color: str = 'var(--background-paper)',
      # Main background color
      background_color: str = 'var(--color-black)', 
      # Information icon default color
      modal_icon_color: str = 'var(--chart-C1)',
      # Information icon hover color
      modal_icon_hover_color: str = 'var(--color-primary-dark)'
  ) -> str:
  ```

  This next example shows a basic configuration of the component that uses the primary colors palette:

  <pre class="language-python"><code class="lang-python">s.plt.html(
      menu_path=menu_path, order=0,
  <strong>    html = s.html_components.create_h1_title_with_modal(
  </strong>        title='New HTML Component', subtitle='modal and title',
          text_color='var(--color-white)', background_color='var(--color-primary)',
          modal_title='Modal Title',
      ),
  )
  </code></pre>

  <figure><img src="https://3782181538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUlHTfmIZY46Z1EDfyGMz%2Fuploads%2F7wVzf6Di9dwFvF2c7hAI%2Fimatge.png?alt=media&#x26;token=b6914ad8-852a-40f2-b327-882f3dc4a7f9" alt=""><figcaption><p>Header and modal open from clicking the icon</p></figcaption></figure>

  <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>The modal used in this component is not the same as the report Modal!</p></div>

* ### Modal

  The new navigation tool added is the **Modal report**! A Modal report is a type of container report that allows you to include other reports inside of it, much like a Tabs report. When a Modal report is opened, it appears as a pop-up window that overlays the current page. This report type is useful for navigating between different reports or for drilling down into specific insights.

  Modal reports are often used in situations where users need to perform complex actions or view large amounts of data. For example, a Modal report might be used to display a detailed breakdown of a particular product, with the ability to drill down into individual components such as sales by region or by customer.

  All the charts have been added the parameter `modal_name: Optional[str]`, when provided it will include the report inside the modal.&#x20;

  For the specific case of the Tabs report a function has been created so that a tabs group can be included inside a Modal:

  ```python
  s.plt.add_tabs_group_to_modal(
      menu_path: str,
      modal_name: str,          # the modal where the tabs group will be included
      tabs_group_name: str,     # the name of the tabs group to be included
  )
  ```

  For the customization and variation of the modal's behavior the function `s.plt.update_modal` must be used. The size of the modal can be changed, and the option to open the modal by default (when the user enters the path) can be achieved by setting the `open_by_default: bool` to `True`.

  ```python
  s.plt.update_modal(
      menu_path: str, 
      modal_name: str, 
      open_by_default: Optional[bool],    # by default False
      width: Optional[int],               # by default 60
      height: Optional[int],              # by default 50
  )
  ```

  Another way to open the modal is by a button that triggers the event, the function to use is `s.plt.modal_button`. It has mostly the same parameters of the button function but is dedicated to opening a modal:

  <pre class="language-python"><code class="lang-python">s.plt.modal_button(
      label: str, 
      menu_path: str, 
      order: int, 
  <strong>    # This modal is the one that will be opened by the button
  </strong><strong>    modal_name_to_open: str, 
  </strong>    rows_size: Optional[int] = 1, 
      cols_size: int = 2, 
      align: Optional[str] = 'stretch', 
      padding: Optional[str] = None, 
      bentobox_data: Optional[Dict] = None, 
      tabs_index: Optional[Tuple[str, str]] = None,
  <strong>    # This is the general modal parameter, for inclusion in a modal 
  </strong><strong>    modal_name: Optional[str] = None, 
  </strong>):
  </code></pre>

  The next example shows how to include a normal report to a modal as well as a tabs group, and how to create a button to open that modal:

  ```python
  menu_path = 'Modal Test'

  s.plt.update_modal(
      menu_path=menu_path, modal_name='Test modal', 
      open_by_default=True, width=90, height=90
  )
  s.plt.add_tabs_group_to_modal(
      menu_path=menu_path, modal_name='Test modal', tabs_group_name='Test'
  )
  s.plt.update_tabs_group_metadata(
      menu_path=menu_path, group_name='Test', order=1
  )

  modal_header = s.html_components.create_h1_title_with_modal(
      title='Modal title', subtitle='Modal subtitle', 
      background_color='var(--chart-C5)'
  )

  s.plt.html(
      html=modal_header, menu_path=menu_path, modal_name='Test modal', order=0
  )

  s.plt.html(
      html=modal_header, menu_path=menu_path, tabs_index=("Test", "Tab 1"), order=0
  )

  data_ = [
      {'date': dt.date(2021, 1, 1), 'x': 5, 'y': 5, 'filtA': 'A', 'filtB': 'Z', 'name': 'Ana'},
      {'date': dt.date(2021, 1, 2), 'x': 6, 'y': 5, 'filtA': 'B', 'filtB': 'Z', 'name': 'Laura'},
      {'date': dt.date(2021, 1, 3), 'x': 4, 'y': 5, 'filtA': 'A', 'filtB': 'W', 'name': 'Audrey'},
      {'date': dt.date(2021, 1, 4), 'x': 7, 'y': 5, 'filtA': 'B', 'filtB': 'W', 'name': 'Jose'},
      {'date': dt.date(2021, 1, 5), 'x': 3, 'y': 5, 'filtA': 'A', 'filtB': 'Z', 'name': 'Jorge'},
  ]
  search_columns: List[str] = ['name']

  s.plt.table(
      title="Test-table",
      data=data_,
      menu_path=menu_path,
      order=2,
      search_columns=search_columns,
      tabs_index=("Test", "Table"),
  )

  s.plt.modal_button(
      menu_path=menu_path, order=0, 
      modal_name_to_open='Test modal', label='Open modal'
  )
  ```

  <figure><img src="https://3782181538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUlHTfmIZY46Z1EDfyGMz%2Fuploads%2FWkaJNcyLn6LhlkFTSm5d%2Fimatge.png?alt=media&#x26;token=ef52a70a-87f8-4519-8a35-b147a652c0fb" alt=""><figcaption><p>Button shown in the dashboard</p></figcaption></figure>

  <figure><img src="https://3782181538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUlHTfmIZY46Z1EDfyGMz%2Fuploads%2FLiHEzHnvgKKHSkY6eucR%2Fimatge.png?alt=media&#x26;token=3625cb24-c8bc-4987-8093-b6a72151929e" alt=""><figcaption><p>Modal content after clicking the button</p></figcaption></figure>

* ### Events In Submit Form

  Now the input forms groups can trigger events when sent! The two new arguments are:

  ```
                modal_to_open_on_submit, acivity_name_to_call_on_submit
  ```

  Using this arguments a modal can be opened or an activity can be called when the submit button is clicked.

  In the following example it is shown how to link a modal and an activity to a form:

  ```python
  form_groups = {
      'Skills': [
          {
              'mapping': 'skills',
              'fieldName': 'Skills',
              'options': ['Backend', 'Frontend', 'UX/UI', 'Api Builder', 'DevOps'],
              'inputType': 'checkbox',
          },
      ]
  }

  s.plt.html(
      html=s.html_components.create_h1_title_with_modal(
          title='Form has been sent, congratulations!', subtitle='Modal Test',
          text_color='var(--color-white)', background_color='var(--color-primary)'
      ),
      menu_path=menu_path,
      modal_name='Congratulations modal',
      order=0
  )

  s.activity.create_activity(
      activity_name='test activity',
      menu_path=menu_path
  )

  s.plt.generate_input_form_groups(
      menu_path=menu_path, order=0,
      form_groups=form_groups,
      dynamic_sequential_show=True,
      modal_to_open_on_submit='Congratulations modal',
      acivity_name_to_call_on_submit='test activity'
  )
  ```

  The form in the dashboard appears:

  <figure><img src="https://3782181538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUlHTfmIZY46Z1EDfyGMz%2Fuploads%2FSUtky0fUxbX9zqp6iqss%2Fimatge.png?alt=media&#x26;token=943d5146-7b2a-44d3-80a9-dfffa82f9123" alt=""><figcaption><p>Input form</p></figcaption></figure>

  After clicking the 'send' button the modal is opened and an activity is called, in this case the activity provided doesn't have a webhook attached so it gives an error:

  <figure><img src="https://3782181538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUlHTfmIZY46Z1EDfyGMz%2Fuploads%2FMv6boPZDzG5cMlD5ttTf%2Fimatge.png?alt=media&#x26;token=3d4ffa52-eb6d-4d2f-87af-046f70394f3f" alt=""><figcaption><p>Modal opened and activity called</p></figcaption></figure>

* ### New Bentobox Charts

  Four new composite charts have been added. Each one of them uses a bentobox to group a user defined chart with a predefined component or group of components.

  * We have named the first type of charts as the **Infographics Charts**. These consist on joining a text bubble with a user selected chart, there are 4 options for the position of the text bubble (top, down, left, right), and it can be customized with background colors and images. It also provides the option to set an image on top of the bubble for the horizontal configuration.

    The function works like so:

    <pre class="language-python"><code class="lang-python">def infographics_text_bubble(
        menu_path: str, 
        title: str, 
        text: str, 
        order: int, 
    <strong>    # This are the parameters that the chart function will take when executed
    </strong><strong>    chart_parameters: Dict,
    </strong>    rows_size: int = 3, cols_size: int = 12, 
    <strong>    # This is the funcion that will be executed passing the previous parameters,
    </strong><strong>    # by default it will use a free_echarts bar chart
    </strong><strong>    chart_function: Optional[Callable] = None,
    </strong>    tabs_index: Optional[Tuple[str, str]] = None, 
        modal_name: Optional[str] = None,
    <strong>    # This will be used as the background image for the bubble
    </strong><strong>    background_url: Optional[str] = None, 
    </strong><strong>    # If there is no image this color will be used as the background
    </strong><strong>    background_color: str = 'var(--background-default)',
    </strong><strong>    # Where the bubble will be located ['top', 'bottom', 'left', 'right']
    </strong><strong>    bubble_location: str = 'top', 
    </strong><strong>    # This will be the image located avobe the bubble in the horizontal configs,
    </strong><strong>    # if the string 'default' is passed it will take a default image
    </strong><strong>    image_url: Optional[str] = None, 
    </strong><strong>    # Size of the previous image
    </strong><strong>    image_size: int = 100,
    </strong>):
    ...
    </code></pre>

    Here are some examples on how it could be used:

    * To start, the variable values that will be used are:

      ```python
      menu_path = 'Infographics'
      title = 'Lorem ipsum'
      text = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et " \
             "dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex" \
             " ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu" \
             " fugiat nulla pariatur. "
      data = [
          {'date': dt.date(2021, 1, 1), 'x': 5, 'y': 5},
          {'date': dt.date(2021, 1, 2), 'x': 6, 'y': 5},
          {'date': dt.date(2021, 1, 3), 'x': 4, 'y': 5},
          {'date': dt.date(2021, 1, 4), 'x': 7, 'y': 5},
          {'date': dt.date(2021, 1, 5), 'x': 3, 'y': 5},
      ]
      stacked_data = [
          {'Weekday': 'Mon', 'Email': 120, 'Union Ads': 132, 'Video Ads': 101, 'Search Engine': 134},
          {'Weekday': 'Tue', 'Email': 220, 'Union Ads': 182, 'Video Ads': 191, 'Search Engine': 234},
          {'Weekday': 'Wed', 'Email': 150, 'Union Ads': 232, 'Video Ads': 201, 'Search Engine': 154},
          {'Weekday': 'Thu', 'Email': 820, 'Union Ads': 932, 'Video Ads': 901, 'Search Engine': 934},
          {'Weekday': 'Fri', 'Email': 120, 'Union Ads': 132, 'Video Ads': 101, 'Search Engine': 134},
          {'Weekday': 'Sat', 'Email': 220, 'Union Ads': 182, 'Video Ads': 191, 'Search Engine': 234},
          {'Weekday': 'Sun', 'Email': 150, 'Union Ads': 232, 'Video Ads': 201, 'Search Engine': 154},
      ]
      ```

    * Top and bottom:

      ```python
      s.plt.infographics_text_bubble(
          menu_path=menu_path, order=4, cols_size=6,
          title=title, text=text,
          chart_function=s.plt.shimoku_gauge,
          chart_parameters=dict(
              value=random.randint(0, 100), name='Gauge', rows_size=18,
              padding='0,0,0,0'
          ),
      )
      s.plt.infographics_text_bubble(
          menu_path=menu_path, order=6, cols_size=6, rows_size=4,
          title=title, text=text, bubble_location='bottom',
          chart_function=s.plt.stacked_barchart,
          chart_parameters=dict(
              data=stacked_data,
              x="Weekday",
              x_axis_name='weekday',
              y_axis_name='visits',
          ),
          background_color='var(--color-stripe-light)',
      )
      ```

      <figure><img src="https://3782181538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUlHTfmIZY46Z1EDfyGMz%2Fuploads%2Fj6KiURr2aCmWz36bULRm%2Fimatge.png?alt=media&#x26;token=6502ed6a-d5e8-49f3-a197-bece93e33589" alt=""><figcaption><p>Gauge and stacked infographics charts</p></figcaption></figure>

    * Default chart and background image:

      ```python
      s.plt.infographics_text_bubble(
          menu_path=menu_path, order=8,
          title=title, text=text, bubble_location='right',
          chart_parameters=dict(
              data=data
          ),
          background_url='https://images.unsplash.com/photo-1569982175971-d92b01cf8694?ixlib=rb-4.0.3&ixid='
                         'MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=870&q=80'
      )
      s.plt.infographics_text_bubble(
          menu_path=menu_path, order=14, cols_size=6,
          title=title, text=text, bubble_location='left',
          image_url='default', image_size=60,
          background_color='var(--color-primary-light)',
          chart_parameters=dict(
              data=data,
              cols_size=10,
          )
      )
      s.plt.infographics_text_bubble(
          menu_path=menu_path, order=16, cols_size=6, rows_size=4,
          title=title, text=text, bubble_location='right',
          image_url='default',
          chart_function=s.plt.table,
          chart_parameters=dict(
              data=data,
              cols_size=10,
          )
      )
      ```

      <figure><img src="https://3782181538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUlHTfmIZY46Z1EDfyGMz%2Fuploads%2FrxARWGnYyFAtddTJZ2XZ%2Fimatge.png?alt=media&#x26;token=84469660-9d48-48f5-b60f-3fa45b3d85a0" alt=""><figcaption><p>Default chart and background image</p></figcaption></figure>

    * Horizontal configuration with top image:

      ```python
      s.plt.infographics_text_bubble(
          menu_path=menu_path, order=14, cols_size=6,
          title=title, text=text, bubble_location='left',
          image_url='default', image_size=60,
          background_color='var(--color-primary-light)',
          chart_parameters=dict(
              data=data,
              cols_size=10,
          )
      )
      s.plt.infographics_text_bubble(
          menu_path=menu_path, order=16, cols_size=6, rows_size=4,
          title=title, text=text, bubble_location='right',
          image_url='default',
          chart_function=s.plt.table,
          chart_parameters=dict(
              data=data,
              cols_size=10,
          )
      )
      ```

      <figure><img src="https://3782181538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUlHTfmIZY46Z1EDfyGMz%2Fuploads%2FZbNVTJ1N3KLMEHN7AZLU%2Fimatge.png?alt=media&#x26;token=6b52138c-1673-44cb-9844-ccfc0971927c" alt=""><figcaption><p>Horizontal configuration with top image</p></figcaption></figure>

  * The next entry is a **drill-down chart** that joins a user defined chart with a message and a modal button. The function parameters are:

    <pre class="language-python"><code class="lang-python">def chart_and_modal_button(
        menu_path: str, 
        order: int, 
    <strong>    # This are the parameters that the chart function will take when executed
    </strong><strong>    chart_parameters: Dict,
    </strong><strong>    # This is the name of the modal that will be used by the button
    </strong><strong>    button_modal: str, 
    </strong>    rows_size: int = 3,
        cols_size: int = 12, 
    <strong>    # This is the funcion that will be executed passing the previous parameters,
    </strong><strong>    # by default it will use a free_echarts bar chart
    </strong><strong>    chart_function: Optional[Callable] = None,
    </strong><strong>    button_label: str = 'Read more',
    </strong>    tabs_index: Optional[Tuple[str, str]] = None, 
        modal_name: Optional[str] = None,
    <strong>    button_side_text: str = "Click on the button to read more about this topic.",
    </strong>):
    ...
    </code></pre>

    An example on how to use it is:

    ```python
    menu_path = 'stacked with drill-down'

    data = [
        {'Email': 120, 'Union Ads': 132, 'Video Ads': 101, 'Search Engine': 134, 'Weekday': 'Mon'},
        {'Email': 220, 'Union Ads': 182, 'Video Ads': 191, 'Search Engine': 234, 'Weekday': 'Tue'},
        {'Email': 150, 'Union Ads': 232, 'Video Ads': 201, 'Search Engine': 154, 'Weekday': 'Wed'},
        {'Email': 820, 'Union Ads': 932, 'Video Ads': 901, 'Search Engine': 934, 'Weekday': 'Thu'},
        {'Email': 120, 'Union Ads': 132, 'Video Ads': 101, 'Search Engine': 134, 'Weekday': 'Fri'},
        {'Email': 220, 'Union Ads': 182, 'Video Ads': 191, 'Search Engine': 234, 'Weekday': 'Sat'},
        {'Email': 150, 'Union Ads': 232, 'Video Ads': 201, 'Search Engine': 154, 'Weekday': 'Sun'},
    ]

    s.plt.chart_and_modal_button(
        menu_path=menu_path, order=0,
        button_modal='test modal',
        chart_function=s.plt.stacked_area_chart,
        chart_parameters=dict(
            data=data,
            x="Weekday",
            x_axis_name='Visits per weekday',
        )
    )
    ```

    <figure><img src="https://3782181538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUlHTfmIZY46Z1EDfyGMz%2Fuploads%2FoWTU67KF9gyLkI2ZFNlF%2Fimatge.png?alt=media&#x26;token=8bb25c3b-b4b0-4799-a675-8181bd03574b" alt=""><figcaption><p>Area chart with drill-down modal</p></figcaption></figure>

  * A common use case of the bentobox is to fuse indicators with other indicators and charts, as they are small reports that can easily add insight, so we have facilitated this with the **chart with indicators**. The function parameters are:

    <pre class="language-python"><code class="lang-python">def chart_and_indicators(
        menu_path: str, 
        order: int, 
    <strong>    # This are the parameters that the chart function will take when executed
    </strong><strong>    chart_parameters: Dict,
    </strong><strong>    # List of groups of indicators, each one of them will be used as the input
    </strong><strong>    # of an indicators function call
    </strong><strong>    indicators_groups: List[Union[pd.DataFrame, List[Dict]]],
    </strong><strong>    # The parameters that will be passed to the indicators calls
    </strong><strong>    indicators_parameters: Dict,
    </strong>    chart_rows_size: int = 3, 
        cols_size: int = 12,
    <strong>    # This is the funcion that will be executed passing the previous parameters,
    </strong><strong>    # by default it will use a free_echarts bar chart
    </strong><strong>    chart_function: Optional[Callable] = None,
    </strong>    tabs_index: Optional[Tuple[str, str]] = None, 
        modal_name: Optional[str] = None,
    ) -> int:
    </code></pre>

    <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>Because it is using multiple indicators the function will return the next available order.</p></div>

    The next example uses four groups of indicators and a line chart:

    ```python
    menu_path = 'chart-and-indicators'
    indicator_groups = [
        [
            {
                "footer": "-950.55",
                "header": "Dow Jones",
                "val": "33,195.92",
                "alignment": "left",
                "color": "success",
                'variant': 'contained'
            },
            {
                "footer": "-84.68",
                "header": "Nasdaq",
                "val": "10,852.16",
                "alignment": "left",
                "color": "success",
                'variant': 'contained'
            },
            {
                "footer": "-950.55",
                "header": "Dow Jones",
                "val": "33,195.92",
                "alignment": "left",
                "color": "success",
                'variant': 'contained'
            },
            {
                "footer": "-84.68",
                "header": "Nasdaq",
                "val": "10,852.16",
                "alignment": "left",
                "color": "success",
                'variant': 'contained'
            },
            {
                "footer": "-950.55",
                "header": "Dow Jones",
                "val": "33,195.92",
                "alignment": "left",
                "color": "success",
                'variant': 'contained'
            },
        ],
        [
            {
                "footer": "-950.55",
                "header": "Dow Jones",
                "val": "33,195.92",
                "alignment": "left",
                "color": "success",
                'variant': 'contained'
            },
            {
                "footer": "-84.68",
                "header": "Nasdaq",
                "val": "10,852.16",
                "alignment": "left",
                "color": "success",
                'variant': 'contained'
            }
        ],
        [
            {
                "footer": "Return of investment",
                "header": "ROI",
                "val": "1.5M",
                "alignment": "left",
                "color": "success",
                'variant': 'contained'
            },
            {
                "footer": "% of times the algorithm has predicted the relative position of "
                          "NY prices with respect to HK prices correctly",
                "header": "Accuracy",
                "val": "76.67%",
                "alignment": "left",
                "color": "success",
                'variant': 'contained'
            }
        ],
        [
            {
                "footer": "Return of investment",
                "header": "ROI",
                "val": "1.5M",
                "alignment": "left",
                "color": "success",
                'variant': 'contained'
            },
            {
                "footer": "% of times the algorithm has predicted the relative position of "
                          "NY prices with respect to HK prices correctly",
                "header": "Accuracy",
                "val": "76.67%",
                "alignment": "left",
                "color": "success",
                'variant': 'contained'
            },
            {
                "footer": "% of times the algorithm has predicted the relative position of "
                          "NY prices with respect to HK prices correctly",
                "header": "Accuracy",
                "val": "76.67%",
                "alignment": "left",
                "color": "success",
                'variant': 'contained'
            }
        ]
    ]

    s.plt.chart_and_indicators(
        menu_path=menu_path, order=0,
        chart_rows_size=3, cols_size=6,
        chart_function=s.plt.line,
        chart_parameters=dict(
            data=data,
            x='date',
            y='x',
            title='Line Chart With Indicators',
        ),
        indicators_groups=indicator_groups,
        indicators_parameters=dict(
            value='val',
            header='header',
            footer='footer',
            align='alignment',
            color='color',
        )
    )
    ```

    <figure><img src="https://3782181538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUlHTfmIZY46Z1EDfyGMz%2Fuploads%2FP0P1X5g4r4sppkp6o7KI%2Fimatge.png?alt=media&#x26;token=4576f2a9-43d0-4737-88d1-3dc731535a7e" alt=""><figcaption><p>Line chart with  4 groups of indicators</p></figcaption></figure>

  * This last composite chart uses the previous one to create a **group of indicators with a header**. In this case the function definition is just a call of the previous one:

    <pre class="language-python"><code class="lang-python">def indicators_with_header(
        self, menu_path: str, 
        order: int, 
    <strong>    # List of groups of indicators, each one of them will be used as the input
    </strong><strong>    # of an indicators function call
    </strong><strong>    indicators_groups: List[Union[pd.DataFrame, List[Dict]]],
    </strong><strong>    # The parameters that will be passed to the indicators calls
    </strong><strong>    indicators_parameters: Dict,
    </strong><strong>    # Header configuration
    </strong><strong>    title: str, 
    </strong><strong>    subtitle: str = '', 
    </strong><strong>    background_color: str = 'var(--color-primary)',
    </strong><strong>    text_color: str = 'var(--background-paper)',
    </strong><strong>    icon_url: str = 'https://uploads-ssl.webflow.com/619f9fe98661d321dc3beec7/63e3615716d4435d29e0b82c_Acurracy.svg', 
    </strong>    cols_size: int = 12,
        tabs_index: Optional[Tuple[str, str]] = None, 
        modal_name: Optional[str] = None,
    ) -> int:
        return chart_and_indicators(
            self=self,
            menu_path=menu_path, order=order,
            chart_rows_size=1, cols_size=cols_size,
            tabs_index=tabs_index, modal_name=modal_name,
            chart_function=self.html,
            chart_parameters=dict(
                html=create_h1_title_with_modal(
                    title=title, subtitle=subtitle, background_color=background_color,
                    text_color=text_color, icon_url=icon_url
                ),
                padding='0,0,0,0',
                cols_size=24,
            ),
            indicators_groups=indicators_groups,
            indicators_parameters=indicators_parameters
        )
    </code></pre>

    <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>Because it is using multiple indicators the function will return the next available order.</p></div>

    The next example shows how to use the function:

    ```python
    indicators_groups = [
        [
            {
                "footer": "Total of successes predictions",
                "header": "True",
                "val": "154",
                "alignment": "left",
                "color": "success"
            },
            {
                "footer": "Total of Failed predictions",
                "header": "False",
                "val": "22",
                "alignment": "left",
                "color": "error",
            },
            {
                "footer": "Return of investment",
                "header": "ROI",
                "val": "1.5M",
                "alignment": "left",
                "color": "",
            },
            {
                "footer": "% of times the algorithm has predicted the relative position of NY prices with respect to HK prices correctly",
                "header": "Accuracy",
                "val": "76.67%",
                "alignment": "left",
                "color": "success",
                "variant": "contained"
            }
        ]
    ]

    s.plt.indicators_with_header(
        menu_path='test', order=0,
        title='Accuracy', subtitle='Cross-listed trading suite',
        indicators_groups=indicators_groups,
        indicators_parameters=dict(
            value='val',
            header='header',
            footer='footer',
            align='alignment',
            color='color',
            variant='variant',
            padding='0,0,0,1',
            cols_size=24,
        )
    )
    ```

    <figure><img src="https://3782181538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUlHTfmIZY46Z1EDfyGMz%2Fuploads%2Fs3xUIhQIlVGpBly3mFBM%2Fimatge.png?alt=media&#x26;token=9113e9d3-784a-4900-897a-59a410b1a40b" alt=""><figcaption><p>Indicators with a header</p></figcaption></figure>

* ### New Free-echarts Based Charts

  Six new charts that use the `s.plt.free_echarts` method have bee added. Each one of them solves a concrete problem or group of problems important enough so that they have been included as library charts.

  * **Scatter with effect**: A scatter plot with a visual effect that highlights important points. This chart is useful for identifying patterns or trends in data and for emphasizing specific data points.

    To specify which points will have the effect the parameter `effect_points` must be used, it interprets each element of a list, if the elment is a list of two elements it will take that as coordinates and if the element is an integer it will take the coordinates of the point stored in the 'element' index from the source points (f.e. if element==1 the coordinates of the first point will be used).

    The input parameters are the following:

    <pre class="language-python"><code class="lang-python">def scatter_with_effect(
        self, data: Union[str, DataFrame, List[Dict]],
        menu_path: str, 
    <strong>    # Names of columns fields that will be used for each axis
    </strong><strong>    x: str = 'x', y: str = 'y', 
    </strong>    order: int, 
        rows_size: int = 3, cols_size: int = 12,
        padding: Optional[str] = None,
        title: Optional[str] = None,  # second layer
        x_axis_name: Optional[str] = None,
        y_axis_name: Optional[str] = None,
        option_modifications: Optional[Dict] = None,
        filters: Optional[Dict] = None,
        bentobox_data: Optional[Dict] = None,
        tabs_index: Optional[Tuple[str, str]] = None,
    <strong>    # The points in the plane that will have the effect activated
    </strong><strong>    effect_points: Optional[List] = None,
    </strong>):
    </code></pre>

    An example of use is:

    <pre class="language-python"><code class="lang-python">main_scatter_points = [
        [161.2, 51.6], [167.5, 59.0], [159.5, 49.2], [157.0, 63.0], [155.8, 53.6],
        [170.0, 59.0], [159.1, 47.6], [166.0, 69.8], [176.2, 66.8], [160.2, 75.2],
        [172.5, 55.2], [170.9, 54.2], [172.9, 62.5], [153.4, 42.0], [160.0, 50.0],
        [147.2, 49.8], [168.2, 49.2], [175.0, 73.2], [157.0, 47.8], [167.6, 68.8],
        [159.5, 50.6], [175.0, 82.5], [166.8, 57.2], [176.5, 87.8], [170.2, 72.8],
        [174.0, 54.5], [173.0, 59.8], [179.9, 67.3], [170.5, 67.8], [160.0, 47.0],
        [154.4, 46.2], [162.0, 55.0], [176.5, 83.0], [160.0, 54.4], [152.0, 45.8],
        [162.1, 53.6], [170.0, 73.2], [160.2, 52.1], [161.3, 67.9], [166.4, 56.6],
        [168.9, 62.3], [163.8, 58.5], [167.6, 54.5], [160.0, 50.2], [161.3, 60.3],
        [167.6, 58.3], [165.1, 56.2], [160.0, 50.2], [170.0, 72.9], [157.5, 59.8],
    ]

    dataFramed_scatter_points = [
        {'x': point[0], 'y': point[1] } for point in main_scatter_points
    ]

    s.plt.scatter_with_effect(
        data=dataFramed_scatter_points,
        menu_path=menu_path,
        order=0,
        x_axis_name='X axis',
        y_axis_name='Y axis',
        title='Scatter with effect',
    <strong>    effect_points=[1, 2, [172.7, 105.2], [153.4, 42]]
    </strong>)
    </code></pre>

    <figure><img src="https://3782181538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUlHTfmIZY46Z1EDfyGMz%2Fuploads%2FCXRgMCtrD81XwNIYcQ0b%2Fimatge.png?alt=media&#x26;token=cae60fe3-5d12-43be-a924-2bdf73e5deb9" alt=""><figcaption><p>Scatter with effect</p></figcaption></figure>

  * **Line and bar charts**: A combination of line and bar charts where the lines have one y-axis and the bar charts have another. This chart is useful for comparing two different sets of data that have different scales, such as sales revenue and customer satisfaction scores.

    Each axis has it's scale and it's axis name, both groups share the same space. The parameters of the function are:

    <pre class="language-python"><code class="lang-python">def line_and_bar_charts(self,
        data: Union[str, DataFrame, List[Dict]],
        menu_path: str, x: str = 'x', 
    <strong>    bar_names: Optional[List[str]] = None, 
    </strong><strong>    line_names: Optional[List[str]] = None,
    </strong>    order: Optional[int] = None, 
        rows_size: int = 3, cols_size: int = 12,
        padding: Optional[str] = None,
        title: Optional[str] = None,  # second layer
        x_axis_name: Optional[str] = None,
    <strong>    bar_axis_name: Optional[str] = None,
    </strong><strong>    line_axis_name: Optional[str] = None,
    </strong><strong>    bar_suffix: Optional[str] = None,
    </strong><strong>    line_suffix: Optional[str] = None,
    </strong>    option_modifications: Optional[Dict] = None,
        filters: Optional[Dict] = None,
        bentobox_data: Optional[Dict] = None,
        tabs_index: Optional[Tuple[str, str]] = None,
    ):
    </code></pre>

    An example on how to use the function is:

    ```python
    menu_path: str = 'Bar and line chart'

    data =  [
        {'day': 'Mon', 'Evaporation': 2.0, 'Precipitation': 2.6, 'Temperature': 2.0},
        {'day': 'Tue', 'Evaporation': 4.9, 'Precipitation': 5.9, 'Temperature': 2.2},
        {'day': 'Wed', 'Evaporation': 7.0, 'Precipitation': 9.0, 'Temperature': 3.3},
        {'day': 'Thu', 'Evaporation': 23.2, 'Precipitation': 26.4, 'Temperature': 4.5},
        {'day': 'Fri', 'Evaporation': 25.6, 'Precipitation': 28.7, 'Temperature': 6.3},
        {'day': 'Sat', 'Evaporation': 76.7, 'Precipitation': 70.7, 'Temperature': 10.2},
        {'day': 'Sun', 'Evaporation': 135.6, 'Precipitation': 175.6, 'Temperature': 20.3},
    ]

    s.plt.line_and_bar_charts(
        data=data, menu_path=menu_path, order=0,
        x='day', 
        bar_names=['Evaporation', 'Precipitation'], 
        line_names=['Temperature'],
        title='rainfall and temperature', 
        x_axis_name='Day', 
        line_axis_name='Temperature',
        line_suffix=' °C', 
        bar_axis_name='Evaporation and precipitacion', 
        bar_suffix=' ml',
    )
    ```

    <figure><img src="https://3782181538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUlHTfmIZY46Z1EDfyGMz%2Fuploads%2FBxY8GrE3POyMdfo43IFR%2Fimatge.png?alt=media&#x26;token=c6ae3989-4b37-4d9e-8eb1-e72fe3821611" alt=""><figcaption><p>Bar and line charts</p></figcaption></figure>

  * **Line with confidence area**: A line chart with a shaded area that represents a confidence interval around the line. This chart is useful for showing the range of possible values around a trend line and for indicating the level of confidence in the data.

    The dataframe will have to have three value fields (top line, value line and bottom\_line). The parameters of the function are:

    <pre class="language-python"><code class="lang-python">def line_with_confidence_area(
       data: Union[str, DataFrame, List[Dict]],
       menu_path: str, 
    <strong>   # Fields for the x axis and the values
    </strong><strong>   x: str = 'x', lower: str = 'l', y: str = 'y', upper: str = 'u',
    </strong>   order: Optional[int] = None, 
       rows_size: int = 3, cols_size: int = 12,
       padding: Optional[str] = None,
       title: Optional[str] = None,  # second layer
       x_axis_name: Optional[str] = None,
       y_axis_name: Optional[str] = None,
       option_modifications: Optional[Dict] = None,
       filters: Optional[Dict] = None,
       bentobox_data: Optional[Dict] = None,
       tabs_index: Optional[Tuple[str, str]] = None,
       percentages: bool = False,
    ):
    </code></pre>

    An example is:

    ```python
    menu_path = 'Line with confidence area'

    # Download the data
    res = requests.get(url='https://echarts.apache.org/examples/data/asset/data/confidence-band.json')

    # Convert it to json
    data = res.json()

    for dat in data:
        dat['value'] = dat['value'] * 100
        dat['l'] = dat['l'] * 100
        dat['u'] = dat['u'] * 100

    s.plt.line_with_confidence_area(
        data=data,
        menu_path=menu_path,
        order=0,
        title='Confidence Band Chart',
        x='date', y='value', lower='l', upper='u',
        x_axis_name='Date',
        y_axis_name='Value',
        percentages=True,
    )
    ```

    <figure><img src="https://3782181538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUlHTfmIZY46Z1EDfyGMz%2Fuploads%2FihwZ4PdSqWtyXE0HLVtA%2Fimatge.png?alt=media&#x26;token=e38be57a-b8a2-4fc6-9f69-2f5a184ece30" alt=""><figcaption><p>Line with confidence area</p></figcaption></figure>

  * **Waterfall**: A chart that shows how an initial value is affected by a series of positive and negative values. This chart is useful for illustrating changes in a value over time or for identifying the components that contribute to a change.

    The input dataframe has to contain a field for positive values and a field for negative values. The balance connecting the bars can be enabled by setting the parameter `show_balance` to `True`. The  parameters of the function are:

    <pre class="language-python"><code class="lang-python">def waterfall(
        data: Union[str, DataFrame, List[Dict]],
        menu_path: str, 
    <strong>    # Fields for the x axis and the values
    </strong><strong>    xAxis: str = 'x', positive: str = 'Income', negative: str = 'Expenses',
    </strong>    order: Optional[int] = None, 
        rows_size: Optional[int] = 3, cols_size: int = 12,
        padding: Optional[str] = None,
        title: Optional[str] = None,  # second layer
        x_axis_name: Optional[str] = None,
        y_axis_name: Optional[str] = None,
        option_modifications: Optional[Dict] = None,
        filters: Optional[Dict] = None,
        bentobox_data: Optional[Dict] = None,
        tabs_index: Optional[Tuple[str, str]] = None,
    <strong>    show_balance: Optional[bool] = False,
    </strong>):
    </code></pre>

    An example on how to use the function is:

    ```python
    menu_path = 'waterfall-test'

    data = [
        {'x': 'Nov 1', 'income': 900, 'expenses': 0},
        {'x': 'Nov 2', 'income': 345, 'expenses': 0},
        {'x': 'Nov 3', 'income': 393, 'expenses': 0},
        {'x': 'Nov 4', 'income': 0, 'expenses': 108},
        {'x': 'Nov 5', 'income': 0, 'expenses': 154},
        {'x': 'Nov 6', 'income': 135, 'expenses': 0},
        {'x': 'Nov 7', 'income': 178, 'expenses': 0},
        {'x': 'Nov 8', 'income': 286, 'expenses': 0},
        {'x': 'Nov 9', 'income': 0, 'expenses': 119},
        {'x': 'Nov 10', 'income': 0, 'expenses': 361},
        {'x': 'Nov 11', 'income': 0, 'expenses': 203},
        {'x': 'Nov 12', 'income': 450, 'expenses': 156},
        {'x': 'Nov 13', 'income': 45, 'expenses': 189},
        {'x': 'Nov 14', 'income': 0, 'expenses': 0},
        {'x': 'Nov 15', 'income': 122, 'expenses': 87},
        {'x': 'Nov 16', 'income': 65, 'expenses': 156},
        {'x': 'Nov 17', 'income': 336, 'expenses': 450},
        {'x': 'Nov 18', 'income': 560, 'expenses': 400},
        {'x': 'Nov 19', 'income': 1200, 'expenses': 1130},
        {'x': 'Nov 20', 'income': 3200, 'expenses': 3130},
        {'x': 'Nov 21', 'income': 100, 'expenses': 3000},
        {'x': 'Nov 22', 'income': 5000, 'expenses': 30},
    ]

    s.plt.waterfall(
        data=data,
        title='Waterfall with balance',
        menu_path=menu_path,
        positive='income',
        negative='expenses',
        show_balance=True,
        order=0,
    )
    ```

    <figure><img src="https://3782181538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUlHTfmIZY46Z1EDfyGMz%2Fuploads%2FLc24WEDJuPJwuyaXvhrx%2Fimatge.png?alt=media&#x26;token=84b6f0af-c64a-457d-859b-f1ad317b667e" alt=""><figcaption><p>Waterfall</p></figcaption></figure>

  * **Top bottom line charts**: Two groups of line charts that share an x-axis, with one group of charts above the x-axis and the other below. Each chart has a different y-axis. This chart is useful for comparing two sets of data that have different scales and for identifying patterns or trends in each set.

    Each axis has it's scale and its configuration options the parameters of the function are:

    <pre class="language-python"><code class="lang-python">def top_bottom_line_charts(self,
        data: Union[str, DataFrame, List[Dict]],
        menu_path: str, 
    <strong>    # Field for the x Axis
    </strong><strong>    x: str = 'x', 
    </strong><strong>    # Fields for the y Axes for the top chart
    </strong><strong>    top_names: List[str] = None, 
    </strong><strong>    # Fields for the y Axes for the bottom chart
    </strong><strong>    bottom_names: List[str] = None,
    </strong>    order: Optional[int] = None, rows_size: Optional[int] = 3, cols_size: int = 12,
        padding: Optional[str] = None,
        title: Optional[str] = None,  # second layer
        x_axis_name: Optional[str] = None,
    <strong>    top_axis_name: Optional[str] = None, 
    </strong><strong>    bottom_axis_name: Optional[str] = None,
    </strong>    option_modifications: Optional[Dict] = None,
        filters: Optional[Dict] = None,
        bentobox_data: Optional[Dict] = None,
        tabs_index: Optional[Tuple[str, str]] = None,
    ):
    </code></pre>

    An example, using the data found at the end of the page, is:

    ```python
    menu_path = 'top_bottom_line_charts'

    data = pd.read_csv('rainfall-area.csv')

    s.plt.top_bottom_line_charts(
        data=data, menu_path=menu_path, order=1,
        x='Date', top_names=['flow'], bottom_names=['rainfall'],
        title='rainfall and flow', 
        x_axis_name='Date', 
        top_axis_name='flow(m³/s)', bottom_axis_name='rainfall(mm)',
    )
    ```

    <figure><img src="https://3782181538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUlHTfmIZY46Z1EDfyGMz%2Fuploads%2FRjm0Ct8dFpy3VpmI5J8f%2Fimatge.png?alt=media&#x26;token=3a2e9b0b-6653-4d07-bf43-cbb567e74788" alt=""><figcaption><p>Top bottom line charts</p></figcaption></figure>

  * **Top bottom area charts**: Very similar to the previous chart but they have the area between the line and the axis painted and both chart groups share the same space.

    <figure><img src="https://3782181538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUlHTfmIZY46Z1EDfyGMz%2Fuploads%2FxU0X1MmYuYasAcWZ1ftm%2Fimatge.png?alt=media&#x26;token=d9b1c315-49cf-4907-85a4-c515a85646c1" alt=""><figcaption><p>Top bottom area charts</p></figcaption></figure>

{% file src="<https://3782181538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUlHTfmIZY46Z1EDfyGMz%2Fuploads%2FoHT4jrvwXbiKewHEI87M%2Frainfall-area.csv?alt=media&token=10fc8c04-907e-46c6-960f-55afe6dc8152>" %}