Lets-plot

Added

- `gggrid()` function ([docs](https://lets-plot.org/kotlin/-lets--plot--kotlin/org.jetbrains.letsPlot/gggrid.html)), as a replacement for earlier variant of [gggrid()](https://github.com/JetBrains/lets-plot-kotlin/blob/master/plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/gggrid_deprecated.kt).
- plots inner area alignment in grid
- nested grids
- works well with `ggsize()`

See: [example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.3.0/plot_grid.ipynb).


- `jointPlot()`.

See: [example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.3.0/joint_plot.ipynb).


- Axis `position` parameter in position scales `scaleX*(), scaleY*()`.

See: [example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.3.0/axis_position.ipynb).


- Drawing quantile lines and filling quantile areas in `geomViolin()` and `geomDensity()`.

See: [example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.3.0/quantile_parameters.ipynb).


- `angle` parameter in `elementText()` in `theme()`.

See: [example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.3.0/axis_text_angle.ipynb).


- Additional "color" aesthetics: `paint_a, paint_b, paint_c`.

These aesthetics are flexible and can be used as either "color" or "fill" as needed.

See [Multiple Color Scales](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.3.0/multiple_color_scales.ipynb) demo.

Also added a set of related "color scale" functions with the "aesthetic" parameter for configuring of additional color scales.

See [New "Scale" Functions](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.3.0/scale_functions.ipynb) demo.


- `density2d` and `density2df` geometry types in `residualPlot()`.


Changed

- [BREAKING] `geomViolin()` no longer supports parameter `drawQuantiles`. Use new `quantileLines` and `quantiles` parameters as needed.

- [BREAKING] `stack` and `fill` position adjustments now stack objects on top of each other only if these objects belong to different **groups**.

If necessary, use `mode="all"` in `positionStack()` or `positionFill()` to stack objects regardless of their group.

See: [example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.3.0/position_stack.ipynb).

- [BREAKING] The deprecation level raised to "ERROR" for all API that was deprecated in v. 4.2.0 and earlier.

- [DEPRECATED] The earlier variant of [gggrid()](https://github.com/JetBrains/lets-plot-kotlin/blob/master/plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/gggrid_deprecated.kt).

From now-on please use new variant added in this release: [new gggrid()](https://lets-plot.org/kotlin/-lets--plot--kotlin/org.jetbrains.letsPlot/gggrid.html).

- Sampling: drastically increased default N for "pick sampling" and for other types of sampling [[687](https://github.com/JetBrains/lets-plot/issues/687)].

Fixed

- Tooltip does not reflect `..quantile..` aesthetic change [[658](https://github.com/JetBrains/lets-plot/issues/658)].
- 'map_join': variable is lost after "stat" [[664](https://github.com/JetBrains/lets-plot/issues/664)].
- Error when tooltip has variable mapped to aesthetic used by stat [[665](https://github.com/JetBrains/lets-plot/issues/665)].
- Groups not sorted similarly when `position='stack'` [[673](https://github.com/JetBrains/lets-plot/issues/673)].
- Area ridges: fill overlaps geometry borders when colors are repeated [[674](https://github.com/JetBrains/lets-plot/issues/674)].
- Sampling: increase the default N for "pick sampling" and for other types of sampling [[687](https://github.com/JetBrains/lets-plot/issues/687)].

Added

- `residualPlot()`.

See: [example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.2.0/residual_plot.ipynb).

- `geomAreaRidges()`.

See: [example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.2.0/ridgeline_plot.ipynb).

- `geomPie()`.

See: [example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.2.0/geom_pie.ipynb).

- Annotations for pie chart:

See: [example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.2.0/annotations_for_pie.ipynb).

- New variables computed by 'count' and 'count2d' statistics: '..sum..', '..prop..', '..proppct..'.

See: [example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.2.0/stat_count_2d.ipynb).

- `geomImshow()`.

See: [image_101](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.2.0/image_101.ipynb),
[image_fisher_boat](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.2.0/image_fisher_boat.ipynb),
[image_grayscale](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.2.0/image_grayscale.ipynb),
[image_extent](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.2.0/image_extent.ipynb)

- New parameters in `geomViolin()`:
- `tailsCutoff`
([example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.2.0/violin_tails_cutoff.ipynb))
- `showHalf`
([example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.2.0/violin_show_half.ipynb))

- Static maps:
- `useCRS` parameter with value "provided" for `geomMap()` and other geoms, working with `SpatialDataset`.

See: [example notebook](https://nbviewer.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.2.0/projection_provided.ipynb).


Changed

- Upgraded Lets-Plot version to 3.0.0 (was 2.5.1).
- Java/Swing platf.: Apache Batik upgraded to v.1.16 [[624](https://github.com/JetBrains/lets-plot/issues/624)], [[LPK #140](https://github.com/JetBrains/lets-plot-kotlin/issues/140)].
- The default size is increased for the plot title and decreased for the caption.
- Upgraded Kotlin version to 1.7.21 (was 1.7.20).


Fixed

- Themes: can't change plot background after applying a "flavor" [[623](https://github.com/JetBrains/lets-plot/issues/623)].
- Layout: uneven left/right, top/bottom plot margins [[625](https://github.com/JetBrains/lets-plot/issues/625)].
- A plot building error with empty data on various geoms.
- Precision error in gradient [[634](https://github.com/JetBrains/lets-plot/issues/634)].

Added

- In `geomText(), geomLabel()`:

- the 'newline' character (`\n`) now works as `line break`
- `lineheight` aesthetic
- `nudgeX, nudgeY` parameters
- special text alignments (`vjust` and `hjust`): `"inward"` and `"outward"`

See: [example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.1.1/geom_text_and_label_new_features.ipynb).

- `vjust` parameter in `positionStack()` and `positionFill()`.

See: [example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/position_stack.ipynb).

Changed

- Deprecated API:
- `positionStack`, new usage: `positionStack()`
- `positionFill`, new usage: `positionFill()`

- `geomBoxplot()`: default value for parameter `whiskerWidth` is 0.5.

- Upgraded Kotlin version to 1.7.20 (was 1.6.21).
- Upgraded Lets-Plot version to 2.5.1 (was 2.5.0).

See Lets-Plot [What is new in 2.5.1](https://github.com/JetBrains/lets-plot#what-is-new-in-251)
for more details.

Fixed

- `elementBlank()` has no effect in theme `legendTitle` [[608](https://github.com/JetBrains/lets-plot/issues/608)].
- Tooltip: different formats for same aesthetic Y [[579](https://github.com/JetBrains/lets-plot/issues/579)].
- Positioning with "constant" x/y doesn't work on axis with log10 transform [[618](https://github.com/JetBrains/lets-plot/issues/618)].
- Positional "constant" doesn't honor axis limits [[619](https://github.com/JetBrains/lets-plot/issues/619)].
- Several issues leading to crush in Swing/Batik apps. Related to [[discussions](https://github.com/JetBrains/lets-plot-kotlin/discussions/138)]
- Text labels got trimmed occasionally, when symbols `-`, `/`, `\` or `|` present.

Added

- New theme: `themeBW()`.

See: [example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/complete_themes.ipynb).

- Color schemes (flavors) applicable to existing themes:
- `flavorDarcula()`
- `flavorSolarizedLight()`
- `flavorSolarizedDark()`
- `flavorHighContrastLight()`
- `flavorHighContrastDark()`

See: [example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/theme_flavors.ipynb).

- Viridis color scales: `scaleColorViridis()`, `scaleFillViridis()`.

See: [example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/colors_viridis.ipynb).

- New parameters in theme's `elementText()`:
- `size, family`
([example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/font_size_and_family.ipynb))
- `hjust, vjust` for plot title, subtitle, caption, legend and axis titles
([example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/hjust_vjust.ipynb))
- `margin` for plot title, subtitle, caption, axis titles and tick labels
([example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/text_margins.ipynb))

- Parameter `whiskerWidth` in `geomBoxplot()`.

See: [example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/boxplot_whisker_width.ipynb).

- New geometry `geomLabel()`.

See: [example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/geom_label.ipynb).

Changed

- New tooltip style after applying `coordFlip()` [[580](https://github.com/JetBrains/lets-plot/issues/580)].

See: [example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/coord_flip.ipynb).

Fixed

- Density and area geoms: preserve the z-order when grouping [[552](https://github.com/JetBrains/lets-plot/issues/552)].
- Boxplot, violin, crossbar: position dodge width=0.95 should be used by default [[553](https://github.com/JetBrains/lets-plot/issues/553)].
- Unclear size unit of width [[589](https://github.com/JetBrains/lets-plot/issues/589)].
- No tooltips for `geomBoxplot` with zero height [[563](https://github.com/JetBrains/lets-plot/issues/563)].
- `geomText`: wrong label alignment with `hjust` 0 and 1 [[592](https://github.com/JetBrains/lets-plot/issues/592)].
- Documentation for the `breaks` parameter in scales [[507](https://github.com/JetBrains/lets-plot/issues/507)]

Added

- `plot_message` parameter in `theme(...)` [[863](https://github.com/JetBrains/lets-plot/issues/863)].
See: [example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot/blob/master/docs/f-23d/theme_plot_message.ipynb).


- Add `geom_count()`/`stat_sum()` [[821](https://github.com/JetBrains/lets-plot/issues/821)].
See: [example notebook](https://nbviewer.org/github/JetBrains/lets-plot/blob/master/docs/f-23d/geom_count.ipynb).

Changed

- If layer transparency is set via the alpha-channel in the colors RGBA specification and via the `alpha` aesthetic, \
then the `alpha` aesthetic overrides the alpha-channel in the color. Previousely it was the opposite.


- `geom_pie()` defaults:
- "stroke" is visible and `stroke_side='both'` (was `stroke_side='outer'`).
- the "hole" is not created automatically when `stroke_side = 'both'/'inner'` (was created automatically).

- `geom_bar()` now has solid outline color by default (was transparent).

- `geom_tile()`, `geom_bin2d()` now have solid outline color by default (was transparent).
- however, by default the `size` is 0 (i.e. tiles outline initially is not visible).


Fixed

- `geom_tile()`, `geom_bin2d()` : the `alpha` aesthetic is applied to the tiles outline.
- `scale_x_datetime()`: error building plot for early dates [[346](https://github.com/JetBrains/lets-plot/issues/346)].
- `geom_livemap()`: theme/flavor plot background is not shown [[857](https://github.com/JetBrains/lets-plot/issues/857)].
- `geom_livemap()`: in AWT dragging a map in a facet moves maps in all facets.
- `geom_livemap()`: support rectangle 'linetype' [[307](https://github.com/JetBrains/lets-plot/issues/307)].
- `theme_void()` + `flavor_xxx()`: no expected plot background [[858](https://github.com/JetBrains/lets-plot/issues/858)].
- Inconsistent color in legend when using `paint_a/paint_b/paint_c` [[867](https://github.com/JetBrains/lets-plot/issues/867)].

**In Kotlin project**

- Update all `import` statements: `import jetbrains.letsPlot..` → `import org.jetbrains.letsPlot..`
- In all places in your project where the code needs to be updated, IntelliJ will show you a `deprecation WARNING` and will offer to fix this
automatically.

**In Jupyter notebook**

- As soon as you start using 4.0.0 in you notebook, the only thing you will want to do is to manually replace all
deprecated `Pos.abc` expressions with their new equivalents:
- `Pos.identity` → `positionIdentity`
- `Pos.stack` → `positionStack`
- `Pos.fill` → `positionFill`
- `Pos.dodge` → `positionDodge()`
- `Pos.nudge` → `positionNudge()`
- `Pos.jitterdodge` → `positionJitterDodge()`

> **NOTE:** If your notebook also uses another Kotlin library which depends on an older version of Lets-Plot, then the
> classloader may refuse to load classes from both libraries.
> If this is the case, then you will want to do **NOT** update your notebook to Lets-Plot v4.0.0 as yet:
> - Make sure your notebook is not using the `%useLatestDescriptors` line magic
> - Make sure you are using Kotlin Jupyter Kernel version 0.11.0.95 (or earlier), which bundles a previous version of Lets-Plot.