MVLib - Short Writeup - Version 4.0
Graphic routines - Last update: June 2013
Source code available for local users only
Overview
MVLib graphic routines provide an easy-to-use fortran interface to NCAR-GKS package and include many tools allowing several graphic output. Essentially the user may call different routines producing different output on a same plot; this sequence of graphic tools always end with a call to displayplot subroutine that actually displays the plot or produces a file in different graphic format. To make clearer this documentation the different graphic routines are listed in different sections, at each section a blocks of routines are described. In the first block the general pourpose routines are listed and described; this routines allow to manipulate graphic format and produce particular graphic results as the the animated gif, these routines are usually called a the end of a sequence of graphic tools. In the second and third blocks the specific routines for 1-D and 2-D plots are listed and documented. Section 4 and 5 list the specific routines to plot bidimensional fields of MM5 and CHyM model respectively; in the last section the subroutines to create histograms are documented.
Section 1. Manipulate GKS environment and produces different graphic output
displayplot(filename,title,stitle)
oldname produciplot
Close the GKS environment and produce the graphic file specified by the first argument; the extension of filename will be used to establish the format of graphic file. If the first argument is an empty string, the plot is displayed by an X11 window and the temporary file will be deleted when the window will be closed. title and stitle are two input string specifying a title and a subtitle that will be added to the current plot.
visualizzaplot(titolo,sottotitolo) Close the GKS environment and display the current plot by an X11 window and the temporary file will be deleted when the window will be closed. title and stitle are two input string specifying a title and a subtitle that will be added to the current plot.
viacolvento(inputfiles,outputfile) Create an animated gif called outputfile from the input file specified by wildcard (*) as the first argument. This routine is accected by the MVLiB parameter "Distruggi fotogrammi, establishing wheter or not the input files are deleted after the animated gif is created.
checkifgksisopen Check if NCAR GKS environment is open, if not this rpoutine open it.
apriilgks(iflg) Open NCAR GKS environment. The routine is usually called by macro graphic routine. If the iflg=1 graphic environment is opened to plot MM5 map.
chiudiilgks Close NCAR GKS environment. The routine is usually automatically called by visualizzaplot or produciplot routine right before to produce the plot.
Section 2. - Creating one-dimensional plots
The user can add data to be plotted with a sequence of call to plottaxy or plottay routines, after all the data have been passed, the subroutine plotta must be called to actually paint the curve. The sequence can be repeated several times to produce a plot with several curves. If the data to be plotted are stored in arrays or vectors, the user may call the routines plottav or plottavw. The subroutines plottaframe and plottaborder allows to fix the X/Y scale before to paint the curves. See also the examples 5 and 14.
plottaxy(x,y) The point of coordinates x and y is stored in the MVLib internal arrays and will be plotted by the next call to the routine plotta.
plottay(y) The point of coordinates y is stored in the MVLib internal arrays and will be plotted by the next call to the routine plotta, the coordinate x is assumed to be a sequence of integer whose first value is 1.
plotta(desc) Plots a curve with the data stored in the MVLib internal arrays by the previous sequence of call to plottay and/or plottaxy routines. The string desc will be written on the plot to create a short legend, this is useful if several call to this routine are carried out to plot several curves. If this routine is called after only 2 calls to plottay and/or plottaxy routines, no curves are plotted but only the ranges of x and y axis are set; the maximum and minimum of these range are also set picking easy values.
plottav(y,n,desc) Plots the n components of vector y, the string desc will be written on the plot to create a short legend, this is useful if several call to this routine are carried out to plot several curves. The color of the curve is affected by the value of MVLib parameters Colore Plotta, if this value is negative (default) a different color is used to plot each curve.
plottavw(x,y,n,desc) Plots a curve of n points with the coordinate specified by the real vectors x and y, the string desc will be written on the plot to create a short legend, this is useful if several call to this routine are carried out to plot several curves. The color of the curve is affected by the value of MVLib parameters Colore Plotta, if this value is negative (default) a different color is used to plot each curve. If this routine is called with only 2 values (n=2), no curves are plotted but only the ranges of x and y axis are set; the maximum and minimum of these range are also set picking easy values.
plottaframe(xmin,xmax,ymin,ymax) This routine can be called before the routines plottaxy, plottay, plottav or plottavw in order to set the ranges of x and y axis. The same action can be carried out calling plottaviw with only only two components of input vectors; the difference is that plottaframe allows to user to exactly set the ranges of x and y axis, while plottaviw set this limit to easy values close to the values provided by the users.
plottaborder(x1,x2,y1,y2) This routine can be called before the routines plottaxy, plottay, plottav or plottavw in order to set the portion of the graphic space that will be used to produce the next plot, the arguments must be in the range 0-1, you may want to give a look to example 23 to easily understand how it works.
meteogrammi(x,y,ndim,ncurves,npunti,assey) meteogrammi is a simple interpahe to autograph package of NCAR GKS library. x(ndim) is a vector with the vlaues of X axis; y(ndim,ncurves) contains the values to track different curves. The string desc will be written on the plot along the Y axis.
plottailmese(x,y,ndim,ncurve,npunti,assey) Identical to meteogrammi, the arguments are the same, but the plot is splitted in three decades, X axis is supposed to represent the monthtime.
monthlyplot(x,y,ndim,ncurve,npunti,ymin,ymax) Identical to plottailmese, but in this case the last two real arguments allow to fix the minimum and maximum of y axis for all the three dacades.
labelsuassex(x,label) labelsuassex allows to customize the labels on X axis. Before to call plotta and othe routines for 1-D graphics you have to set the MVLib internal parameter "Asse X" to 3 as a consequence the label will not be written on X axis. After the call to different graphic routine you may want to add customized labels; as an example:
       call labelsuassex(2.0,'tuesday')
       call labelsuassex(3.0,'wednesday')
       call labelsuassex(4.0,'thursday')
will add the name of the weekday on X axis.
labelsuassey(y,label) Identical to labelsuassex but acts on Y axis, in this case you have to set the MVLib internal parameter "Asse Y" to 3.
Section 3. - Creating 2-dimensional plots
boxplot(xm,m1,m2,xlv,xfv,n1,n2,leg) boxplot allows two produce a two-dimensional plot using the data stored in the real xm(m1,m2) array. xlv and xfv are the lower and the higher value that must be considered; the two integer n1 and n2 specify the range of color indexes that must be used. The last argument is and empty string or it is a vector of string that will be used to produce a label bar.
boxzoom(xm,m1,m2,i1,i2,j1,j2,xlv,xfv,n1,n2,leg) Same as boxplot but in this case only a portion of xm input array is plotted. The portion to be plotted is specified by the the four integer parameter i1,i2,j1,j2.
boxnumber(xm,n1,n2,xlv,xfv,format) Same as boxplot but in this case the values of xm real array are written on the plot.
boxzoomnumber(xm,n1,n2,i1,i2,j1,j2,xlv,xfv,format) Same as boxnumber but in this case only a portion of xm input array is written. The portion to be written is specified by the the four integer parameter i1,i2,j1,j2.
boxarrow(m,s,n1,n2,iflag) An array of arrow is produced using the value contained in the integer matrix m(n1,n2) and real matrix s(n1,n2). The last argument is an integer specifying the behaviour of the routine with the following meaning:
  • flag=1. The arrows are plotted from the integer values specified by the integer array m(n1,n2) following the legenda adpopted within CHyM model, namely 1=North, 2=North-East, etc.
  • flag=any-other-value. Nothing is plotted, this is for future development
