NCL Home > Documentation > Manuals > Reference

NCL command line options and arguments

NCL supports a limited number of options at the command line, and also arguments -- the setting and execution of simple NCL statements, in either interactive or batch mode.

The following is a list of the predefined options and what they do:

  -h    Display command line options usage
  -n    Don't enumerate values in print()
  -p    Don't use a pager program to display output from NCL's system() command
  -x    Echo NCL statements as encountered
  -V    Print the NCL version and exit

The -h option displays command line options available, with a brief description of what each option does.

% ncl -h
Usage: ncl -hnpxV  
         -n: don't enumerate values in print()
         -p: don't page output from the system() command
         -x: echo NCL commands
         -V: print NCL version and exit
         -h: print this message and exit

The -n option turns off enumeration of the dimensions of a variable when using the print function. The default behavior displays the dimensions.

% ncl -n
 Copyright (C) 1995-2005 - All Rights Reserved
 University Corporation for Atmospheric Research
 NCAR Command Language Version 4.2.0.a033
 The use of this software is governed by a License Agreement.
 See http://www.ncl.ucar.edu/ for more details.
ncl 0> f = addfile("T2m.nc", "r")
ncl 1> T = f->T
ncl 2> print(T)

The above yields

   Variable: T
   Type: float
   Total Size: 72192 bytes
               18048 values
   Number of Dimensions: 3
   Dimensions and sizes:   [time | 1] x [lat | 94] x [lon | 192]
   Coordinates: 
               time: [197901..197901]
               lat: [-88.54195..88.54195]
               lon: [ 0..358.125]
   Number Of Attributes: 4
     units :       K
     short_name :  T2m
     long_name :   Temperature (2m)
     _FillValue :  1e+36
   255.49
   255.44
   255.39
   255.34
   255.3
        [...]
   234.23
   234.16
   234.09
   234.02
   233.95
   233.88

The -p option turns off paging of output from NCL's system command. By default, the system pages output for user convenience. It can be particularly useful to turn this off when running commands in the shell in the background (without waiting for those commands to complete). This option will be available in the next release of NCL.

The -x option will echo NCL statements as they are encountered. It can be particularly useful when debugging NCL scripts in batch mode, where it may be used as ncl -x script.ncl.

The following illustrates the effect of the -x option using interactive mode.

% ncl -x
 Copyright (C) 1995-2005 - All Rights Reserved
 University Corporation for Atmospheric Research
 NCAR Command Language Version 4.2.0.a033
 The use of this software is governed by a License Agreement.
 See http://www.ncl.ucar.edu/ for more details.
ncl 0> a = 5
+ a = 5
ncl 1> exit
+ exit

Echoing of NCL statements can also be achieved by using the built-in functions echo_on and echo_off.

The -V option will print the version of NCL you are running, and exit. If this option is found anywhere on the command line, its behavior takes precedence over other options and also arguments.

% ncl -V
4.2.0.a033

Arguments are simple NCL statements to set variables. An argument is defined as an assignment, using the "=" character, with no spaces on either side of the equal sign, similar to variable assignment within NCL.

% ncl nyrStrt=1900 nyrLast=2004
 Copyright (C) 1995-2005 - All Rights Reserved
 University Corporation for Atmospheric Research
 NCAR Command Language Version 4.2.0.a033
 The use of this software is governed by a License Agreement.
 See http://www.ncl.ucar.edu/ for more details.
ncl 0> print(nyrStrt)

Variable: nyrStrt
Type: integer
Total Size: 4 bytes
            1 values
Number of Dimensions: 1
Dimensions and sizes:   [1]
Coordinates: 
(0)     1900

