The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Geo-ReadGRIB-1.4
River stage zero No dependents
++
/ Geo::ReadGRIB

NAME

Geo::ReadGRIB - Perl extension that gives read access to GRIB 1 "GRIdded Binary" format Weather data files.

SYNOPSIS

  use Geo::ReadGRIB;
  $w = new Geo::ReadGRIB "grib-file";
  
  $w->getFullCatalog() # only needed for text descriptions and units.
  
  # The object now contains the full inventory of the GRIB file
  # including the "verbose" text description of each parameter
  
  print $w->show(); 
  
  $plit = $w->extract(data_type, lat, long, time);

  # or 

  $plit = $w->extractLaLo(data_type, lat1, long1, lat2, long2, time); 
  
  die $w->getError,"\n" if $w->getError;    # undef if no error

  while (  $place =  $plit->current and $plit->next ) {
      
      # $place is a Geo::ReadGRIB::Place object

      $time       = $place->thisTime;
      $latitude   = $place->lat;
      $longitude  = $place->long;
      $data_types = $place->types; # an array ref of type names
      $data       = $place->data( data_type );

      # do something with each place in the extracted rectangular area
  }


  $data = $w->getDataHash();
  
  # $data contains a hash reference to all grib data extracted
  # by extract() the object in its lifetime.
  #
  # As of Version 1.4 extractLaLo() does not save extracted data to 
  # the object by default and so it will not be returned by getDataHash().
  # Use the backflip() method to bring back this older behavior.
  #  
  # $data->{time}->{lat}->{long}->{data_type} now contains data 
  # for data_type at lat,long and time unless there was an error

DESCRIPTION

Geo::ReadGRIB is an Perl module that provides read access to data distributed in GRIB files. Specifically, I wrote it to access NOAA Wavewatch III marine weather model forecasts. As of version 0.98_1 Geo::ReadGRIB is known to support Canadian Meteorological Center's GEM model GRIB files. It may support many other GRIB variants which use a rectangular lat/long grid but they have not been tested. Please notify the maintainers and let them know if it does or doesn't support your files.

Version 0.98 introduced the Geo::ReadGRIB::PlaceIterator class. PlaceIterator objects are returned by extractLaLo() and extract() and can be used for an ordered traversal of the extracted data for a given time. This greatly simplifies map image creation and other data analysis tasks. See Geo::ReadGRIB::PlaceIterator documentation and demo programs in the examples directory.

Wavewatch III GRIB's can currently be found under

ftp://polar.ncep.noaa.gov/pub/waves/

CMC GRIB datasets currently listed at

http://www.weatheroffice.gc.ca/grib/High-resolution_GRIB_e.html

GRIB stands for "GRIdded Binary" and it's a format developed by the World Meteorological Organization (WMO) for the exchange of weather product information. See for example

http://www.nco.ncep.noaa.gov/pmb/docs/on388/

for more about the GRIB format.

wgrib.c

Geo::ReadGRIB uses the C program wgrib to retrieve the GRIB file catalog and to extract the data. wgrib.c is included in the distribution and will compile when you make the module. The resulting executable is named wgrib.exe and should install in the same location as ReadGRIB.pm. ReadGRIB will search for wgrib.exe at run time and die if it can't find it.

wgrib.c is known to compile and install correctly with Geo::ReadGRIB on all common platforms. See the CPAN Testers reports for this module for details.

wgrib.exe creates a file called wgrib.tmp.XXXXXXXXX in the local directory where the X's are random chars. The id that runs a program using Geo::ReadGRIB needs write access to work. This temp file will be removed after use by each method calling wgrib.exe

Methods

$O = new Geo::ReadGRIB "grib_file";

Returns a Geo::ReadGRIB object that can open GRIB format file "grib_file". wgrib.exe is used to extract full header info from the "self describing" GRIB file.

$O->getFullCatalog();

getFullCatalog() will extract the full text descriptions of data items in the GRIB file and store them in the object.

$O->getParam("show");

getParam(show) Returns a string listing the names of all published parameters.

$O->getParam(param);

getParam(param) returns a scalar with the value of param where param is one of TIME, LAST_TIME, La1, La2, LaInc, Lo1, Lo2, LoInc, fileName.

  • TIME is the time of the earliest data items in epoch seconds.

  • LAST_TIME is the time of the last data items in epoch seconds.

  • La1 La2 First and last latitude points in the GRIB file (or most northerly and most southerly).

  • LaInc The increment between latitude points in the GRIB file.

  • Lo1 Lo2 First and last longitude points in the GRIB file (or most westerly and most easterly).

  • LoInc The increment between latitude points in the GRIB file.

  • filename The file name of the GRIB file this object will open to extract data.

$O->show();

Returns a formatted text string description of the data in the GRIB file. This includes latitude, longitude, and time ranges, and data type text descriptions (if getFullCatalog() has been run).

$plit = $O->extractLaLo([data_type, ...], lat1, long1, lat2, long2, time);

Extracts forecast data for a given time and data type(s) for a range of locations. The locations will be all (lat, long) points in the GRIB file inside the rectangular area defined by (lat1, long1) and (lat2, long2) where lat1 >= lat2 and long1 <= long2. That is, lat1 is north or lat2 and long1 is west of long2 (or equal to...)

data_type is either a data type name as a string or a list of data name strings as an array reference.

Time will be in epoch seconds as returned, for example, by Time::Local. If the time requested, is in the range of times in the file, but not one of the exact times in the file, the nearest existing time will be used. An error will be set if time is out of range.

Returns a Geo::ReadGRIB::PlaceIterator object containing the extracted data which can be used to iterate through the data in order sorted by lat and then long.

Extracted data is not retained in the ReadGRIB object data structure by default as of ReadGRIB version 1.4. Use the backflip() method to turn this behavior back on.

Since extractLaLo() needs only one call to wgrib and one temp file open, this is faster than using extract() to get the same data points one at a time.

$plit = $O->extract(data_type, lat, long, time);

Extracts forecast data for given type and location. time is optional. Extracts data for all times in file unless a specific time is given in epoch seconds.

lat and long will be in the range 90 to -90 degrees lat and 0 to 360 degrees long. If lat or long is out of range for the current file an error will be set ( see getError() ).

time will be in epoch seconds as returned, for example, by Time::Local. If the time requested is in the range of times in the file, but not one of the exact times in the file, the nearest existing time will be used. An error will be set if time is out of range.

data_type will be one of the data types in the GRIB file or an error is set.

Returns a Geo::ReadGRIB::PlaceIterator object containing the extracted data which can be used to iterate through the data in order sorted by lat and then long.

Extracted data is also retained in the ReadGRIB object data structure.

$O->getError();

Returns string messages for the last error set. If no error is set getError() returns undef. Only the most recent error will be show. It's good practice to check errors after actions, especially while developing applications.

$bfFlag = $O->backflip();

When true, certain older behaviors return. In version 1.4 this is only the storage in the current object of data extracted by extractLaLo().

backflip() returns false by default

$O->getDataHash();

Returns a hash ref with all the data items in the object. This will be all the data extracted from the GRIB file for in the life of the object.

As of Version 1.4 extractLaLo() does not save extracted data to the object by default and so it will not be returned by getDataHash(). Use the backflip() method to bring back this older behavior.

The hash structure is

   $d->{time}->{lat}->{long}->{type}

DEPRECATED METHODS

$O->getCatalog() DEPRECATED;
$O->getCatalogVerbose() DEPRECATED;

getCatalog() is DEPRECATED and no longer does anything but set an error. It's function of Getting the critical offset index for each data type and time in the file is now done during object creation.

getCatalogVerbose() is also DEPRECATED as redundant and now just calls getFullCatalog(). and sets an error.

PRIVATE METHODS

The following are not public methods and may be removed or changed in future releases. Do not use these in production code.

La1()
La2()
Lo1()
Lo2()
LaInc()
LoInc()
Ni()
Nj()
TR()
adjustLong()
calInc()
clearError()
clearData()
dumpit()
error()
findNearestTime()
lalo2offset()
m2ft()
openGrib()
parseGDS()
sn_scan_flag()
tempfile()
toDecimal()
validLo()
validLa()

BUGS AND LIMITATIONS

There are no known bugs in this module version. Geo::ReadGRIB versions before 1.1 are known to give results that are sometimes off by one LoInc west or east, only on 64bit Perl where nvtype='long double'. Geo::ReadGRIB 1.1 and above will not exhibit this bug.

Versions between 0.98_1 and 1.21 may not parse the time headers correctly for some forecast records in CMC grib files. Geo::ReadGRIB 1.3 and above will not exhibit this bug.

Please report problems through

http://rt.cpan.org

or contact Frank Cox, <frank.l.cox@gmail.com> Patches are welcome.

SEE ALSO

For more on wgrib.c see

http://www.cpc.ncep.noaa.gov/products/wesley/wgrib.html

For more on Wavewatch III see

http://polar.ncep.noaa.gov/waves/wavewatch/wavewatch.html

AUTHOR

Frank Cox, <frank.l.cox@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2006, 2009 by Frank Cox

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.