= Postprocessing with NCL - Usage of PALM NCL scripts =
[[TracNav(doc/app/datatoc|nocollapse)]]
== General == 
The standard output format of data in PALM is [[../netcdf|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'' [[http://www.ncl.ucar.edu/|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 [[source:palm/trunk/SCRIPTS/NCL|/trunk/SCRIPTS/NCL]] to receive a quick overview of the output data: 
* [[source:palm/trunk/SCRIPTS/NCL/cross_sections.ncl|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
* [[source:palm/trunk/SCRIPTS/NCL/profiles.ncl|profiles.ncl]]: profile line plots from profile or 3D data
* [[source:palm/trunk/SCRIPTS/NCL/spectra.ncl|spectra.ncl]]: NCL spectra plots from spectra data
* [[source:palm/trunk/SCRIPTS/NCL/timeseries.ncl|timeseries.ncl]]: line plots from timeseries data
* [[source:palm/trunk/SCRIPTS/NCL/.ncl.config.default|.ncl.config.default]]: default configuration file
The shell script [[source:palm/trunk/SCRIPTS/palmplot|palmplot]] is designed for running the NCL scripts interactively and can be found in [[source:palm/trunk/SCRIPTS|/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 [[../nclparlist|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 [[source:palm/trunk/SCRIPTS/NCL/.hluresfile|.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 [[http://www.ncl.ucar.edu/Document/Graphics/hlures.shtml|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 [[../nclparlist|parameters]] have to be written in {{{.ncl.config}}} according to the rules of the scripting language NCL (see [[http://www.ncl.ucar.edu/Document/Manuals/Ref_Manual/NclDataTypes.shtml|NCL data types]]). The configuration file contains all steering [[../nclparlist|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 ([[../nclparlist/#var|var]], [[../nclparlist/#c_var_pr|c_var]], [[../nclparlist/#vec1_cs|vec1]], [[../nclparlist/#vec2_cs|vec2]], [[../nclparlist/#plotvec_cs|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 [[../examples|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/)'
}}}
== 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” ).