pygmt.Figure.text

Figure.text(textfiles=None, x=None, y=None, position=None, text=None, angle=None, font=None, justify=None, *, region=None, projection=None, frame=None, clearance=None, offset=None, fill=None, no_clip=None, timestamp=None, verbose=None, pen=None, xshift=None, yshift=None, aspatial=None, panel=None, find=None, coltypes=None, header=None, incols=None, perspective=None, transparency=None, wrap=None, **kwargs)

Plot or typeset text strings of variable size, font type, and orientation.

Must provide at least one of the following combinations as input:

textfiles
x/y, and text
position and text

Full option list at https://docs.generic-mapping-tools.org/latest/text.html

Aliases:

B = frame
C = clearance
D = offset
G = fill
J = projection
N = no_clip
R = region
U = timestamp
V = verbose
W = pen
X = xshift
Y = yshift
a = aspatial
c = panel
e = find
f = coltypes
h = header
i = incols
p = perspective
t = transparency
w = wrap

Parameters

textfiles (str or list) – A text data file name, or a list of filenames containing 1 or more records with (x, y[, angle, font, justify], text).
x/y (float or 1d arrays) – The x and y coordinates, or an array of x and y coordinates to plot the text
position (str) –
Sets reference point on the map for the text by using x,y coordinates extracted from region instead of providing them through x/y. Specify with a two letter (order independent) code, chosen from:
- Horizontal: L(eft), C(entre), R(ight)
- Vertical: T(op), M(iddle), B(ottom)
For example, position="TL" plots the text at the Upper Left corner of the map.
text (str or 1d array) – The text string, or an array of strings to plot on the figure
angle (int, float, str or bool) – Set the angle measured in degrees counter-clockwise from horizontal (e.g. 30 sets the text at 30 degrees). If no angle is explicitly given (i.e. angle=True) then the input to textfiles must have this as a column.
font (str or bool) – Set the font specification with format size,font,color where size is text size in points, font is the font to use, and color sets the font color. For example, font="12p,Helvetica-Bold,red" selects a 12p, red, Helvetica-Bold font. If no font info is explicitly given (i.e. font=True), then the input to textfiles must have this information in one of its columns.
justify (str or bool) – Set the alignment which refers to the part of the text string that will be mapped onto the (x,y) point. Choose 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. If no justification is explicitly given (i.e. justify=True), then the input to textfiles must have this as a column.
projection (str) – projcode[projparams/]width. Select map projection.
region (str or list) – xmin/xmax/ymin/ymax[+r][+uunit]. Specify the region of interest. Required if this is the first plot command.
clearance (str) – [dx/dy][+to|O|c|C]. Adjust the clearance between the text and the surrounding box [Default is 15% of the font size]. Only used if pen or fill are specified. Append the unit you want (c for cm, i for inch, or p for point; if not given we consult PROJ_LENGTH_UNIT) or % for a percentage of the font size. Optionally, use modifier +t to set the shape of the textbox when using fill and/or pen. Append lower case o to get a straight rectangle [Default is o]. Append upper case O to get a rounded rectangle. In paragraph mode (paragraph) you can also append lower case c to get a concave rectangle or append upper case C to get a convex rectangle.
fill (str) – Sets the shade or color used for filling the text box [Default is no fill].
offset (str) – [j|J]dx[/dy][+v[pen]]. Offsets the text from the projected (x,y) point by dx,dy [0/0]. If dy is not specified then it is set equal to dx. Use j to offset the text away from the point instead (i.e., the text justification will determine the direction of the shift). Using J will shorten diagonal offsets at corners by sqrt(2). Optionally, append +v which will draw a line from the original point to the shifted point; append a pen to change the attributes for this line.
pen (str) – Sets the pen used to draw a rectangle around the text string (see clearance) [Default is width = default, color = black, style = solid].
no_clip (bool) – Do NOT clip text at map boundaries [Default is will clip].
timestamp (bool or str) – Draw GMT time stamp logo on plot.
verbose (bool or str) –
Select verbosity level [Default is w], which modulates the messages written to stderr. Choose among 7 levels of verbosity:
- q - Quiet, not even fatal error messages are produced
- e - Error messages only
- w - Warnings [Default]
- t - Timings (report runtimes for time-intensive algorithms);
- i - Informational messages (same as verbose=True)
- c - Compatibility warnings
- d - Debugging messages
xshift (str) – [a|c|f|r][xshift]. Shift plot origin in x-direction.
yshift (str) – [a|c|f|r][yshift]. Shift plot origin in y-direction. Full documentation is at https://docs.generic-mapping-tools.org/latest/gmt.html#xy-full.
aspatial (bool or str) – [col=]name[,…]. Control how aspatial data are handled during input and output. Full documentation is at https://docs.generic-mapping-tools.org/latest/gmt.html#aspatial-full.
panel (bool or int or list) – [row,col|index]. 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.
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.
coltypes (str) – [i|o]colinfo. Specify data types of input and/or output columns (time or geographical data). Full documentation is at https://docs.generic-mapping-tools.org/latest/gmt.html#f-full.
header (str) –
[i|o][n][+c][+d][+msegheader][+rremark][+ttitle]. 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.
incols (str or 1d array) –
Specify data columns for primary input in arbitrary order. Columns can be repeated and columns not listed will be skipped [Default reads all columns in order, starting with the first (i.e., column 0)].
- For 1d array: specify individual columns in input order (e.g., incols=[1,0] for the 2nd column followed by the 1st column).
- For 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 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 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].
  - +s to multiple the input values by the factor scale [Default is 1].
  - +o to add the given offset to the input values [Default is 0].
perspective (list or str) – [x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0]. Select perspective view and set the azimuth and elevation angle of the viewpoint. Default is [180, 90]. Full documentation is at https://docs.generic-mapping-tools.org/latest/gmt.html#perspective-full.
transparency (int or float) – Set transparency level, in [0-100] percent range. Default is 0, i.e., opaque. 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). transparency can also be a 1d array to set varying transparency for texts, but this option is only valid if using x/y/text.
wrap (str) –
y|a|w|d|h|m|s|cperiod[/phase][+ccol]. Convert the input x-coordinate to a cyclical coordinate, or a different column if selected via +ccol. 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 https://docs.generic-mapping-tools.org/latest/gmt.html#w-full.