Skip to content

Naming conventions for parameter names #2014

Closed

Description

@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

Activity

  1. maxrjones commented on Aug 2, 2022

    @maxrjones
    Member

    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.

  2. yvonnefroehlich commented on Aug 3, 2022

    @yvonnefroehlich
    MemberAuthor

    Thanks @maxrjones for the explanation and the background information!

  3. seisman commented on Dec 15, 2023

    @seisman
    Member

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

  4. reopened this on Dec 5, 2025
  5. seisman commented on Dec 5, 2025

    @seisman
    Member

    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
    
  6. seisman commented on Dec 5, 2025

    @seisman
    Member

    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
    
    1. 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
    
    1. 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
    
    1. 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
    
    1. 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.

  7. seisman commented on Dec 5, 2025

    @seisman
    Member

    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.

  8. added
    discussionsNeed more discussion before taking further actions
    and removed
    questionFurther information is requested
    on Dec 6, 2025
  9. added this to the 0.18.0 milestone on Dec 6, 2025
  10. seisman commented on Dec 6, 2025

    @seisman
    Member

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

  11. yvonnefroehlich commented on Dec 8, 2025

    @yvonnefroehlich
    MemberAuthor

    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?

  12. weiji14 commented on Dec 9, 2025

    @weiji14
    Member

    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...

    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.

  13. 1 remaining item

  14. weiji14 commented on Dec 9, 2025

    @weiji14
    Member

    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.

  15. seisman commented on Dec 9, 2025

    @seisman
    Member

    I'm a little hesitant about a v1.0.0 release next year, as several parameters still take non-Pythonic arguments.

  16. changed the title [-]Usage of underscores in aliases[/-] [+]Naming conventions for parameter names[/+] on Dec 9, 2025
  17. seisman commented on Dec 9, 2025

    @seisman
    Member

    I believe we've reached an agreement to use underscores between words. This also aligns with the PEP 8 style guide, which recommends:

    Use the function naming rules: lowercase with words separated by underscores as necessary to improve readability.

    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:

    • surftype instead of surf_type or surface_type
    • histtype instead of hist_type
    • timefmt instead of time_fmt or time_format
  18. yvonnefroehlich commented on Dec 11, 2025

    @yvonnefroehlich
    MemberAuthor

    I'm a little hesitant about a v1.0.0 release next year, as several parameters still take non-Pythonic arguments.

    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?

  19. seisman commented on Dec 12, 2025

    @seisman
    Member

    Yes, I think we should rename most of them, especially those used in the manuscript.

  20. seisman commented on Dec 13, 2025

    @seisman
    Member

    @yvonnefroehlich If you want, please also the Contributors Guides.

  21. yvonnefroehlich commented on Dec 16, 2025

    @yvonnefroehlich
    MemberAuthor

    Some more (see also the overview table added at the beginning of this issue based on the script from Dongdong):

  22. seisman commented on Dec 17, 2025

    @seisman
    Member
    • margin for Figure.inset but margins (plural) for Figure.suplot: Would use both times margins for -M.

    Yes.

    • units for pygmt.x2sys_init but unit for the rest.

    x2sys_init takes a list of units, so units is correct.

    • startpoint, endpoint, numpoint : Could be fine as is; or start_point, end_point, num_point ?
    • startpoint: I don't find it in the codes.
    • endpoint: sometimes it's taken as a single word
    • numpoints: The docstrings say "Give the maximum number of data points on either side of the crossover to use in the spline interpolation [3].". I feel numpoints is not a suitable name for it.
    • imagefile, textfiles, worldfile: Could be fine as is; or image_file, text_files, world_file ?

    I prefer to keep them unchanged.

    • newcolname but event_name, distribution_name: Unsure, i.e., new_col_name ?

    I prefer to keep newcolname.

  23. yvonnefroehlich commented on Dec 17, 2025

    @yvonnefroehlich
    MemberAuthor

    startpoint: I don't find it in the codes.

    Your are right, there is no parameter called startpoint. I was mixing it up with center for -C of pygmt.project.

  24. yvonnefroehlich commented on Dec 17, 2025

    @yvonnefroehlich
    MemberAuthor

    One more (hopefully the last one): We have max_retries for Figure.tilemap but maxradius for pygmt.surface. Leave maxradius as is or change it to max_radius ?

  25. seisman commented on Dec 17, 2025

    @seisman
    Member

    change it to max_radius ?

    I think yes.

  26. seisman commented on Dec 18, 2025

    @seisman
    Member

    I guess we can close the issue. We will revisit these PRs later.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    discussionsNeed more discussion before taking further actions

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions