lets-plot 2.1.0rc1

An open source library for statistical plotting

Lets-Plot for Python

Latest Release
License
OS	Linux, MacOS, Windows
Python versions	3.6, 3.7, 3.8, 3.9

• Overview
• Installation
• Quick start with Jupyter
• Example Notebooks
• GGBunch
• Data Sampling
• Export to File
• Formatting
• Tooltip Customization
• The 'bistro' Package
  • Correlation Plot
  • Image Matrix
• Geospatial
  • GeoPandas Support
  • Interactive Maps
  • Geocoding
• 'No Javascript' Mode
• Offline Mode
• Interesting Demos
• Scientific Mode in IntelliJ IDEA / PyCharm
• What is new in 2.0.0
• Change Log
• License

Overview

The Lets-Plot for Python library includes a native backend and a Python API, which was mostly based on the ggplot2 package well-known to data scientists who use R.

R ggplot2 has extensive documentation and a multitude of examples and therefore is an excellent resource for those who want to learn the grammar of graphics.

Note that the Python API being very similar yet is different in detail from R. Although we have not implemented the entire ggplot2 API in our Python package, we have added a few new features to our Python API.

You can try the Lets-Plot library in Datalore. Lets-Plot is available in Datalore out-of-the-box (i.e. you can ignore the Installation chapter below).

The advantage of Datalore as a learning tool in comparison to Jupyter is that it is equipped with very friendly Python editor which comes with auto-completion, intentions, and other useful coding assistance features.

Begin with the quickstart in Datalore notebook to learn more about Datalore notebooks.

Watch the Datalore Getting Started Tutorial video for a quick introduction to Datalore.

Installation

1. For Linux and Mac users:

To install the Lets-Plot library, run the following command:

pip install lets-plot

2. For Windows users:

Install Anaconda3 (or Miniconda3), then install MinGW toolchain to Conda:

conda install m2w64-toolchain

Install the Lets-Plot library:

pip install lets-plot

Quick start with Jupyter

You can use Lets-Plot in Jupyter notebook or other notebook of your choice, like Datalore, Kaggle or Colab.

To evaluate the plotting capabilities of Lets-Plot, add the following code to a Jupyter notebook:

import numpy as np
from lets_plot import *
LetsPlot.setup_html()        

np.random.seed(12)
data = dict(
    cond=np.repeat(['A','B'], 200),
    rating=np.concatenate((np.random.normal(0, 1, 200), np.random.normal(1, 1.5, 200)))
)

ggplot(data, aes(x='rating', fill='cond')) + ggsize(500, 250) \
+ geom_density(color='dark_green', alpha=.7) + scale_fill_brewer(type='seq') \
+ theme(axis_line_y='blank')

           

Example Notebooks

See Example Notebooks.

GGBunch

GGBunch allows to show a collection of plots on one figure. Each plot in the collection can have arbitrary location and size. There is no automatic layout inside the bunch.

• ggbunch.ipynb
• geom_smooth.ipynb
• scatter_matrix.ipynb

Data Sampling

Sampling is a special technique of data transformation, which helps dealing with large datasets and overplotting.

Learn more: Data Sampling.

Export to File

The ggsave() function is an easy way to export plot to a file in SVG or HTML formats.

Note: The ggsave() function currently do not save images of interactive maps to SVG.

Example notebook: export_SVG_HTML

Formatting

Lets-Plot supports formatting of values of numeric and date-time types.

Complementary to the value formatting, a string template is also supported.

For example:

value: 67719.94988293362
+
string template: "Mean income: £{.2s}"
=
the formatting result: "Mean income: £67k"

An empty placeholder {} is also allowed. In this case a default string representation will be shown. This is also applicable to categorical values.

To learn more about format strings see: Formatting.

In Lets-Plot you can use formatting for:

• tooltip text, see: Tooltip Customization.
• labels on X/Y axis. See: Formatting demo.
• the geom_text() labels. See: Label format demo.
• facetting values in facet_grid(), facet_wrap() functions. See: Facets demo.

