Interactive data visualization with python¶

Welcome! Looking for a fast and flexible visualization software? Here we present psyplot, an open source python project that mainly combines the plotting utilities of matplotlib and the data management of the xarray package and integrates them into a software that can be used via command-line and via a GUI!
The main purpose is to have a framework that allows a fast, attractive, flexible, easily applicable, easily reproducible and especially an interactive visualization of your data.
The ultimate goal is to help scientists in their daily work by providing a
flexible visualization tool that can be enhanced by their own visualization
scripts. psyplot
can be used via command line and with the
graphical user interface (GUI) from the
psyplot-gui module.
If you want more motivation: Have a look into the About psyplot section.
The package is very new and there are many features that will be included in the future. So we are very pleased for feedback! Please simply raise an issue on GitHub.
docs | |
---|---|
tests | |
package | |
implementations |
Documentation¶
About psyplot¶
Why psyplot?¶
When visualizing data, one always has to choose:
- Either create the plot with an intuitive graphical user interface (GUI) (e.g. panoply) but less options for customization and difficult to script
- or create the plot from the command line, e.g. via NCL, R or python with more possibilities for customization and scripting but also less intuitive
psyplot
wants to combine these two worlds: create a well-documented and
easy accessible framework to visualize data from a GUI and the command line
(and of course through a script).
There exists nothing like that. Of course you can also work with software like Paraview via the built-in python shell. But, if you really want to explore your data it is totally not straightforward to access and explore it from within such a software using numeric functions from numpy, scipy, etc.
Therefore I developed this modular framework that can create and customize plots efficiently with short and comprehensive commands, that can be accessed through a GUI (see Subprojects) and where you have always a comprehensive API to access your data.
Different from the usual use with matplotlib, which in the end most of the time results in copy-pasting parts of your code, this software is build on the don’t repeat yourself principle. Each of the small parts that make up a visualization, whether it is part of the data evaluation or of the appearance of the plot, psyplot puts it into a formatoption can be reused when it is needed.
Nevertheless, it’s again a new piece of software. Therefore, if you want to use it, for sure you need a bit of time to get comfortable with the framework. I promise to you, it’s worth it. So get started and please let me know if you have a different opinion.
About the author¶
I, (Philipp Sommer), work as a PhD student for climate modeling in the
Atmosphere-Regolith-Vegetation (ARVE) group in the Institute of Earth Surface
Dynamics (IDYST) at the University of Lausanne. During my time at the
Max-Planck-Institute for Meteorology I worked a lot with the
Max-Planck-Institute Earth-System-Model (MPI-ESM) and the ICON model
in the working group on Terrestrial Hydrology of Stefan Hagemann. This
included a lot of evaluation of climate model data. It finally gave the
motivation for the visualization framework psyplot
.
License¶
psyplot is published under the GNU General Public License v2.0
Installation¶
How to install¶
There basically four different methodologies for the installation. You should choose the one, which is the most appropriate solution concerning your skills and your usage:
- The simple installation
- Use standalone installers which will install all the necessary packages and modules. See Installation via standalone installers
- The intermediate installation
- For people coding in python, we recommend to install it through anaconda and the conda-forge channel (see Installation using conda) or, if you are not using anaconda, you can use pip (see Installation using pip)
- The developer installation
- Install it from source (see Installation from source)
Installation via standalone installers¶
![]() Windows
|
![]() Mac OS X
|
![]() Linux
|
---|---|---|
64-bit (bash installer) |
This section contains the necessary informations to install psyplot-conda, a standalone psyplot installation with the most important plugins and the graphical user interface (GUI).
Executables can be downloaded from the links above. Older versions are also available through the the releases page, nightly builds for Linux and OSX are available here.
The installer provided here contain all necessary dependencies for psyplot, psyplot-gui, psy-simple, psy-maps and psy-reg plus the conda package for managing virtual environments. These installers have been created using using the conda constructor package and the packages from the conda-forge channel.
The latest versions for the installers can be downloaded through the links at the top.
Files for all versions can be found in the psyplot-conda repository and explicitly on the releases page.
Note
Under Linux and MacOSX you can also use cURL
and to download the latest
installer. Just open a terminal and type
curl -o psyplot-conda.sh -LO `curl -s https://api.github.com/repos/Chilipp/psyplot-conda/releases/latest | grep browser_download_url | cut -d '"' -f 4 | grep OSNAME` | grep .sh
where OSNAME
is one of Linux
or MacOSX
.
Then install it simply via
bash psyplot-conda.sh
Installation on Linux¶
Download the bash script (file ending on '.sh'
for linux) from
the releases page and open a terminal window.
Type:
bash '<path-to-the-downloaded-file.sh>'
and simply follow the instructions.
For more information on the command line options type:
bash '<Path-to-the-downloaded-file.sh>' --help
It will ask you, whether you want to add a psyplot
alias to your
.bashrc
, such that you can easily start the terminal and type
psyplot
to start the GUI. You can avoid this by setting
NO_PSYPLOT_ALIAS=1
. Hence, to install psyplot-conda
without any
terminal interaction, run:
NO_PSYPLOT_ALIAS=1 bash '<Path-to-the-downloaded-file.sh>' -b -p <target-path>
Installation on OS X¶
You can either install it from the terminal using a
bash-script (.sh
file),
or you can install a standalone app using an
installer (.pkg
file).
The bash script will install a conda installation in your desired location.
Both will create a Psyplot.app
(see below).
This should be straight-forward, however Apple does not provide free Developer IDs for open-source developers. Therefore our installers are not signed and you have to give the permissions to open the files manually. The 4 steps below describe the process.
Just download the
.pkg
fileTo open it, you have to
Right-click on the file →
Open With
→Installer
. In the appearing window, click theOpen
button.Follow the instructions. It will create a
Psyplot.app
in the specified location.To open the app the first time, change to the chosen installation directory for the App (by default
$HOME/Applications
), right-click thePsyplot
app and click onOpen
. In the appearing window, again click onOpen
.
Download the bash script (file ending on '.sh'
for MacOSX) from
the releases page and open a terminal window.
Type:
bash '<path-to-the-downloaded-file.sh>'
and simply follow the instructions.
For more informations on the command line options type:
bash '<Path-to-the-downloaded-file.sh>' --help
By default, the installer asks whether you want to install a Psyplot.app
into your Applications
directory. You can avoid this be setting
NO_PSYPLOT_APP=1
.
Furthermore it will ask you, whether you want to add a psyplot
alias to
your .bash_profile
, such that you can easily start the terminal and type
psyplot
to start the GUI. You can avoid this by setting
NO_PSYPLOT_ALIAS=1
. Hence, to install psyplot-conda
without any
terminal interaction, run:
NO_PSYPLOT_APP=1 NO_PSYPLOT_ALIAS=1 bash '<Path-to-the-downloaded-file.sh>' -b -p <target-path>
Installation on Windows¶
Just double click the downloaded file and follow the instructions. The installation will create an item in the windows menu (Start -> Programs -> Psyplot) which you can use to open the GUI. You can, however, also download installers that create no shortcut from the releases page.
In any case, if you chose to modify your PATH
variable during the
installation, you can open a command window (cmd
) and type psyplot
.
Installation using conda¶
We highly recommend to use conda for installing psyplot. Here you can install it via manually via the conda-forge channel or you can use one of our preconfigured environment files.
Manual installation¶
After downloading the installer from anaconda, you can install psyplot simply via:
$ conda install -c conda-forge psyplot
However, this only installs the raw framework. For your specific task, you should consider one of the below mentioned plugins (see Optional dependencies).
If you want to be able to read and write netCDF files, you can use for example the netCDF4 package via:
$ conda install netCDF4
If you want to be able to read GeoTiff Raster files, you will need to have gdal installed:
$ conda install gdal
Please also visit the xarray installation notes for more informations on how to best configure the xarray package for your needs.
Preconfigured environments¶
There are also some preconfigured environments that you can download which allow an efficient handling of netCDF files and the visualization of data on a globe.
Those environments are
psyplot and psy-maps with netCDF4, dask and bottleneck
. This environment contains the recommended modules to view geo-referenced netCDF files without a GUIpsyplot with graphical user interface and the above packages
. The same environment as above plus graphical user interface
After you downloaded one of the files, you can create and activate the new virtual environment via:
$ conda env create -f <downloaded file>
$ source activate psyplot
Installation using pip¶
If you do not want to use conda for managing your python packages, you can also
use the python package manager pip
and install via:
$ pip install psyplot
However to be on the safe side, make sure you have the Dependencies installed.
Installation from source¶
To install it from source, make sure you have the Dependencies installed, clone the github repository via:
git clone https://github.com/Chilipp/psyplot.git
and install it via:
python setup.py install
Dependencies¶
Required dependencies¶
Psyplot has been tested for python 2.7, 3.4, 3.5 and 3.6. Furthermore the package is built upon multiple other packages, mainly
- xarray>=0.8: Is used for the data management in the psyplot package
- matplotlib>=1.4.3: The python visualiation package
- PyYAML: Needed for the configuration of psyplot
Optional dependencies¶
We furthermore recommend to use
- psyplot-gui: A graphical user interface to psyplot
- psy-simple: A psyplot plugin to make simple plots
- psy-maps: A psyplot plugin for visualizing data on a map
- psy-reg: A psyplot plugin for visualizing fits to your data
- cdo: The python bindings for cdos (see also the cdo example)
Running the tests¶
We us pytest to run our tests. So you can either run clone out the github repository and run:
$ python setup.py test
or install pytest by yourself and run
$ py.test
To also test the plugin functionality, install the psyplot_test
module in
tests/test_plugin
via:
$ cd tests/test_plugin && python setup.py install
and run the tests via one of the above mentioned commands.
Building the docs¶
To build the docs, check out the github repository and install the
requirements in 'docs/environment.yml'
. The easiest way to do this is via
anaconda by typing:
$ conda env create -f docs/environment.yml
$ source activate psyplot_docs
Then build the docs via:
$ cd docs
$ make html
Note
The building of the docs always preprocesses the examples. You might want to
disable that by setting process_examples = False
. Otherwise please note
that the examples are written as python3 notebooks. So if you are using
python2, you may have to install the python3 kernel. Just create a new
environment 'py35'
and install it for IPython via:
conda create -n py35 python=3.5
source activate py35
conda install notebook ipykernel
ipython kernel install --user
You then have to install the necessary modules for each of the examples in
the new 'py35'
environment.
Uninstallation¶
The uninstallation depends on the system you used to install psyplot. Either you did it via the standalone installers (see Uninstalling standalone app), via conda (see Uninstallation via conda), via pip or from the source files (see Uninstallation via pip).
Anyway, if you may want to remove the psyplot configuration files. If you did
not specify anything else (see psyplot.config.rcsetup.psyplot_fname()
),
the configuration files for psyplot are located in the user home directory.
Under linux and OSX, this is $HOME/.config/psyplot
. On other platforms it
is in the .psyplot
directory in the user home.
Uninstalling standalone app¶
The complete uninstallation requires three steps:
- Delete the files (see the OS specific steps below)
- Unregister the locations from your
PATH
variable (see below)
Uninstallation on Linux¶
Just delete the folder where you installed psyplot-conda
. By default, this
is $HOME/psyplot-conda
, so just type:
rm -rf $HOME/psyplot-conda
If you added a psyplot
alias to your .bashrc
(see
installation instructions) or chose to add the
bin
directory to your PATH
variable during the installation, open your
$HOME/.bashrc
in an editor of your choice and delete those parts.
Uninstallation on OSX¶
The uninstallation depends on whether you have used the package installer or the bash script for the installation.
Just delete the app from your Applications
folder. There have been no
changes made to your PATH
variable.
As for linux, just delete the folder where you
installed psyplot-conda
. By default, this is $HOME/psyplot-conda
.
Open a terminal and just type:
rm -rf $HOME/psyplot-conda
If you added a psyplot
alias to your .bash_profile
(see
installation instructions) or chose to add the
bin
directory to your PATH
variable during the installation, open your
$HOME/.bash_profile
in an editor of your choice and delete those parts.
If you chose to add a Psyplot
app, just delete the symbolic link in
/Applications
or $HOME/Applications
.
Uninstallation on Windows¶
Just double-click the Uninstall-Anaconda.exe
file in the directory where
you installed psyplot-conda
and follow the instructions.
This will also revert the changes in your PATH
variable.
Uninstallation via conda¶
If you installed psyplot via conda, simply run:
conda remove psyplot
If you however installed it via a preconfigured environment (see Preconfigured environments), you can simply remove the entire virtual environment via:
conda env remove -n psyplot
Getting started¶
Initialization and interactive usage¶
This section shall introduce you how to read data from a netCDF file and visualize it via psyplot. For this, you need to have netCDF4 and the psy-maps psyplot plugin to be installed (see Installation).
Furthermore we use the demo.nc
netCDF file for our
demonstrations.
Note
We recommend to either run this example using our GUI. However, you can also either use IPython from the terminal via
conda install ipython # or pip install ipython
ipython # starts the ipython console
and copy-paste the commands in this example, or you use a jupyter notebook via
conda install jupyter # or pip install jupyter
jupyter notebook # starts the notebook server
Then create a new notebook in the desired location and copy-paste the examples below. If you want, we also recommend to include the following commands in the notebook
import psyplot.project as psy
# show the figures inline in the notebook and not in a separate window
%matplotlib inline
# don't close the figures after showing them, because than the update
# would not work
%config InlineBackend.close_figures = False
# show the figures after they are drawn or updated. This is useful
# for the visualization in the jupyter notebook
psy.rcParams['auto_show'] = True
After you installed psyplot, you can import the package via
In [1]: import psyplot
Psyplot has several modules and subpackages. The main module for the use of
psyplot is the project
module.
In [2]: import psyplot.project as psy
Plots can be created using the attributes of the plot
instance of
the ProjectPlotter
.
Each new plugin defines several plot methods. In case of the psy-maps package, those are
In [3]: psy.plot.show_plot_methods()
barplot
Make a bar plot of one-dimensional data
combined
Plot a 2D scalar field with an overlying vector field
density
Make a density plot of point data
fldmean
Calculate and plot the mean over x- and y-dimensions
lineplot
Make a line plot of one-dimensional data
mapcombined
Plot a 2D scalar field with an overlying vector field on a map
mapplot
Plot a 2D scalar field on a map
mapvector
Plot a 2D vector field on a map
plot2d
Make a simple plot of a 2D scalar field
vector
Make a simple plot of a 2D vector field
violinplot
Make a violin plot of your data
So to create a simple 2D plot of the temperature field 't2m'
, you can
type
In [4]: p = psy.plot.mapplot('demo.nc', name='t2m')

