<!--Copyright (C) 1988-2005 by the Institute of Global Environment and Society (IGES). See file COPYRIGHT for more information.--><style type="text/css">
<!--
body {
	background-color: #e0f0ff;
}
.style2 {color: #990000}
-->
</style>

<h1>Grads Variables</h1>
<ul>
<a href=variable.html#names>Variable Names</a><br>
<a href=variable.html#new>Defining New Variables</a><br>
<a href=variable.html#undefine>Undefining Variables</a><br>
</ul>
<p>
<h2><a name="names">Variable names</a></h2>
The complete specification for a variable name is:

<ul>
  <p><code>abbrev.file#(dimexpr,dimexpr,...)</code>&nbsp;&nbsp;&nbsp; where: </p>

  <ul>
    <code>abbrev&nbsp;&nbsp;&nbsp;</code>is the abbreviation for the variable as
    specified in the
    data descriptor file
    <br />
    <code>file#&nbsp;&nbsp;&nbsp;&nbsp;</code>is the file number that contains
      this variable.  If <code>file#</code> is absent, GrADS assumes the default file number. <br />
      <code>dimexpr&nbsp;&nbsp;</code>is a dimension expression that locally
      modifies the current dimension environment.
</ul>
</ul>
<p>

The <code>dimexpr</code> is used to override or modify the current dimension environment only for the <code>abbrev</code> variable. Only fixed dimensions can be
modified with a <code>dimexpr</code>. The <code>dimexpr</code> can be given in grid or world coordinates. <b>An important note:</b> When you specify a dimension in grid units,
GrADS always converts it to world coordinates.  In general, this conversion
is done using the scaling of the <i>default file</i>. The only exception to this rule is in this case, when  a
grid coordinate (x, y, z, t, or e) is supplied within a <code>dimexpr</code> as part of a variable specification. In the case of this special exception, the conversion is done using the scaling for
 the file that variable is to be taken from (i.e., file number <code>file#</code>).
<p>An absolute <code>dimexpr</code> uses the &quot;=&quot; operator to override the currently set dimension value:

<br />
<code>&nbsp; x|y|z|t|e|lon|lat|lev|time|ens = value</code>
<br />
Examples of absolute dimension expressions are:<code> x=1, lat=-10, lev=500, t=1, time=02feb1982, e=1, ens=spr</code>
<p>A relative <code>dimexpr</code> uses the &quot;+&quot; or &quot;-&quot; operators to modify the currently set dimension value with an offset: <br />
<code>&nbsp;  x|y|z|t|e|lon|lat|lev|time|ens +/- offset<br />
</code>

Examples of relative dimension expressions are:<code> x+1, lat+30, y-3, t+0, time+12hr</code>
<p>Starting with <span class="style2">GrADS version 2.0.a7</span>, a third option is available, a  <code>dimexpr</code> that specifies an offset
  from the variable's initial time: <br />
  <code>&nbsp;  offt =/+/- offset<br />
  </code> Examples of absolute offset dimension expressions are:<code> offt=0, offt+4, offt-1</code> <br />
  Please consult the section on <a href="offt.html">evaluating expressions that contain the <code>offt</code> dimension override</a> for additional information. <br />
<p>The following sets of commands will yeild the same result, which is to display the 2nd time step of a variable &quot;ps&quot;: <br />
  <code>
&nbsp;&nbsp;'set t 2'; 'd ps'<br />
&nbsp;&nbsp;'set t 1'; 'd ps(t+1)'<br />
&nbsp;&nbsp;'set t 1'; 'd ps(t=2)'<br />
&nbsp;&nbsp;'set t 1'; 'd ps(offt=1)'<br />
&nbsp;&nbsp;'set t 1'; 'd ps(offt+0)'<br />
    </code>Note that an offset of 0 returns the 1st time step, an offset of 1 returns the 2nd time step, etc. 
<p>Using a <code>dimexpr</code> that contains <code>offt</code> is especially handy when your data set has multiple <a href="ensembles.html">ensemble members</a>, and the start time for individual members is not the same. In that case, an expression like:<br /> 
  <code>&nbsp;&nbsp;'set t 1'; 'set e 1 last'; 'd ps(offt=0)'</code> <br />
  will give you the first time step of all ensemble members, which may occur at different time steps in the file. 
  
  
<p>Examples of complete variable specifications are:
<ul>
<code>z.3(lev=500)</code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
File 3, absolute dimension 
expression<br>
<code>tv.1(time-12hr)</code>&nbsp;&nbsp;&nbsp; Relative dimension expression<br>
<code>rh</code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
Default file number is used <br>
<code>q.2(t-1,lev=850)</code>&nbsp; Two dimension expressions <br>
<code>z(t+0)</code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
This does have uses....</ul>
<p>

GrADS has a few "<b>predefined</b>" variable names.  You can think of
these as being variables implicitly contained within any opened
gridded file.  The variable names are:


<ul>
<code>lat <br>
lon <br>
lev</code></ul><p>

When used, they will contain the <code>lat</code>, <code>lon</code>, and
<code>lev</code> at the
respective grid points, using the scaling of the appropriate
file.  You can specify:  <code>lat.2</code>  for example, to get latitudes on
the grid of the 2nd opened data set.


<p>
<h2><a name="new">Defining new variables</a></h2>

<p>
The <a href="gradcomddefine.html"><code>define</code></a> command
allows you to interactively create a new variable. The syntax is:<p>

<ul><code>define varname = <i>expression</i></code></ul>

<p>
The new variable can then be used in subsequent <a
href="gradcomddefine.html"><code>define</code></a> and/or <a
href="gradcomddisplay.html"><code>display</code></a> commands. The new
variable is stored in memory, not on disk, so avoid defining variables
over large dimension ranges.

<p>
Defined variables cover the dimension ranges in effect
at the time the command is issued. You may define a variable that
has from 0 to 4 varying dimensions.  The <a
href="gradcomddefine.html"><code>define</code></a> command is the
only case within GrADS where four varying dimensions is valid.

<p>
When <code>Z</code> and/or <code>T</code> are varying dimensions, the
<a href="gradcomddefine.html"><code>define</code></a> command
evaluates the expression by stepping through <code>Z</code> and <code>T</code>.
In other words, the expression is evaluated within a dimension environment
that has fixed <code>Z</code> and <code>T</code>.  This will affect how you
compose the expression.

<p>
When you use a defined variable, data is taken from the variable in a
way similar to data taken from a GrADS data file.  For example, say
you define a four dimensional variable:<p>

<ul>
<code>
set lon -180 0 <br>
set lat 0 90 <br>
set lev 1000 100 <br>
set t 1 10 <br>
define temp = rh<br>
</code>
</ul>

<p>
After issuing the <a href="gradcomddefine.html"><code>define</code></a> 
command, remember to change the dimension environment so less than 4
dimensions are varying!<p>

<ul>
<code>
set t 5 <br>
set lev 500 <br>
d temp
</code>
</ul>

<p>
The display of the defined variable will display a 2-D slice
taken at time 5 and level 500.

<p>
If you define a variable that has fixed dimensions, and then
later access this variable, the fixed dimensions are treated as
"wild cards".  The best way to show this is with an example:

<ul>
<code>
set lon -180 0 <br>
set lat 0 90 <br>
set lev 500 <br>
set t 10 <br>
define zave = ave(z,t=1,t=30)<br>
</code>
</ul>

<p>
The defined variable has two varying dimensions.  If we now
display this variable (or use it in an expression), the fixed
dimensions of the defined variable, namely <code>Z</code> and <code>T</code>,
will match
ANY <code>Z</code> and <code>T</code> dimension setting:<p>

<ul>
<code>
set t 1 <br>
set lev 200 <br>
d zave<br>
</code>
</ul>

<p>
In the above display, the variable <code>zave</code> would be displayed as it
was defined, ie you would get a time average of 500mb heights,
even though the level is set to 850.

<p>
When the defined variable has varying dimensions, and you have a
dimension environment where that dimension is fixed, the proper
dimension will be retrieved from the variable:

<ul>
<code>
set lon -180 0 <br>
set lat 0 90 <br>
set lev 500 <br>
set t 10 <br>
define temp = z<br>
set lat 40 <br>
d temp<br>
</code>
</ul>

<p>
In the above example, the defined variable has a varying Y
dimension. We then fix the Y dimension to be 40N, and display a
1-D slice.  The data from 40N in the defined grid will be
accessed.  If you then did:

<ul>
<code>
set lat -40 <br>
d temp<br>
</code>
</ul>

<p>
The data from 40S would be accessed from the defined variable. 
Since this is beyond the dimensions originally used when the
variable was defined, the data would be set to missing.

<p>
You can also locally override the dimension environment:

<ul><code>d temp(lat=50)</code></ul>

<p>
If that dimension is a varying dimension within the defined
variable.  If the dimension is a fixed dimension for that
variable, the local override will be ignored:

<ul><code>d temp(t=15)</code></ul>

<p>
In the above command, the defined variable temp has fixed T, so
the t=15 would be ignored.

<p>
N.B.: The <code>define</code> command currently supports only grids.

<p>
Once you have defined a grid variables, you may tell GrADS that
the new variable is climatological, ie that you wish to treat the
time dimension of the new variable in a wild card sense.

<p>
The command is:<p>

<ul>
<code>
<a href="gradcomdmodify.html">modify</a> varname  &lt;<i>seasonal/diurnal</i>&gt;<br>
</code>
</ul>

<p>
where <code>varname</code> is the name of a defined variable.  If the
grid is described as <code>seasonal</code>, then it is assumed that
the defined variable contains monthly (or multi month) means. Daily or
multi-day means are not yet supported.  If <code>diurnal</code> is
specified, it is assumed the defined variable contains means over some
time period less than a day.

<p>
After describing the defined variable as climatological, then the
date/times are treated appropriately when data is accessed from
the defined variable.

<p>
In the following example, the data set contains 10 years of monthly means:<p>

<ul>
<code>
set lon -180 180 <br>
set lat -90 90 <br>
set lev 500 <br>
set t 1 12 <br>
define zave = ave(z,t+0,t=120,1yr)</code></ul>

<p>
This define will set up a variable called <code>zave</code> which
contains 12 times, each time being the 10 year mean for that month. We
are making use here of the fact that the define command loops through
a varying time dimension when evaluating the expression, and within
the <a href="gradfuncave.html"><code>ave</code></a> function we are
making use of the variable time offset of t+0, which uses a start time
that is whatever time the <a
href="gradcomddefine.html"><code>define</code></a> command is using as
it loops.

<ul>
<code>
modify zave seasonal <br>
set t 120 <br>
d z - zave</code></ul>

<p>
The final display will remove the 10 year monthly mean for
December from the last December in the data set.

<p>
<h2><a name="undefine">Undefining variables</a></h2>

<p>
Each variable defined using the <a
href="gradcomddefine.html"><code>define</code></a> command reserves
some system resources.  If you no longer need a defined variable it is
sensible to free these resources for other use.  This is accomplished
with the <a href="gradcomdundefine.html"><code>undefine</code></a>
command. For example:

<ul><code>undefine p</code></ul>

<p>
would free the resources used by the defined variable <code>p</code>.  Of
course, the variable <code>p</code> would no longer be available for GrADS
processing.

</body>
</html>