Merge pull request #497 from palewire/main

feat(scatter): add color column and category customization support

Author: palewire

datawrapper/charts/scatter.py

@@ -15,7 +15,7 @@
     ScatterSize,
 )
 from .models import AnnotationsMixin
-from .serializers import PlotHeight
+from .serializers import ColorCategory, PlotHeight
 
 
 class ScatterPlot(AnnotationsMixin, BaseChart):
@@ -198,6 +198,41 @@ class ScatterPlot(AnnotationsMixin, BaseChart):
         description="Whether to show the color key",
     )
 
+    #: The column with the color for the points
+    color_column: str = Field(
+        default="",
+        alias="color-column",
+        description="The column with the color for the points",
+    )
+
+    #: A mapping of layer names to colors
+    color_category: dict[str, str] = Field(
+        default_factory=dict,
+        alias="color-category",
+        description="A mapping of layer names to colors",
+    )
+
+    #: Dictionary mapping category names to their display labels in the color legend
+    category_labels: dict[str, str] = Field(
+        default_factory=dict,
+        alias="category-labels",
+        description="Dictionary mapping category names to their display labels in the color legend",
+    )
+
+    #: List defining the order in which categories appear in the chart and legend
+    category_order: list[str] = Field(
+        default_factory=list,
+        alias="category-order",
+        description="List defining the order in which categories appear in the chart and legend",
+    )
+
+    #: A list of columns to exclude from the color key
+    exclude_from_color_key: list[str] = Field(
+        default_factory=list,
+        alias="exclude-from-color-key",
+        description="A list of columns to exclude from the color key",
+    )
+
     #
     # Size
     #
@@ -498,6 +533,8 @@ def serialize_model(self) -> dict:
             axes["shape"] = self.shape_column
         if self.label_column:
             axes["labels"] = self.label_column
+        if self.color_column:
+            axes["color"] = self.color_column
 
         # Add axes to metadata
         model["metadata"]["axes"] = axes
@@ -529,6 +566,13 @@ def serialize_model(self) -> dict:
                 "outlines": self.outlines,
                 "color-outline": self.color_outline,
                 "show-color-key": self.show_color_key,
+                "color-category": ColorCategory.serialize(
+                    self.color_category,
+                    self.category_labels,
+                    self.category_order,
+                    self.exclude_from_color_key,
+                ),
+                "color-by-column": bool(self.color_category),
                 # Size
                 "size": self.size,
                 "fixed-size": self.fixed_size,
@@ -604,6 +648,8 @@ def deserialize_model(cls, api_response: dict[str, Any]) -> dict[str, Any]:
         init_data["size_column"] = axes.get("size")
         init_data["shape_column"] = axes.get("shape")
         init_data["label_column"] = axes.get("labels")
+        if "color" in axes:
+            init_data["color_column"] = axes["color"]
 
         # Parse x-axis
         x_axis = visualize.get("x-axis", {})
@@ -653,6 +699,9 @@ def deserialize_model(cls, api_response: dict[str, Any]) -> dict[str, Any]:
         if "show-color-key" in visualize:
             init_data["show_color_key"] = visualize["show-color-key"]
 
+        # Parse color-category using utility
+        init_data.update(ColorCategory.deserialize(visualize.get("color-category")))
+
         # Size
         if "size" in visualize:
             init_data["size"] = visualize["size"]

docs/user-guide/charts/multiple-column-charts.md

@@ -174,14 +174,44 @@ chart.create()
 
 ## Reference
 
+### MultipleColumnChart
+
 ```{eval-rst}
 .. parameter-table:: datawrapper.charts.MultipleColumnChart
 ```
 
+### MultipleColumnTextAnnotation
+
 ```{eval-rst}
 .. parameter-table:: datawrapper.charts.MultipleColumnTextAnnotation
 ```
 
+### MultipleColumnRangeAnnotation
+
 ```{eval-rst}
 .. parameter-table:: datawrapper.charts.MultipleColumnRangeAnnotation
 ```
+
+### MultipleColumnXRangeAnnotation
+
+```{eval-rst}
+.. parameter-table:: datawrapper.charts.MultipleColumnXRangeAnnotation
+```
+
+### MultipleColumnYRangeAnnotation
+
+```{eval-rst}
+.. parameter-table:: datawrapper.charts.MultipleColumnYRangeAnnotation
+```
+
+### MultipleColumnXLineAnnotation
+
+```{eval-rst}
+.. parameter-table:: datawrapper.charts.MultipleColumnXLineAnnotation
+```
+
+### MultipleColumnYLineAnnotation
+
+```{eval-rst}
+.. parameter-table:: datawrapper.charts.MultipleColumnYLineAnnotation
+```