# polar

Plot polarities on the lower hemisphere of the focal sphere

## Synopsis

gmt polar [ table ] -D lon/lat -J parameters -R region -M size[+m mag] -S<symbol><size> [ -B[p|s]parameters ] [ -C lon/lat[+p pen][+s pointsize] ] [ -E fill ] [ -F fill ] [ -G fill ] [ -N ] [ -Q mode[args] ] [ -T[+a angle][+f font][+j justify][+o dx[/dy]] ] [ -U[stamp] ] [ -V[level] ] [ -W pen ] [ -X[a|c|f|r][xshift] ] [ -Y[a|c|f|r][yshift] ] [ -di nodata ] [ -e regexp ] [ -h headers ] [ -i flags ] [ -qi flags ] [ -t transp ] [ -:[i|o] ] [ --PAR=value ]

Note: No space is allowed between the option flag and the associated arguments.

## Description

Reads data values from files [or standard input] and will plot stations on focal mechanisms on a map.

Parameters are expected to be in the following columns:

> 1,2,3:

>   station_code, azimuth, take-off angle

> 4:

>   polarity:

>   - compression can be c,C,u,U,+

>   - rarefaction can be d,D,r,R,-

>   - not defined is anything else

## 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 (more …)

  Select map projection.

-R west/east/south/north[/zmin/zmax][+r][+u unit]

  west, east, south, and north specify the region of interest, and you may specify them in decimal degrees or in [±]dd:mm[:ss.xxx][W|E|S|N] format Append +r if lower left and upper right map coordinates are given instead of w/e/s/n. The two shorthands -Rg and -Rd stand for global domain (0/360 and -180/+180 in longitude respectively, with -90/+90 in latitude). Set geographic regions by specifying ISO country codes from the Digital Chart of the World using -R code1,code2,…[+r|R[incs]] instead: Append one or more comma-separated countries using the 2-character ISO 3166-1 alpha-2 convention. To select a state of a country (if available), append .state, e.g, US.TX for Texas. To specify a whole continent, prepend = to any of the continent codes AF (Africa), AN (Antarctica), AS (Asia), EU (Europe), OC (Oceania), NA (North America), or SA (South America). Use +r to modify the bounding box coordinates from the polygon(s): Append inc, xinc/yinc, or winc/einc/sinc/ninc to adjust the region to be a multiple of these steps [no adjustment]. Alternatively, use +R to extend the region outward by adding these increments instead, or +e which is like +r but it ensures that the bounding box extends by at least 0.25 times the increment [no extension]. Alternatively for grid creation, give R code lon/lat/nx/ny, where code is a 2-character combination of L, C, R (for left, center, or right) and T, M, B for top, middle, or bottom. e.g., BL for lower left. This indicates which point on a rectangular region the lon/lat coordinate refers to, and the grid dimensions nx and ny with grid spacings via -I is used to create the corresponding region. Alternatively, specify the name of an existing grid file and the -R settings (and grid spacing and registration, if applicable) are copied from the grid. Appending +u unit expects projected (Cartesian) coordinates compatible with chosen -J and we inversely project to determine actual rectangular geographic region. For perspective view (-p), optionally append /zmin/zmax. In case of perspective view (-p), a z-range (zmin, zmax) can be appended to indicate the third dimension. This needs to be done only when using the -Jz option, not when using only the -p option. In the latter case a perspective view of the plane is plotted, with no third dimension.

-D longitude/latitude

  Maps the bubble at given longitude and latitude point.

-M size[+m mag]

  Sets the size of the beach ball to plot polarities in. size is in default units (unless c, i, or p is appended). Optionally append +m mag to specify its magnitude, then beachball size is mag / 5.0 * size.

-S<symbol_type><size>

  Selects symbol_type and symbol size. Size is in default units (unless c, i, or p is appended). Choose symbol type from st(a)r, (c)ircle, (d)iamond, (h)exagon, (i)nverted triangle, (p)oint, (s)quare, (t)riangle, (x)cross.

## Optional Arguments

-B[p|s]parameters (more …)

  Set map boundary frame and axes attributes.

-C lon/lat[+p pen][+s pointsize]

  Offsets focal mechanisms to the latitude and longitude specified in the last two columns of the input file. Optionally set the pen and symbol point size.

-E fill (more …)

  Selects filling of symbols for stations in extensive quadrants. Set the color [Default is 250]. If -E fill is the same as -F fill, use -Qe to outline.

-F fill (more …)

  Sets background color of the beach ball. Default is no fill.

-G fill (more …)

  Selects filling of symbols for stations in compressional quadrants. Set the color [Default is black].

-N

  Does not skip symbols that fall outside map border [Default plots points inside border only].

-Q mode[args]

  Sets one or more attributes; repeatable. The various combinations are

  -Qe[pen]

    Outline symbols in extensive quadrants using pen or the default pen (see -W).

  -Qf[pen]

    Outline the beach ball using pen or the default pen (see -W).

  -Qg[pen]

    Outline symbols in compressional quadrants using pen or the default pen (see -W).

  -Qh

    Use special format derived from HYPO71 output

  -Qs half-size[+v v_size[vecspecs]]

    Plots S polarity azimuth. S polarity is in last column. Append +v to select a vector and append head size and any vector specifications. If +v is given without arguments then we default to +v0.3i+e+gblack [Default is a line segment]. Give half-size in default units (unless c, i, or p is appended). See Vector Attributes for specifying additional attributes.

  -Qt pen

    Set pen color to write station code. Default uses the default pen (see -W).

-T[+a angle][+f font][+j justify][+o dx[/dy]]

  Write station code near symbols.

  Optionally append +a angle to change the text angle; +f font to set the font of the text; append +j justify to change the text location relative to the symbol; append +o to offset the text string by dx/dy. [Default to write station code above the symbol; the default font size is 12p]

-U[label][+c][+j just][+o dx/dy] (more …)

  Draw GMT time stamp logo on plot.

-V[level] (more …)

  Select verbosity level [w].

-W[-|+][pen][attr] (more …)

  Set current pen attributes [Default pen is default,black,solid].

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

-Y[a|c|f|r][yshift] (more …)

  Shift plot origin.

-di nodata (more …)

  Replace input columns that equal nodata with NaN.

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

  Only accept data records that match the given pattern.

-i cols[+l][+s scale][+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).

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

  Select input rows or data range(s) [all].

-t[transp] (more …)

  Set transparency level in percent.

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

## Vector Attributes

Several modifiers may be appended to vector-producing options for specifying the placement of vector heads, their shapes, and the justification of the vector. Below, left and right refers to the side of the vector line when viewed from the start point to the end point of a segment:

> +a angle sets the angle of the vector head apex [30].

> +b places a vector head at the beginning of the vector path [none]. Optionally, append t for a terminal line, c for a circle, a for arrow [Default], i for tail, A for plain open arrow, and I for plain open tail. Further append l|r to only draw the left or right half-sides of this head [both sides].

> +e places a vector head at the end of the vector path [none]. Optionally, append t for a terminal line, c for a circle, a for arrow [Default], i for tail, A for plain open arrow, and I for plain open tail. Further append l|r to only draw the left or right half-sides of this head [both sides].

> +g[fill] sets the vector head fill [Default fill is used, which may be no fill]. Turn off vector head fill by not appending a fill.

> +h shape sets the shape of the vector head (range -2/2). Default is controlled by MAP_VECTOR_SHAPE [0].

> +l draws half-arrows, using only the left side of specified heads [both sides].

> +m places a vector head at the mid-point the vector path [none]. Append f or r for forward or reverse direction of the vector [forward]. Optionally, append t for a terminal line, c for a circle, a for arrow [Default], i for tail, A for plain open arrow, and I for plain open tail. Further append l|r to only draw the left or right half-sides of this head [both sides]. Cannot be combined with +b or +e.

> +n norm scales down vector attributes (pen thickness, head size) with decreasing length, where vector plot lengths shorter than norm will have their attributes scaled by length/norm [arrow attributes remains invariant to length]. For Cartesian vectors specify a length in plot units, while for geovectors specify a length in km.

