Naming conventions for parameter names

[yvonnefroehlich]

In the Contributors Guide in the section Code Style:

When wrapping a new alias, use an underscore to separate words bridged by vowels (aeiou), such as no_skip and z_only. Do not use an underscore to separate words bridged only by consonants, such as distcalc, and crossprofile. This convention is not applied by the code checking tools, but the PyGMT maintainers will comment on any pull requests as needed.

However, some aliases seem not to follow this convention. For example:

• pygmt.Figure.plot(): straight_line (A) , error_bar (E), nodata (d)
  Following the convention, they should be straigthline, errorbar , no_data
• pygmt.Figure.rose(): vector_params (M)
  Should be vectorparams.

Please note: This is primarily meant as a general question for understanding, rather than a request for renaming these aliases. 😉

---

Overview table

• ✔️: Changed (PR merged)
• 🚀: TODO / WIP (PR planed or opened)
• ❔: Need disscussion
• 🚧: Need to wait (PR converted to draft)
• ❌: Not changed
• : Already fine

Click to show the table

status	old name	new name	PR	comment
	above
❌	alabel	a_label		see also blabel, clabel
	aliases
	alpha
	angle
	annotate
	annotation
	anti_alias
	anti_aliasing
	area_thresh
	aspatial
🚧	autolabel	auto_label	#4275	not Pythonic yet
	azimuth
	background
✔️	barwidth	bar_width	#4279	split into bar_width and bar_offset in second PR
	bb_style
	below
	between
	binary
🚧	bitcolor	bit_color	#4280	not Pythonic yet
❌	blabel			see also alabel, clabel
✔️	bordervalues	border_values	#4281
	borders
	box
	categorical
	center
	circ_subregion
❌	clabel	c_label		see also alabel, blabel
	clearance
	close
	cmap
	color_model
❌	coltypes	col_types, column_types		shortcut
🚧	combitable	combi_table	#4293	pygmt.x2sys_cross; need suitable name
	compass
	component
✔️	compressionfill	compression_fill	#4269
	connection
✔️	constantfill	constant_fill	#4273
	continuous
	contour
✔️	contourpen	contour_pen	#4260
	convention
	convergence
	cores
	critical
	crop
🚧	crossprofile	cross_profile	#4278	not Pythonic yet
	crs
❌	cstyle	c_style
	cumulative
	cyclic
	data
	data_source
	dcw
	depth
❌	dfile	d_file
	diameter
	direction
	discontinuity
	dist2line
	dist2pt
	distance
❌	distcalc	dist_calc		shortcut
	distribution
	distribution_name
	download
	dpi
✔️	drapegrid	drape_grid	#4276
	duplicate
	ellipse
	empty
❌️	endpoint	end_point		partly written as one word
🚧	equalsize	equal_size	#4277	not Pythonic yet
	error_bar
	event_name
	extend
✔️	extensionfill	extension_fill	#4269
	extreme
✔️	-	facade_fill	#4235	split -N into plane and facade_fill
✔️	facadepen	facade_pen	#4260
❌	figsize	fig_size
	fill
	filter
	filter_type
	find
🚧	fixedlabel	fixed_label	#4275	not Pythonic yet
	flat_earth
	fmt
❌	fmtfile	fmt_file		shortcut
❌	fname	fig_name		shortcut
	font
	force
	force_scan
	frame
	gap
	generate
	geographic
	grid
✔️	gridfill	grid_fill	#4273
	gs_option
	gs_path
	gs_version
	header
❌	histtype	hist_type		shortcut
	hole
	horizontal
	image
❌	imagefile	image_file		see also textfiles, worldfile
	img_in			-D of Figure.grdimage
	incols
	inquire
	intensity
	interpolation
	inverse
	justify
	label
✔️	labelbox	label_box	#4274
	label_placement
	labels
	lakes
	land
	latitude
	length
	levels
	limit
	log
	longitude
❌	lonlat	lon_lat		shortcut
	lower
	map_scale
✔️	margin	margins clearance	#4296	for -C of Figure.inset, for GMT <= 6.4 it was -M
	margins			for -M of Figure.subplot
✔️	grid_mask	mask_grid	#4283
✔️	mask	mask_values	#4288	for -N of pygmt.select
✔️	maskvalues	mask_values	#4281	for -N of pygmt.grdlandmask
	max_retries
✔️	maxradius	max_radius	#4300	consistency
✔️	meshpen	mesh_pen	#4260
	method
	monochrome
	nan_transparent
	nans
❌	ncols	n_cols
	nearest_multiple
✔️	fillnegative	negative_fill	#4271
✔️	neighborfill	neighbor_fill	#4271
❌️	newcolname	new_col_name		see event_name, distribution_name
❌	nlevels	n_levels
	no_bg
	no_clip
	no_scale
	no_skip
	no_sort
	nodal
❌	nodata	no_data		used in too many functions
	no_data		for -N of pygmt.grdfill, deprecated to hole in v0.19.0
	node_table
	norm
	normalize
❌	nrows	n_rows
🚧	numpoints	num_points		-W of pygmt.x2sys_cross; need suitable name
	offset
	orientation
	outcols
	outfile
	outgrid
	outline
	output
	output_type
	override
	overrule_bg
	panel
	pen
	per_column
	perspective
	plane
	plot_latitude
	plot_longitude
	points
	pole
	polygon
	position
✔️	fillpositive	positive_fill	#4271
	prefix
	profile
	projection
	quantile_value
	quantity
	radiance
	radius
	region
	registration
	replace
	required
	resample
	rescale
	resize
	resolution
	reverse
	rivers
	rose
❌	runtimes	run_times	#4294	-C of Figure.x2sys_cross; in Computer Sciences one word
	scale
	scaling
	search_radius
	sector			-A of Figure.rose
	sectors			-N of pygmt.dimfilter
	series
	shading
❌	sharex	share_x
❌	sharey	share_y
	shift
	shorelines
	show
	single_form
	size
	skip
❌	skiprows	skip_rows	#4295	used in five functions
	slope_file
	sort
	source
	spacing
	spec
	speed
✔️	splinefill	spline_fill	#4273
	stack
	stairs
	statistic
	straight_line
	style
❌	subsize	sub_size
	suffix
	summary
❌	surftype	surf_type		shortcut
	symbol
	tag
	tension
	terminator
	terminator_datetime
	text
❌	textfiles	text_files		see also imagefile, worldfile
	tiles
	time_col
❌ ❔	timefmt	time_fmt		shortcut
	title
	toggle
	track
✔️	trackvalues	track_values	#4282
	tracks
	transparency
	transparent
	triangular_mesh_pen
	truncate
	uncertainty
✔️	uncertaintyfill	uncertainty_fill	#4272
🚧	unit	units	#4297	for Q of pygmt.project; need suitable name
	`unit			for -M of pygmt.grdproject, -L of pygmt.sphdistance
	units			for -M of pygmt.x2sys_init
	upper
	use_srtm
	use_word
	vector			-A of Figure.veloc
	vector_params
	vectors			-Em of Figure.rose
	verbose
	voronoi
	wait
	water
	weight
	width
❌❔	worldfile	world_file		see also imagefile, textfiles
	wrap
	x
❌	xmax	x_max
❌	xmin	x_min
❌	xshift	x_shift
	y
❌	ymax	y_max
❌	ymin	y_min
❌	yshift	y_shift
	z
	z_only
	z_subregion
❌	zfile	z_file
	zoom
	zoom_adjust
❌	zscale	z_scale
❌	zsize	z_size
❌	zvalue	z_value

[maxrjones]

I think that the aliases that do not follow this convention were added to PyGMT before the convention was established. For context, the idea of a convention to ensure consistency for alias names was first suggested in #1190 (comment) and added in #1256.

[yvonnefroehlich]

Thanks @maxrjones for the explanation and the background information!

[seisman]

I don't think we will rename these aliases. So closing the issue.

[seisman]

Here is a Python script written by ChatGPT to print all parameters of PyGMT functions and Figure's plotting methods:

import inspect
import pygmt

def list_pygmt_parameters():
    results = {}

    # A helper to extract parameters from a callable
    def extract(name, obj):
        try:
            sig = inspect.signature(obj)
            params = list(sig.parameters.keys())
            results[name] = params
        except (TypeError, ValueError):
            pass

    # 1. Inspect top-level PyGMT module
    for name, obj in inspect.getmembers(pygmt):
        if inspect.isfunction(obj):
            extract(f"pygmt.{name}", obj)

    # 2. Inspect Figure class methods
    for name, obj in inspect.getmembers(pygmt.Figure):
        if inspect.isfunction(obj) or inspect.ismethod(obj):
            # Skip private or dunder methods
            if not name.startswith("_"):
                extract(f"pygmt.Figure.{name}", obj)

    # 3. Inspect submodules (datasets, helpers, etc.)
    for submodule_name, submodule in inspect.getmembers(pygmt, inspect.ismodule):
        prefix = f"pygmt.{submodule_name}"
        for name, obj in inspect.getmembers(submodule):
            if inspect.isfunction(obj):
                extract(f"{prefix}.{name}", obj)

    return results


all_params = list_pygmt_parameters()

# Print each method/function and its parameters
for name, params in list(all_params.items()):
    print(name, params)

# Print all parameters
unique_params = []
for name, params in list(all_params.items()):
    unique_params.extend(params)
for param in sorted(set(unique_params)):
    print(param)

The full list of parameters are pasted below:

Details

above
alabel
aliases
alpha
angle
annotate
annotation
anti_alias
anti_aliasing
area_thresh
args
argstr
aspatial
autolabel
azimuth
background
barwidth
bb_style
below
between
binary
bitcolor
blabel
borders
bordervalues
box
categorical
center
circ_subregion
clabel
clearance
close
cmap
coe
color_model
coltypes
combitable
compass
component
compressionfill
confdict
connection
constantfill
continuous
contour
contourpen
convention
convergence
conversions
cores
critical
crop
crossprofile
crs
cstyle
cumulative
cut
cyclic
data
data_source
dcw
deprecate_version
depth
dfile
diameter
direction
discontinuity
dist2line
dist2pt
distance
distcalc
distribution
distribution_name
download
dpi
drapegrid
duplicate
ellipse
empty
encoding
end
endpoint
equalsize
error_bar
event_name
extend
extensionfill
extreme
facadepen
figsize
file
filename_or_obj
fill
fillnegative
fillpositive
filter
filter_type
find
fixedlabel
flat_earth
fmt
fmtfile
fname
font
force
force_scan
frame
func
gap
generate
geographic
geojson
grid
gridfill
gridmask
gs_option
gs_path
gs_version
header
histtype
hole
horizontal
image
imagefile
img_in
incols
infile
inquire
intensity
interpolation
inverse
justify
kind
kwargs
kwdict
label
label_placement
labelbox
labels
lakes
land
latitude
length
levels
limit
line
log
longitude
lonlat
lower
map_scale
mapping
margin
margins
mask
maskvalues
max_retries
maxradius
meshpen
method
mincols
minmax_pos
mode
modname
module_func
monochrome
name
nan_transparent
nans
ncols
ndim
nearest_multiple
neighborfill
newcolname
newname
nlevels
no_bg
no_clip
no_scale
no_skip
no_sort
nodal
nodata
node_table
norm
normalize
nrows
numpoints
offset
oldname
orientation
outcols
outfile
outgrid
outline
output
output_type
override
overrule_bg
panel
pen
per_column
perspective
plane
plot_latitude
plot_longitude
points
pole
polygon
position
prefix
profile
projection
quantile_value
quantity
radiance
radius
region
registration
remove_version
replace
required
resample
rescale
resize
resolution
reverse
rivers
rose
runtimes
scale
scaling
search_radius
sector
sectors
self
sep
separator
series
shading
sharex
sharey
shift
shorelines
show
single_form
size
skip
skiprows
slope_file
sort
source
spacing
spec
speed
splinefill
stack
stairs
statistic
straight_line
style
subsize
suffix
summary
surftype
symbol
tag
tension
terminator
terminator_datetime
text
textfiles
tiles
time_col
timefmt
title
toggle
track
tracks
trackvalues
transparency
transparent
triangular_mesh_pen
truncate
uncertainty
uncertaintyfill
unit
units
upper
use_srtm
use_word
value
vector
vector_params
vectors
verbose
voronoi
wait
waiting
water
weight
width
worldfile
wrap
x
xmax
xmin
xshift
y
ymax
ymin
yshift
z
z_only
z_subregion
zfile
zoom
zoom_adjust
zscale
zsize
zvalue

[seisman]

Below is a long list of parameters that contain two words.

Details

alabel
anti_alias
anti_aliasing
area_thresh
argstr
aspatial
autolabel
barwidth
bb_style
bitcolor
blabel
bordervalues
circ_subregion
clabel
color_model
coltypes
combitable
compressionfill
confdict
constantfill
contourpen
convention
crossprofile
cstyle
data_source
deprecate_version
dfile
dist2line
dist2pt
distance
distcalc
drapegrid
endpoint
equalsize
error_bar
event_name
extensionfill
facadepen
figsize
filename_or_obj
fillnegative
fillpositive
filter_type
fixedlabel
flat_earth
fmtfile
force_scan
gridfill
gridmask
gs_option
gs_path
gs_version
histtype
imagefile
img_in
incols
infile
label_placement
labelbox
lonlat
map_scale
maskvalues
max_retries
maxradius
meshpen
mincols
minmax_pos
module_func
nan_transparent
nearest_multiple
neighborfill
newcolname
newname
nlevels
no_bg
no_clip
no_scale
no_skip
no_sort
nodata
node_table
nrows
numpoints
oldname
outcols
outfile
outgrid
outline
output_type
overrule_bg
per_column
plot_latitude
plot_longitude
quantile_value
remove_version
search_radius
sharex
sharey
single_form
skiprows
slope_file
splinefill
straight_line
subsize
surftype
terminator_datetime
textfiles
time_col
timefmt
trackvalues
triangular_mesh_pen
uncertaintyfill
use_srtm
use_word
vector_params
worldfile
xmax
xmin
xshift
ymax
ymin
yshift
z_only
z_subregion
zfile
zoom_adjust
zscale
zsize
zvalue

I feel they can be categorized into four groups:

1. Follow the current naming convention and use underscores, e.g., anti_alias, no_skip.

Click to see the list

anti_alias
anti_aliasing
area_thresh
data_source
deprecate_version
filename_or_obj
force_scan
img_in
module_func
no_bg
no_clip
no_scale
no_skip
no_sort
node_table
overrule_bg
slope_file
quantile_value
remove_version
single_form
time_col
use_srtm
use_word

2. Violate the current naming convention and use underscores, e.g., color_model, event_name

Click to see the list

bb_style
circ_subregion
color_model
error_bar
event_name
filter_type
flat_earth
gs_option
gs_path
gs_version
label_placement
map_scale
max_retries
minmax_pos
nan_transparent
nearest_multiple
output_type
per_column
plot_latitude
plot_longitude
search_radius
straight_line
terminator_datetime
triangular_mesh_pen
vector_params
z_only
z_subregion
zoom_adjust

3. Violate the current naming convention, don't use underscores, and can be more readable with underscores, e.g., autolabel

Click to see the list

autolabel
facadepen
splinefill

4. Follow the current naming convention, don't use underscore, but can be more readable with underscores, e.g., bordervalues

Click to see the list

barwidth
bitcolor
bordervalues
combitable
compressionfill
constantfill
contourpen
crossprofile
equalsize
extensionfill
fillnegative
fillpositive
fixedlabel
labelbox
maskvalues
maxradius
meshpen
neighborfill
trackvalues
uncertaintyfill

5. Follow the current naming convention; don't use underscore, but is fine without underscores, e.g., alable, xshfit (some may be controversial)

Click to see the list

alabel
argstr
aspatial
blabel
clabel
coltypes
confdict
cstyle
dfile
dist2line
dist2pt
distance
distcalc
drapegrid
endpoint
figsize
fmtfile
gridfill
gridmask
histtype
imagefile
incols
infile
lonlat
mincols
newcolname
newname
nlevels
nodata
nrows
numpoints
oldname
outcols
outfile
outgrid
outline
sharex
sharey
skiprows
subsize
surftype
textfiles
timefmt
worldfile
xmax
xmin
xshift
ymax
ymin
yshift
zfile
zscale
zsize
zvalue

I agree with @yvonnefroehlich that always using underscores between two words can make the parameter names more readable, and also avoid some inconsistencies. For example, if we follow our current naming convention strictly, we should use contourpen, meshpen, and facade_pen, which can be quite confusing.

[seisman]

In other words, if we decide to follow the current convention strictly, we should fix parameters in group 3 and group 2. If we decide to always use underscores between words (unless the word is already in a short form, e.g., fmtfile), we should fix parameters in group 3 and group 4.

[seisman]

Ping @GenericMappingTools/pygmt-maintainers for discussions on this issue.

[yvonnefroehlich]

Especially from group 2, it's visible that we do not really follow the current convention. I think always using an underscore improves the readability and clarity for users, and for us it's easier to set up new alias names. Thus I would not change the alias names in group 2 to not use an underscore. E.g., if we decide to always use an underscore, we could have spline_fill, compression_fill, extension_fill, negative_fill, positive_fill, grid_fill instead of spline_fill (currently splinefill), compressionfill, extensionfill, fillnegative, fillpositive, gridfill.

In case we decide to fix the names (in any direction), we should do this soon, as we should definitely use the changed parameter names in the paper. It looks like there are fewer parameters in groups 3 and 4 than in groups 3 and 2. I would like to have the naming more consistent and clearer, and I think it pays off in a long-term view, but I do not know how happy users will be with several parameter name changes...

BTW is there any rule used for the Julia wrapper or for the long names for GMT?