README_PYTHON.md

Lets-Plot for Python

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

• Overview

• Installation

• Quick start with Jupyter

• Examples

  • Quickstart and more
  • GeoPandas support
  • Interactive Maps
  • Nonstandard plotting functions
  • GGBanch
  • Data sampling
  • Cloud-based notebooks
  • Interesting demos

• SVG/HTML export to file

• Offline mode

• Scientific mode in IntelliJ IDEA / PyCharm

• What is new in 1.5.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

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 and more

• 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

Interactive Maps.

The interactive map allows zooming in and out and panning around geospatial data that can be added to the base-map layer using regular ggplot geoms.

The basemap layer is created by the geom livemap geom which in addition can also work as scatter plot - similar to geom_point.

Learn more about interactive maps support in Lets-Plot.

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

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.

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:

• Datalore
• Kaggle
• Colab

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)

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 1.5.0

Geocoding API

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

Lets-Plot now offers geocoding API covering the following administrative levels:

• country
• state
• county
• city

Lets-Plot geocoding API allows a user to execute a single and batch geocoding queries, and handle possible names ambiguity.

Relatively simple geocoding queries are executed using the regions_xxx() functions family. For example:

from lets_plot.geo_data import *
regions_country(['usa', 'canada'])

returns the Regions object containing internal IDs for Canada and the US:

  request       id                found name
0     usa   297677  United States of America
1  canada  2856251                    Canada 

More complex geocoding queries can be created with the help of the regions_builder() function that returns the RegionsBuilder object and allows chaining its various methods in order to specify how to handle geocoding ambiguities.

For example:

regions_builder(request='warwick', level='city')  \
    .allow_ambiguous()  \
    .build()

This sample returns the Regions object containing IDs of all cities matching "warwick":

    request        id                   found name
0   warwick    785807                      Warwick
1   warwick    363189                      Warwick
2   warwick    352173                      Warwick
3   warwick  15994531                      Warwick
4   warwick    368499                      Warwick
5   warwick    239553                      Warwick
6   warwick    352897                      Warwick
7   warwick   3679247                      Warwick
8   warwick   8144841                      Warwick
9   warwick    382429                 West Warwick
10  warwick   7042961             Warwick Township
11  warwick   6098747             Warwick Township
12  warwick  15994533  Sainte-Élizabeth-de-Warwick

boston_us = regions(request='boston', within='us')
regions_builder(request='warwick', level='city') \
    .where('warwick', near=boston_us) \
    .build()

This example returns the Regions object containing the ID of one particular "warwick" near Boston (US):

   request      id found name
0  warwick  785807    Warwick

Once the Regions object is available, it can be passed to any Lets-Plot geom supporting the map parameter.

If necessary, the Regions object can be transformed into a regular pandas DataFrame using to_data_frame() method or to a geopandas GeoDataFrame using one of centroids(), boundaries(), or limits() methods.

All coordinates are in the EPSG:4326 coordinate reference system (CRS).

Note what executing geocoding queries requires an internet connection.

Examples:

        

Change Log

See Lets-Plot at Github.

License

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