Repository navigation
Naming conventions for parameter names #2014
Copy link
Copy link
Closed
Labels
discussionsNeed more discussion before taking further actionsNeed more discussion before taking further actions
Milestone
Description
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 bestraigthline,errorbar,no_datapygmt.Figure.rose():vector_params(M)
Should bevectorparams.
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 |
marginsclearance |
#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 |
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
discussionsNeed more discussion before taking further actionsNeed more discussion before taking further actions
Activity
maxrjones commentedon Aug 2, 2022
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 commentedon Aug 3, 2022
Thanks @maxrjones for the explanation and the background information!
seisman commentedon Dec 15, 2023
I don't think we will rename these aliases. So closing the issue.
seisman commentedon Dec 5, 2025
Here is a Python script written by ChatGPT to print all parameters of PyGMT functions and Figure's plotting methods:
The full list of parameters are pasted below:
Details
seisman commentedon Dec 5, 2025
Below is a long list of parameters that contain two words.
Details
I feel they can be categorized into four groups:
anti_alias,no_skip.Click to see the list
color_model,event_nameClick to see the list
autolabelClick to see the list
bordervaluesClick to see the list
alable,xshfit(some may be controversial)Click to see the list
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, andfacade_pen, which can be quite confusing.seisman commentedon Dec 5, 2025
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 commentedon Dec 6, 2025
Ping @GenericMappingTools/pygmt-maintainers for discussions on this issue.
yvonnefroehlich commentedon Dec 8, 2025
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_fillinstead ofspline_fill(currentlysplinefill),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?
weiji14 commentedon Dec 9, 2025
Just wanted to float the idea of going for a breaking PyGMT v1.0.0 release with all these parameter name changes. Though ideally, we should still go through a deprecation cycle with at least one or two minor releases with the old/new names. So e.g., deprecate in v0.18.0 and v0.19.0, then make jump to v1.0.0.
1 remaining item
weiji14 commentedon Dec 9, 2025
Yes, or we could align it with the paper publication (whenever the review is finalized). There are some issues in the v1.0.0 milestone that could be moved to v2 perhaps if we're serious on a major release next year.
seisman commentedon Dec 9, 2025
I'm a little hesitant about a v1.0.0 release next year, as several parameters still take non-Pythonic arguments.
[-]Usage of underscores in aliases[/-][+]Naming conventions for parameter names[/+]seisman commentedon Dec 9, 2025
I believe we've reached an agreement to use underscores between words. This also aligns with the PEP 8 style guide, which recommends:
That said, we need to rename and deprecate some parameter names, but I feel it may make sense not to use underscores for some parameters, especially when a parameter name is already a well-recognized shorthand. For example:
surftypeinstead ofsurf_typeorsurface_typehisttypeinstead ofhist_typetimefmtinstead oftime_fmtortime_formatyvonnefroehlich commentedon Dec 11, 2025
Besides this, there is the discussion about dropping the support of the single-letter flags from GMT with the release of v1.0.0. (However, there are some concerns from users.)
Do we plan to rename all these aliases for the release of v0.18.0?
seisman commentedon Dec 12, 2025
Yes, I think we should rename most of them, especially those used in the manuscript.
seisman commentedon Dec 13, 2025
@yvonnefroehlich If you want, please also the Contributors Guides.
yvonnefroehlich commentedon Dec 16, 2025
Some more (see also the overview table added at the beginning of this issue based on the script from Dongdong):
skiprows: Would change it toskip_rows.Deprecate parameter skiprows to skip_rows (Will be removed in v0.20.0) #4295
combitable: Would change it tocombi_table.pygmt.x2sys_cross: Deprecate parameter combitable to combi_table (Will be removed in v0.2X.0) #4293
runtimes: Would change it torun_times.pygmt.x2sys_cross: Deprecate parameter runtimes to run_times (Will be removed in v0.20.0) #4294
marginforFigure.insetbutmargins(plural) forFigure.suplot: Would use both timesmarginsfor -M.Figure.inset: Deprecate parameter margin to clearance (Will be removed in v0.20.0) #4296
unitsforpygmt.x2sys_initbutunitfor the rest.pygmt.project: Deprecate parameter unit to units (Will be removed in v0.2X.0) #4297
startpoint,endpoint,numpoint: Could be fine as is; orstart_point,end_point,num_point?imagefile,textfiles,worldfile: Could be fine as is; orimage_file,text_files,world_file?newcolnamebutevent_name,distribution_name: Unsure, i.e.,new_col_name?seisman commentedon Dec 17, 2025
Yes.
x2sys_inittakes a list of units, sounitsis correct.startpoint: I don't find it in the codes.endpoint: sometimes it's taken as a single wordnumpoints: The docstrings say "Give the maximum number of data points on either side of the crossover to use in the spline interpolation [3].". I feelnumpointsis not a suitable name for it.I prefer to keep them unchanged.
I prefer to keep
newcolname.yvonnefroehlich commentedon Dec 17, 2025
Your are right, there is no parameter called
startpoint. I was mixing it up withcenterfor -C of pygmt.project.yvonnefroehlich commentedon Dec 17, 2025
One more (hopefully the last one): We have
max_retriesforFigure.tilemapbutmaxradiusforpygmt.surface. Leavemaxradiusas is or change it tomax_radius?seisman commentedon Dec 17, 2025
I think yes.
yvonnefroehlich commentedon Dec 18, 2025
I think we have renamed most of the affected parameter names (see also the overview table in #2014 (comment)). Some parameter names need more discussions reading the new name or a more Pythonic syntax.
skiprowsandnodataremain unchanged as too many functions / methods would be affected.seisman commentedon Dec 18, 2025
I guess we can close the issue. We will revisit these PRs later.