Postprocessing with NCL script Palmplot

General

The standard output format of data in PALM is netCDF. PALM produces output of 3D volume data, 2D cross sections, profiles, timeseries and spectra. All these kinds of output can be plotted with the NCAR Command Language ​NCL which is an interpreted language designed specifically for scientific data analysis and visualization.

For PALM users four NCL scripts and one configuration file exist in the repository /trunk/SCRIPTS/NCL to receive a quick overview of the output data:

• cross_sections.ncl​: contour, isoline or vector plots (of a 2-dimensional vector) from 2D or 3D data; instantaneous or time-averaged xy, xz, yz or 3D data can be used
• profiles.ncl​: profile line plots from profile or 3D data
• spectra.ncl​: NCL spectra plots from spectra data
• timeseries.ncl​: line plots from timeseries data
• .ncl.config.default​: default configuration file

The shell script palmplot​ is designed for running the NCL scripts interactively and can be found in /trunk/SCRIPTS. The usage is as follows:

palmplot plot_identifier

plot_identifier has to be xy, xz, yz, pr, sp or ts in dependence on the data that is to be plotted:

plot_identifier	data	used ncl script
xy	instantaneous or time-averaged xy or 3D data	cross_sections.ncl
xz	instantaneous or time-averaged xz or 3D data	cross_sections.ncl
yz	instantaneous or time-averaged yz or 3D data	cross_sections.ncl
pr	profile or 3D data	profiles.ncl
sp	spectra data	spectra.ncl
ts	timeseries data	timeseries.ncl

Several parameters can be steered to change the output of the plots. They can be either written in the prompt, modified within the configuration file .ncl.config.default or both.

When the PALM NCL scripts are used for the first time, the .hluresfile​ is copied to the home directory. It changes NCL's default graphical display and enlarges the height and width of the default x11 window. This file can also be modified to change other default settings. Further information are available ​here.

Using .ncl.config

It is recommended to create a personal configuration file by copying the default configuration file .ncl.config.default to the PALM working directory ~/palm/current_version and naming it .ncl.config. It is used by NCL directly. So, the parameters have to be written in .ncl.config according to the rules of the scripting language NCL (see ​NCL data types). The configuration file contains all steering parameters with a short description and can be modified to personal needs.

Using palmplot

For controlling the parameters within the prompt, they need to be written as

palmplot plot_identifier parameter=value parameter=string

It is necessary to set the string parameters which can contain lists (var, c_var, vec1, vec2, plotvec) in single quotes. The list itself has to be separated by blanks.
Example: var='pt u w*pt* w”pt”' or c_var='v w' or var='E*'

Setting of parameters in the configuration file .ncl.config will be ignored if parameters are specified in the prompt.

A short introduction for using the shell script is given by using

palmplot ?  

Examples

In the following some examples are given for plotting data of the PALM example run example_cbl.
Change to the directory where the data is stored:

cd ~/palm/current_version/JOBS/example_cbl/OUTPUT

Enter the following commands:
Plotting xy-cross section data:

palmplot xy file_1=example_cbl_xy.nc var='pt_xy'

Plotting profile data:

palmplot pr file_1=example_cbl_pr.nc format_out=eps file_out=pr_data var='pt w”pt” w*2'

Plotting timeseries data:

palmplot ts file_1=example_cbl_ts.nc format_out=pdf file_out=ts_data no_rows=6

Plotting spectra data:

palmplot sp file_1=example_cbl_sp.nc no_rows=2 no_columns=2 height_level='(/0,1/)'

In case that a run with topography (see topography) was carried out, it is also possible to plot the arrays zusi and zwwi which contain the topography information. Assume a run example_topo and the command could be:

palmplot xy file_1=example_topo_xy.nc var='zusi zwwi'

Script crash

If one of the scripts aborts and there is no comment, check your personal configuration file .ncl.config - the scripts should not abort with the default values. Be sure to use the right NCL data type (e.g.: integer = 2; float = 2.0; double = 2.0d; string = “name” ).

List of parameters for Palmplot

The following lists give an overview of all existing parameters to steer palmplot, the PALM NCL scripts. Further descriptions can be found in the configuration file .ncl.config.default​.
Most parameters are allocated with a suitable default value in the configuration file but some need to be changed before running any script. These variables are file_1 and if available file_2, ..., up to file_6. In case of a job chain without extended output files, the scripts will automatically read all necessary files after indicating the first and the last cyclic number (see start_f and end_f).

The parameters are arranged in five different lists:

• Parameters which are common for all four scripts
• Parameters for plotting cross sections
• Parameters for plotting profiles
• Parameters for plotting spectra
• Parameters for plotting timeseries

The following abbreviations for the NCL types are used in the lists:

Abbr.	Explanation	Example
D	double	2.0d
F	float	2.0
I	integer	2
S	string	"name"

The following abbreviations for the NCL scripts are used in the lists:

Abbr.	Explanation
CS	cross sections
PR	profiles
SP	spectra
TS	timeseries

Common parameters

Parameter Name	NCL Type	Default Value	Explanation
end_f	I	-1	Last cyclic number of data from a job chain that shall be used for input. Setting of end_f \= -1 is only useful when more than one file of a job chain exists. First cyclic number can be set with the parameter start_f.
end_time_step	D	-1.0d (last avail- able time step)	Last time step in hour. First time step can be set with start_time_step.
file_1	S	"File in"	Path and name of the input file. If there is more than one file for all time steps of a job chain, declare path and file name without cycle number and ".nc" (e.g. file_1='~/palm/current_version/JOBS/example_cbl/OUTPUT/example_cbl_pr'). First and last cycle numbers are given with the parameters start_f and end_f, otherwise declare path and full file name (e.g. file_1='~/palm/current_version/JOBS/example_cbl/OUTPUT/example_cbl_pr.nc' ).
file_config	S	"$PALM_BIN/../../.ncl.config" or "$PALM_BIN/NCL/.ncl.config.default"	Path and name of the NCL configuration file. If this parameter is omitted, palmplot will first try to load $PALM_BIN/../../.ncl.config. If that file does not exist, palmplot tries to load the default configuration file $PALM_BIN/NCL/.ncl.config.default.
file_out	S	"~/test_**"	Path and name of the output file. The output format of the file can be chosen with format_out.
font_size	F	0.04 (CS) 0.02 (PR+SP) 0.07 (TS)	Font size of the strings in the plots in height of ​NDC coordinates.
format_out	S	"x11"	Format of the output file. Supported file formats are: x11, pdf, ps, eps, epsi ncgm or png. The name and path of the output file can be chosen with file_out.
no_columns	I	1 except for profiles	Number of plots in one row. Number of plots in one columns can be set with no_rows.
no_rows	I	2 except for profiles	Number of plots in one column. Number of plots in one row can be set with no_columns.
start_f	I	-1	First cyclic number of data from a job chain that shall be used for input. Setting of start_f \= -1 is only useful when more than one file of a job chain exists. Last cyclic number can be set with the parameter end_f.
start_time_step	D	-1.0d (first avail- able time step)	First time step in hour. Last time step can be set with end_time_step.
var	S	"all"	Names of variables in the input file that shall be output. For output of u, v and w"pt" use var = 'u v w"pt"' in the prompt or var = ",u,v,w"+dq+"pt"+dq in .ncl.config.

Parameters for plotting cross sections

Parameter Name	NCL Type	Default Value	Explanation
axes_explicit	I	0	Explicit setting of the axes is switched of with axes_explicit = 0 and can be switched on by using the value axes_explicit = 1. When switched on, the parameters major_ticks_x, major_ticks_y, norm_x, norm_y, norm_z, unit_x, unit_y and unit_z can be set.
fill_mode	S	"RasterFill"	Type of filling of the contour plots. Further possibilities are fill_mode = "AreaFill" and fill_mode = "CellFill". In case of a large data set, setting of fill_mode = "AreaFill" leads to a long execution time of the script.
font_size_legend	F	0.04	Font size of legend strings in height of ​NDC coordinates.
legend_label_stride	I	2	With legend_label_stride = 2 every second label is displayed.
major_ticks_x	I	6	Setting of major_ticks_x is only used if axes_explicit = 1 and indicates the number of major tick marks at the x-axis.
major_ticks_y	I	6	Setting of major_ticks_y is only used if axes_explicit = 1 and indicates the number of major tick marks at the y-axis.
mode	S	"Fill"	Type of plot. mode = "Fill" leads to contour plots, mode = "Line" results in an isoline plot and mode = "Both" is a combination of the aforementioned types.
norm_x	F	1.0	Setting of norm_x is only possible if axes_explicit = 1 and normalizes the x-axis with the given value. norm_x = 1.0 results in no normalization. The resulting unit of the axis can be set explicitly with unit_x.
norm_y	F	1.0	Setting of norm_y is only possible if axes_explicit = 1 and normalizes the y-axis with the given value. norm_y = 1.0 results in no normalization. The resulting unit of the axis can be set explicitly with unit_y.
norm_z	F	1.0	Setting of norm_z is only possible if axes_explicit = 1 and normalizes the z-axis with the given value. norm_z = 1.0 results in no normalization. The resulting unit of the axis can be set explicitly with unit_z.
plotvec	S	"plotvec"	Setting of plotvec is only possible if the vector plot is switched on: vector = 1. plotvec can contain a list of variables on which the vector plot shall be overlaid. For example, if the vector plot shall be overlaid to pt and w, use plotvec = 'pt w' in the prompt and plotvec=",pt,w," in .ncl.config.
ref_mag	F	0.05	Length of the reference vector in a vector plot in height of ​NDC coordinates. Setting is only possible with vector plot switched on: vector = 1
shape_cs	I	1	Aspect ratio of the plot is kept with shape = 1 and not kept with shape = 0.
sort	string	"layer"	Type of the sorting of the plots. If sort = "layer" the plots are sorted by height and if sort = "time" the plots are sorted by time.
unit_x	S	" "	Setting of unit_x is only possible if axes_explicit = 1 and useful if a normalization of the axis is used (see norm_x). The default unit is meter.
unit_y	S	" "	Setting of unit_y is only possible if axes_explicit = 1 and useful if a normalization of the axis is used (see norm_y). The default unit is meter.
unit_z	S	" "	Setting of unit_z is only possible if axes_explicit = 1 and useful if a normalization of the axis is used (see norm_z). The default unit is meter.
vector	I	0	By default, no vector plots are produced with vector = 0. Vector plots can be switched on with vector = 1. Then, the setting of the components for the vector plot is required. A plot of horizontal wind vectors can be achieved by vec1='u' in the prompt and vec1=",u," in .ncl.config and vec2='v' or vec2=",v,". Further on, the vector plot can be overlaid on other plots by using plotvec.
vec1	S	"component1"	First component for the vector plot. Setting is only possible with vector plot switched on: vector = 1. By using vec1='u' in the prompt and vec1=",u," in .ncl.config for example, the first component of the vector plot is the wind component in x-direction.
vec2	S	"component2"	Second component for the vector plot. Setting is only possible with vector plot switched on: vector = 1. By using vec2='w' in the prompt and vec2=",w," in .ncl.config for example, the second component of the vector plot is the wind component in z-direction.
xe	D	-1.0d (last avail- able value)	Value for maximum of the x-axis which is only selectable if there are no preset layers for x. The value has to be given in meter which is rounded internally to the next existent grid point on the file. The minimum value of the x-axis can be set with xs.
xs	D	-1.0d (first avail- able value)	Value for minimum of the x-axis which is only selectable if there are no preset layers for x. The value has to be given in meter which is rounded internally to the next existent grid point on the file. The maximum value of the x-axis can be set with xe.
ye	D	-1.0d (last avail- able value)	Value for maximum of the y-axis which is only selectable if there are no preset layers for y. The value has to be given in meter which is rounded internally to the next existent grid point on the file. The minimum value of the y-axis can be set with ys.
ys	D	-1.0d (first avail- able value)	Value for minimum of the y-axis which is only selectable if there are no preset layers for y. The value has to be given in meter which is rounded internally to the next existent grid point on the file. The maximum value of the x-axis can be set with ye.
ze	D	-1 (last avail- able value)	Value for maximum of the z-axis which is only selectable if there are no preset layers for z. The value has to be given as index value of the vertical grid due to possible grid stretching. The minimum value of the z-axis can be set with zs.
zs	D	-1 (first avail- able value)	Value for minimum of the z-axis which is only selectable if there are no preset layers for z. The value has to be given as index value of the vertical grid due to possible grid stretching. The maximum value of the z-axis can be set with ze.

Parameters for plotting profiles

Parameter Name	NCL Type	Default Value	Explanation
black	I	0	The default setting black = 0 leads to colored lines in the plot and black = 1 results in black and white plots.
combine	I	0	Combining of several individual variables in one plot is switched on with combine = 1. The number of combined variables has to be set in number_comb. And the variables have to be specified in c_var.
c_var	S	"c_variables"	List of variables that shall be plotted in a combined plot. This setting is only available when combine = 1. The list must contain number_comb entries. If a combination of u,v and w is desired, set c_var = 'u v w' in the prompt or c_var = ",u,v,w," in .ncl.config.
dash	I	0	The use of dashed lines in the plots can be switched on with dash = 1. The default dash = 0 leads to continuous lines.
end_f_2	I	-1	end_f_2 is only used when no_files > 1 and denotes the last cyclic number of data from a job chain that shall be used for input of file_2. Setting of end_f_2 \= -1 is only useful when more than one file of a job chain exists. The first cyclic number can be set with the parameter start_f_2.
. . .	. . .	. . .	. . .
end_f_6	I	-1	end_f_6 is only used when no_files > 1 and denotes the last cyclic number of data from a job chain that shall be used for input of file_6. Setting of end_f_6 \= -1 is only useful when more than one file of a job chain exists. The first cyclic number can be set with the parameter start_f_6.
end_x	I	-1	If 3D data (DATA_3D_NETCDF or DATA_3D_AV_NETCDF) is used as input, end_x denotes the last grid point which is included in averaging along the x-axis in grid points. The default end_x = -1 uses all grid points in x-direction for averaging. The first grid point for averaging can be set via start_x.
end_y	I	-1	If 3D data (DATA_3D_NETCDF or DATA_3D_AV_NETCDF) is used as input, end_y denotes the last grid point which is included in averaging along the y-axis in grid points. The default end_y = -1 uses all grid points in y-direction for averaging. The first grid point for averaging can be set via start_y.
file_2	S	"File in"	Path and name of the second input file. Declaring of file_2 is only allowed if no_files > 1. If there is more than one file for all time steps of a job chain, declare path and file name without cycle number and ".nc" (e.g. file_2='~/palm/current_version/JOBS/example_cbl/OUTPUT/example_cbl_pr'). First and last cycle numbers are given with the parameters start_f and end_f, otherwise declare path and full file name (e.g. file_2='~/palm/current_version/JOBS/example_cbl/OUTPUT/example_cbl_pr.nc' ).
. . .	. . .	. . .	. . .
file_6	S	"File in"	Path and name of the sixth input file. Declaring of file_6 is only allowed if no_files > 1. If there is more than one file for all time steps of a job chain, declare path and file name without cycle number and ".nc" (e.g. file_6='~/palm/current_version/JOBS/example_cbl/OUTPUT/example_cbl_pr'). First and last cycle numbers are given with the parameters start_f and end_f, otherwise declare path and full file name (e.g. file_6='~/palm/current_version/JOBS/example_cbl/OUTPUT/example_cbl_pr.nc' ).
font_size_legend	F	0.02	Font size of legend strings in height of ​NDC coordinates.
log_z	I	0	A logarithmic scaling of the z-axis can be switched on with log_z = 1. The default setting log_z = 0 results in a linear z-axis.
max_z	D	-1.0d	Value for maximum of the z-axis. The value has to be given in meter which is rounded internally to the next existent grid point on the file. The default value max_z = -1.0d uses the last available grid point. The minimum value of the z-axis can be set with min_z.
min_z	D	-1.0d	Value for minimum of the z-axis. The value has to be given in meter which is rounded internally to the next existent grid point on the file. The default value min_z = -1.0d uses the first available grid point. The maximum value of the z-axis can be set with max_z.
name_legend_1	S	"File 1"	Label for the first item corresponding to the first input file which is placed in an extra legend (see also no_files). Declaring of name_legend_1 is only allowed if no_files > 1.
. . .	. . .	. . .	. . .
name_legend_6	S	"File 6"	Label for the sixth item corresponding to the sixth input file which is placed in an extra legend (see also no_files). Declaring of name_legend_6 is only allowed if no_files > 1.
no_columns	I	-1	If no_columns=-1, profile_columns will be used.
no_rows	I	-1	If no_rows=-1, profile_rows will be used.
no_files	I	1	The number of different files which shall be plotted together is set via no_files. Not more than six different files can be used. All the files must contain the same variables and dimensionality and identical variables are merged in one plot. The path and name of the additional files is set with the parameters file_2, ..., file_6. It is also possible to use files of a job chain which can be declared with start_f_2, ..., start_f_6 and end_f_2, ... , end_f_6. It is not possible to combine variables: combine is automatically switched off. Further on, the overlaying of predefined variables is also not possible: over = 0.
norm_z	F	1.0	The z-axis is normalized with the given value. By default, no normalizing occurs.
number_comb	I	-1	The number of variables for combining is given with number_comb. The maximum number of combined variables is 3. Consequently, only number_comb = 2 or number_comb = 3 are valid values. Overall, the setting of number_comb is only possible if combine = 1.
over	I	0	The predefined overlaying of special variables can be switched on with over = 1. But this feature can not be used if the input file contains output for statistic regions. The default over = 0 results in no overlaying.
start_f_2	I	-1	start_f_2 is only used when no_files > 1 and denotes the first cyclic number of data from a job chain that shall be used for input of file_2. Setting of start_f_2 \= -1 is only useful when more than one file of a job chain exists. The last cyclic number can be set with the parameter end_f_2.
. . .	. . .	. . .	. . .
start_f_6	I	-1	start_f_6 is only used when no_files > 1 and denotes the first cyclic number of data from a job chain that shall be used for input of file_6. Setting of start_f_6 \= -1 is only useful when more than one file of a job chain exists. The last cyclic number can be set with the parameter end_f_6.
start_x	I	0	If 3D data (DATA_3D_NETCDF or DATA_3D_AV_NETCDF) is used as input, start_x denotes the first grid point which is included in averaging along the x-axis in grid points. The default start_x = 0 uses the first available grid point in x-direction for averaging. The last grid point for averaging can be set via end_x.
start_y	I	0	If 3D data (DATA_3D_NETCDF or DATA_3D_AV_NETCDF) is used as input, start_y denotes the first grid point which is included in averaging along the y-axis in grid points. The default start_y = 0 uses the first available grid point in y-direction for averaging. The last grid point for averaging can be set via end_y.
time_stride	I	1	time_stride denotes the temporal stride for the plot. If time_stride = 1 all the profiles between start_time_step and end_time_step are plotted (including start_time_step and end_time_step). If time_stride = 3 every third time step between start_time_step and end_time_step is plotted.
var	S	"cross_profiles"	If var = "cross_profiles", all profiles are plotted as defined in cross_profiles. If var = "all", each profile will be plotted solitary (this is recommended for plotting a high amount of profiles).
xe	F	-1.0	Value for maximum of the x-axis in the plot. When the default value xe = -1.0 is used the maximum value of the data is taken. The minimum value of the x-axis can be set with xs.
xs	F	-1.0	Value for minimum of the x-axis in the plot. When the default value xs = -1.0 is used the minimum value of the data is taken. The maximum value of the x-axis can be set with xe.

