pygmt.show_versions should warn if incompatible packages are installed

[cuitianyu20]

Description of the problem

When I use the pygmt.Figure.plot command to draw a filled shaded region with a rectangle, I find that regardless of whether I set the transparency to 80 or 100, the effect is always opaque. Transparency doesn't seem to work. (I've output files in both PNG and PDF formats).
test.pdf

My PyGMT version is 0.10.0.

Minimal Complete Verifiable Example

fig = pygmt.Figure()
fig.basemap(region=[-3,4,10,20], 
        projection="X5i/5i",
        frame=['xa1f0.5+l"Time (s)"', 'ya1f0.5+l"Distance (\260)"', "WSen"])
region_data = [[-1,10],[1,10],[1,20],[-1,20]]
fig.plot(data=region_data, fill='#66BFBF', transparency=90, close=True)
fig.savefig('test.pdf')
fig.savefig('test.png')

Full error message

The transparency in `pygmt.Figure.plot` command doesn't work.

System information

PyGMT information:
  version: v0.10.0
System information:
  python: 3.9.15 | packaged by conda-forge | (main, Nov 22 2022, 15:55:03)  [GCC 10.4.0]
  executable: /home/tianyu/anaconda3/envs/pygmt/bin/python
  machine: Linux-5.15.0-105-generic-x86_64-with-glibc2.31
Dependency information:
  numpy: 1.23.5
  pandas: 1.5.2
  xarray: 2022.11.0
  netCDF4: 1.6.2
  packaging: 21.3
  contextily: None
  geopandas: None
  IPython: None
  rioxarray: None
  ghostscript: 10.03.0
