In some functions, G is aliased as "fill" but shown "color" in docstrings

[mdtanker]

Noticed a mistake here: -G (fill) is listed as "color" under the "Parameters" section, should be "fill".

[weiji14]

Right, so the code aliases -G as fill:

https://github.com/GenericMappingTools/pygmt/blob/2ebe165373106d7bff5edcea3e5e09e077bc80b6/pygmt/src/histogram.py#L23

But we used {G} in the docstring here:

https://github.com/GenericMappingTools/pygmt/blob/2ebe165373106d7bff5edcea3e5e09e077bc80b6/pygmt/src/histogram.py#L69

which means it shows up in the docs as color:

https://github.com/GenericMappingTools/pygmt/blob/2ebe165373106d7bff5edcea3e5e09e077bc80b6/pygmt/helpers/decorators.py#L46-L47

So, do we go with using color or fill?

[maxrjones]

xref https://github.com/GenericMappingTools/gmt/issues/5563 - I think we're leaning towards fill for GMT, but PyGMT already has color in plot and plot3d.

[weiji14]

xref GenericMappingTools/gmt#5563 - I think we're leaning towards fill for GMT, but PyGMT already has color in plot and plot3d.

Yeah, I think it would be nice to use fill too to standardize with GMT. Just that the color="G" alias for plot/psxy has been here for 4 years already since https://github.com/GenericMappingTools/pygmt/blob/aad12e0879bc71a7dbb396298ed87d68c7d53c80/gmt/ps_modules.py#L10 so this would be a pretty significant deprecation. Ok with deprecating this though, because 'color' is a pretty generic term, and 'fill' is more specific to mean just the inside of the symbol/polygon being plotted. What do others think?

[willschlitzer]

I think fill works better, but it should be changed across the PyGMT modules.

[seisman]

I also agree that fill is better.

I think it's possible to extend the use_alias decorator to support multiple aliases. For example, @use_alias(G=["fill", "color"]) means both fill are color are accepted.

[maxrjones]

I prefer that we don't indefinitely support multiple aliases. The deprecate_parameter decorator is already designed to allow two parameter names, only temporarily with a warning. My preferred path forward would be to update the parameter name of "G" in the COMMON_OPTIONS dict in pygmt/helpers/decorators.py from color to fill and add the deprecate_parameter decorator to plot and plot3d with a long deprecation time-frame (e.g., 4 release cycles). This path forward would not require any changes to https://github.com/GenericMappingTools/pygmt/pull/1431.

[seisman]

I believe the documentation issue has been fixed by #2124.

Now the question is, do we want to deprecate color in plot and plot3d, as suggested in https://github.com/GenericMappingTools/pygmt/issues/1617#issuecomment-1016639486

[willschlitzer]

I believe the documentation issue has been fixed by #2124.

Now the question is, do we want to deprecate color in plot and plot3d, as suggested in #1617 (comment)

If the documentation says fill, I assume we should deprecate color? I agree with @maxrjones that we shouldn't indefinitely support multiple aliases.

[weiji14]

I believe the documentation issue has been fixed by #2124. Now the question is, do we want to deprecate color in plot and plot3d, as suggested in #1617 (comment)

If the documentation says fill, I assume we should deprecate color? I agree with @maxrjones that we shouldn't indefinitely support multiple aliases.

The documentation for fig.histogram and fig.ternary uses the fill alias for -G, but fig.plot and fig.plot3d uses color as the alias, so there's inconsistency. I say we deprecate color as Max recommended above, and do so over 4 minor release cycles, since plot/plot3d are widely used.

[seisman]

I'll work on this issue in a series of PRs:

• [x] Deprecate color to fill in plot.py (https://github.com/GenericMappingTools/pygmt/pull/2177)
• [x] Deprecate color to fill in plot3d.py (https://github.com/GenericMappingTools/pygmt/pull/2178)
• [x] Deprecate color to fill in wiggle.py (https://github.com/GenericMappingTools/pygmt/pull/2205)
• [x] Deprecate color to fill in velo.py (https://github.com/GenericMappingTools/pygmt/pull/2206)
• [x] Deprecate color to fill in rose.py https://github.com/GenericMappingTools/pygmt/pull/2181
• [x] Update color to fill in test_plot.py (https://github.com/GenericMappingTools/pygmt/pull/2189)
• [x] Update color to fill in test_plot3d.py (https://github.com/GenericMappingTools/pygmt/pull/2193)
• [x] Update color to fill in examples and tutorials (https://github.com/GenericMappingTools/pygmt/pull/2201)
• [x] Update uncertaintycolor to uncertaintyfill in example "Velocity arrows and confidence ellipses" (https://github.com/GenericMappingTools/pygmt/pull/2237)