diff --git a/pygmt/figure.py b/pygmt/figure.py index ba43963fa5e..92699cd8632 100644 --- a/pygmt/figure.py +++ b/pygmt/figure.py @@ -115,7 +115,7 @@ def region(self): ) @kwargs_to_strings() def psconvert(self, **kwargs): - """ + r""" Convert [E]PS file(s) to other formats. Converts one or more PostScript files to other formats (BMP, EPS, JPEG, @@ -149,20 +149,22 @@ def psconvert(self, **kwargs): icc_gray : bool Enforce gray-shades by using ICC profiles. anti_aliasing : str - Set the anti-aliasing options for graphics or text. Append the size - of the subsample box (1, 2, or 4) [4]. Default is no anti-aliasing - (same as bits = 1). + [**g**\|\ **p**\|\ **t**\][**1**\|\ **2**\|\ **4**]. + Set the anti-aliasing options for **g**\ raphics or **t**\ ext. + Append the size of the subsample box (1, 2, or 4) [4]. [Default is + no anti-aliasing (same as bits = 1)]. fmt : str - Sets the output format, where *b* means BMP, *e* means EPS, *E* - means EPS with PageSize command, *f* means PDF, *F* means - multi-page PDF, *j* means JPEG, *g* means PNG, *G* means - transparent PNG (untouched regions are transparent), *m* means PPM, - *s* means SVG, and *t* means TIFF [default is JPEG]. To ``'bjgt'`` - you can append ``'+m'`` in order to get a monochrome (grayscale) - image. The EPS format can be combined with any of the other - formats. For example, ``'ef'`` creates both an EPS and a PDF file. - Using ``'F'`` creates a multi-page PDF file from the list of input - PS or PDF files. It requires the *prefix* option. + Sets the output format, where **b** means BMP, **e** means EPS, + **E** means EPS with PageSize command, **f** means PDF, **F** means + multi-page PDF, **j** means JPEG, **g** means PNG, **G** means + transparent PNG (untouched regions are transparent), **m** means + PPM, **s** means SVG, and **t** means TIFF [default is JPEG]. To + **b**\|\ **j**\|\ **g**\|\ **t**\ , optionally append **+m** in + order to get a monochrome (grayscale) image. The EPS format can be + combined with any of the other formats. For example, **ef** creates + both an EPS and a PDF file. Using **F** creates a multi-page PDF + file from the list of input PS or PDF files. It requires the + ``prefix`` parameter. """ kwargs = self._preprocess(**kwargs) # Default cropping the figure to True @@ -178,7 +180,7 @@ def savefig( Save the figure to a file. This method implements a matplotlib-like interface for - :meth:`~gmt.Figure.psconvert`. + :meth:`pygmt.Figure.psconvert`. Supported formats: PNG (``.png``), JPEG (``.jpg``), PDF (``.pdf``), BMP (``.bmp``), TIFF (``.tif``), EPS (``.eps``), and KML (``.kml``). @@ -199,9 +201,10 @@ def savefig( If True, will crop the figure canvas (page) to the plot area. anti_alias: bool If True, will use anti aliasing when creating raster images (PNG, - JPG, TIf). More specifically, uses options ``Qt=2, Qg=2`` in - :meth:`~gmt.Figure.psconvert`. Ignored if creating vector graphics. - Overrides values of ``Qt`` and ``Qg`` passed in through ``kwargs``. + JPG, TIFF). More specifically, it passes arguments ``t2`` + and ``g2`` to the ``anti_aliasing`` parameter of + :meth:`pygmt.Figure.psconvert`. Ignored if creating vector + graphics. show: bool If True, will open the figure in an external viewer. dpi : int diff --git a/pygmt/src/blockmedian.py b/pygmt/src/blockmedian.py index fbed09c023e..0af32ff714f 100644 --- a/pygmt/src/blockmedian.py +++ b/pygmt/src/blockmedian.py @@ -19,7 +19,7 @@ @use_alias(I="spacing", R="region", V="verbose") @kwargs_to_strings(R="sequence") def blockmedian(table, outfile=None, **kwargs): - """ + r""" Block average (x,y,z) data tables by median estimation. Reads arbitrarily located (x,y,z) triples [or optionally weighted @@ -39,15 +39,17 @@ def blockmedian(table, outfile=None, **kwargs): ASCII data table. spacing : str - ``'xinc[unit][+e|n][/yinc[unit][+e|n]]'``. - x_inc [and optionally y_inc] is the grid spacing. + *xinc*\[\ *unit*\][**+e**\|\ **n**] + [/*yinc*\ [*unit*][**+e**\|\ **n**]]. + *xinc* [and optionally *yinc*] is the grid spacing. region : str or list - ``'xmin/xmax/ymin/ymax[+r][+uunit]'``. + *xmin/xmax/ymin/ymax*\[\ **+r**\][**+u**\ *unit*]. Specify the region of interest. outfile : str - Required if 'table' is a file. The file name for the output ASCII file. + Required if ``table`` is a file. The file name for the output ASCII + file. {V} diff --git a/pygmt/src/grdcut.py b/pygmt/src/grdcut.py index 975983aa9dc..2f5277d1535 100644 --- a/pygmt/src/grdcut.py +++ b/pygmt/src/grdcut.py @@ -28,10 +28,10 @@ ) @kwargs_to_strings(R="sequence") def grdcut(grid, **kwargs): - """ + r""" Extract subregion from a grid. - Produce a new *outgrid* file which is a subregion of *grid*. The + Produce a new ``outgrid`` file which is a subregion of ``grid``. The subregion is specified with *region*; the specified range must not exceed the range of *grid* (but see *extend*). If in doubt, run :meth:`pygmt.grdinfo` to check range. Alternatively, define the subregion @@ -54,16 +54,16 @@ def grdcut(grid, **kwargs): {J} {R} extend : bool or int or float - Allow grid to be extended if new *region* exceeds existing boundaries. - Give a value to initialize nodes outside current region. + Allow grid to be extended if new ``region`` exceeds existing + boundaries. Give a value to initialize nodes outside current region. circ_subregion : str - ``'lon/lat/radius[unit][+n]'``. + *lon/lat/radius*\[\ *unit*\][**+n**]. Specify an origin (*lon* and *lat*) and *radius*; append a distance *unit* and we determine the corresponding rectangular region so that all grid nodes on or inside the circle are contained in the subset. If **+n** is appended we set all nodes outside the circle to NaN. z_subregion : str - ``'[min/max][+n|N|r]'``. + [*min/max*\][**+n**\|\ **N**\|\ **r**]. Determine a new rectangular region so that all nodes outside this region are also outside the given z-range [-inf/+inf]. To indicate no limit on *min* or *max* only, specify a hyphen (-). Normally, any NaNs diff --git a/pygmt/src/grdfilter.py b/pygmt/src/grdfilter.py index 1330c8d0528..702ed009742 100644 --- a/pygmt/src/grdfilter.py +++ b/pygmt/src/grdfilter.py @@ -29,18 +29,18 @@ ) @kwargs_to_strings(R="sequence") def grdfilter(grid, **kwargs): - """ + r""" Filter a grid in the space (or time) domain. Filter a grid file in the time domain using one of the selected convolution or non-convolution isotropic or rectangular filters and compute distances using Cartesian or Spherical geometries. The output grid file can - optionally be generated as a sub-region of the input (via *region*) and/or - with new increment (via *spacing*) or registration (via *toggle*). In this - way, one may have "extra space" in the input data so that the edges will - not be used and the output can be within one half-width of the input edges. - If the filter is low-pass, then the output may be less frequently sampled - than the input. + optionally be generated as a sub-region of the input (via ``region``) + and/or with new increment (via ``spacing``) or registration + (via ``toggle``). In this way, one may have "extra space" in the input + data so that the edges will not be used and the output can be within one + half-width of the input edges. If the filter is low-pass, then the output + may be less frequently sampled than the input. Full option list at :gmt-docs:`grdfilter.html` @@ -54,11 +54,23 @@ def grdfilter(grid, **kwargs): The name of the output netCDF file with extension .nc to store the grid in. filter : str - ``xwidth[/width2][modifiers]``. - Name of filter type you which to apply, followed by the width - b: Box Car; c: Cosine Arch; g: Gaussian; o: Operator; m: Median; - p: Maximum Likelihood probability; h: histogram - Example: F='m600' for a median filter with width of 600 + **b**\|\ **c**\|\ **g**\|\ **o**\|\ **m**\|\ **p**\|\ **h**\ *xwidth*\ + [/*width2*\][*modifiers*]. + Name of filter type you which to apply, followed by the width: + + b: Box Car + + c: Cosine Arch + + g: Gaussian + + o: Operator + + m: Median + + p: Maximum Likelihood probability + + h: histogram distance : str Distance *flag* tells how grid (x,y) relates to filter width as follows: @@ -87,10 +99,11 @@ def grdfilter(grid, **kwargs): Spherical distance calculation. spacing : str - ``xinc[+e|n][/yinc[+e|n]]``. - x_inc [and optionally y_inc] is the grid spacing. + *xinc*\[\ *unit*\][**+e**\|\ **n**] + [/*yinc*\ [*unit*][**+e**\|\ **n**]]. + *xinc* [and optionally *yinc*] is the grid spacing. nans : str or float - ``i|p|r``. + **i**\|\ **p**\|\ **r**. Determine how NaN-values in the input grid affects the filtered output. {R} toggle : bool diff --git a/pygmt/src/info.py b/pygmt/src/info.py index 81af4ac176f..490f820abc1 100644 --- a/pygmt/src/info.py +++ b/pygmt/src/info.py @@ -17,20 +17,21 @@ @fmt_docstring @use_alias(C="per_column", I="spacing", T="nearest_multiple", V="verbose") def info(table, **kwargs): - """ + r""" Get information about data tables. Reads from files and finds the extreme values in each of the columns reported as min/max pairs. It recognizes NaNs and will print warnings if the number of columns vary from record to record. As an option, it will find the extent of the first two columns rounded up and down to the nearest - multiple of the supplied increments given by *spacing*. Such output will be - in a numpy.ndarray form ``[w, e, s, n]``, which can be used directly as the - *region* argument for other modules (hence only dx and dy are needed). If - the *per_column* option is combined with *spacing*, then the numpy.ndarray - output will be rounded up/down for as many columns as there are increments - provided in *spacing*. A similar option *nearest_multiple* option will - provide a numpy.ndarray in the form of ``[zmin, zmax, dz]`` for makecpt. + multiple of the supplied increments given by ``spacing``. Such output will + be in a numpy.ndarray form [*w*, *e*, *s*, *n*], which can be used + directly as the ``region`` parameter for other modules (hence only *dx* + and *dy* are needed). If the ``per_column`` parameter is combined with + ``spacing``, then the numpy.ndarray output will be rounded up/down for as + many columns as there are increments provided in ``spacing``. A similar + parameter ``nearest_multiple`` option will provide a numpy.ndarray in the + form of [*zmin*, *zmax*, *dz*]`` for makecpt. Full option list at :gmt-docs:`gmtinfo.html` @@ -45,12 +46,12 @@ def info(table, **kwargs): per_column : bool Report the min/max values per column in separate columns. spacing : str - ``'[b|p|f|s]dx[/dy[/dz...]]'``. + [**b**\|\ **p**\|\ **f**\|\ **s**]\ *dx*\[/*dy*\[/*dz*...]]. Report the min/max of the first n columns to the nearest multiple of the provided increments and output results in the form ``[w, e, s, n]``. nearest_multiple : str - ``'dz[+ccol]'`` + **dz**\[\ **+c**\ *col*]. Report the min/max of the first (0'th) column to the nearest multiple of dz and output this in the form ``[zmin, zmax, dz]``. @@ -59,8 +60,8 @@ def info(table, **kwargs): Returns ------- output : np.ndarray or str - Return type depends on whether any of the 'per_column', 'spacing', or - 'nearest_multiple' parameters are set. + Return type depends on whether any of the ``per_column``, + ``spacing``, or ``nearest_multiple`` parameters are set. - np.ndarray if either of the above parameters are used. - str if none of the above parameters are used. diff --git a/pygmt/src/makecpt.py b/pygmt/src/makecpt.py index bdad3f07952..744f7158542 100644 --- a/pygmt/src/makecpt.py +++ b/pygmt/src/makecpt.py @@ -26,12 +26,12 @@ ) @kwargs_to_strings(T="sequence", G="sequence") def makecpt(**kwargs): - """ + r""" Make GMT color palette tables. This is a module that will help you make static color palette tables (CPTs). By default, the CPT will simply be saved to the current session, - but you can use *output* to save it to a file. You define an equidistant + but you can use ``output`` to save it to a file. You define an equidistant set of contour intervals or pass your own z-table or list, and create a new CPT based on an existing master (dynamic) CPT. The resulting CPT can be reversed relative to the master cpt, and can be made continuous or @@ -49,8 +49,8 @@ def makecpt(**kwargs): the new master file. If not, the parameters :gmt-term:`COLOR_BACKGROUND`, :gmt-term:`COLOR_FOREGROUND`, and :gmt-term:`COLOR_NAN` from the :gmt-docs:`gmt.conf ` file or the command line will be used. This - default behavior can be overruled using the options *background*, - *overrule_bg* or *no_bg*. + default behavior can be overruled using the parameters ``background``, + ``overrule_bg`` or ``no_bg``. The color model (RGB, HSV or CMYK) of the palette created by **makecpt** will be the same as specified in the header of the master CPT. When there @@ -81,7 +81,7 @@ def makecpt(**kwargs): ``background='i'`` to match the colors for the lowest and highest values in the input (instead of the output) CPT. color_model : - ``[R|r|h|c][+c[label]]``. + [**R**\|\ **r**\|\ **h**\|\ **c**][**+c**\ [*label*]]. Force output CPT to be written with r/g/b codes, gray-scale values or color name (**R**, default) or r/g/b codes only (**r**), or h-s-v codes (**h**), or c/m/y/k codes (**c**). Optionally or alternatively, append @@ -93,7 +93,7 @@ def makecpt(**kwargs): labels from *start* (a single letter or an integer). Append - to build ranges *start*-*start+1* instead. series : list or str - ``[min/max/inc[+b|l|n]|file|list]``. + [*min/max/inc*\[**+b**\|\ **l**\|\ **n**]\|\ *file*\|\ *list*]. Defines the range of the new CPT by giving the lowest and highest z-value (and optionally an interval). If this is not given, the existing range in the master CPT will be used intact. The values @@ -102,21 +102,22 @@ def makecpt(**kwargs): For details on array creation, see :gmt-docs:`makecpt.html#generate-1d-array`. truncate : list or str - ``zlo/zhi``. + *zlow/zhigh*. Truncate the incoming CPT so that the lowest and highest z-levels are - to *zlo* and *zhi*. If one of these equal NaN then we leave that end of - the CPT alone. The truncation takes place before any resampling. See + to *zlow* and *zhigh*. If one of these equal NaN then we leave that + end of the CPT alone. The truncation takes place before any + resampling. See also :gmt-docs:`cookbook/features.html#manipulating-cpts`. output : str Optional. The file name with extension .cpt to store the generated CPT file. If not given or False (default), saves the CPT as the session current CPT. reverse : str - Set this to True or c [Default] to reverse the sense of color + Set this to True or **c**\ [Default] to reverse the sense of color progression in the master CPT. Set this to z to reverse the sign of z-values in the color table. Note that this change of z-direction - happens before *truncate* and *series* values are used so the latter - must be compatible with the changed *z*-range. See also + happens before ``truncate`` and ``series`` values are used so the + latter must be compatible with the changed *z*-range. See also :gmt-docs:`cookbook/features.html#manipulating-cpts`. overrule_bg : str Overrule background, foreground, and NaN colors specified in the master diff --git a/pygmt/src/surface.py b/pygmt/src/surface.py index 21343a88652..24ba883c4e2 100644 --- a/pygmt/src/surface.py +++ b/pygmt/src/surface.py @@ -20,7 +20,7 @@ @use_alias(I="spacing", R="region", G="outfile", V="verbose") @kwargs_to_strings(R="sequence") def surface(x=None, y=None, z=None, data=None, **kwargs): - """ + r""" Grids table data using adjustable tension continuous curvature splines. Surface reads randomly-spaced (x,y,z) triples and produces gridded values @@ -47,11 +47,12 @@ def surface(x=None, y=None, z=None, data=None, **kwargs): Either a data file name or a 2d numpy array with the tabular data. spacing : str - ``'xinc[unit][+e|n][/yinc[unit][+e|n]]'``. - x_inc [and optionally y_inc] is the grid spacing. + *xinc*\[\ *unit*\][**+e**\|\ **n**]\ + [/*yinc*\ [*unit*][**+e**\|\ **n**]]. + *xinc* [and optionally *yinc*] is the grid spacing. region : str or list - ``'xmin/xmax/ymin/ymax[+r][+uunit]'``. + *xmin/xmax/ymin/ymax*\[**+r**][**+u**\ *unit*]. Specify the region of interest. outfile : str diff --git a/pygmt/x2sys.py b/pygmt/x2sys.py index 839f977f957..064ecdb2c43 100644 --- a/pygmt/x2sys.py +++ b/pygmt/x2sys.py @@ -69,7 +69,7 @@ def tempfile_from_dftrack(track, suffix): ) @kwargs_to_strings(I="sequence", R="sequence") def x2sys_init(tag, **kwargs): - """ + r""" Initialize a new x2sys track database. x2sys_init is the starting point for anyone wishing to use x2sys; it @@ -113,21 +113,22 @@ def x2sys_init(tag, **kwargs): *fmtfile*). discontinuity : str - ``d|g`` + **d**\|\ **g**. Selects geographical coordinates. Append **d** for discontinuity at the Dateline (makes longitude go from -180 to + 180) or **g** for discontinuity at Greenwich (makes longitude go from 0 to 360 [Default]). If not given we assume the data are Cartesian. spacing : str or list - ``dx[/dy]`` - x_inc [and optionally y_inc] is the grid spacing. Append **m** to + *dx*\[/*dy*]. + *dx* [and optionally *dy*] is the grid spacing. Append **m** to indicate minutes or **s** to indicate seconds for geographic data. These spacings refer to the binning used in the track bin-index data base. units : str or list - ``d|sunit``. + **d**\|\ **s**\ + **c**\|\ **e**\|\ **f**\|\ **k**\|\ **m**\|\ **n**\|\ **u** . Sets the units used for distance and speed when requested by other programs. Append **d** for distance or **s** for speed, then give the desired unit as: @@ -147,12 +148,13 @@ def x2sys_init(tag, **kwargs): {V} gap : str or list - ``t|dgap``. + **t**\|\ **d**\ *gap*. Give **t** or **d** and append the corresponding maximum time gap (in user units; this is typically seconds [Infinity]), or distance (for - units, see *units*) gap [Infinity]) allowed between the two data points - immediately on either side of a crossover. If these limits are exceeded - then a data gap is assumed and no COE will be determined. + units, see ``units``) gap [Default is infinity]) allowed between the + two data points immediately on either side of a crossover. If these + limits are exceeded then a data gap is assumed and no COE will be + determined. {j} """ @@ -177,7 +179,7 @@ def x2sys_init(tag, **kwargs): ) @kwargs_to_strings(R="sequence") def x2sys_cross(tracks=None, outfile=None, **kwargs): - """ + r""" Calculate crossovers between track data files. x2sys_cross is used to determine all intersections between ("external @@ -231,7 +233,7 @@ def x2sys_cross(tracks=None, outfile=None, **kwargs): split_file4coes.m that lives in the x2sys supplement source code. override : bool or str - ``S|N``. + **S**\|\ **N**. Control how geographic coordinates are handled (Cartesian data are unaffected). By default, we determine if the data are closer to one pole than the other, and then we use a cylindrical polar conversion to @@ -245,7 +247,7 @@ def x2sys_cross(tracks=None, outfile=None, **kwargs): longitudinal range at higher latitudes. interpolation : str - ``l|a|c``. + **l**\|\ **a**\|\ **c**. Sets the interpolation mode for estimating values at the crossover. Choose among: @@ -260,7 +262,7 @@ def x2sys_cross(tracks=None, outfile=None, **kwargs): {R} speed : str or list - ``l|u|hspeed``. + **l**\|\ **u**\|\ **h**\ *speed*. Defines window of track speeds. If speeds are outside this window we do not calculate a COE. Specify: