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

NAME

Geo::StormTracker::Main - Master method of the Storm-Tracker perl bundle for dealing with Weather Advisories.

SYNOPSIS

        use Geo::StormTracker::Main;

        #Create a new main object.
        #The mandatory path argument determines the base path to
        #all the data files.
        $main_obj=Geo::StormTracker::Main->new('/archives/');   

        #Add an advisory object to the database.
        #The advisory being added must be a recent advisory.
        #The add_advisory method will try and determine which
        #storm the advisory belongs to and update it accordingly.
        #Second argument can be thought of as a force flag.
        ($data_obj, $region_code, $year, $event_num, $error)=$main_obj->add_advisory($adv_obj,1);

        #Add an advisory object to the database for a
        #known year and weather event number. 
        #Year must have four digits.
        #Weather event number (15th storm of 1999) says
        #which storm of the year this advisory is for.
        #This method can easily corrupt the database if given the wrong information.
        #Designed for use in initially loading and maintaining the database.
        ($data_obj, $year, $event_num,$error)=$main_obj->add_advisory_by_year_and_event($adv_obj,'1999','15');

        #Obtain a listing of data objects for every storm
        #by region (or just one region if desired).
        $region_code='NT'; #North Atlantic
        ($data_HR,$error)=$main_obj->all_storms_by_region($region_code);
        @data_objects_for_region_code=@{$data_HR->{$region_code}};

        #Obtain a listing of data objects for every active storm
        #by region (or just one region if desired).
        $region_code='NT'; #North Atlantic
        ($data_HR,$error)=$main_obj->all_active_storms_by_region($region_code);
        @active_data_objects_for_region_code=@{$data_HR->{$region_code}};

        #Obtain a listing of data objects including every current and active storm
        #keyed by region (or just one region of desired).
        $region_code='NT'; #North Atlantic
        ($mday,$mon,$year)=(gmtime(time))[3,4,5];
        $epoch_date = timegm(0,0,0,$mday,$mon,$year);
        $epoch_retire=$epoch_date-3600*24*5;# 5 days ago or younger
        ($data_HR, $error)=$main_obj->current_storms_by_region($epoch_retire, $region_code);

        #Obtain a listing of data objects for every active storm
        #by region and year (or just one region and/or year if desired).
        $region_code='NT'; #North Atlantic
        $year=1999;
        ($data_HR,$error)=$main_obj->all_storms_by_region_and_year($region_code,$year);
        @active_data_objects_for_region_code_and_year=@{$data_HR->{$region_code}->{$year}};

        #Obtain the data object for a specific storm.
        $region_code='NT'; #North Atlantic
        $year=1999;
        $event_number=15; #15th storm of the year.
        ($data_obj,$error)=$main_obj->specific_storm($region_code,$year,$event_number);

DESCRIPTION

The Geo::StormTracker::Main module is a component of the Storm-Tracker perl bundle. The Storm-Tracker perl bundle is designed to track weather events using the national weather advisories. The original intent is to track tropical depressions, storms and hurricanes. There should be a Geo::StormTracker::Data object for each weather event being stored and/or tracked. The Geo::StormTracker::Data objects are managed by Geo::StormTracker::Main.

CONSTRUCTOR

new (PATHNAME)

Creates a Geo::StormTracker::Main object. This constructor method returns an array of the form (OBJECT,ERROR). OBJECT being the newly created object if successful, and ERROR being any errors encountered during the attempt.

The entire data set for this object is assumed to be contained within the directory specified by the mandatory PATHNAME argument. In the event that a directory with the given PATHNAME does not exist, the method will fail. Check to see if the OBJECT returned is defined.

METHODS

add_advisory (ADVISORY_OBJECT,[FORCE])

Attempts to insert a Geo::StormTracker::Advisory object into the appropriate Geo::StormTracker::Data object. The Geo::StormTracker::Main object looks at the most recent storms for the advisory's region and tries to figure out which storm it belongs to. Once it determines this it inserts the advisory into the storm object it determined was associated with the storm. If necessary it will create a new data object to hold the advisory The optional force flag argument is passed on to the insert_advisory method of Geo::StormTracker::Data.

The method returns an array of the form (DATA_OBJECT, REGION, YEAR, EVENT_NUMBER ,ERROR). DATA_OBJECT being the Geo::StormTracker::Data object the advisory was successfully inserted into. If add_advisory was unsuccessful the DATA_OBJECT will be undefined. The REGION, YEAR and EVENT_NUMBER are the region code, year and event number of the DATA_OBJECT if the method was successful and undefined otherwise. ERROR is a text string reporting what error was encountered if any.

