/ 
Temperature-Calculate-DegreeDays-0.50
/ Temperature::Calculate::DegreeDays

NAME

Temperature::Calculate::DegreeDays - Perl package to compute cooling, heating, and growing degree days

VERSION

Version 0.50

SYNOPSIS

use Temperature::Calculate::DegreeDays;

# Default params
my $dd_degF  = Temperature::Calculate::DegreeDays->new();
# Try cooling and heating degree days in degC, and wheat growing degree days instead of corn!
my $dd_degC  = Temperature::Calculate::DegreeDays->new({
   BASE     => 18,
   GBASE    => 0,
   GCEILING => 27,
   MISSING  => -9999
});

my $daily_high_temperature = 80;
my $daily_low_temperature  = 60;
my $cdd = $dd_degF->cooling($daily_high_temperature,$daily_low_temperature);  # Result is 5
my $hdd = $dd_degF->heating($daily_high_temperature,$daily_low_temperature);  # Result is 0
my $gdd = $dd_degF->growing($daily_high_temperature,$daily_low_temperature);  # Result is 20

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 support energy usage monitoring, as the costs to heat and cool climate controlled structures is directly related to outdoor temperatures. 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 defined by the United States National Weather Service.

The Temperature::Calculate::DegreeDays package provides methods to calculate the following types of degree days:

  • Cooling degree days - zero if the baseline temperature exceeds the mean, otherwise the difference between the mean and baseline rounded to the nearest integer

  • Heating degree days - zero if the mean temperature exceeds the baseline, otherwise the difference between the baseline and mean rounded to the nearest integer

  • Growing degree days - same as cooling degree days, but when calculating the daily mean, temperatures exceeding a maximum "ceiling" value are set to the ceiling value

This package was designed using an object-oriented framework, with a constructor method (new) that returns a blessed reference. The object stores the baseline temperature for heating and cooling degree days, a separate baseline temperature for growing degree days, a growing degree days ceiling temperature, and a value to be interpreted as missing data. The various degree days methods are designed to handle missing or invalid input data gracefully by returning the missing data value, but will fail if the caller does not supply the required number of arguments.

METHODS

new

my $dd_degF    = Temperature::Calculate::DegreeDays->new();
my $dd_degC    = Temperature::Calculate::DegreeDays->new({BASE => 18});
my $dd_degC_2  = 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 default object data can be changed by passing a hashref argument with some or all of the following parameters:

$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 croak. If not supplied, the default values are BASE = 65, GBASE = 50 and GCEILING = 86, which is how the US National Weather Service defines cooling, heating, and corn (maize) growing degree days in degrees Fahrenheit. The default missing value is MISSING = NaN.

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.

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.

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.

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
make test
make install

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:

BUGS

Please report any bugs or feature requests to bug-temperature-calculate-degreedays at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Temperature-Calculate-DegreeDays. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

AUTHOR

Adam Allgood

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.