Standardize parameter name for table data inputs

[weiji14]

Description of the desired feature

Originally posted by @meghanrjones in #1441 (comment)

This is somewhat related - I am not sure if it's worth a deprecation but I think we should decide on whether the parameter for tabular input is data or table for all modules moving forward. Currently, this is the distribution:

data parameter: surface, wiggle, velo, rose, plot3d, plot, contour
table parameter: blockmedian, blockmean, histogram
other: grdtrack (points), text (textfiles)

It would also be worthwhile to set a consistent order for the positional arguments x, y, [z], data, [outfile]

Are you willing to help implement and maintain this feature? Discuss first

[weiji14]

One option to reduce the amount of deprecation notices is to keep two parameters, but with this rule:

• data - use for the fig.* plotting functions (e.g. fig.plot, fig.contour, etc)
• table - use for the data processing functions (e.g. blockmean, histogram, etc)

This way, we'll only need to do the renaming for surface ('data' -> 'table'), grdtrack ('points' -> 'table') and text ('textfiles' -> 'data'). I have some reservations with renaming text's 'textfiles' to 'data' since it's a bit non-standard (and need to wait for #1121), but otherwise, what do people think?

[maxrjones]

One option to reduce the amount of deprecation notices is to keep two parameters, but with this rule:

* `data` - use for the `fig.*` plotting functions (e.g. `fig.plot`, `fig.contour`, etc)

* `table` - use for the data processing functions (e.g. `blockmean`, `histogram`, etc)

This way, we'll only need to do the renaming for surface ('data' -> 'table'), grdtrack ('points' -> 'table') and text ('textfiles' -> 'data'). I have some reservations with renaming text's 'textfiles' to 'data' since it's a bit non-standard (and need to wait for #1121), but otherwise, what do people think?

One complication is that many modules can be plotting or processing (e.g., histogram is mostly plotting but can return statistics with -I). My preference would be to use data moving forward and, if needed, deprecate table to data in blockmean, blockmedian, and histogram. grdtrack and text are non-standard enough for different names in my opinion.

[weiji14]

One complication is that many modules can be plotting or processing (e.g., histogram is mostly plotting but can return statistics with -I).

Those types of dual-purpose functions (e.g. histogram, rose, solar) might end up having two APIs, depending on how we decide at #896. E.g. a fig.histogram for plotting and pygmt.histogram for extracting data.

My preference would be to use data moving forward and, if needed, deprecate table to data in blockmean, blockmedian, and histogram. grdtrack and text are non-standard enough for different names in my opinion.

Ok, sounds like we need a vote. So the options are:

• 🎉 Use data only for all functions, as per Meghan at Standardize parameter name for table data inputs #1479 (comment)
• 🚀 Use table only for all functions
• 👀 Use data for plotting functions, table for processing functions as per Wei Ji at Standardize parameter name for table data inputs #1479 (comment).
• 😕 Some other alternative - leave a comment below.

Place your vote on this comment. Only one vote per person 😛

[maxrjones]

Can we also set the conventional order for the positional arguments as data/table, x, y, [z] or x, y, [z], data/table? My opinion is that this isn't worth deprecating any current syntax, but that #1434, #1429, #1418, #1379, #731 and #1491 should have the same order (if both data/table and x/y[/z] will be supported).

Here's the current count:

• x, y, [z], data/table - (5 current functions) contour, plot3d, wiggle, surface, plot (Used in PRs Wrap nearneighbor #1379
• data/table, [outfile], x, y, [z] - (2 current functions) blockmean, blockmedian (Used in PRs Wrap triangulate #731, Wrap blockmode #1456)
• only data/table with no x/y[/z] option - (2 current functions and 2 functions in v0.5.0) histogram, sphdistance, xyz2grd, info (Used in PRs Wrap gmtselect #1429, Wrap sph2grd #1434, Wrap sphinterpolate #1418, Expand table-like input options for sphdistance #1491)

[weiji14]

Can we also set the conventional order for the positional arguments as data/table, x, y, [z] or x, y, [z], data/table?

Yes, good point. I would say just go with data, x, y, [z], so people can do pygmt.somefunction(data) if data is a pandas.DataFrame/geopandas.GeoDataFrame or any table-like input, similar to other Python-like plotting/processing code like plt.imshow. In this case, we would need to modify:

• x, y, [z], data/table - (5 current functions) contour, plot3d, wiggle, surface, plot (Used in PRs Wrap nearneighbor #1379

Debating on whether we should go through a deprecation cycle (2 releases) for the x/y/z/data -> data/x/y/z parameter ordering change. Personally I try to always do parameter=arg in my code, but many people just pass in the arguments directly. So maybe best to raise a warning to give people time to switch over 🙃

[maxrjones]

Can we also set the conventional order for the positional arguments as data/table, x, y, [z] or x, y, [z], data/table?

Yes, good point. I would say just go with data, x, y, [z], so people can do pygmt.somefunction(data) if data is a pandas.DataFrame/geopandas.GeoDataFrame or any table-like input, similar to other Python-like plotting/processing code like plt.imshow. In this case, we would need to modify:

• x, y, [z], data/table - (5 current functions) contour, plot3d, wiggle, surface, plot (Used in PRs Wrap nearneighbor #1379

Debating on whether we should go through a deprecation cycle (2 releases) for the x/y/z/data -> data/x/y/z parameter ordering change. Personally I try to always do parameter=arg in my code, but many people just pass in the arguments directly. So maybe best to raise a warning to give people time to switch over 🙃

Sounds good. If we will make the change for the functions that have x/y/z/data, I think we should raise a warning.