Lets-plot

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.

Added

- Global theme configuring with `LetsPlot.theme` property.

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

- Quantile-Quantile (Q-Q) plot:
- geometries:
- `geomQQ()`
- `geomQQLine()`
- `geomQQ2()`
- `geomQQ2Line()`
- stats:
- `statQQ()`
- `statQQLine()`
- `statQQ2()`
- `statQQ2Line()`
- quick Q-Q: `qqPlot()`

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

- Marginal plots: the `ggmarginal()` function.

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

- Parameter `orientation` in geoms: `bar, boxplot, density, histogram, freqpoly, smooth, violin`.

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

- New in *plot theme*:
- `face` parameter in `elementText()`.

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

- `panelBorder` parameter in `theme()` [[542](https://github.com/JetBrains/lets-plot/issues/542)].

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

- *Tooltip* theme options, new parameters in `theme()`:
- `tooltip` - tooltip rectangle options;
- `tooltipText, tooltipTitleText` - tooltip text options;
- `axisTooltipText, axisTooltipTextX, axisTooltipTextY` - axis tooltip text options.

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

- `scaleColorGradientN()` and `scaleFillGradientN()` functions [[504](https://github.com/JetBrains/lets-plot/issues/504)].

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


- `kotlinx.datetime` support.
- `arrow` parameter in `geomSegment` - specification for arrow heads, as created by `arrow()` function.


Changed

- Potentially **breaking change**: deprecation level for all deprecated API raised to the **ERROR** level.
- `geomImage()` removed as it is not yet production ready.
- Default sampling type for `geom_violin` switched from `systematic` to `pick`.


Fixed

- Labels out of plot when axisTextY="blank" [[525](https://github.com/JetBrains/lets-plot/issues/525)].
- Outliers are not shown when boxplot' alpha=0.
- JFX rendering issue that causes tooltips to stuck [[539](https://github.com/JetBrains/lets-plot/issues/539)].
- Support trim parameter in `density` and `ydensity` stats [[62](https://github.com/JetBrains/lets-plot/issues/62)].
- `geom_violin`: add missing parameters `kernel`, `bw`, `adjust`, `n`, `fs_max` to signature and docstring.

Added

- New geometries:
- `geomViolin()`

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

- `geomDotplot()`

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

- `geomYDotplot()`

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


- Plot subtitle and caption:
`subtitle` parameter in `ggtitle()` and `labs()`,
`caption` parameter in `labs()`,
`plotSubtitle` and `plotCaption` parameters in `theme()`.

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

- Multi-line labels: The 'newline' character (`\n`) now works as `line break` in plot title, subtitle and caption, in legend's title and in tooltips.

- In tooltip customization API: the `title()` option defines a tooltip "title" text which will always appear above the rest of the tooltip content.

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

- Parameter `scales` in `facetGrid()/facetWrap()` [[451](https://github.com/JetBrains/lets-plot/issues/451),
[479](https://github.com/JetBrains/lets-plot/issues/479)].

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


Changed

- New tooltip style: rounded corners, bold label, colored marker inside the tooltip.
- Deprecated tooltip customization API: function `color()` will be removed in one of the future releases.
- 'Auto shrink': plots automatically shrink when necessary to fit width of the output (notebook) cell [[488](https://github.com/JetBrains/lets-plot/issues/488)].

Fixed

- Automatic detection of DateTime series [[99](https://github.com/JetBrains/lets-plot-kotlin/issues/99)].
- Too limited mapping options in GenericAesMapping [[82](https://github.com/JetBrains/lets-plot-kotlin/issues/82)]
- scaleColorManual Divide by Zero with 1 mapping [[506](https://github.com/JetBrains/lets-plot/issues/506)].
- LinearBreaksHelper$Companion.computeNiceBreaks out of memory error [[105](https://github.com/JetBrains/lets-plot-kotlin/issues/105)].
- CVE-2021-23792 in org.jetbrains.lets-plot:lets-plot-image-export2.2.1 [[497](https://github.com/JetBrains/lets-plot/issues/497)].
- Fix tooltips for `geom_histogram(stat='density')`.
- The axis tooltip overlaps the general tooltip [[515](https://github.com/JetBrains/lets-plot/issues/515)].
- The multi-layer tooltip detection strategy will only be used if more than one layer provides tooltips.

Added

- `scaleXTime()` and `scaleYTime()`.

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

- `plotBackground, legendBackground` parameters in `theme()` [[485](https://github.com/JetBrains/lets-plot/issues/485)].
- `axisOntop, axisOntopX, axisOntopY` parameters in `theme()`

Fixed

- It should automatically stringify enums [[97](https://github.com/JetBrains/lets-plot-kotlin/issues/97)].
- Coord system limits do not work with x/y scale with transform [[474](https://github.com/JetBrains/lets-plot/issues/474)].
- Provide 0-23 hour formatting [[469](https://github.com/JetBrains/lets-plot/issues/469)].
- No tooltip shown when I'm trying to add an empty line [[382](https://github.com/JetBrains/lets-plot/issues/382)].
- `coord_fixed()` should adjust dimensions of "geom" panel accordingly [[478](https://github.com/JetBrains/lets-plot/issues/478)].
- The tooltip dependence on number of factors works separately by layers [[481](https://github.com/JetBrains/lets-plot/issues/481)].
- Tooltip on y-axis looks wrong [[393](https://github.com/JetBrains/lets-plot/issues/393)].
- Is kotlin-reflect really needed for lets-plot? [[471](https://github.com/JetBrains/lets-plot/issues/471)].

Added

- `coordFlip()`.

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

- Date-time formatting support:
- using date-time format pattern in tooltip format();
- date/time scales apply date-time formatting to the `breaks`.

See `Out[7, 8, 10]` in
the [example notebook](https://nbviewer.jupyter.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/formatting_axes_etc.ipynb)
.

- Pre-configured themes:
- Standard ggplot2 themes: `themeGrey(), themeLight(), themeClassic(), themeMinimal()`;
- Other themes: `themeMinimal2()` - the default theme, `themeNone()`.

- Theme modification: more parameters were added to the `theme()` function.

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

> Note: fonts size, family and face still can not be configured.

- `CorrPlot()` function now also accepts pre-computed correlation coefficients.

- Kotlin/JS IR: `xxx.klib` artifacts are now available.

See: [sample Kotlin/JS IR app](https://github.com/alshan/lets-plot-mini-apps/tree/main/js-ir-frontend-app)


Changed

- The size of fonts on plot was slightly increased all across the board.
- The default plot size was increased by 20%, it's now 600x400 px.
- **Deprecated API**: all `Theme.xxxBlank()` functions. Please use corresponding parameters in `theme()`.


Fixed

- Ordering facets - the "order" value 0 disables facet ordering [[454](https://github.com/JetBrains/lets-plot/issues/454)].
- Tooltips for discrete variables: add the dependence of the tooltip on the number of factors.
The X-axis tooltip is always shown for discrete data.
- Unreadable breaks on axis [[430](https://github.com/JetBrains/lets-plot/issues/430)].