GMT library information:
  binary version: 6.4.0
  cores: 6
  grid layout: rows
  image layout: 
  library path: /home/*/anaconda3/envs/pygmt/lib/libgmt.so
  padding: 2
  plugin dir: /home/*/anaconda3/envs/pygmt/lib/gmt/plugins
  share dir: /home/*/anaconda3/envs/pygmt/share/gmt
  version: 6.4.0

[welcome]

👋 Thanks for opening your first issue here! Please make sure you filled out the template with as much detail as possible. You might also want to take a look at our contributing guidelines and code of conduct.

[seisman]

Transparency doesn't work for the combination of GMT 6.4.0 + Ghostscript 10.03.0. Please upgrade your GMT to 6.5.0 instead. Also please note that PyGMT v0.12.0 has been released.

[seisman]

@GenericMappingTools/pygmt-maintainers

We already know that some combinations of GMT versions and Ghostscript versions are problematic. I don't think we want to check the GMT/Ghostscript versions when Figure.savefig or Figure.show is called, as the check will cause performance regression. Instead, we can raise a warning when pygmt.show_versions is called, so that users can learn that their GMT/Ghostscript versions are problematic. Thoughts?

[cuitianyu20]

Transparency doesn't work for the combination of GMT 6.4.0 + Ghostscript 10.03.0. Please upgrade your GMT to 6.5.0 instead. Also please note that PyGMT v0.12.0 has been released.

Thanks, I will try to upgrade my GMT and PyGMT versions.

[cuitianyu20]

@GenericMappingTools/pygmt-maintainers

We already know that some combinations of GMT versions and Ghostscript versions are problematic. I don't think we want to check the GMT/Ghostscript versions when Figure.savefig or Figure.show is called, as the check will cause performance regression. Instead, we can raise a warning when pygmt.show_versions is called, so that users can learn that their GMT/Ghostscript versions are problematic. Thoughts?

Yes, I completely agree with this idea. I often overlooked this step when installing PyGMT. There is also pygmt.show_versions in the end of the PyGMT installation guide, I think if you can add a short note about these conflicts near the pygmt.show_versions. Of course, it's just a simple idea!

[seisman]

I'm looking at some old issue reports and discussions in the GMT repository and trying to summarize the known facts about faulty ghostscript + GMT versions:

1. GMT 6.3/6.4 + Ghostscript 10 doesn't support transparency Update psconvert to handle gs version 10 gmt#7096
2. Gs 10.00 and 10.01.2 are buggy: New gs 10.01.0 from brew yields many subtle failures gmt#7336 (comment), but gs 10.02 look good New gs 10.01.0 from brew yields many subtle failures gmt#7336 (comment).
3. gs 10.03 is the latest version and is good, since no one complains about it.
4. gs 9.56 is the latest version of gs 9, and it's good.
5. gs 9.53-9.56 should be good per Better warnings for faulty gs gmt#3282 (comment)
6. gs 9.51 and 9.52 are faulty Better warnings for faulty gs gmt#3282 (comment)
7. gs 9.50 should be good transparency problem gmt#3798 (comment)
8. gs 9.27 is buggy GhostScript 9.27 released with yet another bug gmt#880

gs 9.53 was released in 2020, so I guess that no one is using such old versions.

Based on the above facts and that PyGMT supports GMT>=6.3, I think we should warn in the following cases:

1. gs < 9.53: too old and some versions are known to have bugs
2. gs 9.53-9.56: Good
3. gs 10.00/10.01: buggy
4. gs 10.02/10.03: good but should warn for GMT<=6.4

[cuitianyu20]

I'm looking at some old issue reports and discussions in the GMT repository and trying to summarize the known facts about faulty ghostscript + GMT versions:

1. GMT 6.3/6.4 + Ghostscript 10 doesn't support transparency Update psconvert to handle gs version 10 gmt#7096
2. Gs 10.00 and 10.01.2 are buggy: New gs 10.01.0 from brew yields many subtle failures gmt#7336 (comment), but gs 10.02 look good New gs 10.01.0 from brew yields many subtle failures gmt#7336 (comment).
3. gs 10.03 is the latest version and is good, since no one complains about it.
4. gs 9.56 is the latest version of gs 9, and it's good.
5. gs 9.53-9.56 should be good per Better warnings for faulty gs gmt#3282 (comment)
6. gs 9.51 and 9.52 are faulty Better warnings for faulty gs gmt#3282 (comment)
7. gs 9.50 should be good transparency problem gmt#3798 (comment)
8. gs 9.27 is buggy GhostScript 9.27 released with yet another bug gmt#880

gs 9.53 was released in 2020, so I guess that no one is using such old versions.

Based on the above facts and that PyGMT supports GMT>=6.3, I think we should warn in the following cases:

1. gs < 9.53: too old and some versions are known to have bugs
2. gs 9.53-9.56: Good
3. gs 10.00/10.01: buggy
4. gs 10.02/10.03: good but should warn for GMT<=6.4

Absolutely agree with you! Thanks for giving these warnings in the PyGMT, and I think these warnings will be useful for choosing the appropriate PyGMT and gs versions to use.

[yvonnefroehlich]

@GenericMappingTools/pygmt-maintainers

We already know that some combinations of GMT versions and Ghostscript versions are problematic. I don't think we want to check the GMT/Ghostscript versions when Figure.savefig or Figure.show is called, as the check will cause performance regression. Instead, we can raise a warning when pygmt.show_versions is called, so that users can learn that their GMT/Ghostscript versions are problematic. Thoughts?

I also started wondering whether it makes sense to add somewhere a note or warning regarding this transparency-GMT-ghostscript issue, after several reports on GitHub and the GMT forum.

As running pygmt.show_versions is recommended after the installation of PyGMT, at least the users who do this will directly see if there is a GMT-ghostscript incompatibility. Also when reporting bugs, the output of pygmt.show_versions should be reported. So, adding such a warning to pygmt.show_versions makes sense to me.

Maybe we can add additionally a note under the common-installation-issues section?

Do we need a reminder in the release checklist regarding updating this warning before each release?

[seisman]

Maybe we can add additionally a note under the common-installation-issues section?

That's a very good point! I think we also should update the "Get Started" test (https://www.pygmt.org/dev/#getting-started) to add a transparency element.

import pygmt
fig = pygmt.Figure()
fig.coast(projection="H10c", region="g", frame=True, land="gray")
fig.show()

Do we need a reminder in the release checklist regarding updating this warning before each release?

Makes sense to me.

[yvonnefroehlich]

I think we also should update the "Get Started" test (https://www.pygmt.org/dev/#getting-started) to add a transparency element.

I was just thinking about such a modification of the current example. I prefer to have an example from which the user can see directly that there is an error regarding the transparency. So far, I wrote two different examples, but I am not 100 % happy. For the first example, I feel a not working transparency is not directly visible, as the figure does not look really wrong. The second example is somehow constructed. Maybe we have to add a sentence as explanation?

import pygmt

# (I) (a) Test if transparency is working
fig = pygmt.Figure()
fig.basemap(projection="N10c", region="g", frame="afg30")
fig.coast(land="tan", water="lightblue@50")
fig.show()

# (I) (b) Simulate NOT working transparency
fig = pygmt.Figure()
fig.basemap(projection="N10c", region="g", frame="afg30")
fig.coast(land="tan", water="lightblue")
fig.show()

# -----------------------------------------------------------------------------

# (II) (a) Test if transparency is working
fig = pygmt.Figure()
fig.coast(projection="N10c", region="g", land="tan", water="lightblue", frame=True)
fig.coast(land="white@99", water="white@99")
fig.show()

# (II) (b) Simulate NOT working transparency
fig = pygmt.Figure()
fig.coast(projection="N10c", region="g", land="tan", water="lightblue", frame=True)
fig.coast(land="white", water="white")
fig.show()

(I) (a) working transparncy	(I) (b) NOT working transparency

(II) (a) working transparncy	(II) (b) NOT working transparency

[seisman]

I was thinking about an example like:

import pygmt

fig = pygmt.Figure()
fig.coast(projection="N10c", region="g", frame=True, land="tan", water="lightblue")
fig.text(position="MC", text="PyGMT", font="60p,Helvetica-Bold,red@75")
fig.show()

[yvonnefroehlich]

I was thinking about an example like:

import pygmt

fig = pygmt.Figure()
fig.coast(projection="N10c", region="g", frame=True, land="tan", water="lightblue")
fig.text(position="MC", text="PyGMT", font="60p,Helvetica-Bold,red@75")
fig.show()

The text looks cool with the transparency effect 😀!
However, I see again the issue that the figure does not really look wrong in case the transparency is not working. So we probably need to add a comment on what users should focus, as new users are probably unfamiliar with creating transparency in [Py]GMT.

working transparncy	NOT working transparency

[seisman]

However, I see again the issue that the figure does not really look wrong in case the transparency is not working. So we probably need to add a comment on what users should focus, as new users are probably unfamiliar with creating transparency in [Py]GMT.

Yes, we need a sentence explaining what the users are expected to see.

Your two examples are also technically correct, but for (I), users are expected to see gridlines but new users may have no ideas about what gridlines means in GMT/PyGMT; for (II), using two Figure.coast calls looks weird.

[seisman]

Maybe we can add additionally a note under the common-installation-issues section?

That's a very good point! I think we also should update the "Get Started" test (https://www.pygmt.org/dev/#getting-started) to add a transparency element.

import pygmt
fig = pygmt.Figure()
fig.coast(projection="H10c", region="g", frame=True, land="gray")
fig.show()

Do we need a reminder in the release checklist regarding updating this warning before each release?

Makes sense to me.

@yvonnefroehlich Do you want to work on it?

[yvonnefroehlich]

import pygmt

fig = pygmt.Figure()
fig.coast(projection="N10c", region="g", frame=True, land="tan", water="lightblue")
fig.text(position="MC", text="PyGMT", font="60p,Helvetica-Bold,red@75")
fig.show()

Maybe we can add additionally a note under the common-installation-issues section?

That's a very good point! I think we also should update the "Get Started" test (https://www.pygmt.org/dev/#getting-started) to add a transparency element.

import pygmt
fig = pygmt.Figure()
fig.coast(projection="H10c", region="g", frame=True, land="gray")
fig.show()

Do we need a reminder in the release checklist regarding updating this warning before each release?

Makes sense to me.

@yvonnefroehlich Do you want to work on it?

Yes, I like to work on this. I just submitted PR #3249; will do the remain aspects in then next (hopefully two) days.