> +o[plon/plat] specifies the oblique pole for the great or small circles. Only needed for great circles if +q is given. If no pole is appended then we default to the north pole.

> +p[pen] sets the vector pen attributes. If no pen is appended then the head outline is not drawn. [Default pen is half the width of stem pen, and head outline is drawn]

> +q means the input angle, length data instead represent the start and stop opening angles of the arc segment relative to the given point. See +o to specify a specific pole for the arc [north pole].

> +r draws half-arrows, using only the right side of specified heads [both sides].

> +t[b|e]trim will shift the beginning or end point (or both) along the vector segment by the given trim; append suitable unit (c, i, or p). If the modifiers b|e are not used then trim may be two values separated by a slash, which is used to specify different trims for the beginning and end. Positive trims will shorted the vector while negative trims will lengthen it [no trim].

In addition, all but circular vectors may take these modifiers:

> +j just determines how the input x,y point relates to the vector. Choose from beginning [default], end, or center.

> +s means the input angle, length are instead the x, y coordinates of the vector end point.

Finally, Cartesian vectors may take these modifiers:

> +z scale expects input dx,dy vector components and uses the scale to convert to polar coordinates with length in given unit.

Note: Vectors were completely redesigned for GMT5 which separated the vector head (a polygon) from the vector stem (a line). In GMT4, the entire vector was a polygon and it could only be a straight Cartesian vector. Yes, the old GMT4 vector shape remains accessible if you specify a vector (-Sv|V) using the GMT4 syntax, explained here: size, if present, will be interpreted as arrowwidth/headlength/headwidth [Default is 0.075c/0.3c/0.25c (or 0.03i/0.12i/0.1i)]. By default, arrow attributes remain invariant to the length of the arrow. To have the size of the vector scale down with decreasing size, append +n norm, where vectors shorter than norm will have their attributes scaled by length/norm. To center the vector on the balance point, use -Svb; to align point with the vector head, use -Svh; to align point with the vector tail, use -Svt [Default]. To give the head point’s coordinates instead of direction and length, use -Svs. Upper case B, H, T, S will draw a double-headed vector [Default is single head].

## Examples

Note: Since many GMT plot examples are very short (i.e., one module call between the gmt begin and gmt end commands), we will often present them using the quick modern mode GMT Modern Mode One-line Commands syntax, which simplifies such short scripts.

    gmt polar -R239/240/34/35.2 -JM8c -N -Sc0.4 -D239.5/34.5 -M5 -pdf test << END
    #stat azim ih pol
    0481 11 147 c
    6185 247 120 d
    0485 288 114 +
    0490 223 112 -
    0487 212 109 .
    END

Use special format derived from HYPO71 output:

    gmt polar -R239/240/34/35.2 -JM8c -N -Sc0.4 -D239.5/34.5 -M5 -Qh -pdf test <<END
    #Date Or. time stat azim ih
    910223 1 22 0481 11 147 ipu0
    910223 1 22 6185 247 120 ipd0
    910223 1 22 0485 288 114 epu0
    910223 1 22 0490 223 112 epd0
    910223 1 22 0487 212 109 epu0
    END

## References

- Aki, K., & Richards, P. G. (1980). Quantitative seismology: theory and methods. San Francisco: W. H. Freeman.

- Dahlen, F. A., & Tromp, J. (1998). Theoretical global seismology. Princeton, N.J: Princeton University Press.

- Frohlich, C. (1996). Cliff’s Nodes Concerning Plotting Nodal Lines for P, SH and SV. Seismological Research Letters, 67(1), 16–24. https://doi.org/10.1785/gssrl.67.1.16

- Lay, T., & Wallace, T. C. (1995). Modern global seismology. San Diego: Academic Press.

## Author

Genevieve Patau, Laboratory of Seismogenesis, Institut de Physique du Globe de Paris, Departement de Sismologie, Paris, France

## See Also

meca, coupe, gmt, basemap, plot