add_advisory_by_year_and_event (ADVISORY_OBJECT, YEAR, EVENT_NUMBER, [FORCE])

Attempts to insert a Geo::StormTracker::Advisory object into the appropriate Geo::StormTracker::Data object. The Geo::StormTracker::Main object uses the data object corresponding to the year and event number specified as arguments. The optional force flag argument is passed on to the insert_advisory method of Geo::StormTracker::Data. If an appropriate data object can not be found, one will be created.

The method returns an array of the form (SUCCESS, ERROR). SUCCESS being a boolean value indicating whether or not the operation was successful and ERROR being a scalar string reporting what error was encountered if any.

all_storms_by_region ([REGION_CODE])

Returns an array of the form (HASH_REF,ERROR). HASH_REF being a reference to a hash of references to arrays of Geo::StormTracker::Data objects. HASH_REF will be keyed by region code. If the optional REGION_CODE argument was given then the region given will be the only key available in the returned HASH_REF, otherwise there will be a key for every region the Geo::StormTracker::Main object knows about. The arrays of Geo::StormTracker::Data objects being referenced will be sorted by year and weather event order. Both inactive and active storms will be listed in the data object arrays.

The scalar ERROR string contains any errors encountered if unsuccessful. The HASH_REF will be undefined in this case.

all_storms_by_region_and_year ([REGION_CODE,[YEAR]])

Returns an array of the form (HASH_REF,ERROR). HASH_REF being a reference to a hash of references to references to arrays of Geo::StormTracker::Data objects. HASH_REF will be keyed by region code and year. If the optional REGION_CODE argument was given then the region given will be the only key available in the returned HASH_REF, otherwise there will be a key for every region the Geo::StormTracker::Main object knows about. Nested within each region key will be hash reference with a key for every year of data (or just one if the optional YEAR argument was used). The arrays of Geo::StormTracker::Data objects being referenced will be sorted by weather event order. Both inactive and active storms will be listed in the data object arrays.

The scalar ERROR string contains any errors encountered if unsuccessful. The HASH_REF will be undefined in this case.

all_active_storms_by_region([REGION_CODE])

Returns an array of the form (HASH_REF,ERROR). HASH_REF being a reference to a hash of references to arrays of Geo::StormTracker::Data objects. HASH_REF will be keyed by region code. If the optional REGION_CODE argument was given then the region given will be the only key available in the returned HASH_REF, otherwise there will be a key for every region the Geo::StormTracker::Main object knows about. The arrays of Geo::StormTracker::Data objects being referenced will be sorted by year and weather event order. Only active storms will be listed in the data object arrays.

The scalar ERROR string contains any errors encountered if unsuccessful. The HASH_REF will be undefined in this case.

all_current_storms_by_region([EPOCH_RETIRE,[REGION_CODE]])

Returns an array of the form (HASH_REF,ERROR). HASH_REF being a reference to a hash of references to arrays of Geo::StormTracker::Data objects. HASH_REF will be keyed by region code. If the optional REGION_CODE argument was given then the region given will be the only key available in the returned HASH_REF, otherwise there will be a key for every region the Geo::StormTracker::Main object knows about. The arrays of Geo::StormTracker::Data objects being referenced will be sorted by year and weather event order. Only active storms and storms with current advisories whose epoch_date is greater than or equal to EPOCH_RETIRE will be listed in the data object arrays.

The scalar ERROR string contains any errors encountered if unsuccessful. The HASH_REF will be undefined in this case.

specific_storm (REGION_CODE, YEAR, EVENT_NUMBER)

Returns an array of the form (DATA_OBJECT, ERROR). DATA_OBJECT being a reference to a Geo::StormTracker::Data object for the desired REGION_CODE, YEAR, and weather EVENT_NUMBER.

The scalar ERROR string contains any errors encountered if unsuccessful.

AUTHOR

Jimmy Carpenter, Jimmy.Carpenter@chron.com

All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Thanks to Dr. Paul Ruscher for his assistance in helping me to understand the weather advisory formats.

SEE ALSO

        Geo::StormTracker::Data
        Geo::StormTracker::Advisory
        Geo::StormTracker::Parser
        perl(1).