Note
If you’re not using the GUI, you have to
call the show()
method to display the plot, i.e. just run
p.show()
Now you created your first project
In [5]: p
Out[5]: psyplot.project.Project([ arr0: 2-dim DataArray of t2m, with (lat, lon)=(96, 192), lev=100000.0, time=1979-01-31T18:00:00])
which contains the xarray.DataArray
that stores the data and the
corresponding plotter that visualizes it
In [6]: p[0]
Out[6]:
<xarray.DataArray 't2m' (lat: 96, lon: 192)>
array([[251.41689, 251.454 , 251.48915, ..., 251.29774, 251.33876, 251.37978],
[254.16493, 254.33095, 254.50087, ..., 253.54774, 253.76845, 253.96376],
[255.86024, 256.3114 , 256.72742, ..., 254.40712, 254.90517, 255.42665],
...,
[263.70984, 263.6454 , 263.58875, ..., 263.96375, 263.86804, 263.78406],
[262.4989 , 262.48718, 262.47742, ..., 262.5536 , 262.5321 , 262.51453],
[260.8485 , 260.8661 , 260.88367, ..., 260.79578, 260.81335, 260.83093]],
dtype=float32)
Coordinates:
* lon (lon) float64 0.0 1.875 3.75 5.625 7.5 9.375 11.25 13.12 15.0 ...
* lat (lat) float64 88.57 86.72 84.86 83.0 81.13 79.27 77.41 75.54 ...
lev float64 1e+05
time datetime64[ns] 1979-01-31T18:00:00
Attributes:
long_name: Temperature
units: K
code: 130
table: 128
grid_type: gaussian
In [7]: type(p[0].psy.plotter)