# pswiggle

Plot z = f(x,y) anomalies along tracks

## Synopsis

gmt pswiggle [ table ] -J parameters -R west/east/south/north[/zmin/zmax][+r][+u unit] -Z scale [ -A[azimuth] ] [ -B[p|s]parameters ] [ -C center ] [ -D refpoint ] [ -F panel ] [ -G fill[+n][+p] ] [ -I fix_az ] [ -K ] [ -O ] [ -P ] [ -T pen ] [ -U[stamp] ] [ -V[level] ] [ -W pen ] [ -X[a|c|f|r][xshift] ] [ -Y[a|c|f|r][yshift] ] [ -bi binary ] [ -di nodata[+c col] ] [ -e regexp ] [ -f flags ] [ -g gaps ] [ -h headers ] [ -i flags ] [ -p flags ] [ -qi flags ] [ -t transp ] [ -w flags ] [ -:[i|o] ] [ --PAR=value ]

## Description

Reads (x,y,z) triplets from files [or standard input] and plots z as a function of distance along track. This means that two consecutive (x,y) points define the local distance axis, and the local z axis is then perpendicular to the distance axis, forming a right-handed coordinate system. The user may set a preferred positive anomaly plot direction, and if the positive normal is outside the ±90 degree window around the preferred direction, then 180 degrees are added to the direction. Either the positive or the negative wiggle (or both) may be shaded.

## Required Arguments

table

  One or more ASCII (or binary, see -bi[ncols][type]) data table file(s) holding a number of data columns. If no tables are given then we read from standard input.

-J parameters

  Specify the projection. (See full description) (See cookbook summary) (See projections table).

-R xmin/xmax/ymin/ymax[+r][+u unit]

  Specify the region of interest. Note: If using modern mode and -R is not provided, the region will be set based on previous plotting commands. If this is the first plotting command in the modern mode levels and -R is not provided, the region will be automatically determined based on the data in table (equivalent to using -Ra). (See full description) (See cookbook information).

> For perspective view -p, optionally append /zmin/zmax. (more …)

-Z scale

  Gives anomaly scale in data-units/distance-unit. Append c, i, or p to indicate the distance unit (cm, inch, or point); if no unit is given we use the default unit that is controlled by PROJ_LENGTH_UNIT.

## Optional Arguments

-A[azimuth]

  Sets the preferred positive azimuth. Positive wiggles will “gravitate” towards that direction, i.e., azimuths of the normal direction to the track will be flipped into the ±90 degree window centered on azimuth and that defines the positive wiggle side. If no azimuth is given the no preferred azimuth is enforced. Default is -A0.

-B[p|s]parameters

  Set map boundary frame and axes attributes. (See full description) (See cookbook information).

-C center

  Subtract center from the data set before plotting [0].

-D[g|j|J|n|x]refpoint+w length[+j justify][+a l|r][+o dx[/dy]][+l[label]]

  Defines the reference point on the map for the vertical scale bar using one of four coordinate systems:

  - g - Append lon/lat for map coordinates. Requires both -R and -J to be set.

  - j - Append code to j or J code for setting the refpoint via a 2-char justification code that refers to the (invisible) projected map bounding box. Requires both -R and -J to be set. Upper case means justify on the outside.

  - n - Append xn/yn for normalized bounding box coordinates (0-1). Requires both -R and -J to be set.

  - x - Append x/y for plot coordinates (append cm, inch, or ppoint).

  Append +w followed by the length or the scale bar in data (z) units. By default, the anchor point on the scale is assumed to be the middle left corner (ML), but this can be changed by appending +j followed by a 2-char justification code justify (see text). Note: If -Dj is used then justify defaults to the same as refpoint, if -DJ is used then justify defaults to the mirror opposite of refpoint. Consequently, -DJ is used to place a scale outside the map frame while -Dj is used to place it inside the frame. Move scale label to the left side with +al [Default is to the right of the scale]. Append +l to set the z unit label that is used in the scale label [no unit]. The FONT_ANNOT_PRIMARY is used for the font setting, while MAP_TICK_PEN_PRIMARY is used to draw the scale bar.

-F[+c clearances][+g fill][+i[[gap/]pen]][+p[pen]][+r[radius]][+s[[dx/dy/][shade]]]

> Without further options, draws a rectangular border around the vertical scale bar using MAP_FRAME_PEN. The following modifiers can be appended to -F, with additional explanation and examples provided in the The background panel cookbook section:

> - +c - Set clearance where clearance is either gap, xgap/ygap, or lgap/rgap/bgap/tgap and gap gives a uniform clearance, xgap/ygap gives separate clearances in the x- and y- directions, and lgap/rgap/bgap/tgap gives individual clearances between the map embellishment and the border for each side.

> - +g - Give fill to fill the box with a color specified by fill [default is no fill].

> - +i - Draw a secondary, inner border border outline [[gap/]pen]. Optionally, append the gap between the inner and outer border and the pen for the inner border [default is a uniform gap between borders of 2p and the MAP_DEFAULT_PEN].

> - +p - append pen to specify different pen attributes for the box outline.

> - +r - Draw a rounded rectangular borders instead of sharp with a corner radius set by radius (append units) [defaults is 6p].

> - +s - Place an offset background shaded region behind the box. Here, dx/dy indicates the shift relative to the foreground frame [default is 4p/-4p] and shade sets the fill style to use for shading [default is gray50].

