Drought-PET-Thornthwaite

 view release on metacpan or  search on metacpan

README.pod  view on Meta::CPAN

=item * C<$ndays>: The number of days in the period over which the PET is calculated, e.g., 7 for a weekly PET. Must be 1 or greater

=item * C<$lat>: The latitude of the location for which the PET is calculated in degrees (must be 0 to 90)

=item * C<$temp>: The average temperature observed during the period in degrees Celsius

=item * C<$tei>: The climatological "temperature efficiency index" defined in Thornthwaite (1948)

An optional sixth argument can be supplied, which would be considered the missing data value. 
The default missing value is NaN. If the YDAY, NDAYS, or LAT arguments are non-numeric or 
invalid, the pet_thornthwaite function will L<croak|https://perldoc.perl.org/Carp>. 
If the TEMP or TEI arguments are undefined, missing, or invalid, the function will return 
the missing value.

This function currently only works for Northern Hemisphere locations.

=back

=cut

=head2 tei_thornthwaite

 my $tei = tei_thornthwaite($jan,$feb,$mar,$apr,$may,$jun,$jul,$aug,$sep,$oct,$nov,$dec);

Calculates and returns the temperature efficiency index (TEI, sometimes called the 
Thornthwaite heat index) based on a monthly average temperature climatology for a given 
location. Since the equation involves a summation of adjusted monthly temperatures, 12 
arguments are required, consisting of the average temperature for each calendar month of 
the year. An optional 13th argument can also be supplied to define a numeric value 
interpreted as missing data. If not supplied, the default missing value is NaN.

The missing value will be returned if any of the temperature values are missing, 
undef, or invalid (e.g., non-numeric).

=cut

=head1 INSTALLATION

The best way to install this module is with a CPAN client, which will resolve and
install the dependencies:

lib/Drought/PET/Thornthwaite.pm  view on Meta::CPAN

=item * C<$ndays>: The number of days in the period over which the PET is calculated, e.g., 7 for a weekly PET. Must be 1 or greater

=item * C<$lat>: The latitude of the location for which the PET is calculated in degrees (must be 0 to 90)

=item * C<$temp>: The average temperature observed during the period in degrees Celsius

=item * C<$tei>: The climatological "temperature efficiency index" defined in Thornthwaite (1948)

An optional sixth argument can be supplied, which would be considered the missing data value. 
The default missing value is NaN. If the YDAY, NDAYS, or LAT arguments are non-numeric or 
invalid, the pet_thornthwaite function will L<croak|https://perldoc.perl.org/Carp>. 
If the TEMP or TEI arguments are undefined, missing, or invalid, the function will return 
the missing value.

This function currently only works for Northern Hemisphere locations.

=back

=cut

sub pet_thornthwaite {
    # Define a NaN value for later use
    my $inf           = exp(~0 >> 1);
    my $nan           = $inf / $inf;

    # Make sure the caller supplied sufficient arguments
    unless(@_ and @_ >= 5) { croak "Insufficient arguments supplied"; }

    # Get the arguments
    my $yday        = shift;
    my $ndays       = shift;
    my $lat         = shift;

lib/Drought/PET/Thornthwaite.pm  view on Meta::CPAN

=head2 tei_thornthwaite

 my $tei = tei_thornthwaite($jan,$feb,$mar,$apr,$may,$jun,$jul,$aug,$sep,$oct,$nov,$dec);

Calculates and returns the temperature efficiency index (TEI, sometimes called the 
Thornthwaite heat index) based on a monthly average temperature climatology for a given 
location. Since the equation involves a summation of adjusted monthly temperatures, 12 
arguments are required, consisting of the average temperature for each calendar month of 
the year. An optional 13th argument can also be supplied to define a numeric value 
interpreted as missing data. If not supplied, the default missing value is NaN.

The missing value will be returned if any of the temperature values are missing, 
undef, or invalid (e.g., non-numeric).

=cut

sub tei_thornthwaite {
    # Define a NaN value for later use
    my $inf           = exp(~0 >> 1);
    my $nan           = $inf / $inf;

    # Make sure the caller supplied sufficient arguments
    unless(@_ and @_ >= 12) { croak "Insufficient arguments supplied"; }

    # Get the arguments
    my @monthly_temperatures;
    my $invalid = 0;
    for(my $i=0; $i<12; $i++) { push(@monthly_temperatures,shift); } 

t/00-worksasexpected.t  view on Meta::CPAN

use strict;
use warnings;
use 5.010;
use Test::More;
use Drought::PET::Thornthwaite qw(pet_thornthwaite tei_thornthwaite);

my $pet;
ok( ! defined(eval { $pet = pet_thornthwaite("NaN",7,20.5,12,12) } ),  'Test pet_thornthwaite with a NaN YDAY (default missing)' );
ok( ! defined(eval { $pet = pet_thornthwaite(12,"NaN",37.8,12,12) } ), 'Test pet_thornthwaite with a NaN NDAYS (default missing)' );
ok( ! defined(eval { $pet = pet_thornthwaite(15,7,"NaN",12,12) } ),    'Test pet_thornthwaite with a NaN LAT (default missing)' );
ok( ! defined(eval { $pet = pet_thornthwaite(0,7,20.5,12,12) } ),      'Test pet_thornthwaite with an invalid YDAY (default missing)' );
ok( ! defined(eval { $pet = pet_thornthwaite(12,0,37.8,12,12) } ),     'Test pet_thornthwaite with an invalid NDAYS (default missing)' );
ok( ! defined(eval { $pet = pet_thornthwaite(15,7,100,12,12) } ),      'Test pet_thornthwaite with an invalid LAT (default missing)' );
ok( ! defined(pet_thornthwaite(12,10,30.8,"NaN",0) <=> 0),             'Test pet_thornthwaite with a missing TEMP arg (default)' );
is( pet_thornthwaite(225,30,75.0,12,-9999,-9999), -9999,               'Test pet_thornthwaite with a missing TEI arg (non-default)' );
is( pet_thornthwaite(300,7,20.5,-5,5), 0,                              'Test pet_thornthwaite with a below-zero temperature' );
is( int(pet_thornthwaite(220,30,20.5,16,52.57)), 74,                   'Test pet_thornthwaite with a positive temperature (regular)' );
is( pet_thornthwaite(220,30,20.5,27,52.57), 141.43,                    'Test pet_thornthwaite with a positive temperature (hot)' );

ok( ! defined(tei_thornthwaite("NaN",2,3,4,5,6,7,8,9,10,11,12) <=> 0), 'Test tei_thornthwaite with a NaN value (default)' );
ok( ! defined(tei_thornthwaite(1,2,3,"NaN",5,6,7,8,9,10,11,12) <=> 0), 'Test tei_thornthwaite with a NaN value (default)' );
is( tei_thornthwaite(1,2,3,-9999,5,6,7,8,9,10,11,12,-9999), -9999,     'Test tei_thornthwaite with a missing value (non-default)' );
is( tei_thornthwaite(1,2,3,"NaN",5,6,7,8,9,10,11,12,-9999), -9999,     'Test tei_thornthwaite with a NaN value (non-default)' );
is( tei_thornthwaite(1,2,"sldkjf",4,5,6,7,8,9,10,11,12,-9999), -9999,  'Test tei_thornthwaite with an invalid value (non-default)' );

done_testing();

exit 0;