xrview¶
Visualizing xarray data with bokeh.
The code is hosted on GitHub: https://github.com/phausamann/xrview
Installation¶
Latest release¶
xrview is currently unreleased, but can be installed from the GitHub
repository via pip:
$ pip install git+https://github.com/phausamann/xrview.git
This will also install the minimal dependencies for creating HTML plots.
Optional dependencies¶
For plotting in a jupyter notebook, you will also need the notebook and
requests packages:
$ pip install notebook requests
Bokeh server support depends on a specific version of tornado:
$ pip install tornado<=4.5.3
Usage¶
xrview provides several utilities for automatically creating interactive bokeh plots from xarray data types.
Basic plotting with HTML output¶
xrview.plot will create a plot of an xarray.DataArray or
Dataset given the name of the dimension that represents the x
coordinate in the plot.
All examples in this section assume the following imports:
>>> import numpy as np
>>> import xarray as xr
>>> import xrview
Minimal example¶
The following code will open a browser tab with the figure shown below.
>>> x = np.linspace(0, 1, 100)
>>> y = np.sqrt(x)
>>> da = xr.DataArray(y, {'x': x}, 'x')
>>> plot = xrview.plot(da, x='x')
>>> plot.show()
Overlaying and tiling plots¶
When passing a Dataset, each variable will be plotted in a separate figure.
If the variable has a second dimension, each element along this dimension will
be plotted as a separate line and a legend will be automatically created
based on the coordinates of this dimension.
>>> x = np.linspace(0, 1, 100)
>>> y = np.vstack([np.sqrt(x), x, x ** 2]).T
>>> ds = xr.Dataset({'Clean': (['x', 'f'], y),
... 'Noisy': (['x', 'f'], y + 0.01*np.random.randn(100, 3))},
... {'x': x, 'f': ['sqrt(x)', 'x', 'x^2']})
>>> plot = xrview.plot(ds, x='x', ncols=2)
>>> plot.show()
Alternatively, you can show the elements of the dimension in separate
figures and overlay the variables by specifying overlay='data_vars':
>>> plot = xrview.plot(ds, x='x', ncols=2, overlay='data_vars')
>>> plot.show()
You can add additional figures to the plot with the add_figure()
method by providing data as a DataArray. The DataArray has to contain a
coordinate with the same name as the x coordinate, but they do not need to
have the same values.
>>> da = xr.DataArray(np.ones(20), {'x': np.linspace(0, 1, 20)}, 'x')
>>> plot = xrview.plot(ds, x='x', ncols=2)
>>> plot.add_figure(da)
>>> plot.show()
Data can also be overlaid onto existing figures with the
add_overlay() method. With the onto parameter, you can select a
figure by index or title on which to overlay the data. By default, the data
will be overlaid onto all figures.
>>> plot = xrview.plot(ds, x='x', ncols=2)
>>> plot.add_overlay(da, onto='Clean')
>>> plot.show()
Customizing glyphs and annotations¶
xrview supports plotting with many of the standard bokeh glyphs as well as
some custom composite glyphs such as error bars and boxes for box plots.
Glyphs can be passed to plot(), add_overlay() and
add_figure() as strings, instances of a glyph class or iterables of
any combination of both. When you pass a glyph instance, you can specify
additional keyword arguments.
In this example, one array is plotted with circles and a second with a blue line and red squares:
>>> from xrview.glyphs import Square
>>> x = np.linspace(0, 1, 100)
>>> y = np.sqrt(x)
>>> da_sqrt = xr.DataArray(y, {'x': x}, 'x')
>>> da_const = xr.DataArray(np.ones(20), {'x': x[::5]}, 'x')
>>> plot = xrview.plot(da_sqrt, x='x', glyphs='circle')
>>> plot.add_overlay(da_const, glyphs=['line', Square(color='red')])
>>> plot.show()
xrview also provides a straightforward way of
Note
See Glyphs for a list of available glyphs.
Categorical and time series data¶
Fine-tuning bokeh figures¶
API Reference¶
Notebook¶
Module: xrview.notebook
Base class for notebook plots. |
|
A notebook grid plot. |
|
A notebook spacer. |
|
Base class for notebook viewers. |
|
A notebook time-series viewer. |
Glyphs¶
Module: xrview.glyphs
A line glyph. |
|
A circle glyph. |
|
A diamond glyph. |
|
A square glyph. |
|
A triangle glyph. |
|
A ray glyph. |
|
A horizontal bar glyph. |
|
A vertical bar glyph. |
|
A rectangle glyph. |
|
A whisker annotation. |
|
A band annotation. |
|
A collection of vertical lines. |
|
A line with an error bar. |
|
A circle with an error bar. |
|
A box-whisker glyph. |
Interactions¶
Module: xrview.interactions
A list widget for selecting unique values of a certain coordinate. |
Class member details¶
html¶
HtmlPlot¶
Plot modifiers¶
Add an annotation to a figure in the layout. |
|
Add a figure to the layout. |
|
Add an overlay to a figure in the layout. |
|
Modify the attributes of a figure. |
Show and export¶
Export the layout as as png or svg file. |
|
Show the plot in an HTML file. |
Internal¶
Create a copy of this instance. |
|
Make the document. |
|
Make the layout. |
notebook¶
NotebookPlot¶
Plot modifiers¶
Add an annotation to a figure in the layout. |
|
Add a figure to the layout. |
|
Add an overlay to a figure in the layout. |
|
Modify the attributes of a figure. |
Show and export¶
Export the layout as as png or svg file. |
|
Show the plot in a jupyter notebook. |
Internal¶
Create a copy of this instance. |
|
Make the document. |
|
Make the layout. |
NotebookViewer¶
Plot modifiers¶
Add an annotation to a figure in the layout. |
|
Add a figure to the layout. |
|
Add an interaction to the layout. |
|
Add an overlay to a figure in the layout. |
|
Modify the attributes of a figure. |
Show and export¶
Export the layout as as png or svg file. |
|
Show the app in a jupyter notebook. |
Internal¶
Create a copy of this instance. |
|
Make the document. |
|
Make the layout. |
|
Reset handlers. |
|
Update a single handler. |
|
Update handlers. |
|
Update this instance with the properties of another layout. |
Callbacks¶
Callback for reset event. |
|
Callback for selection event. |
NotebookTimeseriesViewer¶
Plot modifiers¶
Add an annotation to a figure in the layout. |
|
Add a figure to the layout. |
|
Add an interaction to the layout. |
|
Add an overlay to a figure in the layout. |
|
Modify the attributes of a figure. |
Show and export¶
Export the layout as as png or svg file. |
|
Show the app in a jupyter notebook. |
Internal¶
Create a copy of this instance. |
|
Make the document. |
|
Make the layout. |
|
Reset handlers. |
|
Update a single handler. |
|
Update handlers. |
|
Update this instance with the properties of another layout. |
Callbacks¶
Callback for reset event. |
|
Callback for selection event. |
|
Callback for xrange change event. |
Contributing¶
Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
You can contribute in many ways:
Types of Contributions¶
Report Bugs¶
Report bugs at https://github.com/phausamann/xrview/issues.
If you are reporting a bug, please include:
Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug.
Fix Bugs¶
Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.
Implement Features¶
Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.
Write Documentation¶
xrview could always use more documentation, whether as part of the official xrview docs, in docstrings, or even on the web in blog posts, articles, and such.
Submit Feedback¶
The best way to send feedback is to file an issue at https://github.com/phausamann/xrview/issues.
If you are proposing a feature:
Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that contributions are welcome :)
Get Started!¶
Ready to contribute? Here’s how to set up xrview for local development.
Fork the xrview repo on GitHub.
Clone your fork locally:
$ git clone git@github.com:your_name_here/xrview.git
Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:
$ mkvirtualenv xrview $ cd xrview/ $ python setup.py developCreate a branch for local development:
$ git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
When you’re done making changes, check that your changes all tests and linters with tox:
$ tox
To get tox, just pip install it into your virtualenv.
Commit your changes and push your branch to GitHub:
$ git add . $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-featureSubmit a pull request through the GitHub website.
Pull Request Guidelines¶
Before you submit a pull request, check that it meets these guidelines:
The pull request should include tests.
If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
The pull request should work for Python 3.6, 3,7 and 3.8. Check https://travis-ci.org/phausamann/xrview/pull_requests and make sure that the tests pass for all supported Python versions.
Deploying¶
A reminder for the maintainers on how to deploy. Make sure all your changes are committed (including an entry in HISTORY.rst). Then run:
$ bumpversion patch # possible: major / minor / patch
$ git push
$ git push --tags
Travis will then deploy to PyPI if tests pass.
Credits¶
Development Lead¶
Peter Hausamann <peter.hausamann@tum.de>
Contributors¶
None yet. Why not be the first?