From 8237ef0723139ab29c996a77794983b2989c99bb Mon Sep 17 00:00:00 2001 From: Zach Landry Date: Tue, 28 Jul 2026 15:47:07 -0700 Subject: [PATCH 01/10] Aliased the -Z, calling it zvalue --- pygmt/src/text.py | 1 + 1 file changed, 1 insertion(+) diff --git a/pygmt/src/text.py b/pygmt/src/text.py index c8b6e17d0b9..6f6405d78ba 100644 --- a/pygmt/src/text.py +++ b/pygmt/src/text.py @@ -25,6 +25,7 @@ @fmt_docstring @use_alias( C="clearance", + Z="zvalue", a="aspatial", e="find", f="coltypes", From 98c8b256c43c114226d46b163ec12f4abad0e126 Mon Sep 17 00:00:00 2001 From: Zach Landry Date: Tue, 28 Jul 2026 15:48:45 -0700 Subject: [PATCH 02/10] added z to the text function parameters --- pygmt/src/text.py | 1 + 1 file changed, 1 insertion(+) diff --git a/pygmt/src/text.py b/pygmt/src/text.py index 6f6405d78ba..6ac4e02b9c5 100644 --- a/pygmt/src/text.py +++ b/pygmt/src/text.py @@ -38,6 +38,7 @@ def text( # ruff: ignore[too-many-branches, too-many-statements] textfiles: PathLike | TableLike | None = None, x=None, y=None, + z=None, position: AnchorCode | None = None, text: str | StringArrayTypes | None = None, angle: float | Sequence[float] | bool = False, From cf7ce85d5362734e235e2cba1ca946f4f35e76a7 Mon Sep 17 00:00:00 2001 From: Zach Landry Date: Tue, 28 Jul 2026 15:54:03 -0700 Subject: [PATCH 03/10] Added a combination including z to the possible combinations in docstring --- pygmt/src/text.py | 1 + 1 file changed, 1 insertion(+) diff --git a/pygmt/src/text.py b/pygmt/src/text.py index 6ac4e02b9c5..6946d6ed7cd 100644 --- a/pygmt/src/text.py +++ b/pygmt/src/text.py @@ -65,6 +65,7 @@ def text( # ruff: ignore[too-many-branches, too-many-statements] - ``textfiles`` - ``x``/``y``, and ``text`` + - ``x``/``y``/``z``, and ``text`` - ``position`` and ``text`` The text strings passed via the ``text`` parameter can contain ASCII characters and From e9c8075455617f4dac977b7fcf829fc89faea2e1 Mon Sep 17 00:00:00 2001 From: Zach Landry Date: Tue, 28 Jul 2026 15:59:26 -0700 Subject: [PATCH 04/10] Updated the docstring to include z value --- pygmt/src/text.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/pygmt/src/text.py b/pygmt/src/text.py index 6946d6ed7cd..f01949cdf01 100644 --- a/pygmt/src/text.py +++ b/pygmt/src/text.py @@ -100,6 +100,7 @@ def text( # ruff: ignore[too-many-branches, too-many-statements] * *x*: X coordinate or longitude * *y*: Y coordinate or latitude + * *z*: Z coordinate or altitude * *angle*: Angle in degrees counter-clockwise from horizontal * *font*: Text size, font, and color * *justify*: @@ -111,8 +112,8 @@ def text( # ruff: ignore[too-many-branches, too-many-statements] respectively. If these parameters are set to ``True``, then the corresponding columns must be present in the input file(s) and the columns must be in the order mentioned above. - x/y : float or 1-D arrays - The x and y coordinates, or an array of x and y coordinates to plot + x/y/z : float or 1-D arrays + The x, y, and z coordinates, or an array of x, y, and z coordinates to plot the text. position Set reference point on the plot for the text by using x, y @@ -188,7 +189,7 @@ def text( # ruff: ignore[too-many-branches, too-many-statements] $perspective $transparency ``transparency`` can also be a 1-D array to set varying transparency for texts, - but this option is only valid if using ``x``/``y`` and ``text``. + but this option is only valid if using ``x``/``y``(/``z``) and ``text``. $wrap See Also From 1a4f04c9108204ea0af9600d3c003bdf6324645a Mon Sep 17 00:00:00 2001 From: Zach Landry Date: Tue, 28 Jul 2026 16:01:19 -0700 Subject: [PATCH 05/10] added z value to GMTParameterError --- pygmt/src/text.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pygmt/src/text.py b/pygmt/src/text.py index f01949cdf01..85e05396390 100644 --- a/pygmt/src/text.py +++ b/pygmt/src/text.py @@ -197,11 +197,11 @@ def text( # ruff: ignore[too-many-branches, too-many-statements] pygmt.Figure.paragraph Typeset one or multiple paragraphs. """ - # Ensure inputs are either textfiles, x/y/text, or position/text + # Ensure inputs are either textfiles, x/y(/z)/text, or position/text if ( (textfiles is not None) + (position is not None) - + (x is not None or y is not None) + + (x is not None or y is not None or z is not None) ) != 1: raise GMTParameterError(at_most_one=["textfiles", "position/text", "x/y/text"]) From af8508c2421a5868af0a5af7079df5697c3d6b58 Mon Sep 17 00:00:00 2001 From: Zach Landry Date: Tue, 28 Jul 2026 16:02:44 -0700 Subject: [PATCH 06/10] added z to one other GMTParameterError --- pygmt/src/text.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pygmt/src/text.py b/pygmt/src/text.py index 85e05396390..defa1190637 100644 --- a/pygmt/src/text.py +++ b/pygmt/src/text.py @@ -223,7 +223,7 @@ def text( # ruff: ignore[too-many-branches, too-many-statements] raise GMTParameterError(at_most_one=["text", "textfiles"]) if kind == "empty" and text is None: raise GMTParameterError( - required="text", reason="Required when 'x' and 'y' are set." + required="text", reason="Required when 'x', 'y', and optional 'z' are set." ) # Arguments that can accept arrays. From 9714eaf2737b851a1cc0463cfca932ac095374f7 Mon Sep 17 00:00:00 2001 From: Zach Landry Date: Tue, 28 Jul 2026 16:06:16 -0700 Subject: [PATCH 07/10] added z to the data dictionary --- pygmt/src/text.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/pygmt/src/text.py b/pygmt/src/text.py index defa1190637..c63135b4185 100644 --- a/pygmt/src/text.py +++ b/pygmt/src/text.py @@ -251,6 +251,8 @@ def text( # ruff: ignore[too-many-branches, too-many-statements] data = None if kind == "empty": data = {"x": x, "y": y} + if z is not None: + data["z"] = z for arg, flag, name in array_args: if is_nonstr_iter(arg): From 4d5fe64dc07735db4b58454a4bb2c29d518708ff Mon Sep 17 00:00:00 2001 From: Zach Landry Date: Tue, 28 Jul 2026 16:12:29 -0700 Subject: [PATCH 08/10] adjusted language to mention that z is optional --- pygmt/src/text.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pygmt/src/text.py b/pygmt/src/text.py index c63135b4185..012dbcf4264 100644 --- a/pygmt/src/text.py +++ b/pygmt/src/text.py @@ -100,7 +100,7 @@ def text( # ruff: ignore[too-many-branches, too-many-statements] * *x*: X coordinate or longitude * *y*: Y coordinate or latitude - * *z*: Z coordinate or altitude + * *z*: Optional Z coordinate or altitude * *angle*: Angle in degrees counter-clockwise from horizontal * *font*: Text size, font, and color * *justify*: @@ -113,7 +113,7 @@ def text( # ruff: ignore[too-many-branches, too-many-statements] corresponding columns must be present in the input file(s) and the columns must be in the order mentioned above. x/y/z : float or 1-D arrays - The x, y, and z coordinates, or an array of x, y, and z coordinates to plot + The x, y, and optional z coordinates, or an array of x, y, and z coordinates to plot the text. position Set reference point on the plot for the text by using x, y @@ -203,7 +203,7 @@ def text( # ruff: ignore[too-many-branches, too-many-statements] + (position is not None) + (x is not None or y is not None or z is not None) ) != 1: - raise GMTParameterError(at_most_one=["textfiles", "position/text", "x/y/text"]) + raise GMTParameterError(at_most_one=["textfiles", "position/text", "x/y(/z)/text"]) data_is_required = position is None kind = data_kind(textfiles, required=data_is_required) From d601d5a467a0eab903d96de1045d21c7a9d5bce4 Mon Sep 17 00:00:00 2001 From: Zach Landry Date: Tue, 28 Jul 2026 16:39:53 -0700 Subject: [PATCH 09/10] updated language to reflect what exists in plot3D more closely --- pygmt/src/text.py | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/pygmt/src/text.py b/pygmt/src/text.py index 012dbcf4264..74f4281fcfb 100644 --- a/pygmt/src/text.py +++ b/pygmt/src/text.py @@ -64,8 +64,7 @@ def text( # ruff: ignore[too-many-branches, too-many-statements] Must provide at least one of the following combinations as input: - ``textfiles`` - - ``x``/``y``, and ``text`` - - ``x``/``y``/``z``, and ``text`` + - ``x``/``y``[/``z``], and ``text`` - ``position`` and ``text`` The text strings passed via the ``text`` parameter can contain ASCII characters and @@ -113,8 +112,8 @@ def text( # ruff: ignore[too-many-branches, too-many-statements] corresponding columns must be present in the input file(s) and the columns must be in the order mentioned above. x/y/z : float or 1-D arrays - The x, y, and optional z coordinates, or an array of x, y, and z coordinates to plot - the text. + The x, y, and z coordinates, or arrays of x, y and z coordinates of + the data points. position Set reference point on the plot for the text by using x, y coordinates extracted from ``region`` instead of providing them @@ -223,7 +222,7 @@ def text( # ruff: ignore[too-many-branches, too-many-statements] raise GMTParameterError(at_most_one=["text", "textfiles"]) if kind == "empty" and text is None: raise GMTParameterError( - required="text", reason="Required when 'x', 'y', and optional 'z' are set." + required="text", reason="Required when 'x', 'y' (and optional 'z') are set." ) # Arguments that can accept arrays. @@ -250,9 +249,7 @@ def text( # ruff: ignore[too-many-branches, too-many-statements] confdict = {} data = None if kind == "empty": - data = {"x": x, "y": y} - if z is not None: - data["z"] = z + data = {"x": x, "y": y, "z": z} for arg, flag, name in array_args: if is_nonstr_iter(arg): From cb2e1993f3b231800b17f35329f2e2ededa4a897 Mon Sep 17 00:00:00 2001 From: Zach Landry Date: Wed, 29 Jul 2026 09:06:47 -0700 Subject: [PATCH 10/10] updated data to make sure z is optional --- pygmt/src/text.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/pygmt/src/text.py b/pygmt/src/text.py index 74f4281fcfb..203c9d990c4 100644 --- a/pygmt/src/text.py +++ b/pygmt/src/text.py @@ -249,7 +249,10 @@ def text( # ruff: ignore[too-many-branches, too-many-statements] confdict = {} data = None if kind == "empty": - data = {"x": x, "y": y, "z": z} + data = {"x": x, "y": y} + + if z is not None: + data["z"] = z for arg, flag, name in array_args: if is_nonstr_iter(arg):