#  Copyright (C) 2004  Stanislav Sinyagin
#
#  This program is free software; you can redistribute it and/or modify
#  it under the terms of the GNU General Public License as published by
#  the Free Software Foundation; either version 2 of the License, or
#  (at your option) any later version.
#
#  This program is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU General Public License for more details.
#
#  You should have received a copy of the GNU General Public License
#  along with this program; if not, write to the Free Software
#  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

# $Id: rrd_hwreapply.pod,v 1.4 2004/05/16 14:36:28 ssinyagin Exp $
# Stanislav Sinyagin <ssinyagin@yahoo.com>
#
#

=head1 NAME

rrd_hwreapply - Re-apply Holt-Winters prediction parameters to RRD data

=head1 SYNOPSIS

B<rrd_hwreapply> I<in.rrd> I<out.rrd>
[B<--force>]
[B<--start>=I<start>]
[B<--delta>=I<scale-value>]
[B<--deltapos>=I<scale-value>]
[B<--deltaneg>=I<scale-value>]
[B<--failure-threshold>=I<failure-threshold>]
[B<--window-length>=I<window-length>]
[B<--alpha>=I<adaption-parameter>]
[B<--beta>=I<adaption-parameter>]
[B<--gamma>=I<adaption-parameter>]
[B<--gamma-deviation>=I<adaption-parameter>]
[B<--rralen>=I<rows>]
[B<--season>=I<rows>]
[B<--defaults>]

=head1 DESCRIPTION

The prorgam takes the input RRD, and copies all data to the output RRD,
with new Holt-Winters prediction parameters applied.
If the input file is not Holt-Winters enabled, all parameters must
be specified, or use the B<--defaults> option.

The resulting RRD will not contain exactly the same data as the source file.
It is a result of numerous transformations during the data fetching and
storing. However, the tests have shown quite good results: for a counter
with average values of order of I<1e+06>, the resulting data relative
difference is of order of I<1e-10>. For a counter with average values
at the level of I<1e+03>, the precision is approximately I<1e-08>. 

=head1 OPTIONS

=over 4

=item B<--force>

Forces the output file to be overwritten. Otherwise the program terminates
if the output file already presents.

=item B<--start>=I<start>

Specifies the earliest date to copy the data for. If not specified,
the earliest available data with one-step (no consolidation)
AVERAGE RRAs will be taken.

=item
B<--delta>=I<scale-value>,
B<--deltapos>=I<scale-value>,
B<--deltaneg>=I<scale-value>,
B<--failure-threshold>=I<failure-threshold>,
B<--window-length>=I<window-length>,
B<--alpha>=I<adaption-parameter>,
B<--beta>=I<adaption-parameter>,
B<--gamma>=I<adaption-parameter>,
B<--gamma-deviation>=I<adaption-parameter>

Set the Holt-Winters algorithm parameters. See rrdtune(1) and the
article of Jake Brutlag on Aberrant Behavior Detection.

=item B<--rralen>=I<rows>

Set the length of HWPREDICT RRA. Default is 4032 (2 weeks of 5-minute samples).

=item B<--season>=I<rows>

Set the length of SEASONAL RRA. Default is 288 (1 day of 5-minute samples).

=item B<--defaults>

Use the default values for all Holt-Winters parameters. Individual
parameters may be overwritten by the above options. The default values are:

 delta = 2
 alpha = 0.1
 beta  = 0.0035
 gamma = 0.1
 window_length = 9
 failure_threshold = 6
 hw_rra_length = 4032
 seasonal_period = 288

=back

=head1 RESTRICTIONS

This program requires RRDtool version 1.1.x (currently available as
development snapshot only), Perl version 5.8.2 (version 5.8.0 is known to have
bugs which break this utility).

=head1 NOTES

RRDman is a set of utilities that manipulate the RRDtool database files.

=head1 AUTHOR

Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt>