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.
NCL command line options
The following is a list of the predefined options and what they do:
-f Use new file structure and NetCDF4 features when possible -h Print this message and exit -n Don't enumerate values in print() -o Retain former behavior for certain backwards-incompatible changes -p Don't page output from the system() command -P Enable NCL profiler -s Disable pre-loading of default script files -Q Turn off echo of NCL version and copyright info -V Print NCL version and exit-h
Displays a list of command line options available, with a brief description of what each option does.
% ncl -h Usage: ncl -fhnopxsPQV-f: use new file structure and NetCDF4 features when possible -h: print this message and exit -n: don't enumerate values in print() -o: retain former behavior for certain backwards-incompatible changes -p: don't page output from the system() command -P: enable NCL profiler -s: disable pre-loading of default script files -x: echo NCL commands -Q: turn off echo of NCL version and copyright info -V: print NCL version and exit
-n
Turns off enumeration of the dimensions of a variable when using the print function. The default behavior is to display the dimensions in parentheses before the value:
% ncl -n
Copyright (C) 1995-2018 - All Rights Reserved
University Corporation for Atmospheric Research
NCAR Command Language Version 6.5.0
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)
Output:
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
-pTurns 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).
-P
Enables NCL profiler (NCL V6.5.0 and later).
-s
Disables pre-loading of default script files By default, NCL preloads many scripts automatically (gsn_code.ncl, gsn_csm.ncl, contributed.ncl, etc). Use this option if you don't want this behavior. Note: it's okay to preload scripts even if they are loaded by NCL automatically, however, a little more memory may be used if you do this.
-x
Echos each NCL statement as it is encountered. It can be particularly useful when debugging NCL scripts in batch mode, where it may be used as ncl -x script.ncl. Any code that is enclosed with "begin" and "end" will be echoed as one block, however, so in your main code, you may want to temporarily comment these out before using this option.
The following illustrates the effect of the -x option using interactive mode.
% ncl -x Copyright (C) 1995-2018 - All Rights Reserved University Corporation for Atmospheric Research NCAR Command Language Version 6.5.0 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.
-Q
Turns off all the copyright, license, and version header that gets echoed when you run NCL.
-V
Prints the version of NCL you are running and exits. If this option is found anywhere on the command line, its behavior takes precedence over other options and arguments. If you need to get the version of NCL from within the script, use the get_ncl_version function.
% ncl -V 6.5.0
NCL command line arguments
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-2018 - All Rights Reserved
University Corporation for Atmospheric Research
NCAR Command Language Version 6.5.0
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-2018 - All Rights Reserved
University Corporation for Atmospheric Research
NCAR Command Language Version 6.5.0
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-2018 - All Rights Reserved
University Corporation for Atmospheric Research
NCAR Command Language Version 6.5.0
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-2018 - All Rights Reserved
University Corporation for Atmospheric Research
NCAR Command Language Version 6.5.0
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-2018 - All Rights Reserved
University Corporation for Atmospheric Research
NCAR Command Language Version 6.5.0
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-2018 - All Rights Reserved
University Corporation for Atmospheric Research
NCAR Command Language Version 6.5.0
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-2018 - All Rights Reserved
University Corporation for Atmospheric Research
NCAR Command Language Version 6.5.0
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.nclWhen 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