Fix #820 : Add expand_limits

future_changes.md

@@ -3,6 +3,10 @@
 ### Added
                  
 - `geom_blank()` [[#831](https://github.com/JetBrains/lets-plot/issues/831)].
+- `expand_limits()` [[#820](https://github.com/JetBrains/lets-plot/issues/820)].
+
+  See [example notebook](https://nbviewer.org/github/JetBrains/lets-plot/blob/master/docs/f-24g/expand_limits.ipynb).
+
 - `base` parameter in `waterfall_plot()` [[#1159](https://github.com/JetBrains/lets-plot/issues/1159)]:
 
   See [example notebook](https://nbviewer.org/github/JetBrains/lets-plot/blob/master/docs/f-24g/waterfall_plot_base.ipynb).

plot-builder/src/commonMain/kotlin/org/jetbrains/letsPlot/core/plot/builder/VarBinding.kt

@@ -25,6 +25,9 @@ class VarBinding(
         //  Generally, we can't use VarBinding as a key in a hashmap.
         //  As result, PlotConfigUtil.associateVarBindingsWithData() fails when building Map<VarBinding, DataFrame>
         //  because several (..count.. -> color) bindings become 1 entry in the map.
+        //
+        //  See commit: https://github.com/JetBrains/lets-plot/commit/e492dac808ec4fc12be13337f782f358044f19ec#diff-c6bd11010baad2b31ea05c0a3482f76ebb8f6bac1e3d8303cb6ed3ad28cb04adR16
+        //
         if (variable != other.variable) return false
         if (aes != other.aes) return false
 

plot-stem/src/commonMain/kotlin/org/jetbrains/letsPlot/core/spec/PlotConfigUtil.kt

@@ -149,17 +149,20 @@ internal object PlotConfigUtil {
     }
 
     internal fun defaultScaleName(aes: Aes<*>, variablesByMappedAes: Map<Aes<*>, List<DataFrame.Variable>>): String {
-        return if (variablesByMappedAes.containsKey(aes)) {
-            val variables = variablesByMappedAes.getValue(aes)
-            val labels = variables.map(DataFrame.Variable::label).distinct()
-            if (labels.size > 1 && (aes == Aes.X || aes == Aes.Y)) {
-                // Don't show multiple labels on X,Y axis.
-                aes.name
-            } else {
-                labels.joinToString()
-            }
-        } else {
+        val variables = variablesByMappedAes[aes] ?: emptyList()
+        val labels = variables.map(DataFrame.Variable::label)
+            .distinct()
+            // Give preference to more descriptive labels.
+            // This also prevents overriding axis/legend title by the `expand_limits()` function.
+            .filter { it != aes.name }
+
+        return if (labels.isEmpty()) {
             aes.name
+        } else if (labels.size > 1 && (aes == Aes.X || aes == Aes.Y)) {
+            // Don't show multiple labels on X,Y axis.
+            aes.name
+        } else {
+            labels.joinToString()
         }
     }
 

python-package/lets_plot/plot/__init__.py

@@ -5,6 +5,7 @@
 from .annotation import *
 from .coord import *
 from .core import *
+from .expand_limits_ import *
 from .facet import *
 from .font_features import *
 from .geom import *
@@ -56,5 +57,6 @@
            marginal_layer.__all__ +
            font_features.__all__ +
            gggrid_.__all__ +
-           ggtb_.__all__
+           ggtb_.__all__ +
+           expand_limits_.__all__
            )

python-package/lets_plot/plot/expand_limits_.py

@@ -0,0 +1,48 @@
+#  Copyright (c) 2024. JetBrains s.r.o.
+#  Use of this source code is governed by the MIT license that can be found in the LICENSE file.
+from .core import aes
+from .geom import geom_blank
+
+__all__ = ['expand_limits']
+
+def expand_limits(*, x=None, y=None, size=None, color=None, fill=None, alpha=None, shape=None):
+    """
+    Expand the plot limits to include additional data values.
+
+    This function extends the plot boundaries to encompass new data points,
+    whether a single value or multiple values are provided. It acts as a
+    thin wrapper around geom_blank().
+
+    Parameters
+    ----------
+    x, y, size, color, fill, alpha, shape : Any, list, tuple or range
+        List of name-value pairs specifying the value (or values) that should be included in each scale.
+        These parameters extend the corresponding plot dimensions or aesthetic scales.
+
+    Returns
+    -------
+    FeatureSpec
+        A result of the `geom_blank()` call.
+
+    Examples
+    --------
+
+    """
+    params = locals()
+
+    def standardize(value):
+        if value is None:
+            return [None]
+        elif isinstance(value, (list, tuple, range)):
+            return list(value)
+        else:
+            return [value]
+
+    standardized = {k: standardize(v) for k, v in params.items()}
+
+    max_length = max(len(v) for v in standardized.values())
+    raw_data = {k: v + [None] * (max_length - len(v)) for k, v in standardized.items()}
+
+    # remove all undefined but keep x and y even if undefined.
+    filtered_data = {k: v for k, v in raw_data.items() if k in ['x', 'y'] or not all(e is None for e in v)}
+    return geom_blank(mapping=aes(**filtered_data))

python-package/lets_plot/plot/label.py

@@ -82,12 +82,12 @@ def xlab(label):
 
 def ylab(label):
     """
-    Add label to the y axis.
+    Add label to the y-axis.
 
     Parameters
     ----------
     label : str
-        The text for the y axis label.
+        The text for the y-axis label.
 
     Returns
     -------