lets-plot 1.4.0

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

• Implementation Overview
• Installation
• Quick start with Jupyter
• Examples
• SVG/HTML export to file
• Offline mode
• What is new in 1.4.0

Implementation Overview

The Lets-Plot python extension includes 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 and is almost identical to the one we ship as PyPI package. This is because Lets-Plot is an offshoot of the Datalore project from which it was extracted to a separate plotting library.

One important difference is that the python package in Datalore is named datalore.plot and the package you install from PyPI has name lets_plot.

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.

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

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

Try the following examples to study more features of the Lets-Plot library.

• Quickstart in Jupyter: quickstart.ipynb

• Histogram, density plot, box plot and facets: distributions.ipynb

• Error-bars, crossbar, linerange, pointrange, points, lines, bars, dodge position: error_bars.ipynb

• Points, point shapes, linear regression, jitter position: scatter_plot.ipynb

• Smoothing: linear, LOESS: geom_smooth.ipynb

• as_discrete() function: geom_smooth.ipynb

• Points, density2d, polygons, density2df, bin2d: density_2d.ipynb

• Tiles, contours, polygons, contourf: contours.ipynb

• Raster geom, Image geom: image_fisher_boat.ipynb

• Various presentation options: legend_and_axis.ipynb

GeoDataFrame support (Shapely and GeoPandas).

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

• Map building basics with Lets-Plot and GeoPandas: geopandas_naturalearth.ipynb

• An inset map of Kotlin island: geopandas_kotlin_isl.ipynb

Nonstandard plotting functions

The following features of Lets-Plot are not available or have different implementation in other Grammar of Graphics libraries.

• ggsize() - sets the size of the plot. Used in many examples starting from quickstart.

• geom_density2df() - fills space between equal density lines on a 2D density plot. Similar to geom_density2d but supports the fill aesthetic.

  Example: density_2d.ipynb

• geom_contourf() - fills space between the lines of equal level of the bivariate function. Similar to geom_contour but supports the fill aesthetic.

  Example: contours.ipynb

• geom_image() - displays an image specified by a ndarray with shape (n,m) or (n,m,3) or (n,m,4).

  Example: image_101.ipynb

  Example: image_fisher_boat.ipynb

• gg_image_matrix() - a utility helping to combine several images into one graphical object.

  Example: image_matrix.ipynb

GGBanch

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.

Examples:

• ggbunch.ipynb
• scatter_matrix.ipynb

Data sampling

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

Learn more about sampling in Lets-Plot.

Cloud-based notebooks

Examples:

• Google Colab
• Kaggle
• JetBrains Datalore

Interesting demos

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

SVG/HTML export to file

export_svg function takes plot specification and filename as parameters and saves SVG representation of the plot to a file in the current working directory.

from lets_plot import *
p = ggplot()...

# export SVG to file
from lets_plot.export.simple import export_svg

export_svg(p, "p.svg")

Note: The simple.export_svg() function do not save images of an interactive map.

export_html function takes plot specification and filename as parameters and saves dynamic HTML to a file in the current working directory. When viewing this content the internet connection is required.

export_html has one more option - iframe. If iframe=True then Lets-PLot will wrap output HTML into iframe.

from lets_plot import *
p = ggplot()...

# export HTML to file
from lets_plot.export.simple import export_html

export_html(p, "p.htm")

Example notebook: export_SVG_HTML

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)

What is new in 1.4.0

Interactive maps

Function geom_livemap() enables a researcher to visualize geospatial information on interactive map.

When building interactive geospatial visualizations with Lets-Plot the visualisation workflow remains the same as when building a regular ggplot2 plot.

However, geom_livemap() creates an interactive base-map super-layer and certain limitations do apply comparing to a regular ggplot2 geom-layer:

• geom_livemap() must be added as a 1-st layer in plot;
• Maximum one geom_livemap() layer is alloed per plot;
• Not any type of geometry can be combined with interactive map layer in one plot;
• Internet connection to map tiles provider is required.

The following ggplot2 geometry can be used with interactive maps:

• geom_point
• geom_rect
• geom_path
• geom_polygon
• geom_segment
• geom_text
• geom_tile
• geom_vline, geon_hline
• geom_bin2d
• geom_contour, geom_contourf
• geom_density2d, geom_density2df

Examples:

• map_quickstart.ipynb
• map_california_housing.ipynb

Function as_discrete()

The function as_discrete() is used to annotate a numeric data series as categorical data for the purposes of given visualization.

Code example:

from lets_plot.mapping import as_discrete

mpg_plot + geom_point(aes(color='cyl'))\
         + geom_smooth(aes(color=as_discrete('cyl')), method='lm', deg=2, size=1)

Example notebook: geom_smooth.ipynb

Polynomial regression of arbitrary degree in geom_smooth

New parameter deg in geom_smooth() allows to adjust the degree of the model polynomial when using linear model smoothing method.

Code example:

# Apply 2nd degree polynomial regression 
p + geom_smooth(method='lm', deg=2)

Example notebook: geom_smooth.ipynb

Hiding tooltips on axis

There are new parameters axis_tooltip, axis_tooltip_x and axis_tooltip_y in the function theme() which allow to hide tooltip on axis X, axis Y or on the both axis.

Code example:

# Hide tooltips on both axis.
p + theme(axis_tooltip='blank')

Change Log

See Lets-Plot at Github.

License

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