goose-ref.texi

非常著名的曲线拟合程序

\input texinfo @c -*-texinfo-*-

@c %**start of header
@setfilename goose-ref.info
@settitle The Very Out-of-Date Goose Reference Manual
@setchapternewpage odd
@c %**end of header

@set VERSIONNUMBER 0.0.6
@set VERSIONDATE The Late 20th Century
@set COPYRIGHTYEAR 1999



@ifinfo
This file documents Goose.

Copyright (C) @value{COPYRIGHTYEAR} Jon Trowbridge

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the author.
@end ifinfo

@titlepage
@title The Very Out-of-Date Goose Reference Manual
@subtitle The Goose Object-Oriented Statistics Environment
@subtitle $Id: goose-ref.texi,v 1.10 1999/10/19 00:38:48 trow Exp $
@subtitle For use with Goose version @value{VERSIONNUMBER}
@c @subtitle @value{VERSIONDATE}
@author Jon Trowbridge
@author @email{trow@@emccta.com}

@page
@vskip 0pt plus 1filll
Copyright @copyright{} @value{COPYRIGHTYEAR} Jon Trowbridge

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the author.
@end titlepage



@node Top, Preliminaries, (dir), (dir)
@comment node-name, next, previous, up

@ifinfo
Goose is a library of C++ routines for statistical analysis.
@end ifinfo

@menu
* Preliminaries:: The purpose and goals of Goose.
* Utility Classes:: Random numbers, permutations, linear algebra.
* The RealSet Class:: Goose's main repository for statistical data.
* Linear Regression::
* Bootstrapping Functions::
* Special Functions:: Useful statistical functions provided by Goose.
* Using Goose from Guile::
* Using Goose from Perl::
* Concept Index::
* Function Index::
@end menu

@c ***************************************************************************

@node Preliminaries, Utility Classes, Top, Top
@chapter Preliminaries

Someday, this will be some useful documentation for Goose.

@c ***************************************************************************

@node Utility Classes, The RealSet Class, Preliminaries, Top
@chapter Utility Classes

@section Random Numbers

Certain types of statistical calculations require a large number of
high-quality random numbers.  Since good random number generators are
not universally available, Goose provides one in the form of the
@code{Random} class.

@deftypemethod Random void seed (unsigned @var{seed_value})
When a @code{Random} object is constructed, it is initially seeded with
values derived from the system.  On Unix-type systems, this includes the
time of day, the process ID, and data read in from @code{/dev/random}
(if available).  If you need a repeatable stream of "Random" numbers,
however, the seed value can be set explicitly with this function.
@end deftypemethod

@deftypemethod Random unsigned random ()
Returns a uniformly-distributed random unsigned integer.  (Note that
parts of the implementation of @code{Random} assume that an
@code{unsigned} is 32 bits wide.  If you are using a system where an
@code{unsigned} is larger than 32 bits, only the lower 32 bits are
randomized; any higher-order bits will always be zero.  If your system's
@code{unsigned} has less than 32 bits, expect all of this to end badly.)
@end deftypemethod

@deftypemethod Random void random (unsigned* @var{buffer}, int @var{N})
Generates @var{N} uniformly-distributed random unsigned integers and
writes them into the array that begins at @var{buffer}.
@end deftypemethod

@deftypemethod Random int random_integer (int @var{a}, int @var{b})
Returns a random @code{int} that is greater than or equal to @var{a} and
less than or equal to @var{b}.
@end deftypemethod

@deftypemethod Random int random_integer(int @var{a}, int @var{b}, int* @var{buffer}, int @var{N})
Generates @var{N} uniformly-distributed
random integers between @var{a} and @var{b} and copies them into the
array that begins at @var{buffer}.
@end deftypemethod

@deftypemethod Random double random_uniform (double @var{a}, double @var{b})
@deftypemethodx Random double random_uniform ()
Returns a uniformly-distributed random @code{double} that is greater
than or equal to @var{a} and less than @var{b}.  The version with no
arguments defaults to choosing values between 0 and 1.
@end deftypemethod

