diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py index e8879eaa9b0..eb53067bb2f 100644 --- a/pygmt/helpers/decorators.py +++ b/pygmt/helpers/decorators.py @@ -102,23 +102,130 @@ Control how aspatial data are handled during input and output. Full documentation is at :gmt-docs:`gmt.html#aspatial-full`. """, + "b": r""" + binary : bool or str + **i**\|\ **o**\ [*ncols*][*type*][**w**][**+l**\|\ **b**]. + Select native binary input (using ``binary="i"``) or output + (using ``binary="o"``), where *ncols* is the number of data columns + of *type*, which must be one of: + + - **c** - int8_t (1-byte signed char) + - **u** - uint8_t (1-byte unsigned char) + - **h** - int16_t (2-byte signed int) + - **H** - uint16_t (2-byte unsigned int) + - **i** - int32_t (4-byte signed int) + - **I** - uint32_t (4-byte unsigned int) + - **l** - int64_t (8-byte signed int) + - **L** - uint64_t (8-byte unsigned int) + - **f** - 4-byte single-precision float + - **d** - 8-byte double-precision float + - **x** - use to skip *ncols* anywhere in the record + + For records with mixed types, append additional comma-separated + combinations of *ncols* *type* (no space). The following modifiers + are supported: + + - **w** after any item to force byte-swapping. + - **+l**\|\ **b** to indicate that the entire data file should + be read as little- or big-endian, respectively. + + Full documentation is at :gmt-docs:`gmt.html#bi-full`.""", + "d": r""" + nodata : str + **i**\|\ **o**\ *nodata*. + Substitute specific values with NaN (for tabular data). For + example, ``d="-9999"`` will replace all values equal to -9999 with + NaN during input and all NaN values with -9999 during output. + Prepend **i** to the *nodata* value for input columns only. Prepend + **o** to the *nodata* value for output columns only.""", "c": r""" panel : bool or int or list [*row,col*\|\ *index*]. - Selects a specific subplot panel. Only allowed when in subplot + Select a specific subplot panel. Only allowed when in subplot mode. Use ``panel=True`` to advance to the next panel in the selected order. Instead of *row,col* you may also give a scalar value *index* which depends on the order you set via ``autolabel`` when the subplot was defined. **Note**: *row*, *col*, and *index* all start at 0. """, + "e": r""" + find : str + [**~**]\ *"pattern"* \| [**~**]/\ *regexp*/[**i**]. + Only pass records that match the given *pattern* or regular + expressions [Default processes all records]. Prepend **~** to + the *pattern* or *regexp* to instead only pass data expressions + that do not match the pattern. Append **i** for case insensitive + matching. This does not apply to headers or segment headers.""", "f": r""" coltypes : str [**i**\|\ **o**]\ *colinfo*. Specify data types of input and/or output columns (time or geographical data). Full documentation is at - :gmt-docs:`gmt.html#f-full`. - """, + :gmt-docs:`gmt.html#f-full`.""", + "g": r""" + gap : str or list + [**a**]\ **x**\|\ **y**\|\ **d**\|\ **X**\|\ **Y**\|\ + **D**\|[*col*]\ **z**\ *gap*\ [**+n**\|\ **p**]. + Examine the spacing between consecutive data points in order to + impose breaks in the line. To specify multiple critera, provide + a list with each item containing a string describing one set of + critera. Prepend **a** to specify that all the criteria must be + met [Default is to impose breaks if any criteria are met]. The + following modifiers are supported: + + - **x**\|\ **X** - define a gap when there is a large enough + change in the x coordinates (upper case to use projected + coordinates). + - **y**\|\ **Y** - define a gap when there is a large enough + change in the y coordinates (upper case to use projected + coordinates). + - **d**\|\ **D** - define a gap when there is a large enough + distance between coordinates (upper case to use projected + coordinates). + - [*col*]\ **z** - define a gap when there is a large enough + change in the data in column *col* [default *col* is 2 (i.e., + 3rd column)]. + + A unit **u** may be appended to the specified *gap*: + + - For geographic data (**x**\|\ **y**\|\ **d**), the unit may + be arc **d**\ (egree), **m**\ (inute), and **s**\ (econd), or + (m)\ **e**\ (ter), **f**\ (eet), **k**\ (ilometer), + **M**\ (iles), or **n**\ (autical miles) [Default is + (m)\ **e**\ (ter)]. + - For projected data (**X**\|\ **Y**\|\ **D**), the unit may be + **i**\ (nch), **c**\ (entimeter), or **p**\ (oint). + + One of the following modifiers can be appended to *gap* [Default + imposes breaks based on the absolute value of the difference + between the current and previous value]: + + - **+n** - specify that the previous value minus the current + column value must exceed *gap* for a break to be imposed. + - **+p** - specify that the current value minus the previous + value must exceed *gap* for a break to be imposed.""", + "h": r""" + header : str + [**i**\|\ **o**][*n*][**+c**][**+d**][**+m**\ *segheader*][**+r**\ + *remark*][**+t**\ *title*]. + Specify that input and/or output file(s) have *n* header records + [Default is 0]. Prepend **i** if only the primary input should have + header records. Prepend **o** to control the writing of header + records, with the following modifiers supported: + + - **+d** to remove existing header records. + - **+c** to add a header comment with column names to the + output [Default is no column names]. + - **+m** to add a segment header *segheader* to the output + after the header block [Default is no segment header]. + - **+r** to add a *remark* comment to the output [Default is no + comment]. The *remark* string may contain \\n to indicate + line-breaks. + - **+t** to add a *title* comment to the output [Default is no + title]. The *title* string may contain \\n to indicate + line-breaks. + + Blank lines and lines starting with \# are always skipped.""", "i": r""" incols : str or 1d array Specify data columns for primary input in arbitrary order. Columns @@ -131,23 +238,23 @@ - For :py:class:`str`: specify individual columns or column ranges in the format *start*\ [:*inc*]:*stop*, where *inc* defaults to 1 if not specified, with columns and/or column ranges - separated by commas (e.g., ``incols='0:2,4+l'`` to input the + separated by commas (e.g., ``incols="0:2,4+l"`` to input the first three columns followed by the log-transformed 5th column). To read from a given column until the end of the record, leave off *stop* when specifying the column range. To read trailing text, add the column **t**. Append the word number to **t** to ingest only a single word from the trailing text. Instead of - specifying columns, use ``incols='n'`` to simply read numerical + specifying columns, use ``incols="n"`` to simply read numerical input and skip trailing text. Optionally, append one of the following modifiers to any column or column range to transform the input columns: - **+l** to take the *log10* of the input values. - **+d** to divide the input values by the factor *divisor* - [default is 1]. + [Default is 1]. - **+s** to multiple the input values by the factor *scale* - [default is 1]. - - **+o** to add the given *offset* to the input values [default + [Default is 1]. + - **+o** to add the given *offset* to the input values [Default is 0].""", "j": r""" distcalc : str @@ -177,6 +284,29 @@ - **c** for bicubic [Default] - **l** for bilinear - **n** for nearest-neighbor""", + "o": r""" + outcols : str or 1d array + *cols*\ [,...][,\ **t**\ [*word*]]. + Specify data columns for primary output in arbitrary order. Columns + can be repeated and columns not listed will be skipped [Default + writes all columns in order, starting with the first (i.e., column + 0)]. + + - For *1d array*: specify individual columns in output order (e.g., + ``outcols=[1,0]`` for the 2nd column followed by the 1st column). + - For :py:class:`str`: specify individual columns or column + ranges in the format *start*\ [:*inc*]:*stop*, where *inc* + defaults to 1 if not specified, with columns and/or column ranges + separated by commas (e.g., ``outcols="0:2,4"`` to output the + first three columns followed by the 5th column). + To write from a given column until the end of the record, leave + off *stop* when specifying the column range. To write trailing + text, add the column **t**. Append the word number to **t** to + write only a single word from the trailing text. Instead of + specifying columns, use ``outcols="n"`` to simply read numerical + input and skip trailing text. Note: if ``incols`` is also used + then the columns given to ``outcols`` correspond to the order + after the ``incols`` selection has taken place.""", "p": r""" perspective : list or str [**x**\|\ **y**\|\ **z**]\ *azim*\[/*elev*\[/*zlevel*]]\ @@ -191,6 +321,22 @@ Force gridline (**g**) or pixel (**p**) node registration. [Default is **g**\ (ridline)]. """, + "s": r""" + skiprows : bool or str + [*cols*][**+a**][**+r**]. + Suppress output for records whose *z*-value equals NaN [Default + outputs all records]. Optionally, supply a comma-separated list of + all columns or column ranges to consider for this NaN test [Default + only considers the third data column (i.e., *cols = 2*)]. Column + ranges must be given in the format *start*\ [:*inc*]:*stop*, where + *inc* defaults to 1 if not specified. The following modifiers are + supported: + + - **+r** to reverse the suppression, i.e., only output the + records whose *z*-value equals NaN. + - **+a** to suppress the output of the record if just one or + more of the columns equal NaN [Default skips record only + if values in all specified *cols* equal NaN].""", "t": """\ transparency : int or float Set transparency level, in [0-100] percent range. @@ -198,6 +344,24 @@ Only visible when PDF or raster format output is selected. Only the PNG format selection adds a transparency layer in the image (for further processing). """, + "w": r""" + wrap : str + **y**\|\ **a**\|\ **w**\|\ **d**\|\ **h**\|\ **m**\|\ **s**\|\ + **c**\ *period*\ [/*phase*][**+c**\ *col*]. + Convert the input *x*-coordinate to a cyclical coordinate, or a + different column if selected via **+c**\ *col*. The following + cyclical coordinate transformations are supported: + + - **y** - yearly cycle (normalized) + - **a** - annual cycle (monthly) + - **w** - weekly cycle (day) + - **d** - daily cycle (hour) + - **h** - hourly cycle (minute) + - **m** - minute cycle (second) + - **s** - second cycle (second) + - **c** - custom cycle (normalized) + + Full documentation is at :gmt-docs:`gmt.html#w-full`.""", "x": r""" cores : bool or int [[**-**]\ *n*]. diff --git a/pygmt/src/blockm.py b/pygmt/src/blockm.py index 4eb2a715cc9..22f6cbd43c5 100644 --- a/pygmt/src/blockm.py +++ b/pygmt/src/blockm.py @@ -72,7 +72,10 @@ def _blockm(block_method, table, outfile, x, y, z, **kwargs): a="aspatial", f="coltypes", i="incols", + o="outcols", r="registration", + s="skiprows", + w="wrap", ) @kwargs_to_strings(R="sequence") def blockmean(table=None, outfile=None, *, x=None, y=None, z=None, **kwargs): @@ -112,7 +115,10 @@ def blockmean(table=None, outfile=None, *, x=None, y=None, z=None, **kwargs): {a} {i} {f} + {o} {r} + {s} + {w} Returns ------- @@ -137,7 +143,10 @@ def blockmean(table=None, outfile=None, *, x=None, y=None, z=None, **kwargs): a="aspatial", f="coltypes", i="incols", + o="outcols", r="registration", + s="skiprows", + w="wrap", ) @kwargs_to_strings(R="sequence") def blockmedian(table=None, outfile=None, *, x=None, y=None, z=None, **kwargs): @@ -177,7 +186,10 @@ def blockmedian(table=None, outfile=None, *, x=None, y=None, z=None, **kwargs): {a} {f} {i} + {o} {r} + {s} + {w} Returns ------- diff --git a/pygmt/src/wiggle.py b/pygmt/src/wiggle.py index ddabb48c35e..f7a24cd6dc4 100644 --- a/pygmt/src/wiggle.py +++ b/pygmt/src/wiggle.py @@ -19,7 +19,12 @@ X="xshift", Y="yshift", Z="scale", + b="binary", c="panel", + d="nodata", + e="find", + g="gap", + h="header", i="columns", p="perspective", ) @@ -75,7 +80,12 @@ def wiggle(self, x=None, y=None, z=None, data=None, **kwargs): pen : str Specify outline pen attributes [Default is no outline]. {XY} + {b} {c} + {d} + {e} + {g} + {h} columns : str or 1d array Choose which columns are x, y, and z, respectively if input is provided via *data*. E.g. ``columns = [0, 1, 2]`` or ``columns = "0,1,2"`` if