From 5d3d308643cc59fa2cf71acf6315255e27edf2c0 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 5 Mar 2025 16:01:41 +0800 Subject: [PATCH 01/11] Rename 'required_z' to 'required_ncols' in _validate_data_input --- pygmt/helpers/utils.py | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/pygmt/helpers/utils.py b/pygmt/helpers/utils.py index 94c1d8a8901..e14c1c4a15e 100644 --- a/pygmt/helpers/utils.py +++ b/pygmt/helpers/utils.py @@ -42,7 +42,7 @@ def _validate_data_input( - data=None, x=None, y=None, z=None, required_z=False, required_data=True, kind=None + data=None, x=None, y=None, z=None, required_data=True, required_ncols=2, kind=None ) -> None: """ Check if the combination of data/x/y/z is valid. @@ -65,7 +65,7 @@ def _validate_data_input( Traceback (most recent call last): ... pygmt.exceptions.GMTInvalidInput: Must provide both x and y. - >>> _validate_data_input(x=[1, 2, 3], y=[4, 5, 6], required_z=True) + >>> _validate_data_input(x=[1, 2, 3], y=[4, 5, 6], required_ncols=3) Traceback (most recent call last): ... pygmt.exceptions.GMTInvalidInput: Must provide x, y, and z. @@ -73,13 +73,13 @@ def _validate_data_input( >>> import pandas as pd >>> import xarray as xr >>> data = np.arange(8).reshape((4, 2)) - >>> _validate_data_input(data=data, required_z=True, kind="matrix") + >>> _validate_data_input(data=data, required_ncols=3, kind="matrix") Traceback (most recent call last): ... pygmt.exceptions.GMTInvalidInput: data must provide x, y, and z columns. >>> _validate_data_input( ... data=pd.DataFrame(data, columns=["x", "y"]), - ... required_z=True, + ... required_ncols=3, ... kind="vectors", ... ) Traceback (most recent call last): @@ -87,7 +87,7 @@ def _validate_data_input( pygmt.exceptions.GMTInvalidInput: data must provide x, y, and z columns. >>> _validate_data_input( ... data=xr.Dataset(pd.DataFrame(data, columns=["x", "y"])), - ... required_z=True, + ... required_ncols=3, ... kind="vectors", ... ) Traceback (most recent call last): @@ -115,6 +115,7 @@ def _validate_data_input( GMTInvalidInput If the data input is not valid. """ + required_z = required_ncols >= 3 if data is None: # data is None if x is None and y is None: # both x and y are None if required_data: # data is not optional From 406cb39bfd16b5e3b4902a75852f67f0565788d2 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 5 Mar 2025 16:03:19 +0800 Subject: [PATCH 02/11] Rename 'required_z' to 'required_ncols' in Session.virtualfile_in --- pygmt/clib/session.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pygmt/clib/session.py b/pygmt/clib/session.py index 9ab3e37574e..96378d92767 100644 --- a/pygmt/clib/session.py +++ b/pygmt/clib/session.py @@ -1773,8 +1773,8 @@ def virtualfile_in( y=None, z=None, extra_arrays=None, - required_z=False, required_data=True, + required_ncols=2, ): """ Store any data inside a virtual file. @@ -1797,11 +1797,11 @@ def virtualfile_in( extra_arrays : list of 1-D arrays Optional. A list of numpy arrays in addition to x, y, and z. All of these arrays must be of the same size as the x/y/z arrays. - required_z : bool - State whether the 'z' column is required. required_data : bool Set to True when 'data' is required, or False when dealing with optional virtual files. [Default is True]. + required_ncols + Number of minimum required columns. Returns ------- @@ -1835,8 +1835,8 @@ def virtualfile_in( x=x, y=y, z=z, - required_z=required_z, required_data=required_data, + required_ncols=required_ncols, kind=kind, ) From af189e675e4ef81044ad6474312ac5c18b1f8ba1 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 5 Mar 2025 16:03:34 +0800 Subject: [PATCH 03/11] Rename 'required_z' to 'required_ncols' in Session.virtualfile_in tests --- pygmt/tests/test_clib_virtualfile_in.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pygmt/tests/test_clib_virtualfile_in.py b/pygmt/tests/test_clib_virtualfile_in.py index 8a43c1dc273..35477bcf845 100644 --- a/pygmt/tests/test_clib_virtualfile_in.py +++ b/pygmt/tests/test_clib_virtualfile_in.py @@ -42,7 +42,7 @@ def test_virtualfile_in_required_z_matrix(array_func, kind): data = array_func(dataframe) with clib.Session() as lib: with lib.virtualfile_in( - data=data, required_z=True, check_kind="vector" + data=data, required_ncols=3, check_kind="vector" ) as vfile: with GMTTempFile() as outfile: lib.call_module("info", [vfile, f"->{outfile.name}"]) @@ -64,7 +64,7 @@ def test_virtualfile_in_required_z_matrix_missing(): data = np.ones((5, 2)) with clib.Session() as lib: with pytest.raises(GMTInvalidInput): - with lib.virtualfile_in(data=data, required_z=True, check_kind="vector"): + with lib.virtualfile_in(data=data, required_ncols=3, check_kind="vector"): pass @@ -91,7 +91,7 @@ def test_virtualfile_in_fail_non_valid_data(data): with clib.Session() as lib: with pytest.raises(GMTInvalidInput): lib.virtualfile_in( - x=variable[0], y=variable[1], z=variable[2], required_z=True + x=variable[0], y=variable[1], z=variable[2], required_ncols=3 ) # Should also fail if given too much data From 2d55e5a37241fa7dbd890d4061c8be8d3fadffb3 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 5 Mar 2025 16:04:28 +0800 Subject: [PATCH 04/11] Rename 'required_z' to 'required_ncols' in module wrappers --- pygmt/src/blockm.py | 2 +- pygmt/src/contour.py | 2 +- pygmt/src/nearneighbor.py | 2 +- pygmt/src/plot3d.py | 2 +- pygmt/src/project.py | 2 +- pygmt/src/surface.py | 2 +- pygmt/src/triangulate.py | 4 ++-- pygmt/src/wiggle.py | 2 +- pygmt/src/xyz2grd.py | 2 +- 9 files changed, 10 insertions(+), 10 deletions(-) diff --git a/pygmt/src/blockm.py b/pygmt/src/blockm.py index 581167bcd5d..1afbd51d978 100644 --- a/pygmt/src/blockm.py +++ b/pygmt/src/blockm.py @@ -55,7 +55,7 @@ def _blockm( with Session() as lib: with ( lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, required_z=True + check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=3 ) as vintbl, lib.virtualfile_out(kind="dataset", fname=outfile) as vouttbl, ): diff --git a/pygmt/src/contour.py b/pygmt/src/contour.py index c5aa26a3b10..a951811a9ed 100644 --- a/pygmt/src/contour.py +++ b/pygmt/src/contour.py @@ -145,7 +145,7 @@ def contour(self, data=None, x=None, y=None, z=None, **kwargs): with Session() as lib: with lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, required_z=True + check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=3 ) as vintbl: lib.call_module( module="contour", args=build_arg_list(kwargs, infile=vintbl) diff --git a/pygmt/src/nearneighbor.py b/pygmt/src/nearneighbor.py index 94cb02bdf68..7a3e0412c01 100644 --- a/pygmt/src/nearneighbor.py +++ b/pygmt/src/nearneighbor.py @@ -141,7 +141,7 @@ def nearneighbor( with Session() as lib: with ( lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, required_z=True + check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=3 ) as vintbl, lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd, ): diff --git a/pygmt/src/plot3d.py b/pygmt/src/plot3d.py index e8e75382d74..e8b4f9b2372 100644 --- a/pygmt/src/plot3d.py +++ b/pygmt/src/plot3d.py @@ -263,6 +263,6 @@ def plot3d( y=y, z=z, extra_arrays=extra_arrays, - required_z=True, + required_ncols=3, ) as vintbl: lib.call_module(module="plot3d", args=build_arg_list(kwargs, infile=vintbl)) diff --git a/pygmt/src/project.py b/pygmt/src/project.py index a49d5a1ad1f..33aa5dcaac5 100644 --- a/pygmt/src/project.py +++ b/pygmt/src/project.py @@ -245,7 +245,7 @@ def project( x=x, y=y, z=z, - required_z=False, + required_ncols=2, required_data=False, ) as vintbl, lib.virtualfile_out(kind="dataset", fname=outfile) as vouttbl, diff --git a/pygmt/src/surface.py b/pygmt/src/surface.py index 4d6a828986e..cab9d313e02 100644 --- a/pygmt/src/surface.py +++ b/pygmt/src/surface.py @@ -155,7 +155,7 @@ def surface( with Session() as lib: with ( lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, required_z=True + check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=3 ) as vintbl, lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd, ): diff --git a/pygmt/src/triangulate.py b/pygmt/src/triangulate.py index 1fa60d6a301..19718841f8f 100644 --- a/pygmt/src/triangulate.py +++ b/pygmt/src/triangulate.py @@ -138,7 +138,7 @@ def regular_grid( with Session() as lib: with ( lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, required_z=False + check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=2 ) as vintbl, lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd, ): @@ -238,7 +238,7 @@ def delaunay_triples( with Session() as lib: with ( lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, required_z=False + check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=2 ) as vintbl, lib.virtualfile_out(kind="dataset", fname=outfile) as vouttbl, ): diff --git a/pygmt/src/wiggle.py b/pygmt/src/wiggle.py index 921c5317349..917cd753167 100644 --- a/pygmt/src/wiggle.py +++ b/pygmt/src/wiggle.py @@ -108,6 +108,6 @@ def wiggle( with Session() as lib: with lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, required_z=True + check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=3 ) as vintbl: lib.call_module(module="wiggle", args=build_arg_list(kwargs, infile=vintbl)) diff --git a/pygmt/src/xyz2grd.py b/pygmt/src/xyz2grd.py index ca7c9e94c6b..e87899c6129 100644 --- a/pygmt/src/xyz2grd.py +++ b/pygmt/src/xyz2grd.py @@ -149,7 +149,7 @@ def xyz2grd( with Session() as lib: with ( lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, required_z=True + check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=3 ) as vintbl, lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd, ): From 5eeb37bcb3117560efef27ee59418065cb1a76e0 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Mon, 10 Mar 2025 16:08:06 +0800 Subject: [PATCH 05/11] Rename required_ncols to the shorter ncols --- pygmt/clib/session.py | 6 +++--- pygmt/helpers/utils.py | 12 ++++++------ pygmt/src/blockm.py | 2 +- pygmt/src/contour.py | 2 +- pygmt/src/nearneighbor.py | 2 +- pygmt/src/plot3d.py | 2 +- pygmt/src/project.py | 2 +- pygmt/src/surface.py | 2 +- pygmt/src/triangulate.py | 4 ++-- pygmt/src/wiggle.py | 2 +- pygmt/src/xyz2grd.py | 2 +- pygmt/tests/test_clib_virtualfile_in.py | 10 +++------- 12 files changed, 22 insertions(+), 26 deletions(-) diff --git a/pygmt/clib/session.py b/pygmt/clib/session.py index 96378d92767..d40546cfdd1 100644 --- a/pygmt/clib/session.py +++ b/pygmt/clib/session.py @@ -1774,7 +1774,7 @@ def virtualfile_in( z=None, extra_arrays=None, required_data=True, - required_ncols=2, + ncols=2, ): """ Store any data inside a virtual file. @@ -1800,7 +1800,7 @@ def virtualfile_in( required_data : bool Set to True when 'data' is required, or False when dealing with optional virtual files. [Default is True]. - required_ncols + ncols Number of minimum required columns. Returns @@ -1836,7 +1836,7 @@ def virtualfile_in( y=y, z=z, required_data=required_data, - required_ncols=required_ncols, + ncols=ncols, kind=kind, ) diff --git a/pygmt/helpers/utils.py b/pygmt/helpers/utils.py index e14c1c4a15e..c8a37a24a5e 100644 --- a/pygmt/helpers/utils.py +++ b/pygmt/helpers/utils.py @@ -42,7 +42,7 @@ def _validate_data_input( - data=None, x=None, y=None, z=None, required_data=True, required_ncols=2, kind=None + data=None, x=None, y=None, z=None, required_data=True, ncols=2, kind=None ) -> None: """ Check if the combination of data/x/y/z is valid. @@ -65,7 +65,7 @@ def _validate_data_input( Traceback (most recent call last): ... pygmt.exceptions.GMTInvalidInput: Must provide both x and y. - >>> _validate_data_input(x=[1, 2, 3], y=[4, 5, 6], required_ncols=3) + >>> _validate_data_input(x=[1, 2, 3], y=[4, 5, 6], ncols=3) Traceback (most recent call last): ... pygmt.exceptions.GMTInvalidInput: Must provide x, y, and z. @@ -73,13 +73,13 @@ def _validate_data_input( >>> import pandas as pd >>> import xarray as xr >>> data = np.arange(8).reshape((4, 2)) - >>> _validate_data_input(data=data, required_ncols=3, kind="matrix") + >>> _validate_data_input(data=data, ncols=3, kind="matrix") Traceback (most recent call last): ... pygmt.exceptions.GMTInvalidInput: data must provide x, y, and z columns. >>> _validate_data_input( ... data=pd.DataFrame(data, columns=["x", "y"]), - ... required_ncols=3, + ... ncols=3, ... kind="vectors", ... ) Traceback (most recent call last): @@ -87,7 +87,7 @@ def _validate_data_input( pygmt.exceptions.GMTInvalidInput: data must provide x, y, and z columns. >>> _validate_data_input( ... data=xr.Dataset(pd.DataFrame(data, columns=["x", "y"])), - ... required_ncols=3, + ... ncols=3, ... kind="vectors", ... ) Traceback (most recent call last): @@ -115,7 +115,7 @@ def _validate_data_input( GMTInvalidInput If the data input is not valid. """ - required_z = required_ncols >= 3 + required_z = ncols >= 3 if data is None: # data is None if x is None and y is None: # both x and y are None if required_data: # data is not optional diff --git a/pygmt/src/blockm.py b/pygmt/src/blockm.py index 1afbd51d978..1d3d1dd099c 100644 --- a/pygmt/src/blockm.py +++ b/pygmt/src/blockm.py @@ -55,7 +55,7 @@ def _blockm( with Session() as lib: with ( lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=3 + check_kind="vector", data=data, x=x, y=y, z=z, ncols=3 ) as vintbl, lib.virtualfile_out(kind="dataset", fname=outfile) as vouttbl, ): diff --git a/pygmt/src/contour.py b/pygmt/src/contour.py index a951811a9ed..d7ac6ab75b0 100644 --- a/pygmt/src/contour.py +++ b/pygmt/src/contour.py @@ -145,7 +145,7 @@ def contour(self, data=None, x=None, y=None, z=None, **kwargs): with Session() as lib: with lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=3 + check_kind="vector", data=data, x=x, y=y, z=z, ncols=3 ) as vintbl: lib.call_module( module="contour", args=build_arg_list(kwargs, infile=vintbl) diff --git a/pygmt/src/nearneighbor.py b/pygmt/src/nearneighbor.py index 7a3e0412c01..6d25ecd65eb 100644 --- a/pygmt/src/nearneighbor.py +++ b/pygmt/src/nearneighbor.py @@ -141,7 +141,7 @@ def nearneighbor( with Session() as lib: with ( lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=3 + check_kind="vector", data=data, x=x, y=y, z=z, ncols=3 ) as vintbl, lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd, ): diff --git a/pygmt/src/plot3d.py b/pygmt/src/plot3d.py index e8b4f9b2372..1d7f2b4357a 100644 --- a/pygmt/src/plot3d.py +++ b/pygmt/src/plot3d.py @@ -263,6 +263,6 @@ def plot3d( y=y, z=z, extra_arrays=extra_arrays, - required_ncols=3, + ncols=3, ) as vintbl: lib.call_module(module="plot3d", args=build_arg_list(kwargs, infile=vintbl)) diff --git a/pygmt/src/project.py b/pygmt/src/project.py index 33aa5dcaac5..7b3afc25127 100644 --- a/pygmt/src/project.py +++ b/pygmt/src/project.py @@ -245,7 +245,7 @@ def project( x=x, y=y, z=z, - required_ncols=2, + ncols=2, required_data=False, ) as vintbl, lib.virtualfile_out(kind="dataset", fname=outfile) as vouttbl, diff --git a/pygmt/src/surface.py b/pygmt/src/surface.py index cab9d313e02..11d13506efb 100644 --- a/pygmt/src/surface.py +++ b/pygmt/src/surface.py @@ -155,7 +155,7 @@ def surface( with Session() as lib: with ( lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=3 + check_kind="vector", data=data, x=x, y=y, z=z, ncols=3 ) as vintbl, lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd, ): diff --git a/pygmt/src/triangulate.py b/pygmt/src/triangulate.py index 19718841f8f..1daf477a7d4 100644 --- a/pygmt/src/triangulate.py +++ b/pygmt/src/triangulate.py @@ -138,7 +138,7 @@ def regular_grid( with Session() as lib: with ( lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=2 + check_kind="vector", data=data, x=x, y=y, z=z, ncols=2 ) as vintbl, lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd, ): @@ -238,7 +238,7 @@ def delaunay_triples( with Session() as lib: with ( lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=2 + check_kind="vector", data=data, x=x, y=y, z=z, ncols=2 ) as vintbl, lib.virtualfile_out(kind="dataset", fname=outfile) as vouttbl, ): diff --git a/pygmt/src/wiggle.py b/pygmt/src/wiggle.py index 917cd753167..4b28d5fd640 100644 --- a/pygmt/src/wiggle.py +++ b/pygmt/src/wiggle.py @@ -108,6 +108,6 @@ def wiggle( with Session() as lib: with lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=3 + check_kind="vector", data=data, x=x, y=y, z=z, ncols=3 ) as vintbl: lib.call_module(module="wiggle", args=build_arg_list(kwargs, infile=vintbl)) diff --git a/pygmt/src/xyz2grd.py b/pygmt/src/xyz2grd.py index e87899c6129..7b5b355b3f6 100644 --- a/pygmt/src/xyz2grd.py +++ b/pygmt/src/xyz2grd.py @@ -149,7 +149,7 @@ def xyz2grd( with Session() as lib: with ( lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, required_ncols=3 + check_kind="vector", data=data, x=x, y=y, z=z, ncols=3 ) as vintbl, lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd, ): diff --git a/pygmt/tests/test_clib_virtualfile_in.py b/pygmt/tests/test_clib_virtualfile_in.py index 35477bcf845..1f97abe3bb2 100644 --- a/pygmt/tests/test_clib_virtualfile_in.py +++ b/pygmt/tests/test_clib_virtualfile_in.py @@ -41,9 +41,7 @@ def test_virtualfile_in_required_z_matrix(array_func, kind): ) data = array_func(dataframe) with clib.Session() as lib: - with lib.virtualfile_in( - data=data, required_ncols=3, check_kind="vector" - ) as vfile: + with lib.virtualfile_in(data=data, ncols=3, check_kind="vector") as vfile: with GMTTempFile() as outfile: lib.call_module("info", [vfile, f"->{outfile.name}"]) output = outfile.read(keep_tabs=True) @@ -64,7 +62,7 @@ def test_virtualfile_in_required_z_matrix_missing(): data = np.ones((5, 2)) with clib.Session() as lib: with pytest.raises(GMTInvalidInput): - with lib.virtualfile_in(data=data, required_ncols=3, check_kind="vector"): + with lib.virtualfile_in(data=data, ncols=3, check_kind="vector"): pass @@ -90,9 +88,7 @@ def test_virtualfile_in_fail_non_valid_data(data): continue with clib.Session() as lib: with pytest.raises(GMTInvalidInput): - lib.virtualfile_in( - x=variable[0], y=variable[1], z=variable[2], required_ncols=3 - ) + lib.virtualfile_in(x=variable[0], y=variable[1], z=variable[2], ncols=3) # Should also fail if given too much data with clib.Session() as lib: From 0e0c1d8e212aef35ba567faa7b2c52603e118847 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 26 Mar 2025 16:59:19 +0800 Subject: [PATCH 06/11] Deprecate required_z in a backward-compatible way --- pygmt/clib/session.py | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/pygmt/clib/session.py b/pygmt/clib/session.py index d40546cfdd1..bc0a7de836f 100644 --- a/pygmt/clib/session.py +++ b/pygmt/clib/session.py @@ -1765,7 +1765,7 @@ def virtualfile_from_stringio( seg.header = None seg.text = None - def virtualfile_in( + def virtualfile_in( # noqa: PLR0912 self, check_kind=None, data=None, @@ -1775,6 +1775,7 @@ def virtualfile_in( extra_arrays=None, required_data=True, ncols=2, + required_z=False, ): """ Store any data inside a virtual file. @@ -1802,6 +1803,12 @@ def virtualfile_in( optional virtual files. [Default is True]. ncols Number of minimum required columns. + required_z : bool + State whether the 'z' column is required. + + .. deprecated:: v0.16.0 + The parameter 'required_z' will be removed in v0.20.0. Use parameter + 'ncols' instead. E.g., ``required_z=True`` is equivalent to ``ncols=3``. Returns ------- @@ -1829,6 +1836,17 @@ def virtualfile_in( ... print(fout.read().strip()) : N = 3 <7/9> <4/6> <1/3> """ + # TODO(PyGMT>=0.20.0): Remove the deprecated 'required_z' parameter. + if required_z is True: + warnings.warn( + "The parameter 'required_z' is deprecated and will be removed in " + "v0.20.0. Use parameter 'ncols' instead. E.g., ``required_z=True`` is " + "equivalent to ``ncols=3``.", + category=FutureWarning, + stacklevel=1, + ) + ncols = 3 + kind = data_kind(data, required=required_data) _validate_data_input( data=data, From f8293cdf2c63b2fe1a254a8ad52d9c9c3db6b7b9 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 26 Mar 2025 17:11:24 +0800 Subject: [PATCH 07/11] Add one test with the deprecated 'required_z' parameter to increase code coverage --- pygmt/tests/test_clib_virtualfile_in.py | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/pygmt/tests/test_clib_virtualfile_in.py b/pygmt/tests/test_clib_virtualfile_in.py index 1f97abe3bb2..c1616565709 100644 --- a/pygmt/tests/test_clib_virtualfile_in.py +++ b/pygmt/tests/test_clib_virtualfile_in.py @@ -66,6 +66,22 @@ def test_virtualfile_in_required_z_matrix_missing(): pass +# TODO(PyGMT>=0.20.0): Remove this test for the deprecated 'required_z' parameter. +def test_virtualfile_in_required_z_deprecated(): + """ + Same as test_virtualfile_in_required_z_matrix_missing but using the deprecated + 'required_z' parameter. + """ + data = np.ones((5, 2)) + with clib.Session() as lib: + with pytest.raises(GMTInvalidInput): # noqa: PT012 + with pytest.warns(FutureWarning): + with lib.virtualfile_in( + data=data, required_z=True, check_kind="vector" + ): + pass + + def test_virtualfile_in_fail_non_valid_data(data): """ Should raise an exception if too few or too much data is given. From b7ca239f84f373490d600cae6bad55f35b3808b5 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 28 Mar 2025 21:43:29 +0800 Subject: [PATCH 08/11] Move TODO comment to the top --- pygmt/clib/session.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pygmt/clib/session.py b/pygmt/clib/session.py index bc0a7de836f..c8352421c8a 100644 --- a/pygmt/clib/session.py +++ b/pygmt/clib/session.py @@ -1765,6 +1765,7 @@ def virtualfile_from_stringio( seg.header = None seg.text = None + # TODO(PyGMT>=0.20.0): Remove the deprecated parameter 'required_z'. def virtualfile_in( # noqa: PLR0912 self, check_kind=None, @@ -1836,12 +1837,11 @@ def virtualfile_in( # noqa: PLR0912 ... print(fout.read().strip()) : N = 3 <7/9> <4/6> <1/3> """ - # TODO(PyGMT>=0.20.0): Remove the deprecated 'required_z' parameter. if required_z is True: warnings.warn( - "The parameter 'required_z' is deprecated and will be removed in " - "v0.20.0. Use parameter 'ncols' instead. E.g., ``required_z=True`` is " - "equivalent to ``ncols=3``.", + "The parameter 'required_z' is deprecated in v0.16.0 and will be " + "removed in v0.20.0. Use parameter 'ncols' instead. E.g., " + "``required_z=True`` is equivalent to ``ncols=3``.", category=FutureWarning, stacklevel=1, ) From da874d107b628a3f1c38a2b5e910720e0c354651 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Tue, 15 Apr 2025 10:53:42 +0800 Subject: [PATCH 09/11] Put ncols before required_data --- pygmt/clib/session.py | 2 +- pygmt/helpers/utils.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/pygmt/clib/session.py b/pygmt/clib/session.py index a53c152c5bc..f5b2c26d684 100644 --- a/pygmt/clib/session.py +++ b/pygmt/clib/session.py @@ -1842,8 +1842,8 @@ def virtualfile_in( # noqa: PLR0912 x=x, y=y, z=z, - required_data=required_data, ncols=ncols, + required_data=required_data, kind=kind, ) diff --git a/pygmt/helpers/utils.py b/pygmt/helpers/utils.py index 4be83b10ced..5c4fa66c614 100644 --- a/pygmt/helpers/utils.py +++ b/pygmt/helpers/utils.py @@ -43,7 +43,7 @@ def _validate_data_input( # noqa: PLR0912 - data=None, x=None, y=None, z=None, required_data=True, ncols=2, kind=None + data=None, x=None, y=None, z=None, ncols=2, required_data=True, kind=None ) -> None: """ Check if the combination of data/x/y/z is valid. From 970b8240181e98552f2cff2f69cad488fed62f4d Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Mon, 28 Apr 2025 15:57:42 +0800 Subject: [PATCH 10/11] Update pygmt/clib/session.py Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com> --- pygmt/clib/session.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pygmt/clib/session.py b/pygmt/clib/session.py index 1d4762086f1..5acc1144fef 100644 --- a/pygmt/clib/session.py +++ b/pygmt/clib/session.py @@ -1781,7 +1781,8 @@ def virtualfile_in( # noqa: PLR0912 x/y/z : 1-D arrays or None x, y, and z columns as numpy arrays. ncols - Number of minimum required columns. + Number of minimum required columns. Default is 2 (i.e. require x and y + columns). required_data : bool Set to True when 'data' is required, or False when dealing with optional virtual files. [Default is True]. From 41ff98423152cd156f634e79c7d0b0527e9a5e18 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Mon, 28 Apr 2025 16:55:07 +0800 Subject: [PATCH 11/11] Rename ncols to mincols --- pygmt/clib/session.py | 15 ++++++++------- pygmt/helpers/utils.py | 12 ++++++------ pygmt/src/blockm.py | 2 +- pygmt/src/contour.py | 2 +- pygmt/src/nearneighbor.py | 2 +- pygmt/src/plot3d.py | 2 +- pygmt/src/project.py | 2 +- pygmt/src/surface.py | 2 +- pygmt/src/triangulate.py | 4 ++-- pygmt/src/wiggle.py | 2 +- pygmt/src/xyz2grd.py | 2 +- pygmt/tests/test_clib_virtualfile_in.py | 8 +++++--- 12 files changed, 29 insertions(+), 26 deletions(-) diff --git a/pygmt/clib/session.py b/pygmt/clib/session.py index 5acc1144fef..7680e81108e 100644 --- a/pygmt/clib/session.py +++ b/pygmt/clib/session.py @@ -1757,7 +1757,7 @@ def virtualfile_in( # noqa: PLR0912 x=None, y=None, z=None, - ncols=2, + mincols=2, required_data=True, required_z=False, extra_arrays=None, @@ -1780,7 +1780,7 @@ def virtualfile_in( # noqa: PLR0912 data input. x/y/z : 1-D arrays or None x, y, and z columns as numpy arrays. - ncols + mincols Number of minimum required columns. Default is 2 (i.e. require x and y columns). required_data : bool @@ -1791,7 +1791,8 @@ def virtualfile_in( # noqa: PLR0912 .. deprecated:: v0.16.0 The parameter 'required_z' will be removed in v0.20.0. Use parameter - 'ncols' instead. E.g., ``required_z=True`` is equivalent to ``ncols=3``. + 'mincols' instead. E.g., ``required_z=True`` is equivalent to + ``mincols=3``. extra_arrays : list of 1-D arrays A list of numpy arrays in addition to x, y, and z. All of these arrays must be of the same size as the x/y/z arrays. @@ -1830,12 +1831,12 @@ def virtualfile_in( # noqa: PLR0912 if required_z is True: warnings.warn( "The parameter 'required_z' is deprecated in v0.16.0 and will be " - "removed in v0.20.0. Use parameter 'ncols' instead. E.g., " - "``required_z=True`` is equivalent to ``ncols=3``.", + "removed in v0.20.0. Use parameter 'mincols' instead. E.g., " + "``required_z=True`` is equivalent to ``mincols=3``.", category=FutureWarning, stacklevel=1, ) - ncols = 3 + mincols = 3 kind = data_kind(data, required=required_data) _validate_data_input( @@ -1843,7 +1844,7 @@ def virtualfile_in( # noqa: PLR0912 x=x, y=y, z=z, - ncols=ncols, + mincols=mincols, required_data=required_data, kind=kind, ) diff --git a/pygmt/helpers/utils.py b/pygmt/helpers/utils.py index 3c34941ad11..7223e45fe94 100644 --- a/pygmt/helpers/utils.py +++ b/pygmt/helpers/utils.py @@ -43,7 +43,7 @@ def _validate_data_input( # noqa: PLR0912 - data=None, x=None, y=None, z=None, ncols=2, required_data=True, kind=None + data=None, x=None, y=None, z=None, mincols=2, required_data=True, kind=None ) -> None: """ Check if the combination of data/x/y/z is valid. @@ -66,7 +66,7 @@ def _validate_data_input( # noqa: PLR0912 Traceback (most recent call last): ... pygmt.exceptions.GMTInvalidInput: Must provide both x and y. - >>> _validate_data_input(x=[1, 2, 3], y=[4, 5, 6], ncols=3) + >>> _validate_data_input(x=[1, 2, 3], y=[4, 5, 6], mincols=3) Traceback (most recent call last): ... pygmt.exceptions.GMTInvalidInput: Must provide x, y, and z. @@ -74,13 +74,13 @@ def _validate_data_input( # noqa: PLR0912 >>> import pandas as pd >>> import xarray as xr >>> data = np.arange(8).reshape((4, 2)) - >>> _validate_data_input(data=data, ncols=3, kind="matrix") + >>> _validate_data_input(data=data, mincols=3, kind="matrix") Traceback (most recent call last): ... pygmt.exceptions.GMTInvalidInput: data must provide x, y, and z columns. >>> _validate_data_input( ... data=pd.DataFrame(data, columns=["x", "y"]), - ... ncols=3, + ... mincols=3, ... kind="vectors", ... ) Traceback (most recent call last): @@ -88,7 +88,7 @@ def _validate_data_input( # noqa: PLR0912 pygmt.exceptions.GMTInvalidInput: data must provide x, y, and z columns. >>> _validate_data_input( ... data=xr.Dataset(pd.DataFrame(data, columns=["x", "y"])), - ... ncols=3, + ... mincols=3, ... kind="vectors", ... ) Traceback (most recent call last): @@ -116,7 +116,7 @@ def _validate_data_input( # noqa: PLR0912 GMTInvalidInput If the data input is not valid. """ - required_z = ncols >= 3 + required_z = mincols >= 3 if data is None: # data is None if x is None and y is None: # both x and y are None if required_data: # data is not optional diff --git a/pygmt/src/blockm.py b/pygmt/src/blockm.py index 2f00400fb97..6c32331d298 100644 --- a/pygmt/src/blockm.py +++ b/pygmt/src/blockm.py @@ -56,7 +56,7 @@ def _blockm( with Session() as lib: with ( lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, ncols=3 + check_kind="vector", data=data, x=x, y=y, z=z, mincols=3 ) as vintbl, lib.virtualfile_out(kind="dataset", fname=outfile) as vouttbl, ): diff --git a/pygmt/src/contour.py b/pygmt/src/contour.py index 7519d0cb1e1..ad20bf80c2a 100644 --- a/pygmt/src/contour.py +++ b/pygmt/src/contour.py @@ -148,7 +148,7 @@ def contour( with Session() as lib: with lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, ncols=3 + check_kind="vector", data=data, x=x, y=y, z=z, mincols=3 ) as vintbl: lib.call_module( module="contour", args=build_arg_list(kwargs, infile=vintbl) diff --git a/pygmt/src/nearneighbor.py b/pygmt/src/nearneighbor.py index 39527d331a1..118eba785b0 100644 --- a/pygmt/src/nearneighbor.py +++ b/pygmt/src/nearneighbor.py @@ -147,7 +147,7 @@ def nearneighbor( with Session() as lib: with ( lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, ncols=3 + check_kind="vector", data=data, x=x, y=y, z=z, mincols=3 ) as vintbl, lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd, ): diff --git a/pygmt/src/plot3d.py b/pygmt/src/plot3d.py index 6256410d167..f50894ec060 100644 --- a/pygmt/src/plot3d.py +++ b/pygmt/src/plot3d.py @@ -259,5 +259,5 @@ def plot3d( # noqa: PLR0912 kwargs["S"] = "u0.2c" with Session() as lib: - with lib.virtualfile_in(check_kind="vector", data=data, ncols=3) as vintbl: + with lib.virtualfile_in(check_kind="vector", data=data, mincols=3) as vintbl: lib.call_module(module="plot3d", args=build_arg_list(kwargs, infile=vintbl)) diff --git a/pygmt/src/project.py b/pygmt/src/project.py index e797c5edff1..1356b84495f 100644 --- a/pygmt/src/project.py +++ b/pygmt/src/project.py @@ -246,7 +246,7 @@ def project( x=x, y=y, z=z, - ncols=2, + mincols=2, required_data=False, ) as vintbl, lib.virtualfile_out(kind="dataset", fname=outfile) as vouttbl, diff --git a/pygmt/src/surface.py b/pygmt/src/surface.py index 15dfc154716..d33027b5b7c 100644 --- a/pygmt/src/surface.py +++ b/pygmt/src/surface.py @@ -161,7 +161,7 @@ def surface( with Session() as lib: with ( lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, ncols=3 + check_kind="vector", data=data, x=x, y=y, z=z, mincols=3 ) as vintbl, lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd, ): diff --git a/pygmt/src/triangulate.py b/pygmt/src/triangulate.py index f1ffa2c4ef4..aa50e9d927c 100644 --- a/pygmt/src/triangulate.py +++ b/pygmt/src/triangulate.py @@ -144,7 +144,7 @@ def regular_grid( with Session() as lib: with ( lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, ncols=2 + check_kind="vector", data=data, x=x, y=y, z=z, mincols=2 ) as vintbl, lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd, ): @@ -244,7 +244,7 @@ def delaunay_triples( with Session() as lib: with ( lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, ncols=2 + check_kind="vector", data=data, x=x, y=y, z=z, mincols=2 ) as vintbl, lib.virtualfile_out(kind="dataset", fname=outfile) as vouttbl, ): diff --git a/pygmt/src/wiggle.py b/pygmt/src/wiggle.py index da22756bfd4..c507d13f9f8 100644 --- a/pygmt/src/wiggle.py +++ b/pygmt/src/wiggle.py @@ -109,6 +109,6 @@ def wiggle( with Session() as lib: with lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, ncols=3 + check_kind="vector", data=data, x=x, y=y, z=z, mincols=3 ) as vintbl: lib.call_module(module="wiggle", args=build_arg_list(kwargs, infile=vintbl)) diff --git a/pygmt/src/xyz2grd.py b/pygmt/src/xyz2grd.py index db99cec2c33..4ff93bda894 100644 --- a/pygmt/src/xyz2grd.py +++ b/pygmt/src/xyz2grd.py @@ -155,7 +155,7 @@ def xyz2grd( with Session() as lib: with ( lib.virtualfile_in( - check_kind="vector", data=data, x=x, y=y, z=z, ncols=3 + check_kind="vector", data=data, x=x, y=y, z=z, mincols=3 ) as vintbl, lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd, ): diff --git a/pygmt/tests/test_clib_virtualfile_in.py b/pygmt/tests/test_clib_virtualfile_in.py index 393bdd74c93..7203bbcd4ad 100644 --- a/pygmt/tests/test_clib_virtualfile_in.py +++ b/pygmt/tests/test_clib_virtualfile_in.py @@ -41,7 +41,7 @@ def test_virtualfile_in_required_z_matrix(array_func, kind): ) data = array_func(dataframe) with clib.Session() as lib: - with lib.virtualfile_in(data=data, ncols=3, check_kind="vector") as vfile: + with lib.virtualfile_in(data=data, mincols=3, check_kind="vector") as vfile: with GMTTempFile() as outfile: lib.call_module("info", [vfile, f"->{outfile.name}"]) output = outfile.read(keep_tabs=True) @@ -62,7 +62,7 @@ def test_virtualfile_in_required_z_matrix_missing(): data = np.ones((5, 2)) with clib.Session() as lib: with pytest.raises(GMTInvalidInput): - with lib.virtualfile_in(data=data, ncols=3, check_kind="vector"): + with lib.virtualfile_in(data=data, mincols=3, check_kind="vector"): pass @@ -104,7 +104,9 @@ def test_virtualfile_in_fail_non_valid_data(data): continue with clib.Session() as lib: with pytest.raises(GMTInvalidInput): - lib.virtualfile_in(x=variable[0], y=variable[1], z=variable[2], ncols=3) + lib.virtualfile_in( + x=variable[0], y=variable[1], z=variable[2], mincols=3 + ) # Should also fail if given too much data with clib.Session() as lib: