McIDAS-X User's Guide
Version 2023.1

[Search Manual] [Table of Contents] [Go to Previous] [Go to Next]

PTCON

Converts point data to grids; displays contours and plots.

Format

PTCON dataset1 . . datasetn [keywords]

Parameters

dataset1 . . n

ADDE dataset names and positions; specify one of the following formats for each dataset:

group/descriptor.position

alias.position

a position greater than zero represents an absolute position in the dataset; a position less than or equal to zero represents a relative position in the dataset based on date and time, for example, 0 is the most recent and -1 is the next most recent; the position ALL represents all positions in the dataset (no default for group/descriptor or alias; position default=ALL if DAY is specified with the SELECT keyword, otherwise default=0)

Keywords

OUT=		CON		contours the gridded data (default)
		PLOT		plots grid points
		SAVE ddataset		saves the created grid to a destination dataset
		SCON ddataset		contours the gridded data and saves the created grid to a destination dataset
		SPLOT ddataset		plots grid points and saves the created grid to a destination dataset; see the Remarks
PARam=	parameter to contour; specify a native parameter, a computed parameter or one of the four predefined parameters as listed below:
		native_parameter [unit]
			native parameter to contour and its output units; native parameters are those that are stored in the point file (no default for parameter; unit default=from dataset)
		'computed_parameter [unit]=expression'
			computed parameter to contour, its output units, and the mathematical expression used to compute it; computed parameters do not exist in the point file but are derived with the specified mathematical expression containing math operators (+ - * etc.) and the native parameters specified in the Pn keywords, e.g., PAR='TDD[F]=P1-P2'; see the Remarks and the Pn keyword description for more information (no default for parameter or expression; unit default=from dataset)
		MOVIE	draws streamlines with colored line segments that can be animated using the CM command
		STREAML	draws streamlines using u- and v-component grids
		WINDB	plots wind barbs using u- and v-component grids
		WINDV	plots wind vectors using u- and v-component grids
SELect=	'clause1; clause2; . . ; clausen' finds only the data matching the values in the select clauses; single quotes are mandatory; separate select clauses with semicolons; specify clause as a range or a list using one of the following formats:
		range: list:	parameter [unit] bval eval parameter [unit] val1,val2, . . ,valn
		parameter	point file parameter
		[unit]	units for the parameter values; units are optional but must be in square brackets if specified; see the Remarks (default=from dataset)
		bval eval	range of parameter values; see the Remarks
		val1, . . ,valn	list of parameter values

Mathematical Operations Keywords

Pn=	parameter [unit] 'clause1; clause2; ..; clausen' native parameters to use in the math expression specified in the PARAM keyword; use a number between 1 and 99 in the keyword name (P1,P2,..,P99); each keyword specifies a single native parameter and units to substitute in matching Pn values in the math expression, where:
		parameter [unit] is the native parameter name and units; unit defaults to those for the parameter in the dataset; there is no default for parameter
		'clause1; clause2; ..; clausen' are the clauses used to select data for this keyword; only data matching their criteria is used; they are specified exactly as in the SELECT keyword; the Pn keywords inherit the clauses specified in the SELECT keyword, therefore, you should specify a Pn keyword clause only if a value differs from that in the SELECT keyword or you need to add additional clauses; for example, to set the values of P1 and P2 to the 850 and 1000 mb temperatures in degrees Celsius at 0 UTC, respectively, specify the following keywords: SEL='TIME 0; P 850' P1=T[C] P2=T[C] 'P 1000'
GINFO=	level lunit day time src fhour values to assign to the header of the computed parameter grid created with the PARAM and Pn keywords, where:
		level	grid level
		lunit	grid level units; 2 character maximum
		day	grid day (default=value specified for DAY in the SELECT keyword; otherwise, default=today)
		time	grid time (default=value specified for TIME in the SELECT keyword; otherwise, default=22:22:22)
		src	grid source (default=MDX)
		fhour	grid forecast hour (default=0)

Navigation Keywords

LAT=	lat1 lat2	latitudes of the points at the lower-right and upper-left corners of the map; you cannot use LAT with the NAV or MAP keyword
LON=	lon1 lon2	longitudes of the points at the lower-right and upper-left corners of the map; you cannot use LON with the NAV or MAP keyword
MAP=	map for the contour or plot; see the MAP command for a list of valid predefined maps, for example, MID, USA, WORL; you cannot use MAP with the NAV, LAT or LON keyword
MCOlor=	graphics color level of the map (default=1)
NAV=	num	frame to use for navigation
	C	use the current frame's navigation
	the plot is drawn using the navigation of the specified frame; no map is drawn; you cannot use NAV with the MAP, LAT or LON keyword
PRO=	CONF	polar stereographic or Lambert conformal projection
	MERC	Mercator projection (default)
SLAt=	lat1 lat2	standard latitudes for a CONF projection; two values for a general Lambert conformal projection; one value for a polar stereographic projection (default=60 60 for northern hemisphere maps defined with the LAT and LON, or MAP keywords; -60 -60 for southern hemisphere maps defined with the LAT and LON, or MAP keywords)
SLOn=	standard longitude for a CONF projection (default=computed)

Contour and Plot Keywords

COLor=	graphics color level (default=2 for contour, 3 for plot)
ELE=	bele eele		beginning and ending frame elements for output; specify MAX for maximum element number (default=1 MAX when using the NAV keyword; default=20 MAX-20 when using the MAP keyword)
FORMAT=	designator 'text' output format for the grid point values or contour labels, and associated text; valid formats are I, F, or E; see the Remarks (designator default=from dataset; no text default)
GRA=	graphics frame for the display (default=current)
LABel=	'text' col line ele size text, color, location and size for the contour or plot title
		'text'	72 characters maximum; specify X without quotes for the default title (default=computed)
		col	graphics color level of the title (default=1 if PARAM=MOVIE, otherwise default=value from the COLOR keyword)
		line	beginning TV line to write the title (default=below contour or plot)
		ele	beginning TV element to write the title (default=below contour or plot)
		size	height of the title text in pixels (default=8)
LINE=	blin elin		beginning and ending frame lines for output; specify MAX for maximum line number (default=1 MAX-57 when using the NAV keyword; default=20 MAX-57 when using the MAP keyword)
LSIze=	height, in pixels, of the plot characters or contour labels; the range is 0-50 where 0 omits the labels (default=8)
POWer=	power of 10 to multiply the grid point values by for display (default=0)
TDAy=	CAL		display calendar day on the default title; not valid if the ELE, LINE or PAN keyword is used
	JUL		display the Julian day on the default title (default)

Contour-Specific Keywords

CINt=	num		contour interval; specify 0 to let PTCON compute a reasonable interval; specify your own interval as an integer or decimal value greater than zero; see the Remarks for the default value
	string		contour values; specify a string name that contains up to 64 values; e.g., CINT=SNOWDEPTH will draw contours at the values specified in the string named SNOWDEPTH
DASh=	ALL		dash all contours
	NEG		dash negative contours only
	POS		dash positive contours only (default=solid contours)
LINT=	contour label interval (default=1, meaning label every contour)
MOVie=	bcol ecol bspd espd blen elen change the defaults for the PARAM=MOVIE output
		bcol	beginning graphics color level for line segments (default=2)
		ecol	ending graphics color level for line segments (default=maximum color level)
		bspd	beginning wind speed represented by blen, units are from the created grid (default=computed)
		espd	ending wind speed represented by elen, units are from the created grid (default=computed)
		blen	beginning length of line segments (default=2)
		elen	ending length of line segments (default=40)
SMOoth=	contour smoothing factor; the range is 0 through 50; not valid with PARAM=MOVIE or PARAM=STREAML; larger numbers produce smoother contours (default=20)

Plot-Specific Keyword

PINt=

row col

row and column intervals of grid points to plot with OUT=PLOT, PARAM=WINDB or PARAM=WINDV; for example, PINT=4 3 plots every fourth grid point in the row direction and every third grid point in the column direction (row default=1; col default=row)

Grid Conversion Keywords

