source: trunk/SRC/ReadWrite/idl-NetCDF/ncdf_quickwrite/README_ncdf_quickwrite.txt @ 163

NAME:

   ncdf_quickwrite


SYNOPSIS:

   This is a routine for writing variables from an IDL session to a 
   NetCDF file, in just a very few commands.

   It is designed to be quick to *use*, once you are familiar with the syntax.

   It may possibly also be slightly quicker to *learn* than writing NetCDF
   files the standard way, but this is not particularly the objective.


DESCRIPTION:

1) Ensure that the supplied routines are installed in your IDL_PATH.

         ncdf_quickwrite.pro
         ncdf_quickwrite_helper1.pro
         ncdf_quickwrite_helper2.pro
         ncdf_quickwrite_helper3.pro

2) Set the string variable NCFILE to the NetCDF filename you wish to write,
   For example:

         ncfile='myfile.nc'

   The file should not already exist.  If you wish to permit overwriting, put
   "!" before the filename.  For example:

         ncfile='!myfile.nc'

3) Set the string variable NCFIELDS as follows.
   NB there are a number of options but you do not need to use them all!
   Skip down to "USAGE EXAMPLE" below for a simple example.

   a) For each variable, construct the VARIABLE SPECIFICATION as follows:

        => For an array, use the name of array, with the names of the
           dimensions in square brackets ([]) and separated by commas.
           For example:

                 pressure[longitude,latitude]

        => For a 1-dimensional array, whose dimension name is the same
           as the array name, you can omit the dimension name if you want.
           For example:

                 longitude[]

        => For each scalar, do not use square brackets, e.g.:

                 g

        => If any of variables you want to use in the NetCDF file is not held
           in a variable of the same name in your IDL session, then put 
           follow the variable specification with "=expression".

           Examples:

               1) if pressure is in IDL variable "p", you have:

                       pressure[longitude,latitude]=p

               2) if g is not stored in a variable but should 
                  have value 9.8, you have:

                       g=9.8

        => If any of the variables have attributes to be stored, follow
           the specification with a colon (:) followed by the name of
           a variable containing a structure of attributes.  For example:

               pressure[longitude,latitude]=p:patts

               where "patts" is a structure containing:
                         {units:'pascal',missing_value:1e10}

   b) Join up all the variables with semicolons (;) to make the NCFIELDS
      string.  For example:

      NCFIELDS = $
       'pressure[longitude,latitude]=p:patts;longitude[];latitude[];g=9.8'

   c) If there is a dimension, which you want to be of UNLIMITED size, then
      precede its name with "*" somewhere where it is mentioned (or where
      you omit the dimension name because it matches the variable name,
      nonetheless still include the "*" in the square brackets).  For example
      the "time" dimension in any of the following:

        NCFIELDS = $
         'pressure[longitude,latitude,*time];longitude[];latitude[];time[]'

        NCFIELDS = $
         'pressure[longitude,latitude,time];longitude[];latitude[];time[*time]'

        NCFIELDS = $
         'pressure[longitude,latitude,time];longitude[];latitude[];time[*]'

      (Note that if you put "*" before the same dimension name more than once,
      that is accepted.  But if you put "*" before more than one dimension
      name, that is an error, because only one dimension can be UNLIMITED.)

   d) If there are global attributes, follow the specification with an
      at sign (@) followed by the name of a variable containing a structure
      of attributes.  For example:
       
        NCFIELDS = $
          'pressure[longitude,latitude];longitude[];latitude[]@globatts'

        where "globatts" is a structure containing:
                         {source:'my program',version:2}

   e) You may insert whitespace in NCFIELDS for readability.

4) Type:  @ncdf_quickwrite


USAGE EXAMPLES:

1) SIMPLE EXAMPLE.

      =>  You have the following variables:

           LATITUDE        FLOAT     = Array[73]
           LONGITUDE       FLOAT     = Array[96]
           PRESSURE        DOUBLE    = Array[96, 73]

      =>  You issue the following commands:

           ncfile='my.nc'
           ncfields='latitude[];longitude[];pressure[longitude,latitude]'
           @ncdf_quickwrite

      =>  This makes "my.nc". "ncdump -h my.nc" reports the following:

           netcdf my {
           dimensions:
                   latitude = 73 ;
                   longitude = 96 ;
           variables:
                   float latitude(latitude) ;
                   float longitude(longitude) ;
                   double pressure(latitude, longitude) ;
           }

2) MORE COMPLEX EXAMPLE.

      =>  You have the following variables:

           LATS            FLOAT     = Array[73]
           LONS            FLOAT     = Array[96]
           P               DOUBLE    = Array[96, 73, 100]
           UBAR            DOUBLE    = Array[73, 100]
           YR              LONG      = Array[100]

      =>  You issue the following commands.
          (NB The NCFIELDS assignment can be typed as one long line, but is 
          split below for readability.)

             ncfile='!my.nc'
             angle_attr={units:'degrees'}
             wind_attr={units:'m s-1'}
             press_attr={units:'pascals',missing_value:1e10}
             g_attr={units:'m s-2'}
             globattr={source:'My program',version:2}
             
             ncfields = 'pressure[longitude,latitude,time]=p:press_attr; ' $
                      + 'longitude[]=lons:angle_attr; ' $
                      + 'latitude[]=lats:angle_attr; ' $
                      + 'ubar[latitude,time]:wind_attr; ' $
                      + 'year[*time]=yr; ' $
                      + 'g=9.8:g_attr @ globattr'
             
             @ncdf_quickwrite

      =>  This makes "my.nc", overwriting any existing my.nc.
          "ncdump -h my.nc" reports the following:

           netcdf my {
           dimensions:
                   longitude = 96 ;
                   latitude = 73 ;
                   time = UNLIMITED ; // (100 currently)
           variables:
                   double pressure(time, latitude, longitude) ;
                           pressure:units = "pascals" ;
                           pressure:missing_value = 1.e+10f ;
                   float longitude(longitude) ;
                           longitude:units = "degrees" ;
                   float latitude(latitude) ;
                           latitude:units = "degrees" ;
                   double ubar(time, latitude) ;
                           ubar:units = "m s-1" ;
                   int year(time) ;
                   float g ;
                           g:units = "m s-2" ;
           
           // global attributes:
                           :source = "My program" ;
                           :version = 2s ;
           }
      
           (Note that in this example you have created a NetCDF file 
            with verbose variable names even though the IDL variables
            have terse names.)

BUGS:

  => Writing string variables may fail.


LIMITATIONS:

  => An expression following an "=" sign should not contain ":" or ";" signs
     because these will be treated as separators.

  => An expression following an "=" sign gets evaluated twice.  If this is
     computationally expensive, store it in a variable and reference the
     variable instead.

  => Attribute names are case-insensitive because they are structure tags.
     In fact, they are stored as lower case.


AUTHOR:

   Alan Iwi <A.M.Iwi@rl.ac.uk>


COPYRIGHT:

   I am putting these routines in the public domain.

   But the IDL program itself is subject to copyright restrictions.