=head1 NAME Temperature::Calculate::DegreeDays - Perl package to compute cooling, heating, and growing degree days =head1 VERSION Version 0.50 =cut =head1 SYNOPSIS use Temperature::Calculate::DegreeDays; my $dd_nws = Temperature::Calculate::DegreeDays->new(); # Default values (65 degF base for CDDs and HDDs, corn GDDs) # Set params to degC (Canadian style), use wheat growing degree days my $dd_can = Temperature::Calculate::DegreeDays->new({ BASE => 18, GBASE => 0, GCEILING => 27, }); my $daily_high_temperature = 80; my $daily_low_temperature = 60; my $cdd = $dd_nws->cooling($daily_high_temperature,$daily_low_temperature); # Result is 5 my $hdd = $dd_nws->heating($daily_high_temperature,$daily_low_temperature); # Result is 0 my $gdd = $dd_nws->growing($daily_high_temperature,$daily_low_temperature); # Result is 20 =head1 DESCRIPTION A degree day is a measure of sensible temperature compared to a baseline temperature, typically integrated over time. Degree days have numerous applications in agriculture, as temperatures during the growing season have a direct impact on crop growth progress. Degree days also inform energy usage monitoring, as the costs to heat or cool climate controlled structures is directly related to temperature. The simplest method to calculate degree days is to compare the daily mean temperature (the average of the daily high and low observed temperatures) to a baseline temperature. This is how degree days are L. The Temperature::Calculate::DegreeDays package provides methods to calculate the following types of degree days: =over 4 =item * Cooling degree days - the difference between the daily mean and the baseline temperatures when the daily average is warmer than the baseline, otherwise 0 =item * Heating degree days - the difference between the daily mean and the baseline temperatures when the daily average is colder than the baseline, otherwise 0 =item * Growing degree days - set the daily high and low temperatures to a ceiling threshold temperature if they exceed it before calculating the daily mean, and then follow the procedure of cooling degree days =back This package was designed using an object-oriented (OO) framework, because it's helpful to save the baseline, ceiling, and missing data parameters through multiple method calls, and a calling program may defined different types of degree days. The temperture units, e.g., Celsius or Fahrenheit, do not matter, but the baseline and ceiling temperatures should have the same units as the input temperatures if you want the results to make sense. Temperature::Calculate::DegreeDays attempts to handle missing or invalid (non-numeric or undefined) data by returning the missing value instead of throwing an exception. =head1 METHODS =head2 new my $dd_nws = Temperature::Calculate::DegreeDays->new(); # Uses default values for everything my $dd_degC = Temperature::Calculate::DegreeDays->new({BASE => 18}); # Canadian heating and cooling degree days, deg C # Canadian heating and cooling degree days, wheat growing degree days in deg C, different missing value my $gdd_canada = Temperature::Calculate::DegreeDays->new({ BASE => 18, GBASE => 0, GCEIL => 27, MISSING => -9999 }); Constructs a Temperature::Calculate::DegreeDays object (blessed reference) and returns it to the calling program. The baseline temperatures for the different degree days methods, the ceiling threshold temperature for growing degree days, and a value to be interpreted as missing data can some or all optionally be passed to the constructor with a hash ref, e.g.: $params = { BASE => [baseline temperature for cooling and heating degree days], GBASE => [baseline temperature for growing degree days], GCEILING => [ceiling/heat threshold temperature for growing degree days] MISSING => [missing value] } If supplied, these parameters must have defined and numeric values or the constructor will L. If not supplied, the default values are BASE = 65, which matches the United States NWS standard definition of heating and cooling degree days in degrees Fahrenheit, and GBASE = 50 and GCEILING = 86, which is the definition of corn (maize) growing degree days in degrees Fahrenheit. The default missing value is MISSING => NaN. =cut =head2 cooling my $maxT = 88; my $minT = 60; my $mean = ($maxT + $minT) / 2; my $cdd = $dd->cooling($maxT,$minT); # Order of the args does not matter $cdd = $dd->cooling($mean); # Same result Given one temperature argument taken to be the daily mean temperature, or two arguments taken to be the daily maximum and minimum temperatures, returns the cooling degree days accumulated to the nearest integer. If the argument value(s) are undefined, non-numeric, NaN, or equal to the missing value, the missing value is returned. The method will croak if no argument is supplied. =cut =head2 heating my $maxT = 50; my $minT = 35; my $mean = ($maxT + $minT) / 2; my $hdd = $dd->heating($maxT,$minT); # Order of the args does not matter $hdd = $dd->heating($mean); # Same result Given one temperature argument taken to be the daily mean temperature, or two arguments taken to be the daily maximum and minimum temperatures, returns the heating degree days accumulated to the nearest integer. If the argument value(s) are undefined, non-numeric, NaN, or equal to the missing value, the missing value is returned. The method will croak if no argument is supplied. =cut =head2 growing my $maxT = 90; my $minT = 70; my $gdd = $dd->growing($maxT,$minT); # Order of args does not matter Given two arguments taken to be the daily maximum and minimum temperatures, returns the growing degree days accumulated to the nearest integer. If the argument values are undefined, non-numeric, NaN, or equal to the missing value, the missing value is returned. If fewer than two arguments are supplied, the method will croak. =cut =head1 INSTALLATION The best way to install this module is with a CPAN client, which will resolve and install the dependencies: cpan Temperature::Calculate::DegreeDays cpanm Temperature::Calculate::DegreeDays You can also install the module directly from the distribution directory after downloading it and extracting the files, which will also install the dependencies: cpan . cpanm . If you want to install the module manually do the following in the distribution directory: perl Makefile.PL make bmake test make install =head1 SUPPORT AND DOCUMENTATION After installing, you can find documentation for this module with the perldoc command. perldoc Temperature::Calculate::DegreeDays You can also look for information at: =over 4 =item * RT: CPAN's request tracker (report bugs here) L =item * CPAN Ratings L =item * Search CPAN L =back =head1 BUGS Please report any bugs or feature requests to C, or through the web interface at L. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. =head1 AUTHOR Adam Allgood =head1 LICENSE AND COPYRIGHT This software is copyright (c) 2024 by Adam Allgood. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut