view release on metacpan or  search on metacpan

lib/Finance/Performance/Calc.pm  view on Meta::CPAN

}

1;
__END__
# Below is stub documentation for your module. You better edit it!

=head1 NAME

Finance::Performance::Calc - Perl extension to calculate linked performance numbers.

=head1 SYNOPSIS

  use 5.006001;
  use Finance::Performance::Calc qw (:all);

  print ROR(bmv => 20_000, emv => 21_567.87)
  # or, for convenience
  print ROR(20_000, 21_567.87);


  print ROR(bmv => 20_000, emv => 21_567.87,
	    flows => [
		      {mvpcf => 20_345,
		       cf    => 1000},
		      {mvpcf => 23_500,
		       cf    => -3000}
		     ]);

  print link_ROR(0.017,0.234,'-3.4%');

  print ized_ROR(0.07,5);

  Finance::Performance::Calc::return_percentages(1);
  print ROR(20_000,21_567.87);

  print ROR(bmv => 20_000, emv => 21_567.87,
	    flows => [{mvpcf => 20_345,
		       cf    => 1000},
		      {mvpcf => 23_500,
		       cf    => -3000}
		     ]);

  print link_ROR(0.017,0.234,'-3.4%');

  print ized_ROR(0.07,5);


=head1 DESCRIPTION

This module allows you to calculate performance for number of situations:

Single period performance, given a beginning market value (BMV) and
ending market value (EMV) and optional cash flows in between.

Linked periodic performance; i.e, given three consecutive monthly
returns, calculate the performance over the quarter.

"ized" performance. Given a rate of return that covers multiple
periods, calculate the per-period return.

The formulae are taken from the book "Measuring Investment
Performance". Author: David Spaulding. ISBN: 0-7863-1177-0.

B<NOTE> Before using in a production environment, you should
independently verify that the results obtained match what you
expect. There may be unintentionally made assumptions in this code
about timing and precision and what-not that do not match your
assumptions with respect to the calcualtions.

=head2 FUNCTIONS

=over 4

=item ROR

 my $ror = ROR($bmv, $emv, @flows);

Rate Of Return. Given a beginning market value ($bmv) and an ending
market value ($emv), the rate of return is calculated as

 ($emv - $bmv)/$bmv

If there are intervening cash flows between the beginning market value
and the ending market value, they are each represented by a hash ref
containing the keys 'mvpcf' (market value prior to cash flow) and 'cf'
(cash flow). The return is caculated by determining the rate of return
between each cash flow and then linking the returns together. In this
case, the beginning market value and the ending market value are
treated as zero cash flow events; that is:

 EMV is treated as {mvpcf => EMV, cf => 0}
 BMV is treated as {mvpcf => BMV, cf => 0}

The rate of return is in decimal form (0.02) for a return of two
percent (2.0%).

=item linked_ROR

 my $ror = linked_ROR(0.02, -0.02, '3.5%');

Given previously calculated multiple rates of return, calculate the
overall rate of return. The rates are linked using the algorithm:

o Convert any percentages to decimal (/100).

o Add 1.00 to each rate

o Multiply all the rates together

o Subtract 1.00 from the result

o Convert to percentage (* 100)

The function properly interprets strings with percents signs by
dividing by 100 before using the value in any calculation.

The rate of return is in decimal form (0.02 for a return of two
percent).

=item ized_ROR