.\" Man page generated from reStructuredText.
.
.TH "EVENTS" "1gmt" "Sep 07, 2019" "6.0.0rc4" "GMT"
.SH NAME
events \- Plot event symbols and labels for a moment in time
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
\fBgmt events\fP [ \fItable\fP ]  \fB\-J\fP\fIparameters\fP  \fB\-R\fP\fIwest\fP/\fIeast\fP/\fIsouth\fP/\fInorth\fP[/\fIzmin\fP/\fIzmax\fP][\fB+r\fP]  \fB\-S\fP\fIsymbol\fP[\fIsize\fP[\fIunits\fP]]
[  \fB\-B\fP[\fBp\fP|\fBs\fP]\fIparameters\fP ]
[  \fB\-C\fP\fIcpt\fP ]
[  \fB\-D\fP[\fBj\fP|\fBJ\fP]\fIdx\fP[/\fIdy\fP][\fB+v\fP[\fIpen\fP]] ]
[  \fB\-E\fP\fBs\fP|\fBt\fP[\fB+o\fP|\fBO\fP\fIdt\fP][\fB+r\fP\fIdt\fP][\fB+p\fP\fIdt\fP][\fB+d\fP\fIdt\fP][\fB+f\fP\fIdt\fP] ]
[  \fB\-F\fP[\fB+a\fP\fIangle\fP][\fB+f\fP\fIfont\fP][\fB+j\fP\fIjustify\fP][\fB+r\fP[\fIfirst\fP]|\fB+z\fP[\fIformat\fP]] ]
[  \fB\-G\fP\fIcolor\fP ]
[  \fB\-L\fP[\fIlength\fP|\fBt\fP] ]
[  \fB\-M\fP\fBi\fP|\fBs\fP|\fBt\fP[\fIval1\fP][\fB+c\fP\fIval2\fP] ]
[  \fB\-Q\fP\fIprefix\fP ]
[  \fB\-T\fP\fInow\fP ]
[  \fB\-V\fP[\fIlevel\fP] ]
[  \fB\-W\fP\fIpen\fP ]
[  \fB\-U\fP[\fIstamp\fP] ]
[  \fB\-W\fP\fIpen\fP ]
[  \fB\-X\fP[\fBa\fP|\fBc\fP|\fBf\fP|\fBr\fP][\fIxshift\fP[\fBu\fP]] ]
[  \fB\-Y\fP[\fBa\fP|\fBc\fP|\fBf\fP|\fBr\fP][\fIyshift\fP[\fBu\fP]] ]
[ \fB\-bi\fPbinary ]
[ \fB\-di\fPnodata ]
[ \fB\-e\fPregexp ]
[ \fB\-f\fPflags ]
[ \fB\-h\fPheaders ]
[ \fB\-i\fPflags ]
[ \fB\-p\fPflags ]
[ \fB\-:\fP[\fBi\fP|\fBo\fP] ]
[ \fB\-\-PAR\fP=\fIvalue\fP ]
.sp
\fBNote:\fP No space is allowed between the option flag and the associated arguments.
.SH DESCRIPTION
.sp
Reads (\fIx\fP, \fIy\fP[, \fIz\fP] [, \fIsize\fP], \fItime\fP [, \fIlength\fP]) data from files [or standard
input] and plots how the symbol for each event should look for the specified \fInow\fP time.
The reason they may differ is that events may have different lengths and we may
wish to accentuate the symbol attributes in ways to draw attention to an event when
it first happens and perhaps tone it down after a while to reduce clutter and focus
on more recent events. This module is typically used in conjunction with movie scripts
where the implicit loop over time is used to call it over a time\-sequence and
thus plot symbols as events unfold.
.SH REQUIRED ARGUMENTS
.INDENT 0.0
.TP
\fB\-J\fP\fIparameters\fP (more ...)
Select map projection.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-R\fP\fIxmin\fP/\fIxmax\fP/\fIymin\fP/\fIymax\fP[\fB+r\fP][\fB+u\fP\fIunit\fP] (more ...)
Specify the region of interest.  
.UNINDENT
.sp
For perspective view \fBp\fP, optionally append /\fIzmin\fP/\fIzmax\fP\&. (more ...)  
.INDENT 0.0
.TP
\fB\-S\fP\fIsymbol\fP[\fIsize\fP[\fIunits\fP]]
Specify the symbol to use for the event.  Optionally, append symbol \fIsize\fP with units from
(\fBc\fP|\fBi\fP|\fBp\fP).  If no \fIsize\fP is given then we read an event\-specific size
from the data file\(aqs third column (fourth if \fB\-C\fP is used). Note: Not all the symbols that
are available in psxy can be used here.  At the moment we only support the basic
symbols and custom symbols; bars, vectors, ellipses, fronts, decorated and quoted lines cannot
be specified.
.UNINDENT
.INDENT 0.0
.TP
\fB\-T\fP\fInow\fP
Sets the current plot time.  If absolute times are used you must also use \fB\-fT\fP\&.
.UNINDENT
.SH OPTIONAL ARGUMENTS
.INDENT 0.0
.TP
.B \fItable\fP
One or more ASCII (or binary, see \fB\-bi\fP[\fIncols\fP][\fItype\fP]) data
table file(s) holding a number of data columns. If no tables are given
then we read from standard input.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-B\fP[\fBp\fP|\fBs\fP]\fIparameters\fP (more ...)
Set map boundary frame and axes attributes.
.UNINDENT
.INDENT 0.0
.TP
\fB\-C\fP\fIcpt\fP
Use the \fIcpt\fP to convert \fIz\fP values given in the optional third column to assign symbol colors.
.UNINDENT
.INDENT 0.0
.TP
\fB\-D\fP[\fBj\fP|\fBJ\fP]\fIdx\fP[/\fIdy\fP][\fB+v\fP[\fIpen\fP]]
Offsets the text from the projected (\fIx\fP,\fIy\fP) point by \fIdx\fP,\fIdy\fP
[0/0]. If \fIdy\fP is not specified then it is set equal to \fIdx\fP\&. Use
\fB\-Dj\fP to offset the text away from the point instead (i.e., the
text justification will determine the direction of the shift). Using
\fB\-DJ\fP will shorten diagonal offsets at corners by
sqrt(2). Optionally, append \fB+v\fP which will draw
a line from the original point to the shifted point; append a \fIpen\fP
to change the attributes for this line.
.UNINDENT
.INDENT 0.0
.TP
\fBEs\fP|\fBt\fP[\fB+o\fP|\fBO\fP\fIdt\fP][\fB+r\fP\fIdt\fP][\fB+p\fP\fIdt\fP][\fB+d\fP\fIdt\fP][\fB+f\fP\fIdt\fP]
Sets the time knots for the \fBs\fPymbol or \fBt\fPext time\-functions.  Append
\fB+o\fP to shift the event start and end times by a constant offset (basically shifting
the event in time by \fIdt\fP; or use \fBO\fP to only shift the start time, effectively shortening
the duration of the event), \fB+r\fP to indicate the
duration of the rise phase, \fB+p\fP to set the duration of the plateau phase, \fB+d\fP
tp specify the duration of the decay phase, and \fB+f\fP to set the duration of the
fade phase.  These are all optional, and can be set separately for symbols and texts.
if neither \fBs\fP or \fBt\fP is given then we set the time knots for both features.
.UNINDENT
.INDENT 0.0
.TP
\fB\-F\fP[\fB+a\fP\fIangle\fP][\fB+f\fP\fIfont\fP][\fB+j\fP\fIjustify\fP][\fB+r\fP[\fIfirst\fP] |\fB+z\fP[\fIformat\fP]]
By default, event label text will be placed horizontally, using the primary
annotation font attributes (FONT_ANNOT_PRIMARY), and centered
on the data point. Use this option to override these defaults by specifying up to three
text attributes (font, angle, and justification) directly on the command line. Use \fB+f\fP
to set the font (size,fontname,color), \fB+a\fP to set the angle, and \fB+j\fP to set the justification.
Normally, the text to be plotted is the trailing text.  Instead, use \fB+r\fP to use the
record number (counting up from \fIfirst\fP [0]) or \fB+z\fP to format incoming \fIz\fP values (requires \fB\-C\fP)
to a string using the supplied \fIformat\fP [use FORMAT_FLOAT_MAP].
.UNINDENT
.INDENT 0.0
.TP
\fB\-G\fP\fIfill\fP (more ...)
Set constant shade or color for all symbols.
.UNINDENT
.INDENT 0.0
.TP
\fB\-Jz\fP|\fBZ\fP\fIparameters\fP (more ...)
Set z\-axis scaling; same syntax as \fB\-Jx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
\fB\-L\fP[\fIlength\fP|\fBt\fP]
Specify the length of the event.  Append a \fIlength\fP if all events have the same length,
append \fBt\fP if end\-times instead of lengths are given in the file after the \fItime\fP column,
or leave blank if lengths can be read from the input file after the \fItime\fP column.
.UNINDENT
.INDENT 0.0
.TP
\fB\-M\fP\fBi\fP|\fBs\fP|\fBt\fP[\fIval1\fP][\fB+c\fP\fIval2\fP]
Sets the initial \fBi\fPntensity, \fBs\fPize magnification, or \fBt\fPransparency of the symbol during
the \fIrise\fP interval [1, 1, and 100, respectively].
Optionally, use \fB+c\fP to set the corresponding terminal value during the coda [100].
.UNINDENT
.INDENT 0.0
.TP
\fB\-Q\fP\fIprefix\fP
Save the intermediate event symbols and labels to permanent files instead of removing when done.
Files will be called \fIprefix\fP_symbols.txt and \fIprefix\fP_labels.txt.
.UNINDENT
.INDENT 0.0
.TP
\fB\-U\fP[\fIlabel\fP][\fB+c\fP][\fB+j\fP\fIjust\fP][\fB+o\fP\fIdx\fP/\fIdy\fP] (more ...)
Draw GMT time stamp logo on plot.
.UNINDENT
.INDENT 0.0
.TP
\fB\-V\fP[\fIlevel\fP] (more ...)
Select verbosity level [c].  
.UNINDENT
.INDENT 0.0
.TP
\fB\-W\fP\fIpen\fP
Specify symbol outline pen attributes [Default is no outline].
.UNINDENT
.INDENT 0.0
.TP
\fB\-bi\fP[\fIncols\fP][\fBt\fP] (more ...)
Select native binary format for primary input. [Default is 3 input columns].
.UNINDENT
.INDENT 0.0
.TP
\fB\-di\fP\fInodata\fP (more ...)
Replace input columns that equal \fInodata\fP with NaN.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-e\fP[\fB~\fP]\fI"pattern"\fP \fB|\fP \fB\-e\fP[\fB~\fP]/\fIregexp\fP/[\fBi\fP] (more ...)
Only accept data records that match the given pattern.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-f\fP[\fBi\fP|\fBo\fP]\fIcolinfo\fP (more ...)
Specify data types of input and/or output columns.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-h\fP[\fBi\fP|\fBo\fP][\fIn\fP][\fB+c\fP][\fB+d\fP][\fB+r\fP\fIremark\fP][\fB+r\fP\fItitle\fP] (more ...)
Skip or produce header record(s).  
.UNINDENT
.INDENT 0.0
.TP
\fB\-i\fP\fIcols\fP[\fB+l\fP][\fB+s\fP\fIscale\fP][\fB+o\fP\fIoffset\fP][,\fI\&...\fP][,\fIt\fP[\fIword\fP]] (more ...)
Select input columns and transformations (0 is first column, \fIt\fP is trailing text, append \fIword\fP to read one word only).
.UNINDENT
.INDENT 0.0
.TP
\fB\-p\fP[\fBx\fP|\fBy\fP|\fBz\fP]\fIazim\fP[/\fIelev\fP[/\fIzlevel\fP]][\fB+w\fP\fIlon0\fP/\fIlat0\fP[/\fIz0\fP]][\fB+v\fP\fIx0\fP/\fIy0\fP] (more ...)
Select perspective view.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-:\fP[\fBi\fP|\fBo\fP] (more ...)
Swap 1st and 2nd column on input and/or output.
.UNINDENT
.INDENT 0.0
.TP
\fB\-^\fP or just \fB\-\fP
Print a short message about the syntax of the command, then exits (NOTE: on Windows just use \fB\-\fP).
.TP
\fB\-+\fP or just \fB+\fP
Print an extensive usage (help) message, including the explanation of
any module\-specific option (but not the GMT common options), then exits.
.TP
\fB\-?\fP or no arguments
Print a complete usage (help) message, including the explanation of all options, then exits.
.TP
\fB\-\-PAR\fP=\fIvalue\fP
Temporarily override a GMT default setting; repeatable. See /gmt.conf for parameters.
.UNINDENT
.SH THE THREE TIME-FUNCTIONS
.sp
Events typically have either a finite length, e.g., the temporal extent of
the reign of a particular monarch, or are infinite.  Here, infinite simply means
its length exceeds the temporal extent of the time we are plotting.  In a movie,
a basic representation of these events as points on a map would be to start plotting
the symbol when the event starts and then keep the symbol visible on all frames until the
event ends (or never stop plotting them in the infinite length case).  However, to draw
attention to the arrival of a new event we can temporarily change three aspects of
the symbol: Its size, color intensity, and transparency.  You can think of these three
attributes as functions of time.  For some option settings, Figure Symbol size function
illustrates how the symbol size may vary through the timespan of the movie.
.INDENT 0.0
.INDENT 2.5
[image]
Implied evolution of one symbol\(aqs size\-variation as a function of time
given the time\-knots from \fB\-Es\fP and the magnifications from \fB\-Ms\fP\&.
Here we temporarily magnify the symbol size five times before decaying
to the intended size and eventually shrink it further down to a small
size during the fade and coda phases..UNINDENT
.UNINDENT
.sp
Similarly, to draw attention to the newly arrived event you may want to whiten the color
temporarily; this can be done via the \fB\-Mi\fP option and Figure Symbol intensity function
illustrates how intensity may vary accordingly.
.INDENT 0.0
.INDENT 2.5
[image]
Implied evolution of one symbol\(aqs color intensity as a function of time
given the time\-knots from \fB\-Es\fP and the intensities from \fB\-Mi\fP\&.  Here we
seek to whiten the symbol during the event arrival, as well as darken it
during a permanent code phase..UNINDENT
.UNINDENT
.sp
Finally, for finite events you may wish to either fade them out completely or
simply fade them to a constant but still visible transparency; this future stage
is referred to as the coda and levels can be specified via the \fB\-Mt\fP option.
Figure Symbol transparency function
illustrates how transparency may vary through time.
.INDENT 0.0
.INDENT 2.5
[image]
Here we show how a symbol may go from being invisible to reach full opaqueness
at the event begin time, then finally fade to a near\-invisible stage after reaching
its length..UNINDENT
.UNINDENT
.sp
While shown in these examples, the rise, plateau, fade, and coda periods are all optional
and can be selected or ignored as you wish via \fB\-E\fP\&.  You can choose to specify any or none
of the three time histories.  By default the symbol size is constant, there is no intensity
variation, and all symbols are opaque.  If trailing text is plotted (requires \fB\-Et\fP) then
only a transparency time\-function is used.
.SH EXAMPLES
.sp
To show the display of events visible for May 1, 2018 given the catalog of
large (>5) magnitude earthquakes that year, using a 2\-day rise time during
which we boost symbol size by a factor of 5 and wash out the color, followed
by a decay over 6 days and then a final shrinking to half size and darken the
color, we may try
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt begin layer
  gmt convert "https://earthquake.usgs.gov/fdsnws/event/1/query.csv?starttime=2018\-01\-01%2000:00:00&endtime=2018\-12\-31%2000:00:00&minmagnitude=5&orderby=time\-asc" \e
     \-i2,1,3,4+s50,0 \-hi1 > q.txt
  gmt makecpt \-Cred,green,blue \-T0,70,300,10000 > q.cpt
  gmt events \-Rg \-JG200/5/6i \-Baf q.txt \-SE\- \-Cq.cpt \-\-TIME_UNIT=d \-T2018\-05\-01T \-Es+r2+d6 \-Ms5+c0.5 \-Mi1+c\-0.6 \-Mt+c0
gmt end show
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
gmt, gmtcolors,
plot,
movie
.SH COPYRIGHT
2019, The GMT Team
.\" Generated by docutils manpage writer.
.