.. _commands:

Convsh commands
===============

Below is a list of convsh extensions to the 
`tcl scripting language <http://www.tcl.tk/man/tcl8.6/TclCmd/contents.htm>`_. 
Some commands have the argument *fieldlist*, this is a list of numbers which
represents a subset of the fields which convsh has stored in memory. These
fields will be stored in the same order as they are in xconv, 
therefore the easiest way to
work out the field numbers is to run xconv on one file, before applying a
convsh script to a large number of files. Remember field numbering starts at 0.
A field number of -1 is  shorthand for specifying all field numbers convsh
currently has stored in memory.

**clearall**
     Clears away all internal information about previous input files. This
     command must be used if a separate output file is needed for every 
     input file.

**copyfields** *fieldlist*
     Make a copy of all the fields in *fieldlist*. These additional fields
     will be appended to the list of fields convsh has stored in memory. The 
     command will return the field numbers of the newly created fields.
     For example if the original fields are (a,b,c,d,e) mapped on to field 
     numbers (0,1,2,3,4), after the command **copyfields** *"1 3"*, the new 
     fields will be (a,b,c,d,e,b,d) mapped on to field numbers (0,1,2,3,4,5,6). 
     The command will return "5 6".

**delfields** *fieldlist*
     Delete all the fields in *fieldlist*. Note the field numbers
     will be changed by this command. For example if the original fields are
     (a,b,c,d,e) mapped on to field numbers (0,1,2,3,4), after the command
     **delfields** *"1 3"*, the new fields will be (a,c,e) mapped on
     to field numbers (0,1,2). 

**delm2** *fieldlist*
     Compute the inverse Laplacian of the spectral harmonic coefficients in 
     *fieldlist*

**edit_grid** *fieldlist*
     For each of the fields in *fieldlist* change the values of the x and y 
     dimensions but not the number of rows or columns. The new x,y dimensions
     values are set by running either the **setgrid** or **settrunc** command.

**extendglobatt** *attribute value*
     Extend global attribute *attribute* with *value*.

**extrap** *fieldlist minnbr*
     For each of the fields in *fieldlist* extrapolate over missing data using
     nearest neighbour filling. The value of *minnbr* selects the minimum 
     number of nearest neighbours used and should be a value between 1 and 4.

**get_cal** *fieldlist*
     For each of the fields in *fieldlist* get the calendar type. The command
     return a list of integers where the integer value represents a calendar 
     type

     | *1*  : Gregorian calendar
     | *2*  : 360 day calendar
     | *14* : Julian calendar
     | *15* : No leap year calendar

**get_description** *fieldlist*
     For each of the fields in *fieldlist* get the description string. For 
     netCDF files the description string will be taken from the *source*
     attribute, if that doesn't exist then it will be taken from the *comments*
     attribute.

**get_gridtype** *fieldlist*
     For each of the fields in *fieldlist* get the grid type. The command
     return a list of integers where the integer value represents a grid type

     | *0*  : Gaussian latitude/longitude grid
     | *1*  : Regular latitude/longitude grid
     | *2*  : Reduced Gaussian latitude/longitude grid
     | *3*  : Spectral harmonic coefficients
     | *4*  : Polar stereographic grid
     | *5*  : Space view perspective or orthographic grid
     | *6*  : Mercator projection grid
     | *7*  : Gnomonic projection grid
     | *8*  : Plane polar grid
     | *9*  : Plane Cartesian grid
     | *10* : Staggered latitude/longitude grid
     | *11* : Reduced regular latitude/longitude grid

**get_longname** *fieldlist*
     For each of the fields in *fieldlist* get the long name string. For 
     netCDF files the long name string will be taken from the *long_name*
     attribute, if that doesn't exist then it will be taken from the *title*
     attribute, if that doesn't exist then it will be taken from the 
     *standard_name* attribute.

**get_mdi** *fieldlist*
     For each of the fields in *fieldlist* get the missing data indicator value.

**get_shortname** *fieldlist*
     For each of the fields in *fieldlist* get the short name string. For 
     netCDF files the short name string will be taken from the variable name.

**get_standardname** *fieldlist*
     For each of the fields in *fieldlist* get the standard name string. For 
     netCDF files the standard name string will be taken from the 
     *standard_name* attribute.

**get_tlongname** *fieldlist*
     For each of the fields in *fieldlist* get the time dimension long name string. 

**get_tname** *fieldlist*
     For each of the fields in *fieldlist* get the time dimension name string. 

**get_tstandardname** *fieldlist*
     For each of the fields in *fieldlist* get the time dimension standard name string. 

**get_tunit** *fieldlist*
     For each of the fields in *fieldlist* get the time dimension unit string. 

