Refactor the virtualfile_in function to accept more 1-D arrays

[seisman]

Description of proposed changes

Here are the current definitions of the virtualfile_from_data method and the data_kind function:

pygmt/pygmt/clib/session.py

Lines 1473 to 1483 in c9d6147

	def virtualfile_from_data(
	self,
	check_kind=None,
	data=None,
	x=None,
	y=None,
	z=None,
	extra_arrays=None,
	required_z=False,
	required_data=True,
	):

pygmt/pygmt/helpers/utils.py

Line 110 in c9d6147

def data_kind(data=None, x=None, y=None, z=None, required_z=False, required_data=True):

When I started issue #2731, I realized the current function definitions have some limitations:

1. For some modules, the number of input columns can vary, depending on the given options. For example, binstats usually requires 3 columns (x/y/z), but only requires 2 columns (x/y) if -Cn is used, and requires 4 columns (x/y/z/w) if -W is used. I don't think we want to add w=None and required_w=False to these functions. Also, we don't check if the input table has the required number of columns.
2. The data_kind function does three things: (1) determines the kind of the input data, and (2) checks if the data/x/y/z combinations are valid; and (3) checks if the matrix-type data has 3 columns. The data_kind function is called inside virtualfile_from_data, but sometimes we need to know in data kind when wrapping GMT modules, for example, in Figure.plot and Figure.plot3d. It means the data_kind function is called twice, which is not necessary.

Solutions:

1. Refactor the virtualfile_from_data function like data=None, vectors=None, names=["x", "y"]. vectors is a list of vectors (e.g., vectors=[x, y]) and names is a list of column names. The wrappers are responsible for preparing the list of 1-D arrays (vectors) and counting the column names (names).
2. Let the data_kind focus on determining the data kind and have another separate function to check if the input data/vectors are valid.

[seisman]

I think it's more useful to pass the list of column names instead, i.e., replacing ncols=2 with names=["x", "y"].

So, for most modules, vectors=["x", "y"] and names=["x", "y"] or vectors=[x, y, z] and names=["x", "y", "z"].

For more complicated modules like plot or plot3d, the names can be
names=["x", "y", "direction_arg1", "direction_arg2", "fill", "size", "symbol", "transparency"].

The column names will be very useful when the GMTInvalidInput exception is raised.
For example, instead of "Column 5 can't be None.", we can say "Column 5 ('size') can't be None.". Instead of "data must have at least 8 columns.", we can say

data must have at least 8 columns:
x y direction_arg1 direction_arg2 fill size symbol transparency

[seisman]

Done in f37413b

[weiji14]

Missing unit test for this if-condition.

[weiji14]

Missing unit test for this if-condition.

[weiji14]

Need to append 'z' to names here? Also, need a unit test for this if-condition.

[seisman]

Actually no. The problem is that project only requires two columns, but three or more columns are required. Currently, the variable names are used for two purposes: (1) names of passed columns; (2) the number of columns. So, if we append z to names here, the calling pygmt.project(data=data) will fail if data has only two columns. I think we still need to maintain a variable for the number of required columns.

[weiji14]

The validation checks have been moved from within data_kind to virtualfile_from_data here. But in plot.py, we actually use data_kind on its own here:

pygmt/pygmt/src/plot.py

Line 217 in 3076ddc

kind = data_kind(data, x, y)

Are we ok with raising GMTInvalidInput much later here in virtualfile_from_data (after all the keyword argument parsing), rather than early on in data_kind?

[seisman]

Closing this PR since it will be superseded by #3369.