Issue #17: Visualisation Module: General Aspects (wradlib/wradlib)

[Kai Mühlbauer]

New issue 17: Visualisation Module: General Aspects
https://bitbucket.org/wradlib/wradlib/issue/17/visualisation-module-general-aspects

Kai Mühlbauer:

While working on the new plot_cg_ functions and trying to understand the doc sphinx thing, I stumbled across several inconsistencies in the wradlib.vis module and the accompanying examples, tutorials and even io.routines.

So the status I gathered from the sources is as follows:

* All plot routines which plot cartesian data to a cartesian grid are of status "deprecated".
* Only one special function `plot_max_plan_and_vert` can plot xy-gridded data
* In the documentation as well as in the examples section, functions like `cartesian_plot` are used
* There are also remnants of a implementation of plotting to a map (PolarBasemap) in the examples
* wradlib.io can read cartesian gridded data (DWD RX etc.)
* several times throughout wradlib data is kind of converted to cartesian grid (eg. `CAPPI`)

For cleaning this whole thing up, there should be discussed first what plotting functionality is needed and (of course) wanted.

So from my perspective I see this points to work on:

* simple plotting routine for cartesian data (with projection cababilities), using the deprecated functions to begin with
* Basemap functionality or something similar
* cleaning up examples and documentation
* to be continued

When agreed I will start a discussion thread on the dev-list or on the user-list. What do you think?

[Maik Heistermann]

Dear Kai,

thanks for pointing out these issues.

Just some quick explanations and comments:

Just recently, I discussed with Thomas (and here I am already punished
for not having this discussion via wradlib-dev) how we should proceed
with the cartesian plot functions, most importantly the class
CartesianPlot and the corresponding convenience function
cartesian_plot. We agreed that these functions do not really add value
anymore. Their core basically is a call to pcolormesh, and our
understanding was that this would not need a special wradlib interface.

We thought that it would be more appropriate to provide a tutorial or
a recipe on how to plot data on Cartesian grids using standard
matplotlib funcionalities.

I am very grateful to you for pointing out inconsistencies in the
examples. Basemap is another related issue: Once upon a time, we
carried Basemap as a wradlib dependency and also had corresponding
functions in the vis module. Then we decided to remove Basemap as a
dependency (because it is so bulky and not a standard package in
Python(x,y)), but obviously, I did not clean up the examples. Here,
again, our idea was to provide a recipe on how to plot over maps using
Basemap.

So I guess your suggestions are all pointing in the right direction:

First question should be: Do we want to have a convenience funciton in
wradlib.vis that allows for plotting Cartesian grids? I say no. I
would also vote against making Basemap a part of wradlib, again.

So my suggestion would be the following:

- clean up documentation and all examples. Remove examples that use
deprecated function or even functions that do no onger exist.

- add a tutorial/recipe on how to use matplotlib to plot Cartesian grids

- add a tutorial/recipe on how to use Basemap to plot over maps

I am not so sure on how to proceed with vis.plot_plan_and_vert because
this function provides a little non-standard functionality by allowing
to plot a CAPPI together with vertical cross-sections along both
horizontal axes. One might argue that users could construct something
like this by themselves and we should only provide guidance on that.
One could also argue that it is a useful service to the users to
provide this function, but that it might need some clean-up and
streamlining.

One word about the difference between tutorials and recipes (they also
have different sections in the documentation). We thought that a
tutorial would be a little more systematic introduction into a
specific topic, including also a lot of guidance and explanation. A
recipe, in constrast, would only contain a short header which explains
what the recipe is about, and the rest would be a reference to a more
or less self-explaining Python script.

Altogether, this discussion again proves the need for testing and
automatic deployment...

Ok, that much from me.

Bests,
Maik

> --
> You received this message because you are subscribed to the Google
> Groups "wradlib-dev" group.
> To unsubscribe from this group and stop receiving emails from it,
> send an email to wradlib-dev...@googlegroups.com.
> For more options, visit https://groups.google.com/groups/opt_out.
>



--
Dr. Maik Heistermann
Universität Potsdam
Institut für Erd- und Umweltwissenschaften
Karl-Liebknecht-Str. 24-25
14476 Potsdam-Golm
phone: +49 331 977 2671

[Kai Muehlbauer]

Thanks Maik for summing up on that issue!

I very much agree with your suggestions.

While digging deeper into the documentation/testing stuff, I will go
over my contributions once more and come up at least with documentation,
tutorials/recipies and examples. Don't know if testing is of much use in
plotting routines.

I thought of using the plot examples/tutorials/recipies as testing for
plots. The created images are then bound into the belonging tutorials
and recipies for the documentation.

Cheers,
Kai

P.S.

Which docstring style should we use? I found that the sphinx markup is
somewhat different from the used one. It depends on how the final doc
should look alike.

--
Kai Muehlbauer
Meteorological Institute University of Bonn
Auf dem Huegel 20 | +49 228 739083
D-53121 Bonn | kai.mue...@uni-bonn.de

[Thomas Pfaff]

Hello Kai,

so far we use the numpydoc docstring style that is used by numpy and scipy.

We'll have to be careful with incorporating plots. They are large (compared with the code files) and as binary files don't work well with version control.
The matplotlib-guys seem to have found a way to make Sphinx create plots based on the code inside a documentation file.
The price of contributor of the month would definitely be yours, if you could figure out how that works :-)

Cheers


Thomas

[Kai Muehlbauer]

Hello Thomas,

OK so its numpydoc for the docstrings. To get this right, for the
tutorials its normal "reStructuredText"? Am I correct?

Keep you postet on that figure stuff ;-)

Cheers,
Kai

[Thomas Pfaff]

correct.

[Kai Muehlbauer]

Hi Thomas,

https://bitbucket.org/wradlib/wradlib/pull-request/19/tutorial-on-automagic-applying-images-in

Do you had this in mind?

Cheers,
Kai

Am 05.03.2014 15:05, schrieb Thomas Pfaff: