


COSMO LibraryThis page contains the documentation of the COSMO library. It provides a set of NCL scripts that make analysing and plotting COSMO model output easier.
Introduction
The COSMO Library is a set of NCL scripts which should facilitate the the reading and plotting of the COSMO model output. Note that it works both for grib and NetCDF output. It actually also works for ECMWF and several other models and can greatly reduce your "time to plot" if you simply want to produce some standard plots. All main library commands start with the abbreviation In the standard installation of NCL at CSCS, the COSMO Library is automaticall loaded. This is acknowledged via a short message stating "COSMO Library Version 0.4 loaded" with the appropriate version number of the installation. A typical script using the COSMO Library to make a simple contour plot would look like this
begin f = addfile("lm_fine/lfff00210000.grb", "r") ; open file c = addfile("lm_fine/lfff00000000c.grb", "r") ; open constants file p = jmb_getvar(f, "P", False) ; get pressure field jmb_getgrid(f, c, p, False) ; get grid attributes for field wks = gsn_open_wks("pdf", "pressure") ; open PDF file pressure.pdf rc = jmb_set_ct(wks, "perc_11lev", False) ; set color table rc@cnLevels = (/1,2,3,4,5,6,7,8,9,10,11/)*10000.0 ; set color scale values s = jmb_slice(p, "lat", 47.0, False) ; vertical slice of pressure field at lat=47N cn = jmb_contour(wks, s, rc) ; make a filled contour plot plt = jmb_overlays(wks, (/cn/), False) ; compose plot and draw it delete(wks) ; close graphic port end
jmb_getvarFunction to read a variable from a COSMO model output file in grib1 format. Prototype
function jmb_getvar( f:file, name:string, opt:logical ) Arguments
Description
This function read a variable from a file previously opened using the
Usually, it is sufficient to use the grib key specification to access a certain variable. If you have variables which are not present in the operational grib keys file or need more precise control over the variable you want to access, you will most probably use the exact name of the variable. The naming convections for grib1 variables in NCL are rather involved. For example, the variable
A variable read using
The derived variables that can be computed via a call to
If a variable which you want to compute is not present, you will have to compute it yourself. Care should be taken to not only compute the variable but also update to corresponding attributes. For an example of how to compute the potential temperature, see Example 1 below. If you think that a derived variable you have computed might be useful for others, make sure it gets added to the official COSMO Library instead of copying and pasting it into every NCL script you write. Example 1
f = addfile("lfff00000000.grb","r") p = jmb_getvar(f,"P",False) t = jmb_getvar(f,"T",False) pt = t*(cosmo_p0/p)^(cosmo_r_d/cosmo_cp_d) pt@name = "THETA" pt@long_name = "potential temperature" pt@units = "K"
jmb_getgridRead and attach attributes describing the grid on which a field lives. Prototype
procedure jmb_getgrid( f:file, c:file, var:numeric, opt:logical ) Arguments
Description
This procedure attaches dimension variables and attributes describing the grid on which a certain field lives. The variable var should have been read using the
When a field is read using
In addition,
If you want to plot a field in index space, some information attached by Example 1
f = addfile("lfff01000000.grb","r") c = addfile("lfff00000000c.grb","r") p = jmb_getvar(f,"P",False) jmb_getgrid(f,c,p,False) printVarSummary(p)
jmb_rmgrid
Remove information added to a variable by Prototype
procedure jmb_rmgrid( var:numeric ) Arguments
Description
This procedure removes any information that has been added to a variable using a call to Example 1
f = addfile("lfff01000000.grb","r") c = addfile("lfff00000000c.grb","r") p = jmb_getvar(f,"P",False) jmb_getgrid(f,c,p,False) jmb_rmgrid(p) printVarSummary(p)
jmb_sliceFunction to extract a slice or a column of data from a more dimensional variable. Prototype
function jmb_slice( var:numeric, cutname:string, cutval:numeric ) Arguments
Description This function is a versatile slicer to extract 1dimensional or 2dimensional subsets of a variable. It can be used to extract both horizontal slice, vertical sclices, vertical columns or slices along arbitrary isosurfaces of a field. For example, you can extract pressure on the 320K potential temperature isosurface or extract a vertical crosssection along a constant latitude. The following table contains a description of the different cutname values and what they mean.
Example 1 Make a slice along a constant latitude at 47.0N.
f = addfile("lfff01000000.grb","r") c = addfile("lfff00000000c.grb","r") p = jmb_getvar(f,"P",False) jmb_getgrid(f,c,p,False) s = jmb_slice(p,"lat",47.0) Example 2 Extract relative humidity on the 850hPa level.
f = addfile("lm_coarse/lfff01000000.grb","r") c = addfile("lm_coarse/lfff00000000c.grb","r") p = jmb_getvar(f,"P",False) rh = jmb_getvar(f,"rh",False) cut = 85000.0 cut@z = p s = jmb_slice(p,"z",cut) jmb_getgrid(f,c,s,False)
jmb_set_ctSets the color table to use for the current workstation. Prototype
function jmb_set_ct( wks:graphic, name:string, opt:logical ) Arguments
Description
This function builds on top of the NCL function
The
The
Example 1 Draw a map and a filled contour plot of the COSMO7 topography using a nice color table.
c = addfile("lm_coarse/lfff00000000c.grb","r") hs = jmb_getvar(c,"HSURF",False) jmb_getgrid(c,c,hs,False) wks = gsn_open_wks("pdf", "topography") rc = jmb_set_ct(wks,"topo_15lev",False) mp = jmb_map(wks,hs,False) r = rc r@trXReverse = True cn = jmb_contour(wks,hs,r) delete(r) plt = jmb_overlays(wks,(/mp,cn/),False)
jmb_add_ctAdds a color table to use for the current workstation. Prototype
function jmb_add_ct( wks:graphic, name:string, opt:logical ) Arguments
Description
This function can be called after
The
The
Example 1 Draw a plot of precipitation and topography on the same page.
begin ; open graphic port wks = gsn_open_wks("pdf","test20") c = addfile("lm_coarse/lfff00000000c.grb","r") f = addfile("lm_coarse/lfff00010000.grb", "r") ; make a first plot with a specific colortable (jmb_set_ct) tp = jmb_getvar(f, "TOT_PREC", False) jmb_getgrid(f, c, tp, False) r = jmb_set_ct(wks, "precip1h_17lev", False) cn = jmb_contour(wks, tp, r) mp = jmb_map(wks, tp, False) plt = jmb_overlays(wks, (/mp,cn/), False) delete(cn) delete(plt) ; make a second plot with a specific colortable (jmb_add_ct) hsurf = jmb_getvar(c, "HSURF", False) jmb_getgrid(c, c, hsurf, False) frland = jmb_getvar(c, "FR_LAND", False) hsurf = where(hsurf.lt.0.1,0.1,hsurf) hsurf = where(frland.lt.0.5,1.0,hsurf) r = jmb_add_ct(wks,"topo_15lev",False) cn = jmb_contour(wks, hsurf, r) plt = jmb_overlays(wks, (/mp,cn/), False) end
jmb_mapCreates a map. Prototype
function jmb_map( wks:graphic, var[*][*]:numeric, opt:logical ) Arguments
Description
This function builds on top of the NCL function
The
Example 1 Draw a map and a filled contour plot of the COSMO7 topography.
c = addfile("lm_coarse/lfff00000000c.grb","r") hs = jmb_getvar(c, "HSURF", False) jmb_getgrid(c, c, hs, False) wks = gsn_open_wks("pdf", "topography") rc = jmb_set_ct(wks, "rainbow", False) mp = jmb_map(wks, hs, False) cn = jmb_contour(wks, hs, rc) plt = jmb_overlays(wks, (/mp,cn/), False)
jmb_contourCreates contour plot. Prototype
function jmb_contour( wks:graphic, var[*][*]:numeric, opt:logical ) Arguments
Description
This function builds on top of the NCL function
If the plot is intended to be in lat/lon space, the field
If the plot is intended to be in xz space, the field
The default setup by
The
Example 1 Draw a filled contour plot of the COSMO7 topography in indexspace.
c = addfile("lm_coarse/lfff00000000c.grb","r") hs = jmb_getvar(c, "HSURF", False) wks = gsn_open_wks("pdf", "topography") rc = jmb_set_ct(wks, "rainbow", False) cn = jmb_contour(wks, hs, rc) plt = jmb_overlays(wks, (/cn/), False)
jmb_vectorNOT DOCUMENTED YET
jmb_geographyDraw highresolution geographical information to an existing plot. Prototype
function jmb_geography(wks:graphic , plt:graphic, type:string, opt:logical) Arguments
Description
This function can be used to draw coastlines, national boundaries and rivers onto an existing plot. The return value corresponds to the graphic handles that contain the polylines and care should be taken that they are not destroyed before the plot is actually drawn. This can be tricky if the call to
The resource res can be used to control the amount of detail and the color of the coastlines, national boundaries and rivers, respectively. The attribute Example 1 Plot of the topography of Switzerland in native coordinates. Overlayed are coastlines and country borders in black and rivers in red.
f = addfile("lm_fine/lfff00000000c.grb", "r") h = jmb_getvar(f, "HSURF", False) wks = gsn_open_wks("pdf", "topography") rc = jmb_set_ct(wks, "rainbow", False) cn = jmb_contour(wks, h, rc) r = True r@rank = (/20,3,20/) r@color = (/"black", "black", "red"/) gg = jmb_geography(wks, cn, "cosmo2_ji", r) delete(r) plt = jmb_overlays(wks, (/cn/), False)
jmb_overlaysNOT DOCUMENTED YET
Utilities
meshgridx, meshgridyFunctions to generate 2dimensional cartesian grid coordinates from two vectors spanning the range on each axis. Prototype
function meshgridx( x[*]:numeric, y[*]:numeric ) function meshgridy( x[*]:numeric, y[*]:numeric ) Arguments
Description
These functions generate 2dimensional coordinate values of a regular, Cartesian grid specified by two axis vectors containing the values of the x, and yaxis respectively. These functions are inspired by their counterpart found in the Matlab software package. A simple application would be to generate the full rotated latitude and longitude coordinate arrays from the dimension values of a COSMO field (see Example 1). The return value is a 2dimensional array of the dimensions Example 1
f = addfile("lfff00000000c.grb","r") h = jmb_getvar(f, "HSURF", False) jmb_getgrid(f, f, h, False) rlat = meshgridx(h&rlat, h&rlon) rlon = meshgridy(h&rlat, h&rlon)
latlon2rlat, latlon2rlonFunctions to transform geographical latitudes and longitudes to rotated latitudes and longitudes. Prototype
function latlon2rlat( lat:numeric, lon:numeric, pollat[1]:numeric, pollon[1]:numeric ) function latlon2rlon( lat:numeric, lon:numeric, pollat[1]:numeric, pollon[1]:numeric ) Arguments
Description These functions compute the rotated latitudes and longitudes given a set of geographical latitudes and longitudes. Return values are of same type and dimensions as lat and lon arguments. The formulas for computation closely match the corresponding routines in the source code of the COSMO model. Example 1
f = addfile("lfff00000000c.grb","r") h = jmb_getvar(f, "HSURF", False) jmb_getgrid(f, f, h, False) rlat = latlon2rlat(h@lat2d, h@lon2d, h@pollat, h@pollon) rlon = latlon2rlon(h@lat2d, h@lon2d, h@pollat, h@pollon)
rlatlon2lat, rlatlon2lonFunctions to transform rotated latitudes and longitudes to geographical latitudes and longitudes. Prototype
function rlatlon2lat( rlat:numeric, rlon:numeric, pollat[1]:numeric, pollon[1]:numeric ) function rlatlon2lon( rlat:numeric, rlon:numeric, pollat[1]:numeric, pollon[1]:numeric ) Arguments
Description
These functions compute the geographical latitudes and longitudes given a set of rotated latitudes and longitudes. If rlat and rlon are more than 1dimensional, the return values are of same type and dimensions as rlat and rlon arguments. If rlat and rlon are 1dimensional, they are assumed to be vectors to span a 2dimensional cartesian grid. The return values have the dimensions Example 1
f = addfile("lfff00000000c.grb","r") h = jmb_getvar(f, "HSURF", False) jmb_getgrid(f, f, h, False) s = dimsizes(h) rlat = fspan(h@domain(0), h@domain(2), s(0)) rlon = fspan(h@domain(1), h@domain(3), s(1)) lat = rlatlon2lat(rlat, rlon, h@pollat, h@pollon) lon = rlatlon2lon(rlat, rlon, h@pollat, h@pollon)
swissxy2lat, swissxy2lonFunctions to transform CHcoordinates to geographical latitudes and longitudes. Prototype
function swissxy2lat( x:numeric, y:numeric ) function swissxy2lon( x:numeric, y:numeric ) Arguments
Description These functions compute the geographical latitudes and longitudes given a set of CHcoordinates. The return values have the same dimensions as the x and y arguments. The formulas for computation closely mathc the corresponding routines in the Ruby Library. Example 1
x = 618.847 ; 4419 Lupsingen, Im Budler 3 y = 255.238 lat = swissxy2lat(x,y) lon = swissxy2lon(x,y) print((/lat,lon/))
latlon2swissy, latlon2swissxFunctions to transform geographical latitudes and longitudes to CHcoordinates. Prototype
function latlon2swissy( lat:numeric, lon:numeric ) function latlon2swissx( lat:numeric, lon:numeric ) Arguments
Description These functions compute the geographical latitudes and longitudes given a set of CHcoordinates. The return values have the same dimensions as the x and y arguments. The formulas for computation closely mathc the corresponding routines in the Ruby Library. Example 1
f = addfile("lfff00000000c.grb","r") h = jmb_getvar(f, "HSURF", False) jmb_getgrid(f, f, h, False) s = dimsizes(h) rlat = fspan(h@domain(0), h@domain(2), s(0)) rlon = fspan(h@domain(1), h@domain(3), s(1)) lat = rlatlon2lat(rlat, rlon, h@pollat, h@pollon) lon = rlatlon2lon(rlat, rlon, h@pollat, h@pollon) x = latlon2swissx(lat, lon) y = latlon2swissy(lat, lon)
xy_to_ijFunction to transform points in a regular, deformed, 2dimensional coordinate system to index space. Prototype
function xy_to_ij( x[*][*]:numeric, y[*][*]:numeric, xy[*][2]:numeric ) Arguments
Description This function is used to transform a series of points living in the coordinate system of a deformed but regular 2dimensional grid to index space, thus a regular grid. The points are given by an array of (x,y)pairs of points. The return value is an array of (i,j)points in index space which has the same dimensions as xy. As an example, this function can be used to compute the location of arbitrary lat/lonpoints in index space (see Example 1). Example 1
f = addfile("lfff00000000c.grb","r") h = jmb_getvar(f, "HSURF", False) jmb_getgrid(f, f, h, False) latlon = (/ (/47.0, 3.0/), (/46.0, 2.0/) /) ji = xy_to_ij(h@lat2d, h@lon2d, latlon) print(ji)
ijkcoordsSets index space coordaintes for any 2dimensional or 3dimensional variable. Prototype
procedure ijkcoords( var:numeric ) Arguments
Description
This procedure overwrites the names of all dimensions to "k", "j", "i" for 3dimensional variables and "j", "i" for 2dimensional variables. Also, it sets the coordinate variables to a vector spanning the index space. For example Example 1
f = addfile("lfff00000000c.grb","r") h = jmb_getvar(f, "HSURF", False) ijkcoords(h)
charConvert a NCL string to a character. Prototype
function char(str[1]:string) Arguments
Description This function convert a string of only one letter to a character. This is useful, as the command stringtochar(str) would give you an array of 2 letters, the second one being the NULL termination character. Example 1
s = "t" c = char(s)
strcmpwildCompare a string possibly containing a wildchard character "*" against an array of strings and return all matching strings. Prototype
function strcmpwild(ssearch[1]:string, str[*]:string) Arguments
Description This function will return a array of strings containing all those strings of str which match the search string ssearch. The wildcard character in ssearch can be anywhere (start, middle, end) of the string. If no matchin string is found the return value will contain only missing values. Example 1
s = (/"Apple Pie","Pear Pie","Cat Food","Fruit Pie","Elephant"/) a = strcmpwild("* Pie",s) if (.not.all(ismissing(a))) then print(a) end if
startcapCapitalize the beginning of each word in a string. Prototype
function startcap( s[1]:string ) Arguments
Description
This function will return a string as a return value where all words in s have been capitalized. This can be useful for making nice labels in a plot, as usually long names are given in smallcaps. Note that the handling of special characters is not very elaborate, e.g. Example 1
s1 = "function(argument)" s2 = "the quick brown fox jumps over the lazy dog" print(startcap(s1)) print(startcap(s2))  OliverFuhrer  28 Jan 2009
Attach
