BUG: Inherit DEFAULT_PARAMS down the geom and stat class hierarchy

Subclasses now declare only the parameters that differ from their
parent, and the effective merged set is exposed as `default_params`.
This fixes geoms rejecting parameters that their parent geom
supports: geom_step now accepts lineend, linejoin and arrow,
geom_quantile accepts arrow, and geom_histogram accepts just and
width. geom_step also renders its corners with the documented
round joinstyle, hence the updated baseline images.

Author: has2k1

doc/changelog.qmd

@@ -66,14 +66,21 @@ title: Changelog
   layer(geom=geom_point())
   ```
 
-- `geom.DEFAULT_PARAMS` now implicitly includes `stat="identity"`, `position="identity`
-  and `na_rm=False`.
-
-- `stat.DEFAULT_PARAMS` now implicitly includes `geom="blank"`, `position="identity`
-  and `na_rm=False`.
+- `DEFAULT_PARAMS` declarations are now inherited down the class hierarchy;
+  a subclass geom or stat only declares the parameters that differ from its
+  parent. The base `geom` class declares `stat="identity"`,
+  `position="identity"` and `na_rm=False`, and the base `stat` class declares
+  `geom="blank"`, `position="identity"` and `na_rm=False`, so all geoms and
+  stats include them automatically.
 
 ### Bug Fixes
 
+- Subclass geoms now inherit their parent geom's default parameters, so
+  parameters that a parent geom supports are no longer rejected.
+  [](:class:`~plotnine.geom_step`) accepts `lineend`, `linejoin` and `arrow`,
+  [](:class:`~plotnine.geom_quantile`) accepts `arrow`, and
+  [](:class:`~plotnine.geom_histogram`) accepts `just` and `width`.
+
 - Fixed [](:class:`~plotnine.geom_smooth`) / [](:class:`~plotnine.stat_smooth`) when using a linear model via "lm" with weights for the model to do a weighted regression. This bug did not affect the formula API of the linear model. ({{< issue 1005 >}})
 
 - Fixed rendering of SVGs in jupyter notebooks.

plotnine/_utils/registry.py

@@ -8,7 +8,7 @@
 from ..exceptions import PlotnineError
 
 if TYPE_CHECKING:
-    from typing import TypeVar
+    from typing import Any, TypeVar
 
     T = TypeVar("T")
 
@@ -108,3 +108,28 @@ def __init__(cls, name, bases, namespace):
             for base in bases:
                 for base2 in base.mro()[:-2]:
                     cls._hierarchy[base2.__name__].append(name)
+
+
+class _MergedDefaultParams:
+    """
+    DEFAULT_PARAMS declarations merged down the class hierarchy
+
+    The merged result is cached per class and the cached dict is
+    shared, so consumers must only read it or combine it into a new
+    dict. Assumes single inheritance, which holds for all geoms &
+    stats (the only mixin is ABC on the root classes and it
+    contributes nothing).
+    """
+
+    def __get__(self, obj: Any, cls: type | None = None) -> dict[str, Any]:
+        if cls is None:
+            cls = type(obj)
+        # cls.__dict__ (not getattr) so a parent's cache is never inherited
+        if "_default_params" not in cls.__dict__:
+            declared = cls.__dict__.get("DEFAULT_PARAMS", {})
+            # The parent's view is fully merged: this getattr recurses
+            # through this same descriptor and caches along the way.
+            # Terminates at the root (ABC has no default_params).
+            inherited = getattr(cls.__mro__[1], "default_params", {})
+            cls._default_params = inherited | declared
+        return cls.__dict__["_default_params"]

plotnine/doctools.py

@@ -429,15 +429,13 @@ def document_geom(geom: type[geom]) -> type[geom]:
     It replaces `{usage}`, `{common_parameters}` and
     `{aesthetics}` with generated documentation.
     """
-    from plotnine.geoms.geom import _BASE_PARAMS
-
     docstring = dedent(geom.__doc__ or "")
     docstring = append_to_section(geom_kwargs, docstring, "Parameters")
 
     # usage
     signature = make_signature(
         geom.__name__,
-        _BASE_PARAMS | geom.DEFAULT_PARAMS,
+        geom.default_params,
         common_geom_params,
         common_geom_param_values,
     )
@@ -457,7 +455,7 @@ def document_geom(geom: type[geom]) -> type[geom]:
     aesthetics_doc = indent(aesthetics_doc, " " * 4)
 
     # common_parameters
-    d = geom.DEFAULT_PARAMS
+    d = geom.default_params
     common_parameters = GEOM_PARAMS_TPL.format(
         default_stat=default_class_name(d["stat"]),
         default_position=default_class_name(d["position"]),
@@ -481,8 +479,6 @@ def document_stat(stat: type[stat]) -> type[stat]:
     It replaces `{usage}`, `{common_parameters}` and
     `{aesthetics}` with generated documentation.
     """
-    from plotnine.stats.stat import _BASE_PARAMS
-
     # Dedented so that it lineups (in sphinx) with the part
     # generated parts when put together
     docstring = dedent(stat.__doc__ or "")
@@ -491,7 +487,7 @@ def document_stat(stat: type[stat]) -> type[stat]:
     # usage:
     signature = make_signature(
         stat.__name__,
-        _BASE_PARAMS | stat.DEFAULT_PARAMS,
+        stat.default_params,
         common_stat_params,
         common_stat_param_values,
     )
