view release on metacpan or  search on metacpan

bin/ghcn_fetch  view on Meta::CPAN

the network source.  Default is yearly.  Possible values are:

=over 4

=item yearly

The origin HTTP server is contacted and the page refreshed if the
cached file has not been changed within the current year. The
rationale for this, and for this being the default, is that the GHCN
data for the current year will always be incomplete, and that will
skew any statistical analysis and so should normally be truncated.
If the user needs the data for the current year, they should use a
refresh value of 'always' or a number.

=item always

If a page is in the cache, the origin HTTP server is always checked for
a fresher copy

=item never

The origin HTTP is never contacted, regardless of the page being in
cache or not. If the page is missing from cache, the fetch method will
return undef. If the page is in cache, that page will be returned, no
matter how old it is.

=item <number>

The origin HTTP server is not contacted if the page is in cache
and the cached page was inserted within the last <number> days.
Otherwise the server is checked for a fresher page.

=back

=item -verbose

When given, warning messages about missing data are displayed to
stderr.

=back

=head2 Command-Line Only Options

Options documented in this section can be used on the command line,
but cannot be specified within a profile file.

=over 4

=item -gui

Launch a graphic user interface that can be used to set options.
Not available unless modules Tk and Tk::Getopt are installed.

=item -savegui <filespec>

Designate a file to be used to save load options, or from which to
load options that were previously saved from the GUI.

=item -outclip

Send output to the Windows clipboard.  (Windows only)

=item -readme

Launch the default web browser and display the NOAA Daily Readme.txt
file, providing a description of the Daily data files and station
data.

=item -h | -help

Display this documentation.

=item -usage | -?

Display the Synopsis section of this documentation.

=back

=head1 PROFILE FILE

At startup, ghcn_fetch will look for the file .ghcn_fetch.yaml in
the user home directory (~ on Unix, %UserProfile% on Windows)
in order to capture some additional options. The file content should
contain something like this:

    ---
    cachedir: C:/ghcn_cache

    aliases:
        yow: CA006106000,CA006106001    # Ottawa airport
        cda: CA006105976,CA006105978    # Ottawa CDA and CDA RCS
        center: USC00326365             # geographic center of North America

Any option (except those listed in section Command-Line Only Options)
can be included and will be preloaded as a default.  Command-line
options will override them.  Anything left undefined will be filled in
by built-in defaults.

One extra option not available via the command line but which can be 
specified in the profile file is B<aliases>.  This optional section 
provides a list of shortcut names that are mapped to station id's or 
id-lists and which can be used in the -location option.  If a 
-location value matches a key defined in this section, the station id 
or id-list is substituted.  Note that keys must be lowercase letter 
only, and may have a leading underscore.

=head1 RELATED SCRIPTS

Additional scripts are provided for data analysis.  These scripts
are designed to take the output ghcn_fetch.

For Windows users, a -outclip option directs the tab-separated output
to the Windows clipboard, so it can be pasted into Excel for analysis
using PivotTable and PivotChart. Alternatively you can use the usual
'>' method to direct the output to a file.

=over 4

=item ghcn_extremes.pl

Report patterns of temperature extremes (heatwaves or coldwaves) by
analyzing daily temperature records and looking for consecutive days
of extreme temperatures; e.g.

    ghcn_fetch -country CA -report daily | ghcn_extremes > extremes.tsv

=item ghcn_station_counts.pl

Report the station counts per year for a list of stations generated by
this script using -report stations (which is the default -report
option); e.g.

    ghcn_fetch -country CA | ghcn_station_counts > stn_counts.tsv

=back

=head1 EXAMPLES

Here are some examples of the kinds of reports that can be generated:

List the weather stations in NY state with "New York" in the name:

    ghcn_fetch -country US -state NY -location "New York"

List the New York weather stations active between 1900 and 1920:

    ghcn_fetch -cou US -st NY -location "New York" -active 1900-1920

Report the yearly max, min and average temperatures at JFK airport:

    ghcn_fetch yearly -cou US -st NY -location "New York JFK"

Report the monthly max, min and average temperatures at JFK airport:

    ghcn_fetch monthly -cou US -st NY -location "New York JFK"

Report the daily max, min and average temperatures at JFK airport:

    ghcn_fetch daily -cou US -st NY -location "New York JFK"

Launch the GUI for an options dialog:

    ghcn_fetch -gui  (requires Tk and Tk::Getopt to be installed)

Get documentation on all the options:

    ghcn_fetch -help

Find the 5-day heatwaves at the JFK airport station:

    ghcn_fetch detail -cou US -st NY -loc "New York JFK" | ghcn_extremes

Find the 3-day coldwaves (<= 15C) at the JFK airport station: