.\" Man page generated from reStructuredText.
.
.TH "PSHISTOGRAM" "1gmt" "May 21, 2019" "5.4.5" "GMT"
.SH NAME
pshistogram \- Calculate and plot histograms
.
.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
\fBpshistogram\fP [ \fItable\fP ]  \fB\-J\fP\fBx\fP|\fBX\fP\fIparameters\fP
 \fB\-W\fP\fIbin_width\fP[\fB+l\fP|\fBh\fP|\fBb\fP]
[  \fB\-A\fP ]
[  \fB\-B\fP[\fBp\fP|\fBs\fP]\fIparameters\fP ]
[  \fB\-C\fP\fIcpt\fP ]
[  \fB\-D\fP[\fB+b\fP][\fB+f\fP\fIfont\fP][\fB+o\fP\fIoff\fP][\fB+r\fP] ]
[  \fB\-F\fP ]
[  \fB\-G\fP\fIfill\fP ] [  \fB\-J\fP\fBz\fP|\fBZ\fP\fIparameters\fP ]
[  \fB\-I\fP[\fBo\fP|\fBO\fP] ]
[  \fB\-K\fP ] [  \fB\-L\fP\fIpen\fP ]
[  \fB\-N\fP[\fImode\fP][\fB+p\fP\fIpen\fP] ]
[  \fB\-O\fP ] [ \fB\-P\fP ] [  \fB\-Q\fP ]
[  \fB\-R\fP\fIregion\fP ]
[  \fB\-S\fP ]
[  \fB\-U\fP[\fIstamp\fP] ]
[  \fB\-V\fP[\fIlevel\fP] ]
[  \fB\-X\fP\fIx_offset\fP ]
[  \fB\-Y\fP\fIy_offset\fP ]
[  \fB\-Z\fP[\fItype\fP][\fB+w\fP] ]
[ \fB\-bi\fPbinary ]
[ \fB\-di\fPnodata ]
[ \fB\-e\fPregexp ]
[ \fB\-f\fPflags ]
[ \fB\-h\fPheaders ]
[ \fB\-i\fPflags ]
[ \fB\-p\fPflags ]
[ \fB\-t\fPtransp ]
.sp
\fBNote:\fP No space is allowed between the option flag and the associated arguments.
.SH DESCRIPTION
.sp
\fBpshistogram\fP reads \fIfile\fP [or standard input] and examines the first
data column (or use \fB\-i\fP) to calculate histogram parameters based on
the bin\-width provided. Using these parameters, scaling, and optional
range parameters it will generate PostScript code that plots a
histogram. A cumulative histogram may also be specified.
.SH REQUIRED ARGUMENTS
.INDENT 0.0
.TP
\fB\-Jx\fP
\fIxscale[/yscale]\fP (Linear scale(s) in distance unit/data unit).
.UNINDENT
.INDENT 0.0
.TP
\fB\-W\fP\fIbin_width\fP[\fB+l\fP|\fBh\fP|\fBb\fP]
Sets the bin width used for histogram calculations.
The modifiers specify the handling of extreme values that fall outside the range
set by \fB\-R\fP\&.  By default these values are ignored.  Use \fB+b\fP to let
these values be included in the first or last bins.  To only include
extreme values below first bin into the first bin, use \fB+l\fP, and to
only include extreme values above the last bin into that last bin, use
\fB+h\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\-A\fP
Plot the histogram horizontally from x = 0 [Default is vertically
from y = 0].  The plot dimensions remain the same, but the two
axes are flipped.
.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
Give a CPT. The mid x\-value for each bar is used to
look\-up the bar color.
.UNINDENT
.INDENT 0.0
.TP
\fB\-D\fP[\fB+b\fP][\fB+f\fP\fIfont\fP][\fB+o\fP\fIoff\fP][\fB+r\fP]
Annotate each bar with the count it represents.  Append any of the
following modifiers: Use \fB+b\fP to place the labels beneath the bars
instead of above; use \fB+f\fP to change to another font than the default
annotation font; use \fB+o\fP to change the offset between bar and label [6p];
use \fB+r\fP to rotate the labels from horizontal to vertical.
.UNINDENT
.INDENT 0.0
.TP
\fB\-F\fP
Center bin on each value. [Default is left edge].
.UNINDENT
.INDENT 0.0
.TP
\fB\-G\fP\fIfill\fP
Select filling of bars [Default is no fill].
.UNINDENT
.INDENT 0.0
.TP
\fB\-I\fP[\fBo\fP|\fBO\fP]
Inquire about min/max x and y after binning. The \fIxmin xmax ymin
ymax\fP is output; no plotting is done. Append \fBo\fP to output an
ASCII table of the resulting x,y data instead. Upper case \fBO\fP will
output all x,y bin data even when y == 0.
.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\-K\fP (more ...)
Do not finalize the PostScript plot.
.UNINDENT
.INDENT 0.0
.TP
\fB\-L\fP\fIpen\fP
Draw bar outline using the specified pen thickness. [Default is no outline].
.UNINDENT
.INDENT 0.0
.TP
\fB\-N\fP[\fImode\fP][\fB+p\fP\fIpen\fP]
Draw the equivalent normal distribution; append desired pen [0.5p,black].
The \fImode\fP selects which central location and scale to use:
.INDENT 7.0
.IP \(bu 2
0 = mean and standard deviation [Default];
.IP \(bu 2
1 = median and L1 scale;
.IP \(bu 2
2 = LMS mode and scale.
.UNINDENT
.sp
The \fB\-N\fP option may be repeated to draw several of these curves.
.UNINDENT
.INDENT 0.0
.TP
\fB\-O\fP (more ...)
Append to existing PostScript plot.
.UNINDENT
.INDENT 0.0
.TP
\fB\-P\fP (more ...)
Select "Portrait" plot orientation.
.UNINDENT
.INDENT 0.0
.TP
\fB\-Q\fP
Draw a cumulative histogram.
.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 ...) If not given, \fBpshistogram\fP will automatically find reasonable values for the region.
.INDENT 0.0
.TP
\fB\-S\fP
Draws a stairs\-step diagram which does not include the internal bars
of the default histogram.
.UNINDENT
.INDENT 0.0
.TP
\fB\-U\fP[[\fIjust\fP]/\fIdx\fP/\fIdy\fP/][\fBc\fP|\fIlabel\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
.sp
\fB\-X\fP[\fBa\fP|\fBc\fP|\fBf\fP|\fBr\fP][\fIx\-shift\fP[\fBu\fP]]
.INDENT 0.0
.TP
\fB\-Y\fP[\fBa\fP|\fBc\fP|\fBf\fP|\fBr\fP][\fIy\-shift\fP[\fBu\fP]] (more ...)
Shift plot origin.
.UNINDENT
.INDENT 0.0
.TP
\fB\-Z\fP[\fItype\fP][\fB+w\fP]
Choose between 6 types of histograms:
.INDENT 7.0
.IP \(bu 2
0 = counts [Default]
.IP \(bu 2
1 = frequency_percent
.IP \(bu 2
2 = log (1.0 + count)
.IP \(bu 2
3 = log (1.0 + frequency_percent)
.IP \(bu 2
4 = log10 (1.0 + count)
.IP \(bu 2
5 = log10 (1.0 + frequency_percent).
.UNINDENT
.sp
To use weights provided as a second data column instead of pure counts,
append \fB+w\fP\&.
.UNINDENT
.INDENT 0.0
.TP
\fB\-bi\fP[\fIncols\fP][\fBt\fP] (more ...)
Select native binary input. [Default is 2 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] (more ...)
Select input columns and transformations (0 is first column).
.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\-t\fP[\fItransp\fP] (more ...)
Set PDF transparency level in percent.
.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.
.UNINDENT
.SH EXAMPLES
.sp
To draw a histogram of the data v3206.t containing seafloor depths,
using a 250 meter bin width, center bars, and draw bar outline, use:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt pshistogram v3206.t \-JXh \-W250 \-F \-LP0.5p \-V > plot.ps
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
If you know the distribution of your data, you may explicitly specify
range and scales. E.g., to plot a histogram of the y\-values (2nd column)
in the file errors.xy using a 1 meter bin width, plot from \-10 to +10
meters @ 0.75 cm/m, annotate every 2 m and 100 counts, and use black
bars, run:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt pshistogram errors.xy \-W1 \-R\-10/10/0/0 \-Jxc/0.01c \e
                \-Bx2+lError \-By100+lCounts \-Gblack \-i1 \-V > plot.ps
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Since no y\-range was specified, \fBpshistogram\fP will calculate \fIymax\fP in even
increments of 100.
.SH BUGS
.sp
The \fB\-W\fP option does not yet work properly with time series data
(e.g., \fB\-f\fP0T). Thus, such variable intervals as months and years
are not calculated. Instead, specify your interval in the same units as
the current setting of \fBTIME_UNIT\fP\&.
.SH SEE ALSO
.sp
gmt, gmtcolors,
psbasemap, psrose,
psxy
.SH COPYRIGHT
2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
.\" Generated by docutils manpage writer.
.