Docs 2.1.0

README_PYTHON.md

@@ -21,7 +21,7 @@
  </tr>
  <tr>
  <td>Python versions</td>
- <td>3.6, 3.7, 3.8, 3.9</td>
+ <td>3.6 - 3.9</td>
  </tr>
 </table>
 
@@ -46,7 +46,7 @@
 - [Offline Mode](#offline-mode)
 - [Interesting Demos](#interesting-demos)
 - [Scientific Mode in IntelliJ IDEA / PyCharm](#scientific-mode-in-intellij-idea-pycharm)
-- [What is new in 2.0.0](#what-is-new-in-2-0-0)
+- [What is new in 2.1.0](#what-is-new)
 - [Change Log](#change-log)
 - [License](#license)
 
@@ -326,51 +326,26 @@ To learn more about the plugin check: [Lets-Plot in SciView plugin homepage](htt
 <img src="https://raw.githubusercontent.com/JetBrains/lets-plot/master/docs/examples/images/pycharm_map_fr_low_65.gif" alt="Couldn't load pycharm_map_fr_low_65.png" width="537" height="220"/>
 </div>
 
-<a id="what-is-new-in-2-0-0"></a>
-### What is new in 2.0.0
-
-- Python 3.9 support
-- Faceted plots:
- - new `facet_wrap()` function.
- - ordering of faceting values.
- - formatting of faceting values.
+<a id="what-is-new"></a>
+### What is new in 2.1.0
+
+- Upgraded dependencies:
+ - Kotlin: 1.5.21
+ - Apach Batik: 1.14 [[#398](https://github.com/JetBrains/lets-plot/issues/398)]
 
- See: [Facets demo](https://nbviewer.jupyter.org/github/JetBrains/lets-plot/blob/master/docs/examples/jupyter-notebooks/facets.ipynb)
-
-
-- new `format` parameter on scales: formatting tick labels on X/Y axis.
-
- Example:
- ```python
- scale_x_datetime(format="%b %Y")
- scale_x_continuous(format='is {.2f}')
- ```
- Demo: [Formatting demo](https://nbviewer.jupyter.org/github/JetBrains/lets-plot/blob/master/docs/examples/jupyter-notebooks/formatting_axes_etc.ipynb)
-
- See also: [Formatting](https://jetbrains.github.io/lets-plot-docs/pages/features/formats.html)
-
-
-- Tooltips:
- - new `color` option: overrides the default tooltip color:
-
- ```python
- geom_xxx(tooltips=layer_tooltips().color('red'))
- ```
-
- Learn more: [Tooltip Customization](https://jetbrains.github.io/lets-plot-docs/pages/features/tooltips.html).
- - *crosshair* cursor when tooltip is in a fixed position specified by the `anchor` option.
-
-
-- Brand new Geocoding API.
-
- Note: This is a **breaking change!** Hence we bumped the Lets-Plot version to 2.0.0. 
+- Ordering categories:
+
+ New parameters added to the `as_discrete` function:
+ - `order_by` (string) - the name of the variable by which the ordering will be performed;
+ - `order` (int) - the ordering direction: 1 for ascending direction and -1 for descending (default).
 
- In the Lets-Plot v2.0.0 the peviouse Geocoding API is no longer working.
+ See: [as_discrete](https://github.com/JetBrains/lets-plot/blob/master/docs/as_discrete.md).
 
- The old version of geocoding backend remains on-line for a couple of release cycles
- to continue support of prior Lets-Plot versions.
+- Interactive maps:
+ - Pre-configured raster tilesets in new `lets_plot.tilesets` module.
+ - Builtin blank maptiles.
 
- To learn more about new Geocoding API see: [Geocoding](https://jetbrains.github.io/lets-plot-docs/pages/features/geocoding.html).
+ See: [Configuring basemap tiles](https://github.com/JetBrains/lets-plot/blob/master/docs/basemap_tiles.md).
 
 
 <a id="change-log"></a>

docs/as_discrete.md

@@ -0,0 +1,117 @@
+
+- [Function as_discrete](#description)
+- [Examples](#examples)
+- [Example Notebooks](#example-notebooks)
+
+
+
+<a id="description"></a>
+### Function as_discrete()
+
+The function `as_discrete()` is used to annotate a numeric data series as categorical data with the possibility of its ordering
+for the purposes of given visualization.
+
+
+
+#### Usage:
+
+```as_discrete(variable, label=None, order_by=None, order=None)```
+
+where
+
+* `variable` (string) - the name of the data variable (which is mapped to the plot aesthetic);
+* `label` (string) - the name of the scale - it will be used as the axis label or as the legend title;
+* `order_by` (string) - the name of the variable by which the ordering will be performed;
+* `order` (int) - the ordering direction - `1` for ascending direction and `-1` for descending (default value).
+
+To enable ordering mode, at least one ordering parameter (`order_by` or `order`) should be specified.
+By the default, it will use descending direction and ordering by eigenvalues.
+You cannot specify different order settings for the same variable. However, if these settings don't contradict each other, they will be combined.
+
+The `order_by` is a numeric variable, which values are used for reordering. It's also possible to use statistical variables.
+The reordering uses the average value. The exception is plots with the `stack` position adjustment, where multiple bars occupying the same `x` position are stacked atop one another: 
+in this case, the sum is calculated to get the order of the stack sizes.
+
+
+<a id="examples"></a>
+### Examples
+```
+p = ggplot(mpg)
+p + geom_point(aes('displ', 'hwy', color='cyl'))
+```
+![](examples/images/as_discrete_1.png)
+
+Let's annotate the 'cyl' variable as discrete using the `as_discrete('cyl')` function.
+As a result, the data is divided into groups, a discrete color scale is assigned instead of a continuous one:
+```
+p + geom_point(aes('displ', 'hwy', color=as_discrete('cyl')))
+```
+![](examples/images/as_discrete_2.png)
+
+Set the 'cyl' variable in ascending order of its values:
+```
+p + geom_point(aes('displ', 'hwy', color=as_discrete('cyl', order=1)))
+```
+![](examples/images/as_discrete_3.png)
+
+
+Boxplot example:
+```
+p + geom_boxplot(aes('class', 'hwy'))
+```
+![](examples/images/as_discrete_4.png)
+
+Order `x` alphabetically
+```
+p + geom_boxplot(aes(as_discrete('class', order=1), 'hwy'))
+
+```
+![](examples/images/as_discrete_5.png)
+
+
+Order `x` by another variable - in descending order of the median:
+
+```
+p + geom_boxplot(aes(as_discrete('class', order_by='..middle..'), 'hwy'))
+```
+![](examples/images/as_discrete_6.png)
+
+Add `color` associated with the same variable. 
+The ordering is also applied to it, which will be visible in the legend:
+```
+p + geom_boxplot(aes(as_discrete('class', order=1), 'hwy', color='class'))
+```
+![](examples/images/as_discrete_7.png)
+
+Two different ordering settings are specified for the `class` variable. 
+These settings don't contradict each other. This means that they will be combined,
+and the variable will be ordered in ascending order `ymax`:
+```
+p + geom_boxplot(aes(as_discrete('class', order_by='..ymax..'), 'hwy', color=as_discrete('class', order=1)))
+```
+![](examples/images/as_discrete_8.png)
+
+Example of ordering for two variables:
+```
+p + geom_bar(aes(x=as_discrete('manufacturer', order=1), fill=as_discrete('class', order=1)), color='black')
+
+```
+![](examples/images/as_discrete_9.png)
+
+Reorder `x` by counts to get from highest on the left to lowest on the right:
+```
+p + geom_bar(aes(x=as_discrete('manufacturer', order_by='..count..'), fill=as_discrete('class', order=1)), color='black')
+```
+![](examples/images/as_discrete_10.png)
+
+Apply sampling to the plot after reordering:
+```
+p + geom_bar(aes(x=as_discrete('manufacturer', order_by='..count..'), fill=as_discrete('class', order=1)), color='black', sampling=sampling_pick(4))
+```
+![](examples/images/as_discrete_11.png)
+
+<a id="example-notebooks"></a>
+## Example Notebooks
+
+* [geom_smooth.ipynb](https://nbviewer.jupyter.org/github/JetBrains/lets-plot/blob/master/docs/examples/jupyter-notebooks/geom_smooth.ipynb)
+* [ordering_examples.ipynb](https://nbviewer.jupyter.org/github/JetBrains/lets-plot/blob/master/docs/examples/jupyter-notebooks/ordering_examples.ipynb)