MVLib - Short Writeup - Version 4.0
Routines to retrieve data from MuSEO database - Last update: October 3, 2013
Source code available for local users only
High level interface to NetCDF files
netcdf2mv(file) Produce, in the standard output, full information about the netcdf file passed as argument.
readnetcdfrec(file,field,rec,mat,nlon,nlat) Returns in the real array mat(nlon,nlat) the record specified as third integer argument of the field specified by the second integer argument; the netcdf file is specified by the first input character argument. If the number of record is less or equal to zero, the previous opened file (if any) is closed and other arguments are ignored.
chkncstatus(istatus,nf_noerr,field,dir,cfl) The subroutine allows to check if the last call to netcdf library was successfully completed.
The first integer argument is the integer code retrieved from the last netcdf called funtion.
General Pourpose Routine to access MuSEO files
museodir(dir) Returns in the string passed as argument the path of the main directory where the museo database is located. For the platforms where MuSEO is system-wide installed, this path is usually /usr/local/museo/
openmuseofile(iunit,database,flag) Open the unit iunit with the file specified as second argument. If unit has a negative value the first free unit is used and its number is returned as output value. Of course in this case iunit must be provided by reference and not by value. Third argument specify if the file is formatted (1 or 3) or binary (0 or 2). The status of the file will be unknown if the flag is greater than 1 otherwise "old". Examples: 
	call openmuseofile(10,'comuni.lazio',1)
Open unit 10 with the file containing the list of "Lazio" database sensors. 
	iunit=-1
	call openmuseofile(iunit,'demlakes.bin',0))
Open the first free unit with the bynary file demlakes.bin usually demlaghiupd
openmuseodb(iunit,database,year) Open the logic unit specified by integer parameter iunit col file corrispondente al database specificato dal secondo argomento, il terzo argomento è un intero che specifica l'anno.
Se iunit è negativo la routine cerca automaticamente una unità libera che viene restituita nella stessa variabile, attenzione che in questo caso l'argomento va passato come variabile e non come valore.
The string database specify one of the following database: arssa, iira, lazio, MonteMidia, idrografico, Po, pioggiaoraria, temporaria, Micra, wrf, dewrain, worldrain, acqwarhone, acqwapo, 0100_eraint.dat, mm5con, mm5hum, mm5nuv, mm5pre, mm5rai, mm5t2m, mm5ugr, and mm5vgr. The integer parameter year specify the year and, for mm5 model, it must also contain information about the operational domain, as an example to open data base of domain 3 for year 2006, the parameter year must be 20063.
Examples: 
	call openmuseodb(10,'iira',2006)
open logic unit 10 with the file containing data of IIRA for year 2006. 
	call openmuseodb(15,'mm5pre',20052)
open logic unit 15 with the file containing data of pressure fields simulated by MM5 model on operational domain 2 for year 2005. 
	
	iunit=-1
	call openmuseodb(iunit,'lazio',2009)
Find a free logic unit and open on this unit the file containg the data for lazio meteorological observation for year 2009. The value of used logic unit is passed back in iunit integer parameter.
skipandreadgame(lun,crec,prec,flag) Allows to easily manage the records of the file opened in the logic unit lun. The second argument crec is the record you have to read, the third integer argument prec is the last record you read. The last integer flag specifies if the file is binary (0) or ascii (any other value). The routine will skip the right number of records and after this call you can read the selected record. Note that the value of prec is automatically updated and therefore you have to pass it by name (not by value).
integer function numberoflines(lun) Gives the number of lines of the ascii file opened with logic unit lun . I/O unit is rewind al the end of the routine execution.
demnasa(lat,lon,unit,file) It allows to open the NASA Digital Elevation Model data base. The first two real arguments correspond to the latitude and longitude of the lower left corner of the geographical domain. If the third real argument is greater than zero this logical unit is opened with the selected file, otherwise the MuSEO filename is returned in the last string argument.
Routines to access meteorological observation time series
nrectimeseries(db) nrectimeseries is an integer function returning the number of records contained in the database specifyed as argument. Valid arguments follow: "'iira', 'lazio', 'arssa', 'portateiira', 'Po', 'dewetra', 'dewrain', 'dewtemp', 'acqwarhone', 'acqwapo'; with other strings passed as argument this function returns zero.
museoanagrafica(db,rec,com,sens,xlat,xlon) Allow to access the information for the record rec of database db. db is a string containing 'iira', 'lazio, 'arssa', 'acqwa', 'acqwa1' (dati meteo sul bacino del Po), 'rhone', 'rhonemeteo', or 'portateiira'. The input integer parameter rec allows to specify the record, if this number is outside the range for the selected database, an error message is produced on standard output. As output the string com will contain the name of the town where sensor is located, the string sens will contain the sensor type (as an example "Termometro Aria"), the real variables xlat and xlon will contain the latitude and longitude where the sensor is located. See also the examples 7 and 20.
museotimeseries(db,rec,year,x,y,n) Allow to access the time series contained in the record rec for data base db for the year year. rec and year are integer, db is a string containing 'iira', 'lazio', 'acqwa1', 'rhonemeteo' or 'arssa'. As an example 
        call museotimeseries('iira',207,2009,x,y,n)
