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:

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]