Docs for 4.7.4 (#256)

* Docs: Add aesthetics.html page.

* Docs: Add us_unemployment.ipynb notebook to the Gallery.

* Docs: Add links to the new cookbooks.

* Docs: Mention annotations on the formats.html page.

* Docs: Move explanation of the color and fill from KDoc to the documentation site.

* Docs: Small fix on the aesthetics.html page.

* Docs: Move explanation of the point shape and linetype from KDoc to the documentation site.

* Docs: Move explanation of the font family and font face from KDoc to the documentation site.

* Docs: Small fix.

* Docs: Updates for layerKey() function.

* Docs: Fix KDoc for the geomImshow() function.

* Docs: Update the library version to 4.7.4.

* Docs: Add band to the Charts page.

* Docs: Fix links to the cookbooks about legend.

* Docs: Add link to the manual_legend.ipynb cookbook.

Writerside/lpk.tree

@@ -11,6 +11,7 @@
     <toc-element topic="gallery.md"/>
     <toc-element topic="charts.md"/>
     <toc-element toc-title="Key Features">
+        <toc-element topic="aesthetics.md"/>
         <toc-element topic="as_discrete.md"/>
         <toc-element topic="multiplot.md"/>
         <toc-element topic="bistro.md"/>

Writerside/topics/aesthetics.md

@@ -0,0 +1,55 @@
+# Aesthetics
+
+## Color and Fill
+
+Colors and fills of geometries can be specified in the following ways:
+
+- RGB/RGBA (e.g. `"rgb(0, 0, 255)"`).
+
+- HEX (e.g. `"#0000ff"`).
+
+- A name, one of:
+
+  ![Color names](aesthetics_color.png)
+
+- A system color name, one of:
+
+<list columns="3">
+    <li>
+        <img alt="Color 'pen'" src="aesthetics_color_pen.png"/>
+    </li>
+    <li>
+        <img alt="Color 'brush'" src="aesthetics_color_brush.png"/>
+    </li>
+    <li>
+        <img alt="Color 'paper'" src="aesthetics_color_paper.png"/>
+    </li>
+</list>
+
+- An instance of the `java.awt.Color` class.
+
+## Point Shapes
+
+![Point shapes](aesthetics_shape.png)
+
+## Line Types
+
+![Line types](aesthetics_linetype.png)
+
+## Text
+
+### Font Family
+
+Universal font names:
+
+![Font families](aesthetics_font_family.png)
+
+The default font family is `'sans'`.
+
+You can also use the name of any other font installed on your system (e.g. `"Times New Roman"`).
+
+### Font Face
+
+![Font faces](aesthetics_font_face.png)
+
+The default font face is `'plain'`.

Writerside/topics/bistro.md

@@ -38,4 +38,13 @@ See: [Joint plot](%nb-joint_plot%)
 
 <img src="residual_plot.png" alt="Residual plot" width="480"/>
 
-See: [Residual plot](%nb-residual_plot%)
+See: [Residual plot](%nb-residual_plot%)
+
+
+## Waterfall Plot
+
+[`waterfallPlot`](%api_bistro%.residual/waterfall-plot.html) - function that produces a waterfall plot showing the cumulative effect of sequentially introduced values.
+
+<img src="waterfall_plot.png" alt="Waterfall plot" width="480"/>
+
+See: [Waterfall plot](%nb-waterfall_plot%)

Writerside/topics/charts.md

@@ -29,6 +29,7 @@ Lines:
 
 Areas:
 [`area`](%api_geom%/geom-area/index.html),
+[`band`](%api_geom%/geom-band/index.html),
 [`ribbon`](%api_geom%/geom-ribbon/index.html)
 
 Polygons:
@@ -111,6 +112,7 @@ Examples:
 - [Violin plot](%nb-geom_violin%)
 - [Ridgeline plot](%nb-ridgeline_plot%)
 - [The `orientation` parameter](%nb-y_orientation%)
+- [Parameter `threshold` in `geomHistogram()`](%nb-geom_histogram_threshold%)
 
 
 ## Stats

Writerside/topics/formats.md

@@ -119,9 +119,10 @@ The number format can be used in a template to create a string with variable sub
 The string template contains “replacement fields” surrounded by curly braces `{}`.
 Anything that is not contained in braces is considered literal text, which is copied unchanged to the result string.
 If you need to include a brace character in the literal text, it can be escaped by doubling: {{ and }}.
-This approach is used in function `layerTooltips()` to customize the content of tooltips.
+This approach is used in functions [`layerTooltips()`](%api_tooltips%/layer-tooltips/index.html) and [`layerLabels()`](%api_annotations%/layer-labels/index.html)
+to customize the content of tooltips and annotations.
 
-See: [Tooltip Customization in Lets-Plot](tooltips.md).
+See: [Tooltip Customization in Lets-Plot](tooltips.md) and [Annotating Charts in Lets-Plot](annotations.md).
 
 ## Date and Time Format
 
@@ -216,6 +217,10 @@ letsPlot() +
 
 You can format text in tooltips, see: [Tooltip Customization](tooltips.md).
 
+## Annotating Charts
+
+You can format text in annotations, see: [Annotating Charts](annotations.md).
+
 ## Demo Notebooks
 
 - [Formatting labels on plots](%nb-formatting_axes_etc%)

Writerside/topics/gallery.md

@@ -1,6 +1,11 @@
 # Gallery
 
 <list columns="3">
+    <li>
+        <a href="%nb-us_unemployment%">
+            <img alt="Unemployment in the US since 1967" src="square-us_unemployment.png"/>
+        </a>
+    </li>
     <li>
         <a href="%nb-pushkin%">
             <img alt="Pushkin as a traveller" src="square-pushkin.png"/>

Writerside/topics/misc.md

@@ -1,5 +1,15 @@
 # Miscellaneous
 
+## Manual Legend
+
+In Lets-Plot, as in ggplot2, legends are automatically generated based on the aesthetic mappings in the plot.
+Sometimes, however, this automatic generation doesn't provide the precise control needed for complex visualizations.
+Parameter `manualKey` and aesthetic parameters of the [`guideLegend()`](%api_scale%/guide-legend.html) function addresses this limitation.
+
+See: [manual_legend.ipynb](%nb-manual_legend%)
+
+<img src="manual_legend.png" alt="Custom Legend with manualKey Option" width="480"/>
+
 ## Multiple Color Scales
 
 Use `colorBy`/`fillBy` parameters and `paint_a`/`paint_b`/`paint_c` aesthetics if you need to display two different layers with the same color aesthetic but different color scales.

Writerside/topics/presentation_options.md

@@ -54,8 +54,7 @@
 - [Plot title, subtitle and caption](%nb-title_subtitle_caption%)
 - [Theme colors for geometries](%nb-geom_theme_colors%)
 - [Theme flavors](%nb-theme_flavors%)
-- [Legend and axis](%nb-legend_and_axis%)
-- [Multiple lines for legend text](%nb-legend_text_multiline%)
+- [Customizing the Legend](%nb-legend%)
 - [Tooltip customization](%nb-tooltip_config%)
 - [Set font faces](%nb-set_font_faces%)
 - [Set font size and family](%nb-font_size_and_family%)

Writerside/v.list

@@ -1,13 +1,15 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE vars SYSTEM "https://resources.jetbrains.com/writerside/1.0/vars.dtd">
 <vars>
-    <var name="version" value="4.7.3"/>
+    <var name="version" value="4.7.4"/>
     <var name="current_year" value="2024"/>
     <var name="web_root" value="https://lets-plot.org"/>
 
     <!-- API -->
     <var name="api_reference" value="%web_root%/kotlin/api-reference"/>
     <var name="api_lets_plot" value="%api_reference%/-lets--plot--kotlin/org.jetbrains.letsPlot"/>
+    <var name="api_annotations" value="%api_reference%/-lets--plot--kotlin/org.jetbrains.letsPlot.annotations"/>
+    <var name="api_bistro" value="%api_reference%/-lets--plot--kotlin/org.jetbrains.letsPlot.bistro"/>
     <var name="api_coord" value="%api_reference%/-lets--plot--kotlin/org.jetbrains.letsPlot.coord"/>
     <var name="api_export" value="%api_reference%/-lets--plot--kotlin/org.jetbrains.letsPlot.export"/>
     <var name="api_geom" value="%api_reference%/-lets--plot--kotlin/org.jetbrains.letsPlot.geom"/>
@@ -18,7 +20,7 @@
     <var name="api_spatial" value="%api_reference%/-lets--plot--kotlin/org.jetbrains.letsPlot.spatial"/>
     <var name="api_stat" value="%api_reference%/-lets--plot--kotlin/org.jetbrains.letsPlot.stat"/>
     <var name="api_theme" value="%api_reference%/-lets--plot--kotlin/org.jetbrains.letsPlot.themes"/>
-    <var name="api_bistro" value="%api_reference%/-lets--plot--kotlin/org.jetbrains.letsPlot.bistro"/>
+    <var name="api_tooltips" value="%api_reference%/-lets--plot--kotlin/org.jetbrains.letsPlot.tooltips"/>
 
     <!-- NOTEBOOKS -->
     <var name="nbviewer_examples" value="https://nbviewer.org/github/JetBrains/lets-plot-docs/blob/master/source/kotlin_examples"/>
@@ -33,6 +35,7 @@
     <var name="nb-palmer_penguins" value="%nbviewer_demo%/palmer_penguins.ipynb"/>
     <var name="nb-pushkin" value="%nbviewer_demo%/pushkin.ipynb"/>
     <var name="nb-spatialdataset_kotlin_isl" value="%nbviewer_demo%/spatialdataset_kotlin_isl.ipynb"/>
+    <var name="nb-us_unemployment" value="%nbviewer_demo%/us_unemployment.ipynb"/>
     <var name="nb-wind_rose" value="%nbviewer_demo%/wind_rose.ipynb"/>
     <!-- Cookbooks -->
     <var name="nb-aes_size_color_variadic_lines" value="%nbviewer_cookbook%/aes_size_color_variadic_lines.ipynb"/>
@@ -63,6 +66,7 @@
     <var name="nb-geom_curve" value="%nbviewer_cookbook%/geom_curve.ipynb"/>
     <var name="nb-geom_dotplot" value="%nbviewer_cookbook%/geom_dotplot.ipynb"/>
     <var name="nb-geom_function" value="%nbviewer_cookbook%/geom_function.ipynb"/>
+    <var name="nb-geom_histogram_threshold" value="%nbviewer_cookbook%/geom_histogram_threshold.ipynb"/>
     <var name="nb-geom_label" value="%nbviewer_cookbook%/geom_label.ipynb"/>
     <var name="nb-geom_lollipop" value="%nbviewer_cookbook%/geom_lollipop.ipynb"/>
     <var name="nb-geom_pie" value="%nbviewer_cookbook%/geom_pie.ipynb"/>
@@ -86,9 +90,9 @@
     <var name="nb-jittered_points" value="%nbviewer_cookbook%/jittered_points.ipynb"/>
     <var name="nb-joint_plot" value="%nbviewer_cookbook%/joint_plot.ipynb"/>
     <var name="nb-label_format" value="%nbviewer_cookbook%/label_format.ipynb"/>
-    <var name="nb-legend_and_axis" value="%nbviewer_cookbook%/legend_and_axis.ipynb"/>
-    <var name="nb-legend_text_multiline" value="%nbviewer_cookbook%/legend_text_multiline.ipynb"/>
+    <var name="nb-legend" value="%nbviewer_cookbook%/legend.ipynb"/>
     <var name="nb-lines" value="%nbviewer_cookbook%/lines.ipynb"/>
+    <var name="nb-manual_legend" value="%nbviewer_cookbook%/manual_legend.ipynb"/>
     <var name="nb-marginal_layers" value="%nbviewer_cookbook%/marginal_layers.ipynb"/>
     <var name="nb-margins" value="%nbviewer_cookbook%/margins.ipynb"/>
     <var name="nb-multiple_color_scales" value="%nbviewer_cookbook%/multiple_color_scales.ipynb"/>
@@ -125,5 +129,6 @@
     <var name="nb-tooltip_config" value="%nbviewer_cookbook%/tooltip_config.ipynb"/>
     <var name="nb-tooltip_title" value="%nbviewer_cookbook%/tooltip_title.ipynb"/>
     <var name="nb-tooltips_theme" value="%nbviewer_cookbook%/tooltips_theme.ipynb"/>
+    <var name="nb-waterfall_plot" value="%nbviewer_cookbook%/waterfall_plot.ipynb"/>
     <var name="nb-y_orientation" value="%nbviewer_cookbook%/y_orientation.ipynb"/>
 </vars>

build.gradle.kts

@@ -25,7 +25,7 @@ if (project.file("local.properties").exists()) {
 allprojects {
     group = "org.jetbrains.lets-plot"
     version = when (name) {
-        "dokka" -> "4.7.3"
+        "dokka" -> "4.7.4"
         else -> "4.7.4-SNAPSHOT"
 //        else -> "0.0.0-SNAPSHOT"  // for local publishing only
     }

docs/dokka/source/packages.md

@@ -110,7 +110,7 @@ See [formats.html](https://lets-plot.org/kotlin/formats.html).
 
 - [title_subtitle_caption.ipynb](https://nbviewer.org/github/JetBrains/lets-plot-docs/blob/master/source/kotlin_examples/cookbook/title_subtitle_caption.ipynb)
 
-- [legend_and_axis.ipynb](https://nbviewer.org/github/JetBrains/lets-plot-docs/blob/master/source/kotlin_examples/cookbook/legend_and_axis.ipynb)
+- [legend.ipynb](https://nbviewer.org/github/JetBrains/lets-plot-docs/blob/master/source/kotlin_examples/cookbook/legend.ipynb)
 
 # Package org.jetbrains.letsPlot.sampling
 

docs/examples.md

@@ -223,7 +223,7 @@ Complete themes: `themeBW, themeGrey, themeLight, themeClassic, themeMinimal` an
 Use the `theme()` function to modify components of a theme.
 
 * [themes.ipynb](https://nbviewer.org/github/JetBrains/lets-plot-docs/blob/master/source/kotlin_examples/cookbook/themes.ipynb)
-* [legend_and_axis.ipynb](https://nbviewer.org/github/JetBrains/lets-plot-docs/blob/master/source/kotlin_examples/cookbook/legend_and_axis.ipynb)
+* [legend.ipynb](https://nbviewer.org/github/JetBrains/lets-plot-docs/blob/master/source/kotlin_examples/cookbook/legend.ipynb)
 * [Title, subtitle, caption](https://nbviewer.org/github/JetBrains/lets-plot-docs/blob/master/source/kotlin_examples/cookbook/title_subtitle_caption.ipynb)
 * [font size and family](https://nbviewer.org/github/JetBrains/lets-plot-docs/blob/master/source/kotlin_examples/cookbook/font_size_and_family.ipynb)
 * [label hjust, vjust](https://nbviewer.org/github/JetBrains/lets-plot-docs/blob/master/source/kotlin_examples/cookbook/hjust_vjust.ipynb)

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/bistro/joint/JointPlot.kt

@@ -27,13 +27,7 @@ package org.jetbrains.letsPlot.bistro.joint
  *  If only one value given - interpret it as list of two equal values.
  *  Applicable simultaneously for "tile" geom and "histogram" marginal.
  * @param color Color of a geometry.
- *  String in the following formats: 
- *  - RGB/RGBA (e.g. "rgb(0, 0, 255)")
- *  - HEX (e.g. "#0000FF")
- *  - color name (e.g. "red")
- *  - role name ("pen", "paper" or "brush")
- *
- *  Or an instance of the `java.awt.Color` class.
+ *  For more info see: [aesthetics.html#color-and-fill](https://lets-plot.org/kotlin/aesthetics.html#color-and-fill).
  * @param size Size of a geometry.
  * @param alpha Transparency level of a geometry.
  *  Understands numbers between 0 and 1.

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/bistro/qq/QQPlot.kt

@@ -43,28 +43,24 @@ package org.jetbrains.letsPlot.bistro.qq
  * @param showLegend default = true.
  *  false - do not show legend for this layer.
  * @param color Color of a points.
- *  String in the following formats: 
- *  - RGB/RGBA (e.g. "rgb(0, 0, 255)")
- *  - HEX (e.g. "#0000FF")
- *  - color name (e.g. "red")
- *  - role name ("pen", "paper" or "brush")
- *
- *  Or an instance of the `java.awt.Color` class.
+ *  For more info see: [aesthetics.html#color-and-fill](https://lets-plot.org/kotlin/aesthetics.html#color-and-fill).
  * @param fill Color to paint shape's inner points.
  *  Is applied only to the points of shapes having inner points.
  * @param alpha default = 0.5.
  *  Transparency level of a points. Understands numbers between 0 and 1.
  * @param size default = 3.0.
  *  Size of the points.
  * @param shape Shape of the points.
+ *  For more info see: [aesthetics.html#point-shapes](https://lets-plot.org/kotlin/aesthetics.html#point-shapes).
  * @param lineColor default = "#FF0000".
  *  Color of the fitting line.
  * @param lineSize default = 0.75.
  *  Width of the fitting line.
  * @param linetype Int or String.
  *  Type of the fitting line.
  *  Codes and names: 0 = "blank", 1 = "solid", 2 = "dashed", 3 = "dotted", 4 = "dotdash",
- *  5 = "longdash", 6 = "twodash"
+ *  5 = "longdash", 6 = "twodash".
+ *  For more info see: [aesthetics.html#line-types](https://lets-plot.org/kotlin/aesthetics.html#line-types).
  */
 fun qqPlot(
     data: Map<*, *>,

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/bistro/residual/ResidualPlot.kt

@@ -40,13 +40,7 @@ package org.jetbrains.letsPlot.bistro.residual
  *  If only one value given - interpret it as list of two equal values.
  *  Applicable simultaneously for "tile" geom and "histogram" marginal.
  * @param color Color of a geometry.
- *  String in the following formats: 
- *  - RGB/RGBA (e.g. "rgb(0, 0, 255)")
- *  - HEX (e.g. "#0000FF")
- *  - color name (e.g. "red")
- *  - role name ("pen", "paper" or "brush")
- *
- *  Or an instance of the `java.awt.Color` class.
+ *  For more info see: [aesthetics.html#color-and-fill](https://lets-plot.org/kotlin/aesthetics.html#color-and-fill).
  * @param size Size of a geometry.
  * @param alpha Transparency level of a geometry. 
  *  Understands numbers between 0 and 1.

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/bistro/waterfall/WaterfallPlot.kt

@@ -19,8 +19,10 @@ package org.jetbrains.letsPlot.bistro.waterfall
  * @param group Grouping variable.
  *  Each group calculates its own statistics.
  * @param color Color of the box boundary lines.
+ *  For more info see: [aesthetics.html#color-and-fill](https://lets-plot.org/kotlin/aesthetics.html#color-and-fill).
  *  Use "flow_type" to color lines by the direction of the flow.
  * @param fill Fill color of the boxes.
+ *  For more info see: [aesthetics.html#color-and-fill](https://lets-plot.org/kotlin/aesthetics.html#color-and-fill).
  *  Use "flow_type" to color boxes by the direction of the flow.
  * @param size default = 0.0.
  *  Line width of the box boundary lines.
@@ -29,6 +31,7 @@ package org.jetbrains.letsPlot.bistro.waterfall
  *  Type of the box boundary lines.
  *  Codes and names: 0 = "blank", 1 = "solid", 2 = "dashed", 3 = "dotted", 4 = "dotdash",
  *  5 = "longdash", 6 = "twodash".
+ *  For more info see: [aesthetics.html#line-types](https://lets-plot.org/kotlin/aesthetics.html#line-types).
  * @param width default = 0.9.
  *  Width of the boxes. Typically range between 0 and 1.
  *  Values that are greater than 1 lead to overlapping of the boxes.

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/geom/geom_abline.kt

@@ -46,16 +46,11 @@ import org.jetbrains.letsPlot.pos.positionIdentity
  * @param alpha Transparency level of a layer.
  *  Understands numbers between 0 and 1.
  * @param color Color of the geometry.
- *  String in the following formats: 
- *  - RGB/RGBA (e.g. "rgb(0, 0, 255)")
- *  - HEX (e.g. "#0000FF")
- *  - color name (e.g. "red")
- *  - role name ("pen", "paper" or "brush")
- *
- *  Or an instance of the `java.awt.Color` class.
- * @param linetype Type of the line. 
+ *  For more info see: [aesthetics.html#color-and-fill](https://lets-plot.org/kotlin/aesthetics.html#color-and-fill).
+ * @param linetype Type of the line.
  *  Codes and names: 0 = "blank", 1 = "solid", 2 = "dashed", 3 = "dotted", 4 = "dotdash",
  *  5 = "longdash", 6 = "twodash".
+ *  For more info see: [aesthetics.html#line-types](https://lets-plot.org/kotlin/aesthetics.html#line-types).
  * @param size Line width.
  * @param colorBy default = "color" ("fill", "color", "paint_a", "paint_b", "paint_c").
  *  Defines the color aesthetic for the geometry.

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/geom/geom_area.kt

@@ -53,24 +53,13 @@ import org.jetbrains.letsPlot.tooltips.TooltipOptions
  * @param alpha Transparency level of a layer. 
  *  Understands numbers between 0 and 1.
  * @param color Color of the geometry.
- *  String in the following formats: 
- *  - RGB/RGBA (e.g. "rgb(0, 0, 255)")
- *  - HEX (e.g. "#0000FF")
- *  - color name (e.g. "red")
- *  - role name ("pen", "paper" or "brush")
- *
- *  Or an instance of the `java.awt.Color` class.
+ *  For more info see: [aesthetics.html#color-and-fill](https://lets-plot.org/kotlin/aesthetics.html#color-and-fill).
  * @param fill Fill color.
- *  String in the following formats: 
- *  - RGB/RGBA (e.g. "rgb(0, 0, 255)")
- *  - HEX (e.g. "#0000FF")
- *  - color name (e.g. "red")
- *  - role name ("pen", "paper" or "brush")
- *
- *  Or an instance of the `java.awt.Color` class.
+ *  For more info see: [aesthetics.html#color-and-fill](https://lets-plot.org/kotlin/aesthetics.html#color-and-fill).
  * @param linetype Type of the line of border.
  *  Codes and names: 0 = "blank", 1 = "solid", 2 = "dashed", 3 = "dotted", 4 = "dotdash",
  *  5 = "longdash", 6 = "twodash".
+ *  For more info see: [aesthetics.html#line-types](https://lets-plot.org/kotlin/aesthetics.html#line-types).
  * @param size Line width.
  * @param colorBy default = "color" ("fill", "color", "paint_a", "paint_b", "paint_c").
  *  Defines the color aesthetic for the geometry.