NCL data types overview

Basic numeric types

In NCL, basic data types are all of the standard types found in nearly all programming languages. Types classified as numeric types support all of the algebraic functions available in NCL (see Expressions). The following is a list of the basic numeric types currently supported; they are listed by their keywords, default size for most systems, and valid numerical ranges:

CAUTION: Currently, arithmetic overflow and underflow are not reported as errors to the user. Assignment of out-of-range values may cause errors.

	double		64bits		+/- ( 2.22507e-308 ) to (8.98846e+307)
	float		32bits		+/- ( 1.175494e-38 ) to (1.701411e+38)
	long		32bits		+/- ( 2.147483e+09 )
	integer		32bits		+/- ( 2.147483e+09 )
	short		16bits		+/- ( 32767 ) 
	byte		8bits		( 0 ) - ( 255 )

Non-numeric types

The graphic type is a reference to an instance of an HLU object. The file type is a reference to a file in a supported file format. The logical type is generated from relational expressions. Logical values are either True or False. Graphic values are returned by the create statement, HLU functions or the getvalues statement, and file values are returned by the addfile intrinsic function.

	string		N/A
	character	8bits
	graphic		N/A
	file		N/A
	logical		N/A

Coercion of types

Coercion is basically the implicit conversion of data from one data type to another. This occurs when two values of different types are operands to the same operator. Operands must be of a compatible type to perform the requested operation. For example, when a float value is multiplied by an integer value, the integer value can easily, without losing or corrupting the value, be converted to a float value. Because there is no loss of information, NCL does this automatically. The following table lists the automatic conversion possibilities for all of the basic types. The data types on the left side can automatically be converted to values of the types on the right side. If a coercion to a common type doesn't exist for both sides of an expression, then a type mismatch error is generated and the script will exit.

Coercion is discussed again in the section of this document covering expressions.

One very important item, which is covered in the functions and the procedures sections, has to do with how parameters work in functions and procedures. First, parameters in NCL are pass-by-reference, meaning that a change to the value of a parameter inside a function changes the value of a variable passed in to the function or procedure. This is important because when a parameter is expected to be a certain type, say float, and an integer variable is passed as the parameter, the integer parameter must be coerced to a float. Since there is no automatic conversion possible from float to integer, changes to the parameter within the function or procedure can not be propagated back to the calling variable. A warning message is given when this occurs.

	Type 		Coercible to

	character	string

	byte 		character
			string
			short
			integer
			long
			logical
			float
			double

	short 		character
			string
			integer
			long
			logical
			float
			double

	integer		string
			long
			logical
			float
			double

	long 		logical
			string
			float
			double

	float 		logical
			string
			double

	double		logical
			string

A special set of functions exists for forcing the coercion in the reverse direction. For example, the function doubletointeger can be used to convert a double precision number into an integer. This operation will cause the decimal portion to be truncated, and information will be lost. See NCL functions and procedures for other similar functions.

Creating data

There are three ways data can be created:

• By entering constant values.
• By using the new command to allocate space for a multi-dimensional value.
• By using functions like cbinread, fbinrecread, and addfile.

Constants and Arrays of constants

The following are examples of single scalar constant values:

Floating Point Constants:

	3.141592	1e-12	2.

Integer Constants:

	100	1

String Constants:

	"a"	"Hello World"

Arrays of constants can be constructed using the array designator characters "(/" and "/)" with constant values separated by commas. Multi-dimensional constant arrays can be created by nesting the array designator characters. The following are examples of constant arrays. Each example uses the assignment statement to assign the constant arrays to a variable.

1D Floating Point Constant Array:

	var0 = (/ 1.2, 2.3, 3.4, 4.5, 5.6, 6.7 /)

[2]x[6] 2D Floating Point Constant Array:

	var1 = (/ (/ 1.2, 2.3, 3.4, 4.5, 5.6, 6.7 /), (/ 7.8, 8.9, 9.1, 10.2, 11.3, 12.4/) /)

1D Integer Constant Array:

	var2 = (/ -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5 /)

1D String Constant Array:

	var3 = (/ "one", "two", "three", "four", "five" /)

Creating new data arrays

• Create an array of data with a specific missing value assigned to each element.
• Create the array of data using the default missing value.

The new statement takes, as parameters, an array of integer dimension sizes, the keyword for the data type, and optionally a missing value to assign to each element of the new data array. The following creates a [5]x[6]x[7] three-dimensional float array filled with the default missing value for float types and the attribute _FillValue is also set:

        a = new( (/ 5, 6, 7 /), float)
	print(a)


	Variable: a
	Type: float
	Total Size: 840 bytes
            	210 values
	Number of Dimensions: 3
	Dimensions and sizes:   [5] x [6] x [7]
	Coordinates: 
	Number Of Attributes: 1
  		_FillValue :  -999
	(0,0,0) -999
	(0,0,1) -999
	(0,0,2) -999
	 . . .

The default missing values are:

	logical   : -1
        byte      :  0377 (octal)
	short     : -99
	integer   : -999
	long	  : -9999
	float     : -999
	double    : -9999
	graphic   : -9999
	file      : -9999
 	character : 0 or '\0' for those who know C
	string    : "missing"

The following is an example of how to assign a specific missing value. The result is an array filled with -1e12 at every index.

        a = new( (/ 5, 6, 7 /), float, -1e12)

Importing data arrays and files

Another way to import data is to import from a supported file format. Supported file formats are specially recognized data formats that store variables and other information. Supported formats allow direct access to variables and other information in data files through NCL. This access is very different than the abovementioned methods of reading files. NCL has a special syntax for referencing variables in files that simplifies the importation of external data. The addfile function is used to open external files that are in a supported format. The addfile function returns a reference to a file that is used to access data within that file. This is all covered in the variables section of this reference guide.

For specific information on a supported file format, see the Supported data format information section of the reference guide. Currently, with version 4.1, these formats are CCM history tape, netCDF, GRIB, and HDF.

Reference Manual Control Panel

NG4.1 Home, Index, Examples, Glossary, Feedback, Ref Contents, Ref WhereAmI?