This routine is also affected by the MVLiB parameter Stile Freccette and Colore Freccette.
boxzoomarrow(m,s,n1,n2,i1,i2,j1,j2iflag) Same as boxarrow but in this case only a portion of input arrays is plotted. The portion to be plotted is specified by the the four integer parameter i1,i2,j1,j2.
boxlegend(xlv,xfv,n1,n2,format) This routine allows to create a labelbar as legend of the colours used by boxplot. The first 4 aurguments are the same passad to boxplot, the last argument is a string specifying the format to be used to print the label values.
contorni(v,ixm,jxm,ix,jx) Allows to produce a contour plot with the values of the array v(ixm,jxm) the integer arguments ix and jx specify the portion of the matrix to be used, namely only the values of v(1:ix,1:jx) will be used to produce the plot. See the example 29
setgeobounds(slon,elon,slat,elat,xc,yc,xys) The routine settageobounds is usually called before boxplot etc., in order to correctly set the boundaries of the plot in a suitable way, such that a same graphic size corresponds to same geographical distance. The real parameters slon, elon, slat and elat specify the lat/lon limit of the current geographical domain. The real input variables xc and yc specify the center of the next plot (in the range 0-1), The real input variable xys specify the size of the plot (it should be in the range 0.4-0.8).
settaiconfini(slon,elon,slat,elat) The routine settaiconfini is equivalent to settageobounds, but it assumes default values for the size of the plot, namely xc=yc=0.5 and xys=0.8.
boundaries(slon,elon,slat,elat,rpro) The subroutine boundaries allows to superinpose to the current plot, the geographical or political boundaries. The real parameters slon, elon, slat and elat specify the lat/lon geographical limits of the domain. The integer flag rpro specifies the type of boundaries to be plot, with the following meaning:
  • 1 Political boundaries of italian regions
  • 2 Political boundaries of italian provinces
  • 3 Political boundaries of Italy
  • 4 Geographical boundaries of Europe
  • 5 Geographical and political boundaries of Europe
  • 6 Geographical boundaries of World
  • 7 Geographical and political boundaries of World
  • 8 Geographical and political boundaries of World
  • 9 Administrative boundaries of Parco Nazionale d'Abruzzo Using rpro=1 or 2, also the main towns of regions/provinces are written on the plot, if you do not want this, set to zero the MVLib parameter "boundaries behaviour".
  • scatterplot(zlat,zlon,nz) Allows to create a scatter plot using the nz component of real vectors zlat and zlon passed as argument. See also the example 36.
    worldplot(rain,nlon,nlat,title,stitle,opt) Allows to plot the matrix mat(nlon,nlat) on the wordl surface. title and stitle are the two titles of the plot, while opt is a string specifying different options with any combination of the following characters:
    • d To activate the display of the plot
    • l To activate the display of the label bar
    • cXX To set the boundary flag to XX (range 1-12)
    • pXX To select the color palette number XX
    • mXX To set the minimum value of plot to XX
    • MXX To set the maximum value of plot to XX
    If a wrong character is passed to the subroutine an error message containing all the valid options is displayed. See also the example 08.
    atlante(slon,elon,slat,elat,id,ip,if,ic,if) The subroutine atlante allows to plot the Digital Elevation Model for an arbitrary geographical domain. The first four real parameters specify the limit of latitudes and longitues; the other five flags allows to add other layers to the plot, as specified below:
    • id If activated (> 0) the DEM map is plotted
    • ip Specify the boundaries to be plotted (see above the description of subroutine boundaries.
    • if If activated (> 0) the main river as rebuilt by CHYM model ar superimposed to the plot.
    • ic If activated (> 0) the main town are superimposed to i the plot.
    • if Not yet used, it is for future development.
    See also the example 28.
    Section 4. Graphic utilities for CHyM model
    See the CHyM Libraries documentation page
    Section 5. Graphic utilities for MM5 model
    mm5colormap(field,ixm,jxm,ix,jx,palette) Produces a colormap with the values of the array field(ixm,jxm) passed as first argument, ixm and jxm are the dimension of the array, while ix and jx are the component that must actually be used to produce the plot; this means that user have not to change the dimension of the array when working with different MM5 output file. The last argument is a string specifying the colour palette to be used, it can be:
    1. one of the predefined palette: temperatura, temperatura.estate, temperatura.inverno, temperatura.primavera, temperatura.autunno, escursione.termica, orografia.colore, orografia.grigia, vento, vento.forte, vento.grigi, vento.kmh, pioggia, nuvole
    2. the specification of a file containing a customized palette. Note that in this case the backslash must be included in the file path, as an example './mypalette.tbl'. You may to create your own tbl file with the creatbl utility descript below.
    3. An empty string. In this case a temporary tbl file is automatically created using creatbl routine described below.
    See also the description of mm5colorlevels below to see how to select contur levels. See also the examples 01 and 04.
    mm5colorzoom
    (field,ixm,jxm,lat1,lat2,lon1,lon2,palette)
    It works exactly as mm5colormap subroutine, but it allows to plot a subdomain. The integer input parameters lat1, lat2,i lon1 and lon2 specify the grid point interval to be considered Pay attention that it must be:
    lat1 < lat2 < mif(104,1)-1
    e
    lon1 < lon2 < mif(105,1)-1
    being mif(104,1) and mif(105,1) respectyively the number of latituds ans longituds of the of MM5 grid.
    mm5colorlevels(lmeth,rlevels) mm5colorlevels routine allows to specify the method to use when determining contour levels for mm5colormap and mm5colorzoom routines. lmeth is an integer flag, rlevels is a real vector. Choices for integer parameter lmeth are:
    • lmeth = 0. mm5colormap picks everything (defaults) and rlevels is not used.
    • lmeth = -1. A contour interval is given to use between a given contour minimum and a given contour maximum. levels(1) is the contour interval, levels(2) is the contour maximum and levels(3) is the contouri minimum.
    • lmeth = -2. A contour interval is specified, levels(1) is that contour interval. mm5colormap picks the contour minimum and maximum.
    • lmeth > 0. lmeth is the number of levels the user wants, levels is ignored.
    • lmeth < -2. abs(lmeth)-2 is the number of levels the user wants. Each level is specified individually in levels.
    createtbl(xmin,xmax,ipal,filename) Create a tbl file called filename suitable as input for mm5colormap routine. If filename is an empty string, the file is called tbl.tmp and it is usually deleted at the end of the excution of csh script. ipal specify the palette to be used and xmin,xmax are the expected values of maximum and minimum for the matrix to be plotted. The routine works also if the gks environment is already open but in this case ipal value is ignored and the current palette is used to produce the tbl file.
    mm5contorni(v,ixm,jxm,ix,jx) E' identica alla subroutine contorni, ma produce il grafico invertendo il significato degli indici. Questo consente di passare direttamente i campi vettoriali di mm5 che hanno come prima dimensione la latitudine (ovvero l'asse y).
    mm5freccette
    (u,v,lat,lon,ixm,jxm,kxm,ix,jx)
    Sovrappone al grafico corrente le "freccette" con intensita' e direzione del vento. I vettori u e v contengono i venti, lat e lon la griglia su cui sono definiti i campi u e v, ix e jx sono le componenti dei vettori effettivamente definite (nel senso che per esempio, il numero di di latitudini e' ix mentre il vettore e' dimensionato ixm). Il vettori si intendono dimensionati u(ixm,jxm,kxm) v(ixm,jxm,kxm) lat(ixm,jxm) e lon(ixm,jxm).
    mm5freccetelle
    (u,v,,ixm,jxm,kxm,ix,jx)
    Identica alla precedente, ma vengono plottate le freccette anziche' le wind barbs.
    mnuoviconfini('specifica') Se chiamata dopo la mm5freccette, mm5contorni, mm5colormap o mm5colorzoom permette di aggiungere dei confini arbitrari. La stringa passata puo' essere 'Fucino', 'Abruzzo', 'Italia' (non importa minuscolo o maiuscolo) oppure la specifica di un file (ad es.: './miofile.dat'), in cui esiste la sequenza di lat, lon e flagpennino, nel formato: (2f10.4,i3)
    La size della curva e' regolata dal parametro: "Size delle Linee"
    Section 6. Macros and Graphic Primitives
    fammiilcontorno(icol) Allows to add a frame to the current plot, the integer argument specifys the colour to be used.
    legend(x,y,mag,col,str) Allows to add a color based legend on the current plot. The first two real arguments specify the x-y position on the plot (0-1 coordinates system), the third integer argument is magnification factor, the fourth integer argument specifies the color and the last argument is a string specifying the meaning of the color. See also the example 14.
    pallocchetto(xc,yc,r,ic) The subroutine pallocchetto allows to plot a "pallocchetto" like this , xc and yc specify the graphic coordinate (0-1) of the center of the "pallocchetto" and the integer ic specify the color. See the example 13 to understand how it works.
    rettangolino (xc,yc,xl,yl,ic) The subroutine rettangolino allows to plot a coloured frame like this , xc and yc specify the graphic coordinate (0-1) of the center of the frame, xl and yl specify the size of the rectangular area; the last integer argument specfies the color of the frame. See the example 13 to understand how it works.
    triangolino (xc,yc,xl,ic) The subroutine triangolino allows to plot a triangle like this , xc and yc specify the graphic coordinate (0-1) of the center of the triangle, xl specify the lenght of each side; the last integer argumentr specfies the color of the frame. See the example 13 to understand how it works.
    freccia(xc,yc,xl,angle,ic) Paint an arrow like the following in the point specified by the coordinates xc and yc. The graphic coordinates must be specified in the range (0-1) and will corresponds to the center of the arrow. angle is direction specified as the angle respect to the nord direction in the clockwise direction, ic is an integer code specifying the color of the arrow. This routine is affected by MVLib parameter Stile freccia
    scrivisulplot(str,x,y) Writes on the plot the string specified by the first argument, x ed y specify the graphic coordinates, these coordinates are affected by the flag Coordinate Grafiche. If a "complex string" including special characters has to add to the plot see also the description of complexchar routine described below.
    complexchar(x,y,str,size,ang,ali) Writes on the plot the string third argument on the plot; the first two real arguments specify the graphic coordinates (0-1 system); the last three real arguments respectively specify the size, the angle and the alignement.
    contorno(x,y,npt,flag,colore) It allows to plot an arbritrary curve (flag=0) or a solid geometric contour (flag=1). The real vectors x and y specify the sequence of coordinates and npt specifies the number of points. The last argument colore is an integer value specifing the color to be used. If the graphic layout is already setted this routine allows to plot an arbitrary boundary in the geographic domain.
    plotpalette(xy,flag,v,s,n) plotpalette(xy,flag,v,s,n) allows to plot a color bar like the following:
    v and s are two vector of n components containing respectively color indexes (integer) and the description (string) of each element of label bar. The character flag flag can be 'v' or 'h' to specify if the label bar must be placed in the horizontal or vertical direction, an other valid option is also 'H', in this case the label bar is produced in the horizontal direction, but its size corresponds to the size of the current plot, as shown in the example 45. xy is a real value in the range (0-1) specifying the horizontal (or vertical) coordinate where label bar must be placed, this is ignored if the flag is 'H'.
    mvsetplotframe(x1,x2,y1,y2) Allows to select the portion of the plot in the range 0-1 that will be used to produce next plot. It is equivalent to set the values of 4 MVLib parameters: "x left", "x right", "y bottom" and "y top".
    mvlibsignature Produces a title on the right part of the plot with the MVLib signature.
    Section 7. Histograms, statistics and Cellular Automata
    windroseplot(rq,rf,nsec,nent) Allows to plot the wind roses created with windrosebook subroutine. See, as an example, the example 24 and the documentation of mvbook package.
    mvbookplot (id) Allows to plot histograms created and manipulate with mvbook package. See, as an example, the example 20 and the documentation of mvbook package.
    cellularplot(mat,m,n) Create a cellular plot with the real array mat(m,n) passed as argument. If the MVLib flag Cellular Step is zero (default) the matrix is intended to contain analogic values, otherwise it is intended to contain binary values (0 or 1). See also the example 34.
    cellularplotrule(iflag) If the integer flag passed as first argument is 1, this routines displays two plots containing the naming of Cellular Automata rules; otherwise it displays a plot with the Cellular Automata rules defined at current step. See also the example 34.
    autocorrplot(x,n,y,maxlags) Calculates and plots the autocorrelation of the data series passed in the vector x of n components, the last integer maxlags specifies the number of legs to be considered; the results are saved in the first maxlags components of real vector y. See also the example 35.
    taylorplot(xc,yc,mag,sdev,corr,col,leg,n) Produces a taylor plot correlation versus standard deviation.
    • xc and yc are the coordinates of the center of the plot, in the range 0-1
    • mag is a real specifyng the magnification factor (tipically around 1.0)
    • sdev is a real vector containing the values of standard deviation
    • corr is a real vector containing the values of correlation
    • col is an integer vector containing the code of the colors to be used, if the code is greater than 100, a triangle (instead of a bullet) is painted to represent the point; if the code is greater than 200, a rectangle is painted to represent the point.
    • leg is character vector containing the label of each point, the labels are not produced if an empty is passed for this argument.
    • n is an integer specifies the number of points to be painted in the plot.
    See also the example 42.