Parameters for plotting spectra

Parameter Name	NCL Type	Default Value	Explanation
black	I	0	The default setting black = 0 leads to colored lines in the plot and black = 1 results in black and white plots.
dash	I	0	The use of dashed lines in the plots can be switched on with dash = 1. The default dash = 0 leads to continuous lines.
font_size_legend	F	0.02	Font size of legend strings in height of ​NDC coordinates.
height_level	I(0:99)	-1	The default height_level = -1 leads to the plot of all the height levels which are in the file. A sample of several height levels can be chosen by height_level = (/0,3,5/) for example. In this case, the first, fourth and sixth height level in the file are taken. Note that the height levels have to be given as indices and that the first index of an array is 0 in NCL.
log_x	I	1	The logarithmic scaling of the x-axis can be switched off with log_x = 0. The default setting log_x = 1 results in a logarithmic x-axis.
log_y	I	1	The logarithmic scaling of the y-axis can be switched off with log_y = 0. The default setting log_y = 1 results in a logarithmic y-axis.
norm_height	I	0	The x-axis can be normalized with the height of each spectrum with the setting norm_height = 1. The default setting norm_height = 0 leads to no normalizing.
norm_x	F	1.0	The setting of norm_x normalizes the x-axis with the assigned value, for example norm_x = 10.0. The unit of the x-axis can then be set appropriately with unit_x.
norm_y	F	1.0	The setting of norm_y normalizes the y-axis with the assigned value, for example norm_y = 10.0. The unit of the y-axis can then be set appropriately with unit_y.
sort	S	"height"	sort = "height" leads to plots in which all the height levels are merged. The other possibility is sort = "time". Then, all time steps are merged in one plot.
unit_x	S	" "	The unit of the x-axis can be set with unit_x if norm_x is set unequal to 1.0. The default unit on the x-axis is 1/m.
unit_y	S	" "	The unit of the y-axis can be set with unit_y. By default no unit is set for the y-axis.

Parameters for plotting timeseries

Parameter Name	NCL Type	Default Value	Explanation
norm_t	F	1.0	The setting of norm_t normalizes the x-axis (time) with the assigned value, for example norm_t = 3600.0. The unit of the x-axis can then be set appropriately with unit_t. The default setting leads to no normalization.
over	I	0	The predefined overlaying of special variables can be switched on with over = 1. But this feature can not be used if the input file contains output for statistic regions. The default over = 0 results in no overlaying.
unit_t	S	" "	The unit of the x-axis (time) can be set with unit_t if norm_t is set unequal to 1.0. The default unit on the x-axis is s.