BPAr=	smoothing factor for the conversion of point data to grids; a larger number results in a data point influencing a greater number of grid points, and the generation of a smoother grid; BPAR is related to the Barnes parameter used in the grid analysis; the suggested range is 5 to 500 (default=40)
DISt=	distance in grid points to extrapolate into areas without data; the range is 1 to 25; grid points beyond the specified distance are assigned missing value codes and therefore are not contoured; the results will vary for a given value depending on data density, grid spacing and smoothing (default=10)
LLInc=	latinc loninc	latitudinal and longitudinal incremements, in degrees, between the grid points in the grid that PTCON creates; use this keyword to control the smoothing and extents of the output contours (latinc default=1 if the grid is 10° or more in the latitudinal and longitudinal directions, latinc default=computed value <1 if the grid is less than 10° in either direction, loninc default=latinc)

Grid Output Keywords

DEL=	YES	delete the destination grid file before copying
	NO	do not delete the destination grid file (default)
DGRid=	beginning grid number in the destination grid file to place the copied grids; this keyword may overwrite existing grids; see the Remarks (default=append after the last grid in the grid file)
GLEV=	level unit	grid level to use in the grid header and on the display (default=value entered for LEV, THA, or P in the SELECT keyword clause; otherwise, no default)
MAXgrd=	maximum number of grids the newly created destination grid file can store; see the Remarks (default=1000)
TITLE=	'text'	title of the newly created destination grid file; 32 characters maximum

Text Output Keyword

BYTecount=	YES	lists the number of bytes received from the server
	NO	does not list the number of bytes (default)

Remarks

PTCON gathers data from one or more point files in one or more datasets. The SELECT keyword defines which records to match and the PARAM keyword defines which parameters in the matching records to use. The selected point data is used to produce grid data.

The grid data may be saved, displayed, or both. The grid is saved in a Mercator projection with the native units or in the units specified with the PARAM keyword.

You must specify a parameter using the PARAM keyword, and a type of navigation using the NAV, MAP, or LAT and LON keywords. If the point file contains multiple times and/or days, you should also specify the TIME and/or DAY parameter in a SELECT keyword clause. Otherwise, all times and/or days will be used.

To file the correct day information in the output grid header, you must specify the DAY parameter in a SELECT keyword clause. If you don't specify a day, the value stored in the grid header is today's Julian date.

If you specify MOVIE, STREAML, WINDB, or WINDV with the PARAM keyword, grids of both the u- and v-component of the wind are saved or contoured.

The default contour interval for a grid is taken from the text file CONTOUR.DEF. If no file entry matches the grid's parameter, units and level, the default is calculated to produce a reasonable number of contours, usually between 10 and 20. To change, add or delete entries in CONTOUR.DEF, first back up the current version, then modify it using the format described near the top of the file.

If you specify DEL=YES or a position number of a nonexistent grid file in the ddataset parameter, the grids are copied into a newly created grid file with the attributes specified in keywords MAXGRD and TITLE.

Using the DGRID keyword may result in grids being overwritten in the destination grid file. For example, if the destination grid file has 50 grids (in grids 1 to 50) and you specify NUM=10 DGRID=25, the new grids will overwrite grids 25 to 34 in the destination grid file.

Use the FORMAT keyword options below to format output of the grid point values or contour labels based on FORTRAN designators for data output. To add text to the labels, follow the designator with a text in single quotes.

Designator	Description
I	integer
F	floating point
E	exponential

To specify a parameter's output format, use a designator followed by a positive number. For example, I4 specifies an integer of up to four digits; I6.4 specifies an integer of up to six digits and will add leading zeros if necessary to get to four digits; F10.1 specifies a floating point decimal of up to 10 digits (including the decimal point) with one digit to the right of the decimal; E10.3 specifies an exponential number of up to 10 characters (including the decimal point and the four-character exponential flag) with three digits to the right of the decimal. Specify an X to use the parameter's default format. If the specified integer or floating point format is too small for the parameter's values, a series of asterisks (***) is plotted.

When using the SELECT and PARAM keywords, you can use the following units:

Unit type	UNIT=	Definition
Distance	CM	centimeters
	DM	decameters
	FT	feet
	GPM	geopotential meters
	IN	inches
	KM	kilometers
	M	meters
	MI	miles
	MM	millimeters
	NMI	nautical miles
	YD	yards
Pressure	HPA	hectopascals
	INHG	inches of mercury
	MB	millibars
Speed	KT or KTS	knots
	MPH	miles per hour
	MPS	meters per second
Temperature	C	Celsius
	F	Fahrenheit
	K	Kelvin

The PARAM keyword contains the parameter to contour. It can be a native parameter, a computed parameter, or a predefined parameter (STREAML, WINDB, WINDV, or MOVIE).

Native parameters are those stored in the point file. They are specified in the PARAM keyword in the format parameter [unit], where parameter is the parameter name in the file, and [unit] is the output units, which are optional but must be in square brackets if specified.

Computed parameters do not exist in the point file but are derived with a mathematical expression. Computed parameters are specified in the PARAM keyword in the format 'parameter [unit]=expression', where parameter is the user-defined parameter name; [unit] is the label units, which are optional but must be in square brackets if specified; and expression is the mathematical expression consisting of math operators and one or more native parameters defined in the Pn keywords.

The table below lists the math operators valid in the computed parameter expression in the PARAM keyword.

Math Operator	Function
+	addition
–	subtraction
*	multiplication
/	division
**	power
SQRT	square root
EXP	exponential (the number e raised to a power)
LOG	natural logarithm
LOG10	base 10 logarithm
SIN	sine
COS	cosine
TAN	tangent
ASIN	arcsine
ACOS	arccosine
ATAN	arctangent
ABS	absolute value
MIN	minimum of two grids
MAX	maximum of two grids

To compute a power of ten, such as 102 or 10-3 in the math expression of a computed parameter in the PARAM keyword, specify it in either the 1epower or 10**(power) format. For example, both 1e-5 and 10**(-5) represent 10-5. You must include the parenthesis with 10**(-5) for it to be interpreted correctly.

The following character limits exist for the PARAM keyword:

256 characters maximum for the entire PARAM keyword list
four characters maximum for the computed parameter name
four characters maximum for the computed parameter units

When using point/MD files with CYD (ccyyddd) date units (e.g., FO14, IRAB, ISEN, ISFC, ISHP, PIRP and SYN schema MD files created with McIDAS-XCD 7.5 and later), commands PTCON, PTCOPY, PTDISP and PTLIST default to the current year if you don't specify a four-digit year and the nearest century if you specify only the last two digits of the year. For example, if the file uses CYD units for the DAY parameter and its value is 2004260, then you can specify the DAY in the SELECT keyword as 2004260 or 04260. If the current year is 2004, you can also specify it as 260. Use the PTLIST command with FORM=PARAM to list the file's parameters and units.

The PTCON, PTCOPY, PTDISP and PTLIST commands continue to work with point/MD files using the old SYD (ssyyddd) date units (e.g., FO14, IRAB, ISEN, ISFC, ISHP, PIRP and SYN schema MD files created with versions of McIDAS-XCD prior to 7.5), with the following exception: If you want to specify DAY in the SELECT keyword and the ss portion of the MD file's DAY value is nonzero, then you must specify the units with DAY in the SELECT keyword. For example, if the MD file uses SYD units for DAY and its value is 7197240, then it must appear as SELECT='DAY[SYD] 7197240'. If the MD file uses SYD units for DAY but has a zero (blank) ss value, you don't have to specify the units in the SELECT keyword. For example, if the MD file uses SYD units for DAY and its value is 97240 then it can appear as either SELECT='DAY 97240' or SELECT='DAY[SYD] 97240'.

If the dataset's schema has a key that represents time, such as HMS and TIME in the ISFC schema, it must be specified using the HH, HH:MM, or HH:MM:SS formats in the source dataset. For example, 12:00:00 UTC must be in the format 12, 12:00, or 12:00:00.

Examples

PTCON SURFACE/HOURLY PARAM=T[F] SELECT='TIME 6' MAP=USA

This entry draws a contour of today's 6:00 UTC surface temperature data (in degrees Fahrenheit) over the United States. The data is taken from the most recent point file in dataset SURFACE/HOURLY. The grid points used to draw the contour are not saved.

PTCON RTPTSRC/SFCHOURLY RTPTSRC/SYNOPTIC RTPTSRC/SHIP PARAM=TD[C] SELECT='TIME 6; DAY 96311' LAT=0 70 LON=-20 120 PRO=CONF GRA=3 LABEL='DEW POINT TEMPS' FORMAT=F6.1 'degrees C' DASH=NEG

This entry draws a contour of the 6:00 UTC dew point temperature data (in degrees Celsius) for day 96311. All data in datasets RTPTSRC/SFCHOURLY, RTPTSRC/SYNOPTIC, and RTPTSRC/SHIP is searched. The contours are drawn on graphics frame 3 using a map with a latitude range of 0° to 70° North and a longitude range of 20° East to 120° West. The label on the image window is DEW POINT TEMPS. The contour values are labeled with a floating point format with degrees C after each value. Contours with negative values are dashed. The grid points used to draw the contour are not saved.

PTCON SURFACE/SYNOPTIC.7 PARAM=PCP[IN] POW=2 BPAR=20 OUT=SCON TEST/GRIDS.2 MAP=MID SELECT='TIME 18; DAY 96317' DGRID=21 CINT=10 LINT=2

This entry draws contours for the 18:00 UTC six-hour cumulative precipitation (in inches) for day 96317. The data is taken from the point file in position 7 of the dataset SURFACE/SYNOPTIC. The contour is drawn on a map of the Midwest. The values are multiplied by one hundred times their original value. A contour interval of 0.10" is used with labels on every other contour. The grid point conversion is filtered using a smoothing factor of 20. The gridded analysis is saved as grid number 21 of the grid file in position 2 of the dataset TEST/GRIDS.

PTCON SURFACE/HOURLY.5 SURFACE/SYNOPTIC.5 SURFACE/SHIP.5 PARAM=T[C] SELECT='TIME 00; DAY 96315' LAT=-84 -68 LON=20 -171 SLAT=-75 SLON=160 PRO=CONF OUT=SPLOT MYGRIDS.51 DGRID=13 COLOR=3 LLINC=1 4 DIST=6 PINT=2 5

This entry plots surface temperature (in degrees Celsius) from 0:00 UTC for day 96315 using data from the point file in position 5 of datasets SURFACE/HOURLY, SURFACE/SYNOPTIC, and SURFACE/SHIP. Grid point values are plotted on a map of West Antarctica in graphics color level 3 with data from every second row and fifth column displayed. The grid point increment is one degree of latitude and four degrees of longitude. Data is extrapolated up to a distance of six grid points into data void regions. The gridded analysis is saved in grid number 13 of the grid file in position 51 of the dataset with the alias name MYGRIDS.

PTCON SURFACE/HOURLY SELECT='TIME 0; DAY #Y' PARAM=MOVIE MAP=USA MOVIE=2 8

TE MOVIECOLORS "GU MAKE !1 0 !2 0

REPEAT MOVIECOLORS 2 TO 8 BY 1 0 BY 40

CM 2 8 GO=YES

The PTCON entry draws today's 00 UTC surface streamlines with colored line segments on a map of the United States. The TE and REPEAT entries set graphics color levels 2 to 8 to increase linearly from black (level 2) to bright green (level 8). The CM entry then circulates the graphics color levels to animate the wind flow.

PTCON RTPTSRC/SFCHOURLY SEL='DAY #Y;TIME 12' PAR='DELT[F]=P1-P2' P1=T[F] P2=T[F] 'TIME 0' MAP=USA

This entry draws contours of today's 00 UTC to 12 UTC temperature change in degrees Fahrenheit on a map of the United States. The data is taken from the most recent point file in dataset RTPTSRC/SFCHOURLY.

PTCON RTPTSRC/SFCHOURLY SEL='DAY #Y;TIME 12' MAP=NA PARAM='THA[K]=P1/((P2/1000)**.286)' P1=T[K] P2=PSL[MB]

This entry contours potential temperature in degrees Kelvin at 12 UTC today on a map of North America. The potential temperature values are calculated using the equation in the PARAM keyword, known as Poisson's Equation.

[Search Manual] [Table of Contents] [Go to Previous] [Go to Next]