| 1 | # Weather::GHCN::Fetch.pm - class for creating applications that fetch NOAA GHCN data | ||
| 2 | |||
| 3 | ## no critic (Documentation::RequirePodAtEnd) | ||
| 4 | ## no critic [ValuesAndExpressions::ProhibitVersionStrings] | ||
| 5 | ## no critic [TestingAndDebugging::RequireUseWarnings] | ||
| 6 | |||
| 7 | use v5.18; # minimum for Object::Pad | ||
| 8 | |||
| 9 | package Weather::GHCN::Fetch; | ||
| 10 | |||
| 11 | our $VERSION = 'v0.0.011'; | ||
| 12 | |||
| 13 | =head1 NAME | ||
| 14 | |||
| 15 | Weather::GHCN::Fetch - Access the NOAA GHCN Global Historical Climatology Network repository | ||
| 16 | |||
| 17 | =head1 VERSION | ||
| 18 | |||
| 19 | version v0.0.011 | ||
| 20 | |||
| 21 | =head1 DESCRIPTION | ||
| 22 | |||
| 23 | The B<Weather::GHCN >module library provides classes that can be used to develop | ||
| 24 | applications that access weather data collected by the U.S. National | ||
| 25 | Oceanic and Atmospheric Administration. The modules enable the | ||
| 26 | retrieval of the surface station weather data and metadata that NOAA | ||
| 27 | publishes as the Global Historical Climatology Network (GHCN) data | ||
| 28 | repository, which is fed by weather data sources from around | ||
| 29 | the world. | ||
| 30 | |||
| 31 | =head1 NOAA GHCN DATA SOURCES | ||
| 32 | |||
| 33 | The main data sources are: | ||
| 34 | |||
| 35 | =over 4 | ||
| 36 | |||
| 37 | =item | ||
| 38 | |||
| 39 | L<https://www1.ncdc.noaa.gov/pub/data/ghcn/daily/all/> | ||
| 40 | |||
| 41 | =item | ||
| 42 | |||
| 43 | L<https://www1.ncdc.noaa.gov/pub/data/ghcn/daily/ghcnd-stations.txt> | ||
| 44 | |||
| 45 | =item | ||
| 46 | |||
| 47 | L<https://www1.ncdc.noaa.gov/pub/data/ghcn/daily/ghcnd-inventory.txt> | ||
| 48 | |||
| 49 | =back | ||
| 50 | |||
| 51 | NOAA also provides a readme file here: | ||
| 52 | |||
| 53 | =over 4 | ||
| 54 | |||
| 55 | =item | ||
| 56 | |||
| 57 | L<https://www1.ncdc.noaa.gov/pub/data/ghcn/daily/readme.txt> | ||
| 58 | |||
| 59 | =back | ||
| 60 | |||
| 61 | =head1 APPLICATION SCRIPTS | ||
| 62 | |||
| 63 | The B<Weather::GHCN::Fetch> package includes fully functional application | ||
| 64 | scripts that are based on B<Weather::GHCN::App> modules. These are: | ||
| 65 | |||
| 66 | =over 4 | ||
| 67 | |||
| 68 | =item B<ghcn_fetch> | ||
| 69 | |||
| 70 | Fetches station and/or weather data for reporting. | ||
| 71 | |||
| 72 | =item B<ghcn_extremes> | ||
| 73 | |||
| 74 | Reports temperature extremes, including heatwaves and coldwaves, from | ||
| 75 | station-level daily weather retrieved by B<ghcn_fetch>. | ||
| 76 | |||
| 77 | =item B<ghcn_station_counts> | ||
| 78 | |||
| 79 | Take a list of stations found by B<ghcn_fetch>, examines the active | ||
| 80 | date range, and produces a count of stations that were active in | ||
| 81 | each year of the range. | ||
| 82 | |||
| 83 | =back | ||
| 84 | |||
| 85 | The output from all scripts is tab-separated and designed for easy | ||
| 86 | import into Excel (or similar) for analysis, reporting and charting. | ||
| 87 | B<ghcn_extremes> and B<ghcn_station_counts> are designed to take the | ||
| 88 | output from B<ghcn_fetch> via pipeline. | ||
| 89 | |||
| 90 | Each script has a B<-help> option that documents its features and options. | ||
| 91 | |||
| 92 | =head1 APPLICATION MODULES | ||
| 93 | |||
| 94 | The application scripts are mostly just a thin veneer over corresponding | ||
| 95 | modules in the B<Weather::GHCN::App> namespace. That and the POD | ||
| 96 | necessary for B<-help> and B<-usage>. | ||
| 97 | |||
| 98 | The application scripts are built upon the API modules, primarily | ||
| 99 | B<Weather::GHCN::StationTable>. | ||
| 100 | |||
| 101 | =head1 API MODULES | ||
| 102 | |||
| 103 | The API modules are the heart of the package, encapsulating the logic | ||
| 104 | necessary for accessing the GHCN repository, downloading station | ||
| 105 | metadata and daily weather data, managing the plethora of options | ||
| 106 | supported by the B<ghcn_fetch> application, etc. | ||
| 107 | |||
| 108 | The modules are: | ||
| 109 | |||
| 110 | Weather::GHCN::StationTable | ||
| 111 | Weather::GHCN::Station | ||
| 112 | Weather::GHCN::Common | ||
| 113 | Weather::GHCN::CountryCodes | ||
| 114 | Weather::GHCN::Measures | ||
| 115 | Weather::GHCN::Options | ||
| 116 | Weather::GHCN::TimingStats | ||
| 117 | |||
| 118 | This module, B<Weather::GHCN::Fetch>, is actually just a stub that | ||
| 119 | provides documentation and a primary module name for the distribution. | ||
| 120 | |||
| 121 | =head1 EXAMPLES | ||
| 122 | |||
| 123 | The primary usefulness of this package comes from the application | ||
| 124 | scripts. For example of the types of reports that can be generated, | ||
| 125 | see the EXAMPLES section of the help documentation for B<ghcn_fetch>. | ||
| 126 | |||
| 127 | =head1 AUTHOR | ||
| 128 | |||
| 129 | Gary Puckering (jgpuckering@rogers.com) | ||
| 130 | |||
| 131 | =head1 LICENSE AND COPYRIGHT | ||
| 132 | |||
| 133 | Copyright 2022, Gary Puckering | ||
| 134 | |||
| 135 | =cut | ||
| 136 | |||
| 137 | 1; |