# BokehLab
BokehLab is an interactive plotting library with the familiar matplotlib/matlab syntax.
Built upon the [Bokeh](https://bokeh.org/) visualization library. Works with both classic Jupyter notebooks and JupyterLab.
## Installation:
pip install bokehlab
To load this extension in jupyter notebook (both classic jupyter and jupyter lab):
%load_ext bokehlab
Or even shorter:
%bokehlab
To make the short syntax working, either run
python -m bokehlab.install_magic
Or manually copy `bokelab_magic.py` from the distribution directory to `~\.ipython\profile_default\startup`.
## Basic plotting:
plot([1,4,9]) # dots
plot([1,4,9], '.-') # line and dots
plot([1,2,3], [1,4,9]) # x and y
plot([1,2,3], [1,4,9], '.-') # x, y and line style
## Several plots in one figure:
<img src="https://raw.githubusercontent.com/axil/bokehlab/master/img/simple.png" width="800">
## Interactive controls:
click and drag = pan
mouse wheel = zoom,
wheel on x axis = zoom horizontally
wheel on y axis = zoom vertically
## Multiple plots syntax (equivalent ways to draw it):
x = [1,5,10]
y1 = [1,4,9]
y2 = [1,8,27]
- plot(x, y1, '.-') # solid line with dots
plot(x, y2, '.-g') # the second plot is green
- plot([y1, y2]) # auto x, auto colors
- plot(x, [y1, y2])
- plot([y1, y2], '.-bg') # blue and green
- plot([y1, y2], style=['.', '.-'], color=['b', 'g'])
- plot(x, y1, '.-', x, y2, '.-g')
The following markers are supported so far:
'.' dots
'-' line
'.-' dots+line
The following colors are supported so far:
'b' blue
'g' green
'r' red
'O' orange (capital O to avoid clashes with 'o' for open dots)
NB The color specifier must go after the marker if both are present.
## Legend:
- plot([1,2,3], [1,4,9], label='plot1')
plot([1,2,3], [2,5,10], label='plot2')
- plot([y1, y2], label=['y1', 'y2'])
Legend location:
- plot([1,2,3], [1,4,9], label='plot1', legend_loc='top_left')
plot([1,2,3], [2,5,10], label='plot2')
<img src="https://raw.githubusercontent.com/axil/bokehlab/master/img/legend.png" width="800">
Other legend locations:
https://docs.bokeh.org/en/latest/docs/user_guide/styling.html#location
## Axes labels:
- plot([1,2,3], xlabel='time', ylabel='value')
- xlabel('time'); ylabel('value')
- xylabels('time', 'value')
## Other uses:
* `semilogx()`, `semilogy()` and `loglog()` show (semi)logarithmic plots with the same syntax as `plot()`.
* `hist(x)` displays a histogram of x
* `plot(x, y, hover=True)` displays point coordinates on mouse hover.
* `plot(x, y, vline=1, hline=1.5, vline_color='red')` in addition to the (x, y) plot displays an infinite vertical line with x=1 and custom red color and an infinite horizontal line with y=1.5 and the default pink color.
## Visualizing Pandas Dataframes
* `plot(df)` plots all columns of the dataframe as separate lines on the same figure with column names
displayed in the legend and with index taken as the x axis values. If the legend grows too long, it can
be hidden with `legend_loc='hide'` (new in v0.1.13):
<img src="https://raw.githubusercontent.com/axil/bokehlab/master/img/pandas.png" width="800">
* `show_df(df)` displays pandas dataframe as a table (new in v0.1.14):
<img src="https://raw.githubusercontent.com/axil/bokehlab/master/img/datatable.png" width="800">
## Displaying Images
* `imshow(a)` displays an array as an image:
<img src="https://raw.githubusercontent.com/axil/bokehlab/master/img/imshow.png" width="800">
Complete list of colormaps: [https://matplotlib.org/3.5.0/tutorials/colors/colormaps.html](https://matplotlib.org/3.5.0/tutorials/colors/colormaps.html)
* `imshow(im1, im2, ...)` shows several images side by side with linked panning and zooming (`link=False` to disable):
<img src="https://raw.githubusercontent.com/axil/bokehlab/master/img/two_images.png" width="800">
* `imshow([[im1, im2, ...], [im3, im4, ... ], ...])` displays a matrix of images with panning and zooming linked row-wise:
<img src="https://raw.githubusercontent.com/axil/bokehlab/master/img/imshow2x3.png" width="800">
See also a contour plot example in the bokeh gallery [page](https://docs.bokeh.org/en/latest/docs/gallery/image.html).
## Location of the JavaScript code
The Bokeh library consists of two parts: backend is written in Python, the frontend is in javascript.В
By default, Bokehlab (just like Bokeh) will get the required BokehJs code from the internet, from cdn.bokeh.org. This mode is called 'cdn' (=content delivery network). Generally it is fine, except that it doesn't work offline.
Another option is to bundle the javascript into the ipynb notebook:
%bokehlab inline
It is also ok, except that the size of the ipynb file grows by ~6Mb. It would look reasonable if it made notebook work on a computer without Bokeh installed, but in reality the python part is also essential for the plots to work, so basically it is just a waste of disk space.
Bokehlab introduces a third option:В
%bokehlab local
It serves javascript files from the locally installed Bokeh library. It both works offline and does not take any extra space. The only issue with this mode is that it needs a one-shot setup:
pip install bokeh-resources
python -m bokeh-resources.install
This mode can also be used in 'vanilla' Bokeh, see the instructions on github.
## Configuring the defaults
You can set the default size of the figure with %bokehlab_config magic command (or its shorter alias %blc):В
%blc width=500 height=200
This size will apply to all figures in the current notebook. To make this change permanent, use -g (or --global flag):
%blc -g width=500 height=200
It will save those values to ~/.bokeh/bokehlab.yaml and use them in the future Jupyter sessions.
You can also make Bokehlab remember your preferred mode of loading the javascript half of the library, so instead of always writing `%bokehlab local` in every ipynb file can do
%blc -g resources=local
and `%bokehlab` will use locally served resources from now on.
Config is also capable or 'memorizing' the repeated arguments to any of the commands described above. For example, to tell Bokehlab to use thicker lines:
%blc plot.line_width=2
and all subsequent calls to plot will assume line_width argument to be 2 (pixels) instead of one (this feature is work-in-progress, not all options are configurable yet).
To revert any configured option:
%blc -d plot.line_width
A list of currently active settings is displayed with
%blc
## Comparison to bokeh
Bokehlab is a thin wrapper over the excellent library `bokeh` primarily aimed at cutting down the amount of boilerplate code.
The following commands are equivalent:
<img src="https://raw.githubusercontent.com/axil/bokehlab/master/img/bokehlab_vs_bokeh.png" width="800">
Raw data
{
"_id": null,
"home_page": "https://github.com/axil/bokehlab",
"name": "bokehlab",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "bokeh,jupyter,notebook,plot,interactive",
"author": "Lev Maximov",
"author_email": "lev.maximov@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/dc/fe/a26bfb376e62da0e7bb0b31ef2dc034a298a723c1982053a7b827b84dbde/bokehlab-0.2.10.tar.gz",
"platform": null,
"description": "# BokehLab\r\n\r\nBokehLab is an interactive plotting library with the familiar matplotlib/matlab syntax. \r\nBuilt upon the [Bokeh](https://bokeh.org/) visualization library. Works with both classic Jupyter notebooks and JupyterLab.\r\n\r\n## Installation: \r\n\r\n pip install bokehlab\r\n\r\nTo load this extension in jupyter notebook (both classic jupyter and jupyter lab):\r\n\r\n %load_ext bokehlab\r\n\r\nOr even shorter:\r\n\r\n %bokehlab\r\n\r\nTo make the short syntax working, either run \r\n\r\n python -m bokehlab.install_magic\r\n\r\nOr manually copy `bokelab_magic.py` from the distribution directory to `~\\.ipython\\profile_default\\startup`.\r\n\r\n## Basic plotting:\r\n\r\n plot([1,4,9]) # dots \r\n plot([1,4,9], '.-') # line and dots \r\n plot([1,2,3], [1,4,9]) # x and y \r\n plot([1,2,3], [1,4,9], '.-') # x, y and line style\r\n\r\n## Several plots in one figure: \r\n\r\n<img src=\"https://raw.githubusercontent.com/axil/bokehlab/master/img/simple.png\" width=\"800\">\r\n\r\n## Interactive controls:\r\n\r\n click and drag = pan\r\n mouse wheel = zoom, \r\n wheel on x axis = zoom horizontally\r\n wheel on y axis = zoom vertically\r\n\r\n## Multiple plots syntax (equivalent ways to draw it):\r\n\r\n x = [1,5,10]\r\n y1 = [1,4,9]\r\n y2 = [1,8,27]\r\n\r\n - plot(x, y1, '.-') # solid line with dots\r\n plot(x, y2, '.-g') # the second plot is green\r\n\r\n - plot([y1, y2]) # auto x, auto colors \r\n\r\n - plot(x, [y1, y2])\r\n\r\n - plot([y1, y2], '.-bg') # blue and green\r\n\r\n - plot([y1, y2], style=['.', '.-'], color=['b', 'g'])\r\n\r\n - plot(x, y1, '.-', x, y2, '.-g')\r\n\r\n\r\nThe following markers are supported so far:\r\n\r\n '.' dots\r\n '-' line\r\n '.-' dots+line\r\n\r\nThe following colors are supported so far:\r\n\r\n 'b' blue\r\n 'g' green\r\n 'r' red\r\n 'O' orange (capital O to avoid clashes with 'o' for open dots)\r\n \r\nNB The color specifier must go after the marker if both are present.\r\n\r\n## Legend:\r\n\r\n - plot([1,2,3], [1,4,9], label='plot1')\r\n plot([1,2,3], [2,5,10], label='plot2')\r\n\r\n - plot([y1, y2], label=['y1', 'y2'])\r\n\r\nLegend location:\r\n\r\n - plot([1,2,3], [1,4,9], label='plot1', legend_loc='top_left')\r\n plot([1,2,3], [2,5,10], label='plot2')\r\n\r\n<img src=\"https://raw.githubusercontent.com/axil/bokehlab/master/img/legend.png\" width=\"800\">\r\n\r\nOther legend locations:\r\nhttps://docs.bokeh.org/en/latest/docs/user_guide/styling.html#location\r\n\r\n## Axes labels:\r\n \r\n - plot([1,2,3], xlabel='time', ylabel='value')\r\n - xlabel('time'); ylabel('value')\r\n - xylabels('time', 'value')\r\n\r\n## Other uses:\r\n\r\n* `semilogx()`, `semilogy()` and `loglog()` show (semi)logarithmic plots with the same syntax as `plot()`.\r\n\r\n* `hist(x)` displays a histogram of x\r\n\r\n* `plot(x, y, hover=True)` displays point coordinates on mouse hover.\r\n\r\n* `plot(x, y, vline=1, hline=1.5, vline_color='red')` in addition to the (x, y) plot displays an infinite vertical line with x=1 and custom red color and an infinite horizontal line with y=1.5 and the default pink color.\r\n\r\n## Visualizing Pandas Dataframes\r\n\r\n* `plot(df)` plots all columns of the dataframe as separate lines on the same figure with column names \r\ndisplayed in the legend and with index taken as the x axis values. If the legend grows too long, it can \r\nbe hidden with `legend_loc='hide'` (new in v0.1.13):\r\n<img src=\"https://raw.githubusercontent.com/axil/bokehlab/master/img/pandas.png\" width=\"800\">\r\n\r\n* `show_df(df)` displays pandas dataframe as a table (new in v0.1.14):\r\n<img src=\"https://raw.githubusercontent.com/axil/bokehlab/master/img/datatable.png\" width=\"800\">\r\n\r\n## Displaying Images\r\n\r\n* `imshow(a)` displays an array as an image:\r\n\r\n<img src=\"https://raw.githubusercontent.com/axil/bokehlab/master/img/imshow.png\" width=\"800\">\r\n\r\nComplete list of colormaps: [https://matplotlib.org/3.5.0/tutorials/colors/colormaps.html](https://matplotlib.org/3.5.0/tutorials/colors/colormaps.html)\r\n\r\n* `imshow(im1, im2, ...)` shows several images side by side with linked panning and zooming (`link=False` to disable):\r\n\r\n<img src=\"https://raw.githubusercontent.com/axil/bokehlab/master/img/two_images.png\" width=\"800\">\r\n\r\n* `imshow([[im1, im2, ...], [im3, im4, ... ], ...])` displays a matrix of images with panning and zooming linked row-wise:\r\n\r\n<img src=\"https://raw.githubusercontent.com/axil/bokehlab/master/img/imshow2x3.png\" width=\"800\">\r\n\r\nSee also a contour plot example in the bokeh gallery [page](https://docs.bokeh.org/en/latest/docs/gallery/image.html).\r\n\r\n## Location of the JavaScript code\r\n\r\nThe Bokeh library consists of two parts: backend is written in Python, the frontend is in javascript.\u0412\u00a0\r\n\r\nBy default, Bokehlab (just like Bokeh) will get the required BokehJs code from the internet, from cdn.bokeh.org. This mode is called 'cdn' (=content delivery network). Generally it is fine, except that it doesn't work offline.\r\n\r\nAnother option is to bundle the javascript into the ipynb notebook:\r\n\r\n %bokehlab inline\r\n\r\nIt is also ok, except that the size of the ipynb file grows by ~6Mb. It would look reasonable if it made notebook work on a computer without Bokeh installed, but in reality the python part is also essential for the plots to work, so basically it is just a waste of disk space.\r\nBokehlab introduces a third option:\u0412\u00a0\r\n\r\n %bokehlab local\r\n\r\nIt serves javascript files from the locally installed Bokeh library. It both works offline and does not take any extra space. The only issue with this mode is that it needs a one-shot setup:\r\n\r\n pip install bokeh-resources\r\n python -m bokeh-resources.install\r\n\r\nThis mode can also be used in 'vanilla' Bokeh, see the instructions on github.\r\n\r\n## Configuring the defaults\r\n\r\nYou can set the default size of the figure with %bokehlab_config magic command (or its shorter alias %blc):\u0412\u00a0\r\n\r\n %blc width=500 height=200\r\n\r\nThis size will apply to all figures in the current notebook. To make this change permanent, use -g (or --global flag):\r\n\r\n %blc -g width=500 height=200\r\n\r\nIt will save those values to ~/.bokeh/bokehlab.yaml and use them in the future Jupyter sessions.\r\n\r\nYou can also make Bokehlab remember your preferred mode of loading the javascript half of the library, so instead of always writing `%bokehlab local` in every ipynb file can do\r\n\r\n %blc -g resources=local\r\n\r\nand `%bokehlab` will use locally served resources from now on.\r\n\r\nConfig is also capable or 'memorizing' the repeated arguments to any of the commands described above. For example, to tell Bokehlab to use thicker lines:\r\n \r\n %blc plot.line_width=2\r\n\r\nand all subsequent calls to plot will assume line_width argument to be 2 (pixels) instead of one (this feature is work-in-progress, not all options are configurable yet).\r\n\r\nTo revert any configured option:\r\n\r\n %blc -d plot.line_width\r\n\r\nA list of currently active settings is displayed with\r\n\r\n %blc\r\n\r\n## Comparison to bokeh\r\n\r\nBokehlab is a thin wrapper over the excellent library `bokeh` primarily aimed at cutting down the amount of boilerplate code.\r\n\r\nThe following commands are equivalent:\r\n\r\n<img src=\"https://raw.githubusercontent.com/axil/bokehlab/master/img/bokehlab_vs_bokeh.png\" width=\"800\">\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Interactive plotting with familiar syntax in Jupyter notebooks.",
"version": "0.2.10",
"project_urls": {
"Homepage": "https://github.com/axil/bokehlab"
},
"split_keywords": [
"bokeh",
"jupyter",
"notebook",
"plot",
"interactive"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "66a59e0bb41ac44f1917e393b698ef5a07df913a813ff066449c123044bedc46",
"md5": "33580cac8aec011fa4c2aecb5212853f",
"sha256": "f51b7af8ba7972fd9b6400edc1cf84a748cd1c2f1576d0c36b4014ad8e1f2664"
},
"downloads": -1,
"filename": "bokehlab-0.2.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "33580cac8aec011fa4c2aecb5212853f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 23849,
"upload_time": "2023-07-28T16:52:51",
"upload_time_iso_8601": "2023-07-28T16:52:51.126677Z",
"url": "https://files.pythonhosted.org/packages/66/a5/9e0bb41ac44f1917e393b698ef5a07df913a813ff066449c123044bedc46/bokehlab-0.2.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dcfea26bfb376e62da0e7bb0b31ef2dc034a298a723c1982053a7b827b84dbde",
"md5": "8d334ca7babc9e5fe1ac2a3aafa4c5c9",
"sha256": "c0a4c7bb742e2ac41eeeabb64b46a3b394e9122b8f81c8860b2a7aa3bb18a090"
},
"downloads": -1,
"filename": "bokehlab-0.2.10.tar.gz",
"has_sig": false,
"md5_digest": "8d334ca7babc9e5fe1ac2a3aafa4c5c9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 25540,
"upload_time": "2023-07-28T16:52:53",
"upload_time_iso_8601": "2023-07-28T16:52:53.181287Z",
"url": "https://files.pythonhosted.org/packages/dc/fe/a26bfb376e62da0e7bb0b31ef2dc034a298a723c1982053a7b827b84dbde/bokehlab-0.2.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-28 16:52:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "axil",
"github_project": "bokehlab",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "bokehlab"
}
JSON
