PyGrADS Interactive Shell

From OpenGrads Wiki
Jump to: navigation, search

IPython is an enhanced Python shell designed for efficient interactive work. It includes many enhancements over the default Python shell, including the ability for controlling interactively all major GUI toolkits in a non-blocking manner. The script pygrads is a wrapper script which starts IPython with a number of aliases and customizations convenient for interactive GrADS work. In particular, it starts PyLab bringing together all the GrADS and Matplotlib capabilities.

Starting pygrads

From your OS the command line enter

% pygrads -h

for a list of the pygrads command line options:

   Welcome to PyGrADS, a GrADS-based 
   iPython environment.

Usage: pygrads [options] [files_to_open]

Options:
 --version             show program's version number and exit
 -h, --help            show this help message and exit
 -x GABIN, --binary=GABIN
                       path to grads binary (default=gradshdf)
 -C, --classic         starts GrADS classic (gradsc)
 -D, --dods            starts GrADS DODS (gradsdods)
 -d, --dap             starts GrADS with OPeNDAP (gradsdap)
 -H, --hdf4            starts GrADS HDF-4 (gradshdf)
 -n, --nc              starts GrADS NetCDF (gradsnc4)
 -N, --nc4             starts GrADS NetCDF (gradsnc
 -b, --batch           start GrADS in batch mode
 -c GACMD, --command=GACMD
                       run a GrADS command on startup (e,g., a script)
 -g GEOM, --geometry=GEOM
                       set size of graphics window, e.g., 800x600
 -l, --landscape       start GrADS in landscape mode
 -m N, --metasize=N    set metafile buffer size to N
 --nopylab             start iPython without pylab
 -p, --portrait        start GrADS in portrait mode
 -W, --wideline        use X server wide lines (faster) instead of s/w
                       (better)
 -X XMODE, --xmode=XMODE
                       Mode for exception reporting. The valid modes are
                       Plain, Context, and Verbose. 'Plain' similar to
                       python's normal traceback printing. 'Context' prints 5
                       lines of context source code around each line in the
                       traceback. 'Verbose' is similar to Context, but
                       additionally prints the variables currently visible
                       where the exception happened (shortening their strings
                       if too long). Default is 'Plain'.

Notice that you can specify must of the classic GrADS command line options, as well as some of IPython options. You can also select with GrADS binary to start. As implemented, pygrads is a convenience script which starts an embedded IPython shell, loading module ipygrads. See below for instructions on how to start ipygrads from your $HOME/.ipython directory.

Aliases provided by ipygrads

At any time from within IPython, on-line help is available with these commands:

   help(ipygrads)   up to date module documentation
   qref             PyGrADS quick reference
   examples         Some PyGrADS examples

Based on command line arguments supplied by the user, the top level script pygrads defines key environments variables necessary for this module to start a GrADS connection, defining the global object "ga". You can use "ga" to interact with GrADS directly:

   ga("q config")

However, a number of shortcuts are provided so that rarely one needs to explicitly type ga.cmd(...). The following generic GrADS commands are available:

   clear/c, define, disable, display/d, draw, enable,
   Open/o, Print/pp, printim/pim, Set/s, query/q, reinit

Notice that some commands (e.g., "Open") are capitalized to avoid conflict with standard Python keywords.

In addition, any generic GrADS command can be entered by starting the line with a period and a space ('. '), for example example

   . open model.ctl
   . display ps

The following convenience aliases are provided:

   cb         run cbarn (for color bar script)
   sh         set gxout shaded
   yat        run gxyat
                                                                                 

These shortcuts run specific methods from module "grads" on the GrADS object "ga":

   dd $name   runs the "imp" method, displaying a NumPy array in
              GrADS; this is equivalent to
                   ga.imp('<display>',$name)
   eof $name  compute EOF using Singular Value Decomposition; the
              *time* dimension contains the eofs; this equivalent to:
               $name,$name_d,$name_c = ga.eof('$name')
   ii $name   runs the "imp" method, importing a NumPy array into
              GrADS; this is equivalent to
                    ga.imp("$name",$name)
   oo $fname  runs the "open" method,  setting "fh"
   qq $what   runs the "query" method, setting "qh"
   xx $name   runs the "exp" method, returning a NumPy array and an
              associated grid with coordinate information.
              This magic command is equivalent to
                   $name = ga.exp("$name")
                   $lon = $name.grid.lon
                   $lat = $name.grid.lat
                   $lev = $name.grid.lev
                   $time = $name.grid.time
                                                                                 

The shortcuts "dd/ii/xx" are somewhat limited interfaces to the "imp"/"exp" methods as they do not work on expressions; use "ga.imp()"/"ga.exp()" directly for a more flexible alternative.

For additional information on these and other methods, consult the documnentation for the module grads:

  help('grads')

Examples

For running this example, obtain sample files from here. Then start the pygrads shell:

% pygrads 

Open a file and display a variable

  [] ga-> q config
  [] ga-> o model
  [] ga-> d ts
  [] ga-> . draw title Surface Temperature (Kelvin)

Exchanging data with python

Ga tc.png

Export variable "ts", change units in python, and display it in GrADS:

  [] ga-> xx ts
  [] ga-> ts = ts - 273
  [] ga-> c
  [] ga-> sh
  [] ga-> dd ts
  [] ga-> cb
  [] ga-> . draw title Surface Temperature (Celsius)

Display the modified variable in Python with Plain Matplotlib

Here is a simple usage of Matplotlib with does not involve use of the Basemap Toolkit:

Py tc.png
  [] ga-> contourf(lon,lat,ts)
  [] ga-> title('Surface Temperature (Celsius)')
  [] ga-> figure(2)
  [] ga-> plot(lat,ts[:,0]))
  [] ga-> title('Surface Temperature (Celsius) at lon=0')

See below for an equivalent example using the Basemap Toolkit.

Export an expression, change it in Python, and import it back

  [] ga-> . set lev 300
  [] ga-> uv  = ga.exp('ua*ua+va*va')
  [] ga-> speed = sqrt(uv)
  [] ga-> ga.imp('speed', speed)
  [] ga-> clear
  [] ga-> display speed
  [] ga-> . draw title Wind Speed
  [] ga-> cb

A variation on the same theme

Here is another of way of accomplishing the same, this following the name conventions so that *dd* can be used:

Ga speed.png
  [] ga-> clear
  [] ga-> uv = ga.exp('ua*ua+va*va')
  [] ga-> speed = sqrt(uv)
  [] ga-> dd speed

Using Basemap

If you have Matplotlib with the Basemap toolkit installed, you can do most of your plotting in python. Shaded contours can be produced with the command:

  [] ga-> ga.contourf('ts')
  [] ga-> title('Surface Temperature')

Continuous Color Scale

If instead you would like a continuous color scale do this

  [] ga-> clf()
  [] ga-> ga.imshow('ts')

Plain Image

If all you want is a plain image covering all of your graphics window to later be exported to GoogleEarth then

  [] ga-> clf()
  [] ga-> ga.implain('ts')

Pseudo-color plots

A pseudo-color plot, just like one would obtain with "set gxout grfill", can be produced with

  [] ga-> clf()
  [] ga-> ga.pcolor('ts')

Blue Marble

Here is how to plot a variable on a blue marble background

  [] ga-> ga.blue_marble('on')
  [] ga-> s lon -180 180
  [] ga-> ga.imshow('ua')
  [] ga-> title('Zonal Wind')

Map Projections

You can also select your map projection, e.g.

  [] ga-> ga.basemap('npo')
  [] ga-> ga.contour('zg(lev=300)')
  [] ga-> title('300 hPa Heights')

Saving a Figure

If in any moment you would like to save the graphics window just type

  [] ga-> savefig('myfile.png')

For more information type:

  [] ga-> help galab
  [] ga-> help pylab

Terminating your session

Do not forget the ():

  [] quit()

Computing EOFs

Here you specify the data file to be opened on the command line, then proceed to compute Empirical Orthogonal Functions (EOFs) after setting the dimension environment to span all the time steps on the file:

Ga nao.png
  % pygrads slp_djf.nc
  [] ga-> . set t 1 41
  [] ga-> eof djfslp

To display the first mode in GrADS you simply set t 1 and display it:

  [] ga-> . set t 1
  [] ga-> . set gxout shaded 
  [] ga-> dd djfslp
  [] ga-> . draw title NAO Pattern