@deftypemethod Random void random_uniform (double @var{a}, double @var{b}, double* @var{buffer}, int @var{N}
@deftypemethodx Random void random_uniform (double* @var{buffer}, int @var{N})
Generates @var{N} uniformly-distributed random numbers between @var{a}
and @var{b} and stores them in the array starting at @var{buffer}.
The version with only two arguments chooses values between 0 and 1.
@end deftypemethod

@deftypemethod Random double random_normal (double @var{m}, double @var{sd})
@deftypemethodx Random double random_normal ()
@end deftypemethod

@deftypemethod Random double random_normal (double @var{m}, double @var{sd}, double* @var{buffer}, int @var{N})
@deftypemethodx Random double random_normal (double* @var{buffer}, int @var{N})
@end deftypemethod

@deftypemethod Random bool random_bool (double @var{prob_true})
@deftypemethodx Random bool random_bool ()
Returns a random boolean value, where @var{prob_true} is a value between
0 and 1 that specifies the probability that the returned value will be
true.  The version with no arguments returns true fifty percent of the time.
@end deftypemethod

@deftypemethod Random void scramble (X* @var{data}, size_t @var{N})
@deftypemethodx Random  void scramble (vector<X>& @var{data})
These are a pair of template functions that randomly scramble the order
of a linear container, either an array of length @var{N} or an STL
vector, containing objects of type @code{X}.
@end deftypemethod

Goose's @code{Random} implements the @dfn{Mersenne Twister}
method, as described in Matusumoto and Nishimura's ``Mersenne Twister: A
623-dimensional equidistributed uniform pseudorandom number generator''
(@cite{ACM Transactions on Modelling and Computer Simulation}, 1998).
This algorithm only uses integer operations, and is therefore
particularly efficient.  It is important to be aware, however, that
there is non-negligible amount of overhead required to initialize the
data structures that are used by the Mersenne Twister algorithm.
Because of this, the @code{Random} object is definitely best-suited for
producing random numbers in bulk.  Code like
@example
  double sum = 0.0;
  for (int i=0; i<1000; ++i) @{
    Random rnd;
    sum += rnd.random_normal(0.0, 1.0);
  @}
@end example
will be wildly inefficient.  Consider using
@example
  double sum = 0.0;
  Random rnd;
  for (int i=0; i<1000; ++i)
    sum += rnd.random_normal(0.0, 1.0);
@end example
instead.  This allows the cost of constructing the @code{Random} object
to be borne only once, rather than once for each iteration in the loop.
Another alternative is to use
@example
  double sum = 0.0;
  double buffer[1000];
  Random rnd;
  rnd.random_normal(0.0, 1.0, buffer, 1000);
  for (int i=0; i<1000; ++i)
    sum += buffer[i];
@end example
and thereby avoid the function call overhead of repeated calls to
@code{random_normal}.

@section Permutations

A permutation is nothing more than a precise mathematical specification
for how a set of objects is to be re-ordered.  Since it will
occasionally be useful for us to be able to re-order sets in a
controlled way, Goose defines a Permutation class that encapsulates just
such a specification.

@deftypemethod Permutation size_t size ()
@end deftypemethod

@deftypemethod Permutation const size_t* map ()
@end deftypemethod

@deftypemethod Permutation size_t map (size_t @var{i})
@end deftypemethod

@deftypemethod Permutation void initialize (size_t @var{N}, size_t* @var{data});
@end deftypemethod

@deftypemethod Permutation size_t cycle_count ()
Returns the number of distinct cycles of the Permutation.
@end deftypemethod

@deftypemethod Permutation size_t orbit_size (size_t @var{i})
Return the size of the orbit of @var{i} under the action of the Permutation.
@end deftypemethod

@deftypemethod Permutation size_t order ()
Return the order of the Permutation in the sense of group theory.  This
is the smallest positive integer such that composing the Permutation
with itself that may times results in the identity Permutation.
@end deftypemethod

@deftypemethod Permutation void set_identity (size_t @var{N})
Convert this Permutation to the identity permutation on @var{N} elements.
@end deftypemethod

@deftypemethod Permutation void set_shift (size_t @var{N}, int @var{k})
Convert this Permutation to one that shifts @var{N} elements, moving the
@var{i}th element to the @var{(i+k)}th place and wrapping around as
necessary.
@end deftypemethod

@deftypemethod Permutation void set_reverse (size_t @var{N})
Convert this Permutation to one that reverses the order of a list of
@var{N} elements.
@end deftypemethod

@deftypemethod Permutation void scramble ()
Convert this Permutation to one that randomly scrambles a set of elements.
@end deftypemethod

@deftypemethod Permutation void precompose (const Permutation& @var{p})
Convert this Permutation to one that corresponds to the transformation
experienced by a set of object permuted first according to @var{p} and
then according to this Permutation.
@end deftypemethod

@deftypemethod Permutation void postcompose (const Permutation& @var{p})
Convert this Permutation to one that corresponds to the transformation
experienced by a set of object permuted first according this
Permutation and then according to @var{p}.
@end deftypemethod

@deftypemethod Permutation void invert ()
Replace this Permutation by one that transforms a set to reverse the
effects of this Permutation.
@end deftypemethod

@deftypemethod Permutation void permute (X* @var{data})
This is a template method that applies this Permutation to re-order the
array of X-objects in place.
@end deftypemethod

@section Linear Algebra: Vectors

@section Linear Algebra: Matrices

@c ***************************************************************************

@node The RealSet Class, Linear Regression, Utility Classes, Top
@chapter The RealSet Class

@section Manipulating the Contents of a RealSet

@section Performing Calculations on a RealSet

The RealSet class defines a large number of methods for calculating
quantities related to the stored data.  When it is possible and
practical, associates statistics are calculated in constant
time.

@tex
In some cases, we will give a mathematical expression that specifies exactly
what is being calculated by the function.  The following notation will
be used throughout:
@table @asis
@item $N$
The number of elements in the RealSet.
@item $x_i$
The $i$th element of the RealSet, indexed $1$ to $N$.
@item $x_{(i)}$
The $i$th-ranked element of the RealSet, ranked from low to high.
(So $x_{(1)}$ is the smallest element, and $x_{(N)}$ is the largest.)
@end table
@end tex

@deftypemethod RealSet size_t size ()
Returns the number of elements stored in the RealSet.
@end deftypemethod

@deftypemethod RealSet double min ()
Returns the smallest value stored in the RealSet.
@end deftypemethod

@deftypemethod RealSet double max ()
Returns the largest value stored in the RealSet.
@end deftypemethod

@deftypemethod RealSet double range ()
Returns the difference between the largest and the smallest values stored
in the RealSet.
@end deftypemethod

@deftypemethod RealSet double sum ()
Returns the sum of all of the elements in the RealSet.
@end deftypemethod

@deftypemethod RealSet double mean ()
Returns the mean (or average) of the RealSet.
@end deftypemethod

@deftypemethod RealSet double var ()
Returns the variance of the RealSet.
@end deftypemethod

@deftypemethod RealSet double sdev ()
Returns ths population standard deviation of the RealSet, which
is equal to the square root of the variance.
@end deftypemethod

@deftypemethod RealSet double sdevs ()
Returns the sample standard deviation of the RealSet. 

This function is very similar to the population standard deviation, and
the values of @code{sdev()} and @code{sdevs()} will be almost identical
for moderately large data sets.  The difference is that we divide by an
@var{N-1} term rather than @var{N}.  This removes a slight downward bias
caused by the fact that, in a random sample, there is some unknown error
in our estimate of the mean.  This is something that has confused
students for generations.
@end deftypemethod

@deftypemethod RealSet double percentile (double @var{p})
Returns a value @var{x} that has the property that @var{p} percent of
the data set is less than or equal to @var{x}.  By this definition, @var{x} is
not uniquely defined.  We construct our preferred value of @var{x} by
interpolating between RealSet elements as necessary.
@end deftypemethod

@deftypemethod RealSet double median ()
Returns the median of the RealSet.
@end deftypemethod

@deftypemethod RealSet double q1 ()
Returns the first quartile of the RealSet.
@end deftypemethod

@deftypemethod RealSet double q3 ()
Returns the third quartile of the RealSet.
@end deftypemethod

@deftypemethod RealSet double iqr ()
Returns the inter-quartile range of the RealSet.  The inter-quartile