**get_unit** *fieldlist*
     For each of the fields in *fieldlist* get the unit string. For 
     netCDF files the unit string will be taken from the 
     *units* attribute.

**get_xlongname** *fieldlist*
     For each of the fields in *fieldlist* get the x dimension long name string.

**get_xname** *fieldlist*
     For each of the fields in *fieldlist* get the x dimension name string. 

**get_xstandardname** *fieldlist*
     For each of the fields in *fieldlist* get the x dimension standard name string. 

**get_xunit** *fieldlist*
     For each of the fields in *fieldlist* get the x dimension unit string. 

**get_ylongname** *fieldlist*
     For each of the fields in *fieldlist* get the y dimension long name string. 
**get_yname** *fieldlist*
     For each of the fields in *fieldlist* get the y dimension name string. 

**get_ystandardname** *fieldlist*
     For each of the fields in *fieldlist* get the y dimension standard name string. 

**get_yunit** *fieldlist*
     For each of the fields in *fieldlist* get the y dimension unit string. 

**get_zlongname** *fieldlist*
     For each of the fields in *fieldlist* get the z dimension long name string.

**get_zname** *fieldlist*
     For each of the fields in *fieldlist* get the z dimension name string. 

**get_zstandardname** *fieldlist*
     For each of the fields in *fieldlist* get the z dimension standard name string. 

**get_zunit** *fieldlist*
     For each of the fields in *fieldlist* get the z dimension unit string. 

**getdimatt** *attribute1 attribute2 attribute3 ...*
     The command returns a list where each element is the dimension attribute 
     state for the corresponding attribute argument. The dimension attribute 
     state can have one of the following values

     | *att_use*   : This attribute will be used for all relevant dimensions
     | *att_nouse* : This attribute will not be used for any dimensions
     | *att_cond*  : This attribute will be used only when there is data 
                     available or when the attribute value is different 
                     from the assumed default value.

**getglobatt** *attribute1 attribute2 attribute3 ...*
     The command returns a list where each element is the global attribute 
     state for the corresponding attribute argument. The global attribute 
     state can have one of the following values

     | *att_use*   : This global attribute will be used
     | *att_nouse* : This global attribute will not be used

**getvaratt** *attribute1 attribute2 attribute3 ...*
     The command returns a list where each element is the variable attribute 
     state for the corresponding attribute argument. The variable attribute 
     state can have one of the following values

     | *att_use*   : This attribute will be used for all variables
     | *att_nouse* : This attribute will not be used for any variables
     | *att_cond*  : This attribute will be used only when there is data 
                     available or when the attribute value is different 
                     from the assumed default value.

**interp_grid** *fieldlist*
     Interpolate data, for fields in *fieldlist*, from one grid to 
     another. The initial grid will either 
     be the grid the data was read in on, or the grid from a previous 
     **interp_grid** or **spec_trans** command. If a new grid is not
     defined using **setgrid** or **settrunc**, the new grid will be the 
     same as the initial grid. 

**list_fields** [*fieldtitle*]
     List all of the fields currently active in convsh. The output format is
     the same as in the main xconv window. The *fieldtitle* argument is
     optional, it can have three values *short*, *long* and 
     *both*. *short* uses the
     short form of the field title, *long* uses the long form and 
     *both* uses both.
     If *fieldtitle* is not given the long form of the field title is 
     used. 

**meridonal_mean** *fieldlist*
     For each of the fields in *fieldlist* calculate the meridonal mean.

**readfile** *filetype filename*
     Read into convsh the file given by *filename*, the file type is
     given by the *filetype* argument. If *filetype* has the value
     *0* convsh will try to automatically determine the file type, this 
     will usually work but if it fails the actual file type can be given. 
     The various values of *filetype* for different input file types 
     are given below:
     
     | *0*   : Automatic
     | *1*   : UM format (32 bit IEEE)
     | *2*   : PP format (32 bit IEEE)
     | *3*   : GRIB format (Unblocked)
     | *4*   : GRIB format (Cray blocked)
     | *7*   : NetCDF format
     | *8*   : Grads format
     | *34*  : PP format (64 bit Real 32 bit Integer IEEE)
     | *65*  : UM format (64 bit IEEE)
     | *66*  : PP format (64 bit IEEE)
     | *165* : UM format (64 bit Cray)
     | *166* : PP format (Cray blocked 64 bit Cray)
     | *167* : PP format (Cray blocked 64 bit IEEE)
     | *201* : UM format (32 bit IEEE byte swapped)
     | *202* : PP format (32 bit IEEE byte swapped)
     | *265* : UM format (64 bit IEEE byte swapped) 
     | *266* : PP format (64 bit IEEE byte swapped)

**reset_trans**
     Reset transformation/interpolation variables to their default values.
     See the individual commands for the default values. 