Take care to protect characters that the user shell considers special, such as double quotes, parentheses, exclamation points, and the like. To protect such characters from being interpreted by the shell before being interpreted by NCL, use single quotes (') around statements. This allows attributes to be assigned on the command line:

% ncl nyrStrt=1930 'nyrStrt@long_name="Model Run Begin Year"' 'nyrStrt@units="Years"'
 Copyright (C) 1995-2005 - All Rights Reserved
 University Corporation for Atmospheric Research
 NCAR Command Language Version 4.2.0.a033
 The use of this software is governed by a License Agreement.
 See http://www.ncl.ucar.edu/ for more details.
ncl 0> print(nyrStrt)

Variable: nyrStrt
Type: integer
Total Size: 4 bytes
            1 values
Number of Dimensions: 1
Dimensions and sizes:   [1]
Coordinates: 
Number Of Attributes: 2
  units :       Years
  long_name :   Model Run Begin Year
(0)     1930

Some characters special to the shell must be escaped -- that is, have their meaning to the shell rendered meaningless, with a backslash (\) character. Such special characters may be shell-dependent; this is particularly true of the exclamation point character, which is used to define a named dimension. If you are using the C-Shell derivative (csh, tcsh), you must escape the exclamation point.

% echo $SHELL
/bin/tcsh

% ncl nyrStrt=1930 'nyrStrt@long_name="Model Run Begin Year"' 'nyrStrt@units="Years"' 'nyrStrt\!0="Time"'
 Copyright (C) 1995-2005 - All Rights Reserved
 University Corporation for Atmospheric Research
 NCAR Command Language Version 4.2.0.a033
 The use of this software is governed by a License Agreement.
 See http://www.ncl.ucar.edu/ for more details.
ncl 0> print(nyrStrt)

Variable: nyrStrt
Type: integer
Total Size: 4 bytes
            1 values
Number of Dimensions: 1
Dimensions and sizes:   [Time | 1]
Coordinates: 
Number Of Attributes: 2
  units :       Years
  long_name :   Model Run Begin Year
(0)     1930

If you are using a Bourne-Shell derivative (sh, ksh, bash), simply enclosing statements with single quotes (') is sufficient.

% echo $SHELL
/bin/bash

% ncl nyrStrt=1930 'nyrStrt@long_name="Model Run Begin Year"' 'nyrStrt@units="Years"' 'nyrStrt!0="Time"'
 Copyright (C) 1995-2005 - All Rights Reserved
 University Corporation for Atmospheric Research
 NCAR Command Language Version 4.2.0.a033
 The use of this software is governed by a License Agreement.
 See http://www.ncl.ucar.edu/ for more details.
ncl 0> print(nyrStrt)

Variable: nyrStrt
Type: integer
Total Size: 4 bytes
            1 values
Number of Dimensions: 1
Dimensions and sizes:   [Time | 1]
Coordinates: 
Number Of Attributes: 2
  units :       Years
  long_name :   Model Run Begin Year
(0)     1930

Arrays can be easily defined on the command line:

% ncl 'modelYears=(/1900, 1920, 1940, 1960, 1980, 2000/)'
 Copyright (C) 1995-2005 - All Rights Reserved
 University Corporation for Atmospheric Research
 NCAR Command Language Version 4.2.0.a033
 The use of this software is governed by a License Agreement.
 See http://www.ncl.ucar.edu/ for more details.
ncl 0> print(modelYears)

Variable: modelYears
Type: integer
Total Size: 24 bytes
            6 values
Number of Dimensions: 1
Dimensions and sizes:   [6]
Coordinates: 
(0)     1900
(1)     1920
(2)     1940
(3)     1960
(4)     1980
(5)     2000

NCL functions can be executed via command line arguments. Given the potentially complex calling sequence of some functions and protecting special characters from the shell, calling some NCL functions from the command line may be tedious.

% ncl 'dataFile=addfile("./modelData.nc", "r")'
 Copyright (C) 1995-2005 - All Rights Reserved
 University Corporation for Atmospheric Research
 NCAR Command Language Version 4.2.0.a033
 The use of this software is governed by a License Agreement.
 See http://www.ncl.ucar.edu/ for more details.
ncl 0> print(dataFile)
Variable: dataFile (file variable)

filename:       modelData
path:   /ptmp/model/data/modelData.nc
   file global attributes:
      title : Model Data netcdf
      [...]

% ncl 'initConditions=ispan(/0, 100, 20/)'
 Copyright (C) 1995-2005 - All Rights Reserved
 University Corporation for Atmospheric Research
 NCAR Command Language Version 4.2.0.a033
 The use of this software is governed by a License Agreement.
 See http://www.ncl.ucar.edu/ for more details.
ncl 0> print(initConditions)

Variable: initConditions
Type: integer
Total Size: 24 bytes
            6 values
Number of Dimensions: 1
Dimensions and sizes:   [6]
Coordinates: 
(0)     0
(1)     20
(2)     40
(3)     60
(4)     80
(5)     100

When used in conjunction with an NCL script, command line arguments can set a variable's value, help determine initial conditions, and so forth:

% cat modelRun.ncl
begin
  [...]

  if (.not. isvar("nyrStrt")) then      ; is nyrStrt on command line?
      nyrSrt = 1960
  end if

  if (.not. isvar("nyrLast")) then      ; is nyrLast on command line?
      nyrLast = 2002;
  end if

  print(nyrStrt)                        ; for illustrative purposes
  print(nyrLast)

  [...]
end

(Variables nyrStrt and nyrLast are set on the command line)

% ncl nyrStrt=1900 nyrLast=1968 modelRun.ncl

Variable: nyrStrt
Type: integer
Total Size: 4 bytes
            1 values
Number of Dimensions: 1
Dimensions and sizes:   [1]
Coordinates: 
(0)     1900


Variable: nyrStrt
Type: integer
Total Size: 4 bytes
            1 values
Number of Dimensions: 1
Dimensions and sizes:   [1]
Coordinates: 
(0)     1968

Consider the following

ncl nyrStrt=1930 'fName="Model*"' gravity=9.8 opt=True cyclic=False latS=-30 latN=30 lonL=130 lonR=290 modelRun.ncl

When the number of CLOs is large, it might be clearer to enter only one or two per line. The Unix line continuation character, \, can be used to accomplish this:

 ncl nyrStrt=1930      \ 
     'fName="Model*"'  \
     gravity=9.8       \
     latS=-30 latN=30  \
     lonL=130 lonR=290 \
     modelRun.ncl