Library for plotting interactive graphs on Jupyter Notebook
Project description
Croquis: plot graphs 100x faster on Jupyter Notebook
Croquis is a lightweight Python library for drawing interactive graphs really fast on Jupyter Notebook. It lets you effortlessly browse and examine much larger data than other similar libraries.
As an example, here's hourly ground temperature data of 2020 from the world's weather stations, downloaded from NOAA website. The data set contains 127 million points.
The word "croquis" means a quick, sketchy drawing - it's from French croquis which simply means "sketch." (The final -s is silent: it's French, after all.)
Requirements
- 64-bit Linux/Mac OS running on x86 with
AVX2
instruction set support. (Intel: Haswell (2013) or later; AMD: Excavator
(2015) or later.)
- Windows support is under work.
- Sorry, other architectures aren't supported yet.
- Python 3.6 or later.
- Jupyter Notebook.
- A modern browser (if it can run Jupyter Notebook, it's probably fine).
How to install
pip install croquis
For building from the source, see DEVELOPMENT.md.
To test if it's working correctly, try this inside Jupyter Notebook:
# Paste into a Jupyter cell.
import croquis
import numpy as np
N = 1000000
X = np.random.normal(size=(N, 1))
Y = np.random.normal(size=(N, 1))
labels=['pt %d' % i for i in range(N)]
fig = croquis.plot()
fig.add(X, Y, marker_size=3, labels=labels)
fig.show()
It should generate a plot like this:
See below for documentation.
By the way, this library is of course open source (MIT License) and totally free to use, but just in case you really liked it for some reason, the author could use a cup of coffee or two... :)
Limitations
Croquis is still experimental: as of version 0.1, we only support the absolute bare minimum functionality. In particular:
- Only line plots are supported, nothing else: no bars, pie charts, heatmaps, etc.
- All lines are solid: no dotted/dashed lines.
- All markers are solid circles: no other shapes are currently supported.
- No subplots: each Jupyter cell can contain only one graph.
- Very few options to customize the plot. No titles, axis labels, or secondary axes.
- No support for mobile browsers.
- No dark mode.
- As you can see, the UI is rather primitive.
If croquis seems useful to you, but some features are missing for your use case, then please feel free to file an issue. (Of course I can't guarantee anything, but it will be nice to know that someone's interested.)
Documentation
See the tutorial and the (very short) reference.
FAQ
Is it really 100 times faster?
With large data, croquis can be several hundred times faster than other popular libraries. With very small data, there's less difference, as fixed-size overheads start to dominate.
Can we use it outside of Jupyter Notebook?
No, croquis is currently tied to Jupyter's message passing architecture, and all computation is done in the backend, so it needs an active Jupyter Python kernel.
How does it work?
Unlike most other similar libraries, croquis works by running a C++ "tile server," which computes fixed-sized "tiles" which is then sent back to the browser. If you have used Google Maps, the idea should be familiar. This has an important advantage:
- The browser only has to know about tiles. Hence, the size of the data the browser needs to know is independent of the data set size.
As a result, the browser stays lean and "snappy" even with massive data.
(As explained in the reference, we support copy_data=False
option that even eliminates data copies altogether.)
Moreover, unlike the browser's single-threaded javascript code, the C++-based tile server can draw multiple tiles in parallel, which allows even more speedup.
(On the other hand, there are drawbacks - we have to basically re-implement every graph drawing algorithm inside this tile server, not being able to use any javascript API, except for very trivial things like coordinate grids.)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distributions
Hashes for croquis-0.1.0-cp39-cp39-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 061d3e04fbd7edc704782a060a5e85d2a41d3958f1f95a53a68fdb984fd3808f |
|
MD5 | f7711173027fb6dd7e36d03d3874b844 |
|
BLAKE2b-256 | 4be47a451be1bdfd8de1171d7ac51d47355a69c31a655419dc6082e623cad208 |
Hashes for croquis-0.1.0-cp39-cp39-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 162ad96769ca5c65cfa78fd98c98a3b9c73e4a626f8fcca47826c611ed2b6877 |
|
MD5 | 11089afef9c947dc315d6b32387dcb18 |
|
BLAKE2b-256 | f5b7d4e25956c74918192973c5438ff810d4b4dad578a099ea5046d52ae644b9 |
Hashes for croquis-0.1.0-cp38-cp38-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a38cfaea8fcf5856ba1d81d8a559c1fc34abaa72efdec45a9d188bf173bba645 |
|
MD5 | afee91477bd8206fe21258521c0dfe37 |
|
BLAKE2b-256 | 7ca2d0ab3477c6368852681f41e03f1f293b9ecdc389989d3f1a2234f82edd3c |
Hashes for croquis-0.1.0-cp38-cp38-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0eae3b7f2b1955d468378fb93903ce6ce7665062c6c3ca41cc57283456aafc68 |
|
MD5 | 2fa87e2ff9617aa4ca08d8242cd9ef64 |
|
BLAKE2b-256 | 8e25313be761d2fafe4810cb22d1dab46410f9e1bbd7f4631511e0edcee22500 |
Hashes for croquis-0.1.0-cp37-cp37m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5737815c52a706f87353ef078278e554181f9f0c8d8fdcf62d27a2de8de9ea21 |
|
MD5 | 87d8044ce8e470d753548c93c9b5d7fa |
|
BLAKE2b-256 | 5ab187434bfa0000731553ec483b80a3a1546fb7cf23e6dfd49f61f4192414a3 |
Hashes for croquis-0.1.0-cp37-cp37m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 890abd384c8e267235d3d4aa51c63f496c9d8ffa7297d5d8eeda9876f9f97498 |
|
MD5 | b3b83b50998bd76a95d651dc1bb92085 |
|
BLAKE2b-256 | 460635b285af51f987795a34f39cfe5ca14ded5c55476771929f1dd9f1b60d8d |
Hashes for croquis-0.1.0-cp36-cp36m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 37f55fd8ee30fe094ec0b2e07795b4b4c36d525c946e9cbbb65a08ce37a3f052 |
|
MD5 | a6481a6d0f0b493fc476e85dd86ffdc8 |
|
BLAKE2b-256 | 35ad736d857094ef28374f5091abe79b317017d83b38efaf4e8b4a378acd94db |
Hashes for croquis-0.1.0-cp36-cp36m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 20e18ac7590b9a4d38c613e55e942b5923e2e79486ff0f10635933fc147f68d5 |
|
MD5 | 62368c7be55bf5b0ab4ddc19c0eeb1a5 |
|
BLAKE2b-256 | 9d554df418b4031105a9c310a26705ec5b2d3512c8da3444525f29a6db3d5987 |