@@ -507,7 +503,7 @@ def document_stat(stat: type[stat]) -> type[stat]:
     aesthetics_doc = indent(aesthetics_doc, " " * 4)
 
     # common_parameters
-    d = stat.DEFAULT_PARAMS
+    d = stat.default_params
     common_parameters = STAT_PARAMS_TPL.format(
         default_geom=default_class_name(d["geom"]),
         default_position=default_class_name(d["position"]),

plotnine/geoms/geom.py

@@ -12,7 +12,7 @@
     data_mapping_as_kwargs,
     remove_missing,
 )
-from .._utils.registry import Register
+from .._utils.registry import Register, _MergedDefaultParams
 from ..exceptions import PlotnineError
 from ..layer import layer
 from ..mapping.aes import rename_aesthetics
@@ -33,13 +33,6 @@
     from plotnine.typing import DataLike
 
 
-_BASE_PARAMS: dict[str, Any] = {
-    "stat": "identity",
-    "position": "identity",
-    "na_rm": False,
-}
-
-
 class geom(ABC, metaclass=Register):
     """Base class of all Geoms"""
 
@@ -52,15 +45,27 @@ class geom(ABC, metaclass=Register):
     NON_MISSING_AES: set[str] = set()
     """Required aesthetics for the geom"""
 
-    DEFAULT_PARAMS: dict[str, Any] = {}
-    """Required parameters for the geom"""
+    DEFAULT_PARAMS: dict[str, Any] = {
+        "stat": "identity",
+        "position": "identity",
+        "na_rm": False,
+    }
+    """
+    Default values for the parameters that the geom accepts
+
+    A geom inherits the parameters of its parent geom; declare only
+    those that are new or have a different default value.
+    """
 
     data: DataLike
     """Geom/layer specific dataframe"""
 
     mapping: aes
     """Mappings i.e. `aes(x="col1", fill="col2")`{.py}"""
 
+    # All recognized parameters and their default values
+    default_params = _MergedDefaultParams()
+
     aes_params: dict[str, Any] = {}  # setting of aesthetic
     params: dict[str, Any]  # parameter settings
 
@@ -87,14 +92,15 @@ def __init__(
         kwargs = rename_aesthetics(kwargs)
         kwargs = data_mapping_as_kwargs((data, mapping), kwargs)
         self._raw_kwargs = kwargs  # Will be used to create stat & layer
+        overridden_params = self.default_params.keys() & kwargs.keys()
 
         # separate aesthetics and parameters
-        possible_params = _BASE_PARAMS | self.DEFAULT_PARAMS
         self.aes_params = {
             ae: kwargs[ae] for ae in self.aesthetics() & set(kwargs)
         }
-        self.params = possible_params | {
-            k: v for k, v in kwargs.items() if k in possible_params
+        self.params = {
+            **self.default_params,
+            **{k: kwargs[k] for k in overridden_params},
         }
         self.mapping = kwargs["mapping"]
         self.data = kwargs["data"]

plotnine/geoms/geom_bar.py

@@ -51,7 +51,7 @@ def setup_data(self, data: pd.DataFrame) -> pd.DataFrame:
             else:
                 data["width"] = resolution(data["x"], False) * 0.9
 
-        just = self.params.get("just", 0.5)
+        just = self.params["just"]
 
         bool_idx = data["y"] < 0
 

plotnine/geoms/geom_col.py

@@ -33,4 +33,4 @@ class geom_col(geom_bar):
 
     REQUIRED_AES = {"x", "y"}
     NON_MISSING_AES = {"xmin", "xmax", "ymin", "ymax"}
-    DEFAULT_PARAMS = {"position": "stack", "just": 0.5, "width": None}
+    DEFAULT_PARAMS = {"stat": "identity"}

plotnine/geoms/geom_density.py

@@ -25,4 +25,4 @@ class geom_density(geom_area):
         "weight": 1,
     }
 
-    DEFAULT_PARAMS = {"stat": "density", "outline_type": "upper"}
+    DEFAULT_PARAMS = {"stat": "density", "position": "identity"}

plotnine/geoms/geom_freqpoly.py

@@ -13,9 +13,4 @@ class geom_freqpoly(geom_path):
     of the parameters.
     """
 
-    DEFAULT_PARAMS = {
-        "stat": "bin",
-        "lineend": "butt",
-        "linejoin": "round",
-        "arrow": None,
-    }
+    DEFAULT_PARAMS = {"stat": "bin"}

plotnine/geoms/geom_histogram.py

@@ -18,4 +18,4 @@ class geom_histogram(geom_bar):
     plotnine.geom_bar : The default `stat` for this `geom`.
     """
 
-    DEFAULT_PARAMS = {"stat": "bin", "position": "stack"}
+    DEFAULT_PARAMS = {"stat": "bin"}

plotnine/geoms/geom_label.py

@@ -61,7 +61,6 @@ class geom_label(geom_text):
 
     DEFAULT_AES = {**geom_text.DEFAULT_AES, "fill": "white"}
     DEFAULT_PARAMS = {
-        **geom_text.DEFAULT_PARAMS,
         # boxstyle is one of
         #   circle, larrow, rarrow, round, round4,
         #   roundtooth, sawtooth, square