Merge branch 'dev/add-initial-version'

Dockerfile

@@ -0,0 +1,18 @@
+# read the doc: https://huggingface.co/docs/hub/spaces-sdks-docker
+# you will also find guides on how best to write your Dockerfile
+
+FROM python:3.9
+
+RUN useradd -m -u 1000 user
+
+WORKDIR /app
+
+COPY --chown=user ./requirements.txt requirements.txt
+
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+
+COPY --chown=user . /app
+
+EXPOSE 7860
+
+CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:7860", "app:server"]

LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 FT Interactive News
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,11 +1,103 @@
----
-title: Demo Visual Vocabulary
-emoji: 🌖
-colorFrom: indigo
-colorTo: indigo
-sdk: docker
-pinned: false
-license: apache-2.0
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Vizro - Visual vocabulary
+
+This dashboard shows a gallery of charts. It includes guidance on when to use each chart type and sample Python code
+to create them using [Plotly](https://plotly.com/python/) and [Vizro](https://github.com/mckinsey/vizro).
+
+**Created by:**
+
+- [Huong Li Nguyen](https://github.com/huong-li-nguyen) and [Antony Milne](https://github.com/antonymilne)
+
+- Images created by QuantumBlack
+
+**Inspired by:**
+
+- [The FT Visual Vocabulary](https://github.com/Financial-Times/chart-doctor/blob/main/visual-vocabulary/README.md): Alan Smith, Chris Campbell, Ian Bott, Liz Faunce, Graham Parrish, Billy Ehrenberg, Paul McCallum,
+  Martin Stabe.
+
+- [The Graphic Continuum](https://www.informationisbeautifulawards.com/showcase/611-the-graphic-continuum): Jon Swabish and Severino Ribecca
+
+**Credits, tutorials and resources:**
+
+- [Plotly](https://plotly.com/python/plotly-express/)
+- [Guide to data chart mastery](https://www.atlassian.com/data/charts)
+
+## Chart types
+
+The dashboard is still in development. Below is an overview of the chart types for which a completed page is available.
+
+| Chart Type            | Status | Category                 |
+| --------------------- | ------ | ------------------------ |
+| Arc                   | ❌     | Part-to-whole            |
+| Area                  | ✅     | Time                     |
+| Bar                   | ✅     | Magnitude                |
+| Barcode               | ❌     | Distribution             |
+| Beeswarm              | ❌     | Distribution             |
+| Boxplot               | ✅     | Distribution             |
+| Bubble                | ✅     | Correlation              |
+| Bubble map            | ❌     | Spatial                  |
+| Bubble timeline       | ❌     | Time                     |
+| Bullet                | ❌     | Magnitude                |
+| Bump                  | ❌     | Ranking                  |
+| Butterfly             | ✅     | Deviation, Distribution  |
+| Chord                 | ❌     | Flow                     |
+| Choropleth            | ✅     | Spatial                  |
+| Column                | ✅     | Magnitude, Time          |
+| Column and line       | ✅     | Correlation, Time        |
+| Connected scatter     | ✅     | Correlation, Time        |
+| Cumulative curve      | ❌     | Distribution             |
+| Diverging bar         | ❌     | Deviation                |
+| Diverging stacked bar | ❌     | Deviation                |
+| Donut                 | ✅     | Part-to-whole            |
+| Dot map               | ❌     | Spatial                  |
+| Dot plot              | ❌     | Distribution             |
+| Fan                   | ❌     | Time                     |
+| Flow map              | ❌     | Spatial                  |
+| Funnel                | ✅     | Part-to-whole            |
+| Gantt                 | ❌     | Time                     |
+| Gridplot              | ❌     | Part-to-whole            |
+| Heatmap               | ✅     | Time                     |
+| Heatmap matrix        | ❌     | Correlation              |
+| Histogram             | ✅     | Distribution             |
+| Line                  | ✅     | Time                     |
+| Lollipop              | ❌     | Ranking, Magnitude       |
+| Marimekko             | ❌     | Magnitude, Part-to-whole |
+| Network               | ❌     | Flow                     |
+| Ordered bar           | ✅     | Ranking                  |
+| Ordered bubble        | ❌     | Ranking                  |
+| Ordered column        | ✅     | Ranking                  |
+| Paired bar            | ✅     | Magnitude                |
+| Paired column         | ✅     | Magnitude                |
+| Parallel coordinates  | ✅     | Magnitude                |
+| Pictogram             | ❌     | Magnitude                |
+| Pie                   | ✅     | Part-to-whole            |
+| Radar                 | ❌     | Magnitude                |
+| Radial                | ❌     | Magnitude                |
+| Sankey                | ✅     | Flow                     |
+| Scatter               | ✅     | Correlation              |
+| Scatter matrix        | ✅     | Correlation              |
+| Slope                 | ❌     | Ranking, Time            |
+| Sparkline             | ❌     | Time                     |
+| Stacked bar           | ✅     | Part-to-whole            |
+| Stacked column        | ✅     | Part-to-whole            |
+| Stepped line          | ✅     | Time                     |
+| Surplus deficit line  | ❌     | Deviation                |
+| Treemap               | ✅     | Part-to-whole            |
+| Venn                  | ❌     | Part-to-whole            |
+| Violin                | ✅     | Distribution             |
+| Waterfall             | ❌     | Part-to-whole, Flow      |
+
+To contribute a chart, follow the steps below:
+
+1. Place an `svg` file named after the chart type in the `assets` folder if it doesn't already exist.
+2. Add the data set to `_pages_utils.py` if it doesn't already exist.
+3. Create a new page for the chart type and add it to the relevant category `.py` file such as `correlation.py`,
+   `deviation.py`, `distribution.py`, etc.
+4. Add a `.py` file containing a code example of the chart type in the `pages/examples` folder, for instance, `area.py`
+5. Remove the `IncompletePage(..)` entry for that chart type in `chart_groups.py`.
+6. Update this `README.md` with the new chart type.
+
+## How to run the example locally
+
+1. If you have `hatch` set up, run the example with the command `hatch run example _visual-vocabulary`.
+   Otherwise, with a virtual Python environment activated, run `pip install -r requirements.txt` and then `python app.py`.
+2. You should now be able to access the app locally via http://127.0.0.1:8050/.

app.py

@@ -0,0 +1,111 @@
+"""App configuration for dashboard."""
+
+from typing import List, Union
+
+import vizro.models as vm
+from chart_groups import ALL_CHART_GROUP, CHART_GROUPS, ChartGroup, IncompletePage
+from custom_components import FlexContainer, Markdown
+from vizro import Vizro
+
+
+def make_chart_card(page: Union[vm.Page, IncompletePage]) -> vm.Card:
+    """Makes a card with svg icon, linked to the right page if page is complete.
+
+    Args:
+        page: page to make card for
+
+    Returns: card with svg icon, linked to the right page if page is complete.
+
+    """
+    # There's one SVG per chart title, so that e.g. pages distribution-butterfly and deviation-butterfly, which both
+    # have title "Butterfly", correspond to butterfly.svg.
+    # Incomplete pages have page.path = "" so won't be linked to here.
+    svg_name = page.title.lower().replace(" ", "-")
+    return vm.Card(
+        text=f"""
+           ![](assets/images/charts/{svg_name}.svg#chart-icon)
+
+           #### {page.title}
+           """,
+        href=page.path,
+    )
+
+
+def make_homepage_container(chart_group: ChartGroup) -> vm.Container:
+    """Makes a container with cards for each completed and incomplete chart in chart_group.
+
+    Args:
+        chart_group: group of charts to make container for.
+
+    Returns: container with cards for each chart in chart_group.
+
+    """
+    # Pages are sorted in title's alphabetical order and deduplicated so that e.g. pages distribution-butterfly and
+    # deviation-butterfly, which both have title "Butterfly", correspond to a single card.
+    return vm.Container(
+        title=chart_group.name,
+        layout=vm.Layout(grid=[[0, 1, 1]], col_gap="40px"),
+        components=[
+            Markdown(text=chart_group.intro_text, classname="intro-text"),
+            FlexContainer(
+                components=[
+                    make_chart_card(page)
+                    for page in sorted(
+                        _remove_duplicates(chart_group.pages + chart_group.incomplete_pages),
+                        key=lambda page: page.title,
+                    )
+                ],
+            ),
+        ],
+    )
+
+
+def _remove_duplicates(pages: List[Union[vm.Page, IncompletePage]]) -> List[Union[vm.Page, IncompletePage]]:
+    # Deduplicate pages that have the same title. Using reversed means that the page that is kept is the first one
+    # in the dashboard. This will be the one that the card on the homepage links to.
+    return list({page.title: page for page in reversed(pages)}.values())
+
+
+def make_navlink(chart_group: ChartGroup) -> vm.NavLink:
+    """Makes a navlink with icon and links to every complete page within chart_group.
+
+    Args:
+        chart_group: chart_group to make a navlink for.
+
+    Returns: navlink for chart_group.
+
+    """
+    # Pages are sorted in alphabetical order within each chart group.
+    return vm.NavLink(
+        label=chart_group.name,
+        pages={chart_group.name: [page.id for page in sorted(chart_group.pages, key=lambda page: page.title)]},
+        icon=chart_group.icon,
+    )
+
+
+homepage = vm.Page(
+    title="Overview",
+    components=[
+        vm.Tabs(tabs=[make_homepage_container(chart_group) for chart_group in [ALL_CHART_GROUP, *CHART_GROUPS]]),
+    ],
+)
+
+# TODO: consider whether each chart group should have its own individual homepage,
+# e.g. at http://localhost:8050/deviation/. This could just repeat the content of the tab from the homepage and would
+# work nicely with the hierarchical navigation.
+dashboard = vm.Dashboard(
+    # ALL_CHART_GROUP.pages has duplicated pages, e.g. both distribution-butterfly and deviation-butterfly.
+    title="Vizro - Visual Vocabulary",
+    pages=[homepage, *ALL_CHART_GROUP.pages],
+    navigation=vm.Navigation(
+        nav_selector=vm.NavBar(
+            items=[
+                vm.NavLink(label="Overview", pages=[homepage.id], icon="Home"),
+            ]
+            + [make_navlink(chart_group) for chart_group in CHART_GROUPS]
+        )
+    ),
+)
+
+if __name__ == "__main__":
+    Vizro().build(dashboard).run()

assets/css/custom.css

@@ -0,0 +1,71 @@
+#page-header {
+  padding-left: 8px;
+}
+
+#left-main {
+  width: 288px;
+}
+
+img[src*="#chart-icon"] {
+  width: 100%;
+}
+
+.code-clipboard {
+  font-size: 20px;
+  position: absolute;
+  right: 14px;
+  top: 12px;
+}
+
+.code-clipboard-container {
+  background: var(--surfaces-bg-card);
+  font-family: monospace;
+  max-height: 500px;
+  overflow: auto;
+  padding: 1rem;
+  position: relative;
+}
+
+.code-clipboard-container::-webkit-scrollbar-thumb {
+  border-color: var(--surfaces-bg-card);
+}
+
+.flex-container {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 24px;
+  justify-content: flex-start;
+}
+
+.flex-container h4 {
+  color: var(--text-secondary);
+  margin: 0;
+  padding-top: 12px;
+  text-align: center;
+}
+
+.flex-container .card {
+  height: 232px;
+  margin: 0 0 auto;
+  opacity: 0.3;
+  width: 176px;
+}
+
+.flex-container .card-nav {
+  opacity: 1;
+}
+
+.flex-container .card img {
+  width: 100%;
+}
+
+.intro-text {
+  border-left: 4px solid var(--text-secondary);
+  padding: 4px 12px;
+}
+
+.intro-text p {
+  font-size: 16px;
+  line-height: 20px;
+  margin: 0;
+}