**set_cal** *fieldlist calendar*
     For each of the fields in *fieldlist* set the calendar type. The value of
     *calendar* can be one of these strings "GREGORIAN", "gregorian", "360",
     "JULIAN", "julian", "NOLEAP" or "noleap" or it can be an integer value
     which represents a calendar type

     | *1*  : Gregorian calendar
     | *2*  : 360 day calendar
     | *14* : Julian calendar
     | *15* : No leap year calendar

**set_description** *fieldlist name*
     For each of the fields in *fieldlist* set the description string. For 
     netCDF files the description string will be written out as the *source*
     attribute, if selected.

**set_longname** *fieldlist name*
     For each of the fields in *fieldlist* set the long name string. For 
     netCDF files the long name string will be twritten out as the *long_name*
     or the *title* attribute, if selected.

**set_mdi** *fieldlist newmdi*
     For each of the fields in *fieldlist* set the missing data indicator value.
     This command can be used to correct the missing data indicator if it does 
     not match the actual missing data values.

**set_shortname** *fieldlist name*
     For each of the fields in *fieldlist* set the short name string. For 
     netCDF files the short name string will be written out as the 
     *short_name* attribute or the *name* attribute, if selected. It will also
     be used for the variable name.

**set_standardname** *fieldlist name*
     For each of the fields in *fieldlist* set the standard name string. For 
     netCDF files the standard name string will be written out as the 
     *standard_name* attribute, if selected.

**set_tlongname** *fieldlist name*
     For each of the fields in *fieldlist* set the time dimension long name string.

**set_tname** *fieldlist name*
     For each of the fields in *fieldlist* set the time dimension name string. 

**set_tstandardname** *fieldlist name*
     For each of the fields in *fieldlist* set the time dimension standard name string.

**set_tunit** *fieldlist name*
     For each of the fields in *fieldlist* set the time dimension unit string. 

**set_unit** *fieldlist name*
     For each of the fields in *fieldlist* set the unit string. For 
     netCDF files the unit string will be written out as the 
     *units* attribute, if selected.

**set_xlongname** *fieldlist name*
     For each of the fields in *fieldlist* set the x dimension long name string.

**set_xname** *fieldlist name*
     For each of the fields in *fieldlist* set the x dimension name string. 

**set_xstandardname** *fieldlist name*
     For each of the fields in *fieldlist* set the x dimension standard name string.

**set_xunit** *fieldlist name*
     For each of the fields in *fieldlist* set the x dimension unit string. 

**set_ylongname** *fieldlist name*
     For each of the fields in *fieldlist* set the y dimension long name string.

**set_yname** *fieldlist name*
     For each of the fields in *fieldlist* set the y dimension name string. 

**set_ystandardname** *fieldlist name*
     For each of the fields in *fieldlist* set the y dimension standard name string.

**set_yunit** *fieldlist name*
     For each of the fields in *fieldlist* set the y dimension unit string. 

**set_zlongname** *fieldlist name*
     For each of the fields in *fieldlist* set the z dimension long name string.

**set_zname** *fieldlist name*
     For each of the fields in *fieldlist* set the z dimension name string. 

**set_zstandardname** *fieldlist name*
     For each of the fields in *fieldlist* set the z dimension standard name string.

**set_zunit** *fieldlist name*
     For each of the fields in *fieldlist* set the z dimension unit string. 

**setdim** *dim fieldlist dimlist*
     Choose the values given by *dimlist* for the dimension given by 
     *dim*, for the fields in *fieldlist*. The value of *dim*
     should be one of *1*, *2*, *3* or *4* corresponding to
     the x, y, z and time dimensions.
     Currently convsh only allows dimension sub-sampling for the z and time
     dimensions, therefore *dim* should be either *3* or *4*. 
     As an example 
     suppose field number 2 has the following levels (1000,900,800,500,200,100)
     defined and only levels (1000,500,100) were needed, then the following 
     should be used: **setdim** *3 2 "0 3 5"*. 

**setdimatt** *attribute1 attribute2 attribute3 ... state*
     Set the state of netCDF dimension attributes. There is a special attribute
     *all* which will set all attributes to a particular state. This can be 
     useful to set a default attribute state, not used for example, then just 
     select the particular attributes you wish to include. Some attributes apply
     to all dimensions others only to a particular dimension.
     The values available for state are

     | *att_use*   : This attribute will be used for all relevant dimensions
     | *att_nouse* : This attribute will not be used for any dimensions
     | *att_cond*  : This attribute will be used only when there is data 
                     available or when the attribute value is different 
                     from the assumed default value.

**setglobatt** *attribute1 attribute2 attribute3 ... state*
     Set the state of netCDF global attributes. There is a special attribute
     *all* which will set all attributes to a particular state. This can be 
     useful to set a default attribute state, not used for example, then just 
     select the particular attributes you wish to include. The *history* 
     attribute is set internally by convsh and therefore can't be turned off.
     The values available for state are

     | *att_use*   : This global attribute will be used
     | *att_nouse* : This global attribute will not be used

**setgrid** *dim n v0 dv*
     Defines the new grid for the **interp_grid**, **spec_trans** or 
     **edit_grid** commands. The argument *dim* should have the value *1* if a 
     new x grid is being defined and the value *2* if a new y grid is 
     being defined. The
     argument *n* gives the number of points on the new grid. The argument 
     *v0* gives the first value of the new grid. The argument 
     *dv* gives the grid length of the new grid, *dv* should be
     negative if the grid values are decreasing. 

**setgridtype** *gridtype*
     Sets the new grid type for the **interp_grid** or **spec_trans**
     commands, *gridtype* has the value *regular* for
     a regular grid and the value *gaussian* for a Gaussian grid. If 
     **setgridtype** is not used **interp_grid** will interpolate to a 
     regular grid and **spec_trans** will transform to a Gaussian grid. 

**setinterp** *interp*
     Defines the interpolation method for **interp_grid**, *interp*
     is either *bilinear* for bilinear interpolation or 
     *area_weighted* for area weighted interpolation. 
     The default type of interpolation is bilinear. 

**setlsm** *lsm*
     Defines whether the input data to **interp_grid** is a land/sea mask,
     *lsm* is *true* if the data is a land/sea mask, 
     *false* otherwise. The 
     default value of *lsm* is *false*. 

**setmiss** *miss*
     Defines whether the input data to **interp_grid** contains missing
     data values, *miss* is *true* if the data contains missing
     data values, *false* otherwise. 
     The default value of *miss* is *false*. 

**setpole** *pole*
     Defines whether **interp_grid** will average polar data values,
     if *pole* is *true* then polar data will be averaged, 
     otherwise it will not. 
     The default value of *pole* is *false*. 

**setprecip** *precip1 precip2*
     Defines whether **interp_grid** will use a precipitation cutoff,
     if *precip1* is *true* then a precipitation cutoff value of 
     *precip2* will be used, otherwise no precipitation cutoff is used.
     The precipitation cutoff is implemented in two steps, firstly any output
     field value less than *precip2* will be set to zero. Secondly, for
     each output grid point, the nearest input field grid point is determined,
     if the value of precipitation at this latter point in the input data
     field is less than *precip2*, then the precipitation at the output
     grid point is set to zero.
     The default value of *precip1* is *false*. 

**setrotpole** *xpole ypole*
     If **interp_grid** is interpolating to a grid with a rotated pole,
     **setrotpole** should be used to set the new north pole longitude to
     *xpole* and the  new north pole latitude to *ypole*. By default
     *xpole* has the value *0.0* and *ypole* has the value 
     *90.0* i.e. an unrotated grid. 

**settrunc** *nspec*
     Defines the output truncation for **spec_trunc**. The command will
     also set up the equivalent Gaussian grid for T *nspec* truncation,
     which can be used by the **interp_grid**, **spec_trans** and **edit_grid** 
     commands. 

**setvaratt** *attribute1 attribute2 attribute3 ... state*
     Set the state of netCDF variable attributes. There is a special attribute
     *all* which will set all attributes to a particular state. This can be 
     useful to set a default attribute state, not used for example, then just 
     select the particular attributes you wish to include. The values available 
     for state are

     | *att_use*   : This attribute will be used for all variables
     | *att_nouse* : This attribute will not be used for any variables
     | *att_cond*  : This attribute will be used only when there is data 
                     available or when the attribute value is different 
                     from the assumed default value.

**spec_trans** *fieldlist*
     Transform spectral data onto a grid, for fields in *fieldlist*.
     The initial spectral coefficients will either come from the input data
     or from a previous **spec_trunc** command. If a grid is not
     defined using **setgrid** or **settrunc**, then the 
     equivalent Gaussian grid for the input spectral truncation will
     be used. 

**spec_trunc** *fieldlist*
     Truncate spectral data, for fields in *fieldlist*, 
     by chopping off the small wavelength coefficients.
     The initial spectral coefficients will either come from the input data
     or from a previous **spec_trunc** command. The output truncation is 
     defined using **settrunc**. 

**writefile** *filetype filename fieldlist*
     Write out the fields in *fieldlist* to file *filename* of type
     *filetype*. The argument *filetype* can be one of
     *netcdf* or *grads*. 

**writeglobatt** *attribute value*
     write *value* into the global attribute *attribute*

**zonal_mean** *fieldlist*
     For each of the fields in *fieldlist* calculate the zonal mean.