Customizing Precipitation Intensity Range in plot_precip_field()

[rutkovskii]

Hello,

I am currently working with the code provided by @RubenImhoff, referenced in Issue #415. I noticed that PySTEPS uses a fixed range for precipitation intensity, which doesn't align well with my specific use case. My dataset, for instance, includes precipitation intensities ranging from 0 to 203.2 mm/h, which is beyond the default settings.

I am looking into modifying the precipfield.py to allow for customizable ranges that better represent different datasets.

In the code shared by @RubenImhoff, the colorbar is generated as follows:

###
# Set the colormap for the legend
###

color_list = ['lightgrey','lightskyblue','deepskyblue','blue','darkblue', 'yellow','gold','darkorange','red','darkred'] # 12
clevs = [0.1,0.5,1.0,1.6,2.5,4.0,6.4,10.0,16.0,25.0,40.0]  #13

cmap_name = 'my_list'

# Create the colormap
cmap = colors.ListedColormap(color_list)
cmap.set_over('darkmagenta')
cmap.set_under('white')

norm = colors.BoundaryNorm(clevs, cmap.N)

###
# Add a colorbar
###

bounds = [0.1,1,2.5,6.4,16,40]
cbaxes = fig.add_axes([0.45, 0.0, 0.3, 0.02])
cbar = fig.colorbar(cm.ScalarMappable(norm = norm, cmap = cmap), ax = ax27, cax = cbaxes, orientation = 'horizontal', fraction = 0.1, shrink = 0.5, anchor = (0.5, 1.0), panchor = (0.5, 0.0), ticks = bounds, extend = 'both', extendfrac = 'auto', spacing = 'uniform')
cbar.ax.set_xlabel(r'Rainfall intensity (mm h$^{-1}$)', fontsize = 37)
cbar.ax.tick_params(labelsize = 32)

Similarly to above, I can define custom cmap, norm, clevs, and clevs_str variables and pass them into the plot_precip_field() function. Of course, it requires more thinking and designing, but this is the thought in a nutshell.

Before proceeding, I wanted to check if there are any existing plans or ongoing efforts to introduce this kind of functionality. If so, are there specific aspects or edge cases that I should be aware of? If not, what additional features or considerations would you like to see included in this enhancement? I am also available to get on call to discuss this enhancement.

I'm eager to contribute to the PySTEPS project and enhance its utility, especially in a way that supports my thesis work. Any guidance or suggestions would be greatly appreciated!

[dnerini]

Hello @rutkovskii and thanks for your enthusiastic input

colorscales in plot_precip_fields are currently available as a set of precomputed and hardcoded options, see here

pysteps/pysteps/visualization/precipfields.py

Line 324 in ee60fa6

if colorscale == "BOM-RF3":

for example. Clearly, this is not ideal for both users (who have to stick to a limit range of options) and developers (who cannot easily introduce new ones).

I suppose one more general approach would be to give the option to pass a a tuple of (cmap, norm, clevs, clevs_str) (or even better, a class instance) instead of a string, which would then provide a way to pass any arbitrary colorscale, for example using the https://github.com/aperezhortal/cmap_builder developed by our @aperezhortal ;-)

We don't have any specific plan in this sense and we would welcome a contribution from your side!

[rutkovskii]

Sounds great. cmap_builder seems quite helpful.

Do you suggest creating a class around cmap_builder with cmap, norm, clevs, clevs_str properties, or would it be better to allow plot_precip_fields() to accept any custom class that provides these properties, regardless of whether it uses cmap_builder?

[dnerini]

Indeed, it's better to keep it simple and leave it to the user to define the custom colorbars, using cmap_builder or else. So accepting a simple class with those properties would be great.

[rutkovskii]

Having an example on creating the custom class (with cmap_builder) could be useful for future users.

Should I make one to be placed into the examples directory?
If so, should it be ipynb or py?
Maybe both with cmap_builder and without it?

[dnerini]

An example would be great!

I think it would fit best as a python script so that it'll get rendered in the gallery of examples in our documentation, but the problem with that is that you would have to install camp_builder globally, something I'm not sure we want to do. The jupyter notebook would probably be less visible, but would give you the option to install camp_builder locally on the collab session only

[rutkovskii]

I will do it the example the way you believe is the best.
I would agree – we should not update the pySTEPS to contain cmap_builder in its environment.

Therefore, I can make:

1. python script that uses creates cmap without cmap_builder.
2. colab/jupyter notebook that uses cmap_builder.

I can do both if it is reasonable.

[rutkovskii]

@dnerini I decided to omit the use of cmap_builder in the example.
It uses class PiecewiseNorm(Normalize): which removes ability to do cmap.set_over(),cmap.set_under(), cmap.set_bad()

From the docstring:

clip: bool
If True values falling outside the data_points range are mapped to 0 or 1,
whichever is closer, and masked values are set to 1.
If False masked values remain masked.

        Clipping silently defeats the purpose of setting the over, under, and
        masked colors in a colormap, so it is likely to lead to surprises;
        therefore the default is clip=False.

Original image:

Custom Config with cmap_builder AND specifying over, under, bad colors:

• You can see how the color of the lower threshold is used for the values below the lowest threshold, which we do not want for clarity and flexibility reasons.
  

Custom Config using the same colors as cmap_builder and specifying over, under, and bad colors:

[dnerini]

Hello @rutkovskii , thanks, lets keep it simple and do only the py example without cmap_builder

[rutkovskii]

@dnerini Do you have knowledge of where I may find a frame with high precipitation over 100 mm/hr?

[dnerini]

mmmh not sure if it reaches really 100 mm/h, but I'd say that among our example data, this one from BoM used in this example script reaches the highest intensities: https://pysteps.readthedocs.io/en/stable/auto_examples/plot_linear_blending.html#sphx-glr-auto-examples-plot-linear-blending-py

[rutkovskii]

@dnerini, I was wondering, on average, how long it usually takes for core developers to review and provide feedback on a contribution? Additionally, once a contribution is ready, do you typically merge it right away, or is there a waiting period?

I'm just trying to get an estimate of when this change might be available in the master branch, as I plan to use it as a library for my thesis work.

[dnerini]

#433 is been merged into master

[rutkovskii]

@dnerini I checked out the Example for plotting, I used geodata to represent US on the map and it appears that pySTEPS version that used for examples does not used cartopy leading to

/home/docs/checkouts/readthedocs.org/user_builds/pysteps/envs/latest/lib/python3.10/site-packages/pysteps/visualization/utils.py:439: UserWarning: cartopy package is required for the get_geogrid function but it is not installed. Ignoring geographical information.
  warnings.warn(

Wanted to bring that to you attention.

[dnerini]

hi @rutkovskii , thanks, yes, I'm aware, we consciously decided not to install cartopy during the build of the documentation, so that warning is expected