will retrieve the complete time series for 2009 of record 207 of IIRA (Istituto Idrografico della Regione Abruzzo) database. The time series will be stored in the vector y dimensioned at least 366*24*4. The vector x will contains the corresponding julian day, the last component actually avaibale is passed in the integer variable n. See also the examples 7 and 20.
Components of y that are not available will contain -9999.0. The component of the vector containing -9999.0 can be cleaned using cavectorfill routine described in the Cellular Automata section. In any case it is very simple. After to call museotimeseries as above described, simply give: 
        call cavectorfill(y,wk1,wk2,n)
being wk1 and wk2 two vectors dimensioned as y. If you pass rec=0 museotimeseries routine will provide a table to standard output where the number of components for each record is displayed.
iiraflowdis(staz,year,nyear,flow) iiraflowdis (by Annalina Lombardi) allows to retrieve the historical time series of flow discharge in the Abruzzo region. The input string variable staz must contains the specification of station name or an integer specifying the requested location in the range 1-54, in this case the string will contain as output the station name. year is a positive integer specifying the year or a negative integer specifyng the requested record, in this case the variable will contain as output the year corresponding to the requested record. If staz or year contain, as input, a wrong value, the list of valid values are provided. nyear will contain as output the number of valid years for the requested data. The real vector flow(366) will contain as output the daily flow discharge time series. Examples: 
	call iiraflowdis('Salinello a Cavatassi',2004,nyear,flow)
will retrieve the data for year 2004 for the specified location. The sequence: 
	loc='4' ; year=-2
	call iiraflowdis(loc,year,nyear,flow)
will retrieve the data for the second record of location number 4.
Routines to access hourly temperature and precipitation archives
hourlyrain(hour,day,month,year,p,lat,lon,n) Ritorna i dati delle stazioni pluviometriche provenienti da diversi data base ed integrati in un unico formato. ih,ig,im,ia sono 4 interi che specificano rispettivamente ora, giorno, mese ed anno. p,lat,lon,n sono le variabili di output. p è un vettore che conterrà la pioggia (mm) misurata in quell'ora, lat,lon sono i due vettori che conterranno latitudine e longitudine delle varie stazioni, mentre n è un intero in cui viene memorizzato il numero di stazioni disponibili per quello step temporale. Si noti che vengono restituiti tutte e solo le misure effettivamente disponobili, quindi n cambia parecchio, ma per i giorni di cui abbiamo i dati di entrambi gli enti ci sono almeno 70 misure tra abruzzo e molise. Per una rappresentazione solo grafica dei dati potete copiarvi ed utilizzare l'utility: hourlyrain (invocando lo script con l'opzione -help vi dice come si usa).
hourlytemp(hour,day,month,year,p,lat,lon,n) E' identica alla precedente, ma restituisce le temperature. L'utility per la visualizzazione dei dati è:
/utenti/verdecch/miosw/2museo/hourlytemp
(invocando lo script con l'opzione -help vi dice come si usa)
worldrain(hour,day,month,year,p,lat,lon,n) Similar to the previous routines, it returns all the observed precipitations for the rest of the world (not Italy).
worldtemp(hour,day,month,year,p,lat,lon,n) Similar to the previous routines, it returns all the observed temperatures for the rest of the world (not Italy).
acqwascen01(hour,day,month,year,flag,p,lat,lon,n)
acqwascen02(hour,day,month,year,flag,p,lat,lon,n)
acqwascen03(hour,day,month,year,flag,p,lat,lon,n)
acqwascen04(hour,day,month,year,flag,p,lat,lon,n)
acqwascen5a(hour,day,month,year,flag,p,lat,lon,n)
acqwascen5b(hour,day,month,year,flag,p,lat,lon,n)
acqwascen6a(hour,day,month,year,flag,p,lat,lon,n)
acqwascen6b(hour,day,month,year,flag,p,lat,lon,n) 		Similar to the previous routines, these subroutines return the temperatures and precipitations from ACQWA scenario 01, 02, 03, 04, 5a, 5b, 6a and 6b. See also the complete description of such routines and related scenarios here.
Routines to access Radar precipitation estimation
montemidiamap(rec,year,rain,n) Give in the output matrix rain(480,480) the map of estimated precipitation from Monte Midia radar. The input variable rec specifies the record number ranging from 1 (january, 1 h: 00) to 8760 (December, 31 h: 23). To calculate rec index you may want to use the routine index1h. As an example 
	call montemidiamap(index1h(7,20,6,2010),2010,rain,n)
provide the data correspondig to June, 20 2010 h: 07. Please note that also the year must be specified to index1h routines because hourly index is different for leap years. As output the variable n will contains the number of grid points where the precipitaion is greater than the threshold of 1 mm/h. If n is -1 means that no data are available for that record.
montemidiavec(rec,year,v1,v2,v3,n) Is similar to montemidiamap routines, but provide the data in vectorial form. As output the vectors vi, v2 and v3 will contain the values of precipitation, latitudes and longitudes respectively. Se the documentation about montemidiamap routines for the description of rec, year and n variables. The vectors vi, v2 and v3 must be dimensioned at least 179364, these are the number of grid points inside radar range.
montemidiagrid(i,j,ylon,ylat,map) Dati gli indici della mappa i e j rispettivamente longitudine e latitudine restituisce il corrispondente valore della longitudine e latitudine nella variabili ylon e ylat. map è un intero che conterrà in uscita 1 se il punto si trova all'interno del dominio di visibilità del radar, altrimenti il suo valore sarà 0.
Routines to access ModIS archive
snowfrommodis(rec,year,modis,nlon,nlat,n1,n2,slon,elon,slat,elat) Allows to retrive the data of ModIS archive. The first two integer input arguments specify the julian day and the year. The real output array modis(nlon,nlat) must be dimonsiened at least (3458,2529) and it will contain, as output, a coded value with the following meaning:
  • 0 data missing
  • 1 no decision
  • 11 night
  • 25 no snow
  • 37 lake
  • 39 ocean
  • 50 cloud
  • 100 lake ice
  • 200 snow
  • 254 detector saturated
  • 255 fill
Integer output arguments n1,n2 and real output arguments slon,elon,slat,elat can be ignored in the current version but, for fucture generality they will respectively contain the grid of the array, currently (3458,2529), and the boundary of the geographical domain, in the current version the value are always slon=6.3600 ; elon=21.9210 ; slat=36.3095 ; elat=47.6900. The spatial resolution of the grid is:
(elat-slat)/(n2-1)=(elon-slon)/(n1-1)=0.0045 deg.
See also the example 37.
Routine to access the archive of ERA data
eraheader(lun,hour,day,month,year,lat,lon) Allows to open the file of ERA data base containing the global precipitation for the hourly time step specified by hour,day,month,year arguments. lun is the I/O unit to be used, if it is less than zero the first free I/O unit is used and its value is passed back to the caller. The matrix lat,lon will contains as output the values of latitudes and longitudes in the range (-90,90) and (-180,180). Matrix is dimensioned 480x241. Data is currently available from 1989 to 2005.
eradata(lun,hour,day,month,year,rain) Allows to retrieve in the matrix rain the field of global rain at the hourly time step specified by hour,day,month,year arguments. Matrix is dimensioned 480x241 lun is the I/O unit to be used, if it is less than zero the first free I/O unit is used and its value is passed back to the caller, in this case the routine eraheader is also automatically called. Global precipitation field is from ERA-Interim reanalysis data described at URL http://www.ecmwf.int/publications/newsletters/pdf/119.pdf. Data is currently available from 1989 to 2005.
erashiftlon(mat,nlon,nlat) This routine is usually called by eradata and/or eraheader routines. It allows to shift the longitudes of matrix mat from the range (0,360) to the range (-180,180).
eralat(i,j)
eralon(i,j)		 These two real functions respectively return the latitude and longitude of of the grid point specified by the input integer i and j. In other words these functions gives the coordinates of the grid points of matrix rain retrieved using eradata routine listed above. Longitude index i must be in the range 1-480, latitude index j must be in the range 1-241, lat/lon resolution is 0.75 deg.
Routines to access WRF fields archive
wrfrainv(hour,day,month,year,dom,pi,la,lo,n) Allows to retrieve the precipitation fields predicted by WRF model, data are available since the end of 2012. The first 4 integer input arguments specify the time at hourly resolution, the integer flag dom specifies the geografical domain (1 or 2); the output vectors pi,la and lo will contain the values of precipitation and the corresponding values of latitudes and longitudes.
Routines to access MM5 fields archive
museomm52d(fld,iy,im,ig,ih,id,v,xlat,xlon,ixm,jxm,lix,ljx) Restituisce un campo 2D delle simulazioni di mm5 dal Database di MuSEO. Il significato delle variabili è il seguente
fld A three characters string specifying the field
  • nuv - Cloudness
  • rai - Accumulated precipitation (cm)
  • con - Accumulated convective precipitation (cm)
  • t2m - 2 meters temperatrure (K)
  • ugr - Ground wind, zonal component
  • vgr - Ground wind, meridional component
  • pre - Sea level Pressure (mb)
  • hum - Ground relative humidity (%)
Fields for convective precipitation, pressure and relative humidity re available since March 2002.
iy,im,ig Three integer input parameters specifying year, month and and day respectively.
ih An integer in the range (1-24) specifying the daytime. Please note that:
  • the routine actually retrieves the data at hour ih-1 (first time slice is at midnight);
  • MM5 timing corresponds to GMT;
as a conseguence ih actually corresponds to italian time (CET) during wintertime and one hour later during daylight saving time (DST). If ih=0 is passed to this routine, thw whole day is returned, of course in this case the v array must be dimensioned (ixm,jxm,24) instead of (ixm,jxm). If a negative value of ih is passed to the subroutine a number of time slice correspoinding to abs(ih) are retrieved. Finally the precipitation fields are stored as accumulated rain, with the first time slice corresponding, by definition, to a zero field; in this case the v array must be dimensioned (ixm,jxm,25) and the precipitation in a selected range of hours (say ih1-ih2) can be obtained by substracting (ixm,jxm,ih1) from (ixm,jxm,ih2).
Se devi leggere la pioggia passa ih=-25!!!!!!!
id An integer specifying the operational domain in the range (1-3)
v A real array dimensioned (ixm,jxm) or (ixm,jxm,24) (see above the description of ih input parameter that will contain, as output, the retrieved fields.
xlat,xlon Two arrays dimensioned (ixm,jxm) that will contain, as output, the latitudes and longitudes for each grid points.
lix,ljx Two integer parameters that will contain, as output, the number of latitudes lix and longitudes ljx that are actually stored in v, xlat and xlon arrays. Note that lix=ljx=0 if the selected field is not available.
museomm52dw(iy,im,ig,ih,id,u,v,lat,lon,ixm,jxm,lix,ljx) Similar to museomm52d, but both zonal and meridional component of wind are retrieved in arrays u and v.
mm5basefld(fld,dom,dum,ixm,jxm,ix,jx,err) Retrieves in the array dum(ixm,jxm) one of the static field used in the operational run of MM5 model for the Central Italy. The input character variable fld specify the field to be retrieved and can assume one of the following values: 'land use', 'terrain', 'latitdot', 'longidot', 'latitcrs', or 'longicrs'. dom is an integer specifying the operational domain in the range (1-3). The two integer parameters lix and ljx will contain, as output, the number of latitudes and longitudes that are actually stored in dum array. The integer variable err will contain as output a flag error: 0=Ok, 1=fld string is incorrect, 2=dom integer is not within the correct range, 3=error opening MuSEO file, 4=error reading MuSEO file.
The description of old and (may be) obselete routines is available here