-G fill[+n][+p] (more …)

  Set fill shade, color or pattern for positive and/or negative wiggles [Default is no fill]. Optionally, append +p to fill positive areas (this is the default behavior). Append +n to fill negative areas. Append +n+p to fill both positive and negative areas with the same fill. Note: You will need to repeat the -G option to select different fills for the positive and negative wiggles.

-I fix_az

  Set a fixed azimuth projection for wiggles [Default uses track azimuth, but see -A]. With this option, the calculated track-normal azimuths are overridden by fix_az.

-T pen

  Draw track [Default is no track]. Append pen attributes to use [Defaults: width = 0.25p, color = black, style = solid].

-U[label|+c][+j justify][+o dx[/dy]][+t text]

  Draw GMT time stamp logo on plot. (See full description) (See cookbook information).

-V[level]

  Select verbosity level [w]. (See full description) (See cookbook information).

-W pen

  Specify outline pen attributes [Default is no outline].

-X[a|c|f|r][xshift]

  Shift plot origin. (See full description) (See cookbook information).

-Y[a|c|f|r][yshift]

  Shift plot origin. (See full description) (See cookbook information).

-bi record[+b|l] (more …)

  Select native binary format for primary table input. [Default is 3 input columns].

-di nodata[+c col] (more …)

  Replace input columns that equal nodata with NaN.

-e[~]“pattern” | -e[~]/regexp/[i] (more …)

  Only accept data records that match the given pattern.

-f[i|o]colinfo (more …)

  Specify data types of input and/or output columns.

-g x|y|z|d|X|Y|D gap[u][+a][+c col][+n|p] (more …)

  Determine data gaps and line breaks.

-h[i|o][n][+c][+d][+m segheader][+r remark][+t title] (more …)

  Skip or produce header record(s).

-i cols[+l][+d divisor][+s scale|d|k][+o offset][,…][,t[word]] (more …)

  Select input columns and transformations (0 is first column, t is trailing text, append word to read one word only).

-p[x|y|z]azim[/elev[/zlevel]][+w lon0/lat0[/z0]][+v x0/y0] (more …)

  Select perspective view.

-qi[~]rows|limits[+c col][+a|t|s] (more …)

  Select input rows or data limit(s) [default is all rows].

-t transp[/transp2] (more …)

  Set transparency level(s) in percent.

-wy|a|w|d|h|m|s|c period[/phase][+c col] (more …)

  Convert an input coordinate to a cyclical coordinate.

-:[i|o] (more …)

  Swap 1st and 2nd column on input and/or output.

-^ or just -

  Print a short message about the syntax of the command, then exit (Note: on Windows just use -).

-+ or just +

  Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exit.

-? or no arguments

  Print a complete usage (help) message, including the explanation of all options, then exit.

--PAR=value

  Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

## Classic Mode Arguments

These options are used to manipulate the building of layered GMT PostScript plots in classic mode. They are not available when using GMT modern mode.

-K (more …)

  Do not finalize the PostScript plot.

-O (more …)

  Append to existing PostScript plot.

-P (more …)

  Select “Portrait” plot orientation.

## Examples

Note: Below are some examples of valid syntax for this module. The examples that use remote files (file names starting with `@`) can be cut and pasted into your terminal for testing. Other commands requiring input files are just dummy examples of the types of uses that are common but cannot be run verbatim as written.

To demonstrate a basic wiggle plot we create some synthetic data with gmtmath and pipe it through pswiggle:

    gmt math -T-8/6/0.01 -N3/0 -C2 T 3 DIV 2 POW NEG EXP T PI 2 MUL MUL COS MUL 50 MUL = | gmt pswiggle -R-10/10/-3/3 -JM6i -Baf -Z100i -DjRM+w100+lnT -Tfaint -Gred+p -W1p -BWSne -P > map.ps

To plot the magnetic anomaly stored in the file track.xym along track @ 500 nTesla/cm (after removing a mean value of 32000 nTesla), using a 15-cm-wide Polar Stereographic map ticked every 5 degrees in Portrait mode, with positive anomalies in red on a blue track of width 0.25 points, use

>     gmt pswiggle track.xym -R-20/10/-80/-60 -JS0/90/15c -Z500 -B5 \
>                  -C32000 -P -Gred -T0.25p,blue -DjRM+w1000+lnT -V > track_xym.ps

and the positive anomalies will in general point in the north direction. We used -D to place a vertical scale bar indicating a 1000 nT anomaly. To instead enforce a fixed azimuth of 45 for the positive wiggles, we add -I and obtain

>     gmt pswiggle track.xym -R-20/10/-80/-60 -JS0/90/15c -Z1000 -B5 \
>               -C32000 -P -Gred -I45 -T0.25p,blue -DjRM+w1000+lnT -V > track_xym.ps

## Bugs

Sometimes the (x, y) coordinates are not printed with enough significant digits, so the local perpendicular to the track swings around a lot. To see if this is the problem, you should do this:

>     gmt mapproject -Af yourdata.xyz | more

Then if these numbers jump around a lot, you may do this:

>     awk '{ print NR, $0 }' yourdata.xyz | filter1d -Fb5 -N4/0 \
>     --FORMAT_FLOAT_OUT=%.12g > smoothed.xyz

which performs a 5-point boxcar filter, and plot this data set instead.

## See Also

gmt, gmtcolors, filter1d, psbasemap, gmtsplit