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:

pygmt/pygmt/src/histogram.py

Line 23 in 2ebe165

G="fill",

But we used {G} in the docstring here:

pygmt/pygmt/src/histogram.py

Line 69 in 2ebe165

{G}

which means it shows up in the docs as color:

pygmt/pygmt/helpers/decorators.py

Lines 46 to 47 in 2ebe165

	"G": """\
	color : str or 1d array

So, do we go with using color or fill?

[maxrjones]

xref GenericMappingTools/gmt#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

pygmt/gmt/ps_modules.py

Line 10 in aad12e0

G='color')

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 #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 #1617 (comment)

[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:

• Deprecate color to fill in plot.py (Figure.plot: Deprecate parameter "color" to "fill" (remove in v0.12.0) #2177)
• Deprecate color to fill in plot3d.py (Figure.plot3d: Deprecate parameter "color" to "fill" (remove in v0.12.0) #2178)
• Deprecate color to fill in wiggle.py (Figure.wiggle: Deprecate parameter "color" (remove in v0.12.0) and add "fillpositive"/"fillnegative" #2205)
• Deprecate color to fill in velo.py (Figure.velo: Deprecate parameters "color" to "fill" and "uncertaintycolor" to "uncertaintyfill" (remove in v0.12.0) #2206)
• Deprecate color to fill in rose.py Figure.rose: Deprecate parameter color to fill (remove in v0.12.0) #2181
• Update color to fill in test_plot.py (Figure.plot: Update parameter 'color' to 'fill' in test_plot.py #2189)
• Update color to fill in test_plot3d.py (Figure.plot3d: Update parameter 'color' to 'fill' in test_plot3d.py #2193)
• Update color to fill in examples and tutorials (Update parameter 'color' to 'fill' in examples and tutorials #2201)
• Update uncertaintycolor to uncertaintyfill in example "Velocity arrows and confidence ellipses" (Update parameter 'uncertaintycolor' to 'uncertaintyfill' in example 'velo_arrow_ellipse.py' #2237)