Tooltip Customization

You can customize the content of tooltips for the layer by using the parameter tooltips of geom functions.

Learn more: Tooltip Customization.

The 'bistro' Package

The 'bistro' package is a collection of higher level API functions, each allows to create a certain kind of plot with a single function call instead of combining a plethora of plot features manually.

Correlation Plot

from lets_plot.bistro.corr

The corr_plot() function creates a fluent builder object offering a set of methods for configuring of beautiful correlation plots. A call to the terminal build() method in the end will create a resulting plot object.

Example: correlation_plot.ipynb

Image Matrix

from lets_plot.bistro.im

The image_matrix() function arranges a set of images in a grid.

Example: image_matrix.ipynb

The image_matrix() function uses geom_image under the hood, so you might want to check out these demos as well:

• image_101.ipynb
• image_fisher_boat.ipynb

Geospatial

GeoPandas Support

GeoPandas GeoDataFrame is supported by the following geometry layers: geom_polygon, geom_map, geom_point, geom_text, geom_rect.

Learn more: GeoPandas Support.

Interactive Maps

Interactive maps allow zooming and panning around geospatial data that can be added to the base-map layer using regular ggplot geoms.

Learn more: Interactive Maps.

Geocoding

Geocoding is the process of converting names of places into geographic coordinates.

The Lets-Plot has built-in geocoding capabilities covering the folloing administrative levels:

• countries
• states (US and non-US equivalents)
• counties (and equivalents)
• cities (and towns)

Learn more: Geocoding.

'No Javascript' Mode

In the 'no javascript' mode Lets-Plot genetares plots as bare-bones SVG images.

This mode is halpfull when there is a requirement to render notebooks in an 'ipnb' renderer which does not suppopt javascript (like GitHub's built-in renderer).

Activate 'no javascript' mode using the LetsPlot.setup_html() method call:

from lets_plot import *

LetsPlot.setup_html(no_js=True)

Alternativaly, you can set up the environment variable:

LETS_PLOT_NO_JS = true   (other accepted values are: 1, t, y, yes)

Note: interactive maps do not support the 'no javascript' mode.

Offline Mode

In classic Jupyter notebook the LetsPlot.setup_html() statement by default pre-loads Lets-Plot JS library from CDN. Alternatively, option offline=True will force Lets-Plot adding the full Lets-Plot JS bundle to the notebook. In this case, plots in the notebook will be working without an Internet connection.

from lets_plot import *

LetsPlot.setup_html(offline=True)

Note: internet connection is still required for interactive maps and geocoding API.

Interesting Demos

A set of interesting notebooks using Lets-Plot library for visualization.

Scientific mode in IntelliJ IDEA / PyCharm

Plugin "Lets-Plot in SciView" is available at the JetBrains Plugin Repository.

The plugin adds support for interactive plots in IntelliJ-based IDEs with the enabled Scientific mode.

To learn more about the plugin check: Lets-Plot in SciView plugin homepage.

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.

  See: Facets demo

• new format parameter on scales: formatting tick labels on X/Y axis.

  Example:

  scale_x_datetime(format="%b %Y")
  scale_x_continuous(format='is {.2f}')
  

  Demo: Formatting demo

  See also: Formatting

• Tooltips:

  • new color option: overrides the default tooltip color:

    geom_xxx(tooltips=layer_tooltips().color('red'))
    

    Learn more: Tooltip Customization.

  • 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.

  In the Lets-Plot v2.0.0 the peviouse Geocoding API is no longer working.

  The old version of geocoding backend remains on-line for a couple of release cycles to continue support of prior Lets-Plot versions.

  To learn more about new Geocoding API see: Geocoding.

Change Log

See CHANGELOG.md for other changes and fixes.

License

Code and documentation released under the MIT license. Copyright © 2019-2021, JetBrains s.r.o.