Clarify that the "transparency" parameter in plot/plot3d/text can be 1d array

[core-man]

Description of proposed changes

Fixes #1098

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If adding new functionality, add an example to docstrings or tutorials.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash commands are:

• /format: automatically format and lint the code
• /test-gmt-dev: run full tests on the latest GMT development version

[core-man]

I am going to add 1d array transparency test, so the following functions should be renamed to a general one. How about test_plot_fail_1d_array_with_data and test_plot3d_fail_1d_array_with_data (done in 8eb1369).

pygmt/pygmt/tests/test_plot.py

Lines 94 to 98 in 036e2b0

	def test_plot_fail_color_size_intensity(data):
	"""
	Should raise an exception if array color, size and intensity are used with
	matrix.
	"""

pygmt/pygmt/tests/test_plot3d.py

Lines 111 to 114 in 036e2b0

	def test_plot3d_fail_color_size_intensity(data, region):
	"""
	Should raise an exception if array color, size and intensity are used with
	matrix.

[core-man]

I am wondering if we should add 1d array in the following COMMON_OPTIONS. Currently, some modules still do not support 1d array transparency, e.g, wiggle, since we may update the alias later.

pygmt/pygmt/helpers/decorators.py

Lines 128 to 129 in 036e2b0

	"t": """\
	transparency : int or float

[seisman]

I am wondering if we should add 1d array in the following COMMON_OPTIONS. Currently, some modules still do not support 1d array transparency, e.g, wiggle, since we may update the alias later.

pygmt/pygmt/helpers/decorators.py

Lines 128 to 129 in 036e2b0

	"t": """\
	transparency : int or float

In GMT CLI, only a few modules (e.g., plot, plot3d, text) support varying transparency.

[seisman]

Looks good to me.

[weiji14]

Just one tiny suggestion :)

In GMT CLI, only a few modules (e.g., plot, plot3d, text) support varying transparency.

Seems like we're missing the varying transparency feature for text, maybe open an issue for this, and we can get someone to work on it (after #1121).

[core-man]

In GMT CLI, only a few modules (e.g., plot, plot3d, text) support varying transparency.

Seems like we're missing the varying transparency feature for text, maybe open an issue for this, and we can get someone to work on it (after #1121).

We have varying transparency feature for text, no?

pygmt/pygmt/src/text.py

Lines 200 to 204 in 5125224

	# If an array of transparency is given, GMT will read it from
	# the last numerical column per data record.
	if "t" in kwargs and is_nonstr_iter(kwargs["t"]):
	extra_arrays.append(kwargs["t"])
	kwargs["t"] = ""

pygmt/pygmt/tests/test_text.py

Lines 324 to 327 in 5125224

	def test_text_varying_transparency():
	"""
	Add texts with varying transparency.
	"""

Or you mean improving the documentation for the transparency option in text?

pygmt/pygmt/src/text.py

Line 149 in 5125224

{t}

[weiji14]

Oh yes, forgot that varying transparency for text was added in #716. Could you please add it to the documentation for text then? And change the title of this PR too after.

[core-man]

Oh yes, forgot that varying transparency for text was added in #716. Could you please add it to the documentation for text then? And change the title of this PR too after.

Done in 505ec41 and c3d0223. But it seems that the transparency parameter in text should be polished a little, e.g., raise a GMTInvalidInput if 1d array transparency is not used with x/y.

[weiji14]

Oh yes, forgot that varying transparency for text was added in #716. Could you please add it to the documentation for text then? And change the title of this PR too after.

Done in 505ec41 and c3d0223. But it seems that the transparency parameter in text should be polished a little, e.g., raise a GMTInvalidInput if 1d array transparency is not used with x/y.

Yes, but that can be done in a separate Pull Request, let's keep this one focused on just the docstring (and unit test). I think @seisman is doing a bit of work on refactoring the text function at #1121 so best not to cause conflicts.

P.S. The ubuntu-latest - Python 3.9 / NumPy 1.20 tests are failing due to an unrelated reason at #1278. I'll see if I can come up with a quick fix, if not, it should be fine to merge (as an admin) since the other tests are passing.