Usenet 1994 January/usenetsourcesnewsgroupsinfomagicjanuary1994.iso/sources/misc/volume24/gnucalc/part43

Text File | 1991-11-01 | 55.5 KB | 1,304 lines

Newsgroups: comp.sources.misc
From: [e-mail] (David Gillespie)
Subject:  v24i091:  gnucalc - GNU Emacs Calculator, v2.00, Part43/56
Message-ID: <[e-mail]>
X-Md4-Signature: 39f99093092765d9c0ec1c2c7592f913
Date: Fri, 1 Nov 1991 18:37:34 GMT
Approved: [e-mail]

Submitted-by: [e-mail] (David Gillespie)
Posting-number: Volume 24, Issue 91
Archive-name: gnucalc/part43
Environment: Emacs
Supersedes: gmcalc: Volume 13, Issue 27-45

---- Cut Here and unpack ----
#!/bin/sh
# do not concatenate these parts, unpack them in order with /bin/sh
# file calc.texinfo continued
#
if test ! -r _shar_seq_.tmp; then
    echo 'Please unpack part 1 first!'
    exit 1
fi
(read Scheck
 if test "$Scheck" != 43; then
    echo Please unpack part "$Scheck" next!
    exit 1
 else
    exit 0
 fi
) < _shar_seq_.tmp || exit 1
if test ! -f _shar_wnt_.tmp; then
    echo 'x - still skipping calc.texinfo'
else
echo 'x - continuing file calc.texinfo'
sed 's/^X//' << 'SHAR_EOF' >> 'calc.texinfo' &&
certainty that the number is prime.  After a few steps, the chance that
a number was mistakenly described as prime will be less than one percent.
(Indeed, this is the worst case; in practice even a single iteration is
quite reliable.)  After the @kbd{k p} command, the number will be reported
as definitely prime or non-prime if possible, or otherwise ``probably''
prime with a certain probability of error.
X
@tindex prime
The normal @kbd{k p} command performs one iteration of the primality
test.  Pressing @kbd{k p} repeatedly for the same integer will perform
additional iterations.  Also, @kbd{k p} with a numeric prefix performs
the specified number of iterations.  There is also an algebraic function
@samp{prime(n)} or @samp{prime(n,iters)} which returns 1 if @cite{n}
is (probably) prime and 0 if not.
X
@kindex k f
@pindex calc-prime-factors
@tindex prfac
The @kbd{k f} (@code{calc-prime-factors}) [@code{prfac}] command
attempts to decompose an integer into its prime factors.  For numbers up
to 25 million, the answer is exact although it may take some time.  The
result is a vector of the prime factors in increasing order.  For larger
inputs, prime factors above 5000 may not be found, in which case the
last number in the vector will be an unfactored integer greater than 25
million.  For negative integers, the first element of the list will be
@i{-1}.  For inputs @i{-1}, @i{0}, and @i{1}, the result is a list of
the same number.
X
@kindex k n
@pindex calc-next-prime
@tindex nextprime
The @kbd{k n} (@code{calc-next-prime}) [@code{nextprime}] command finds
the next prime above a given number.  Essentially, it searches by calling
@code{calc-prime-test} on successive integers until it finds one that
passes the test.  This is quite fast for integers less than eight million,
but once the probabilistic test comes into play the search may be rather
slow.  Ordinarily this command stops for any prime that passes one iteration
of the primality test.  With a numeric prefix argument, a number must pass
the specified number of iterations before the search stops.  (This only
matters when searching above eight million.)  You can always use additional
@kbd{k p} commands to increase your certainty that the number is indeed
prime.
X
@kindex I k n
@pindex calc-prev-prime
@tindex prevprime
The @kbd{I k n} (@code{calc-prev-prime}) [@code{prevprime}] command
analogously finds the next prime less than a given number.
X
@kindex k t
@pindex calc-totient
@tindex totient
The @kbd{k t} (@code{calc-totient}) [@code{totient}] command computes the
Euler ``totient'' function@c{ $\phi(n)$}
@asis{}, the number of integers less than @cite{n} which
are relatively prime to @cite{n}.
X
@kindex k m
@pindex calc-moebius
@tindex moebius
The @kbd{k m} (@code{calc-moebius}) [@code{moebius}] command computes the
@c{M\"obius $\mu$}
@asis{Moebius ``mu''} function.  If the input number is a product of @cite{k}
distinct factors, this is @cite{(-1)^k}.  If the input number has any
duplicate factors (i.e., can be divided by the same prime more than once),
the result is zero.
X
@node Probability Distribution Functions, , Combinatorial Functions, Scientific Functions
@section Probability Distribution Functions
X
@noindent
The functions in this section compute various probability distributions.
For continuous distributions, this is the integral of the probability
density function from @cite{x} to infinity.  (These are the ``upper
tail'' distribution functions; there are also corresponding ``lower
tail'' functions which integrate from minus infinity to @cite{x}.)
For discrete distributions, the upper tail function gives the sum
from @cite{x} to infinity; the lower tail function gives the sum
from minus infinity up to, but not including, @cite{x}.
X
To integrate from @cite{x} to @cite{y}, just use the distribution
function twice and subtract.  For example, the probability that a
Gaussian random variable with mean 2 and standard deviation 1 will
lie in the range from 2.5 to 2.8 is @samp{utpn(2.5,2,1) - utpn(2.8,2,1)}
(``the probability that it is greater than 2.5, but not greater than 2.8''),
or equivalently @samp{ltpn(2.8,2,1) - ltpn(2.5,2,1)}.
X
@kindex k B
@kindex I k B
@pindex calc-utpb
@tindex utpb
@tindex ltpb
The @kbd{k B} (@code{calc-utpb}) [@code{utpb}] function uses the
binomial distribution.  Push the parameters @var{n}, @var{p}, and
then @var{x} onto the stack; the result (@samp{utpb(x,n,p)}) is the
probability that an event will occur @var{x} or more times out
of @var{n} trials, if its probability of occurring in any given
trial is @var{p}.  The @kbd{I k B} [@code{ltpb}] function is
the probability that the event will occur fewer than @var{x} times.
X
The other probability distribution functions similarly take the
form @kbd{k @var{X}} (@code{calc-utp@var{x}}) [@code{utp@var{x}}]
and @kbd{I k @var{X}} [@code{ltp@var{x}}], for various letters
@var{x}.  The arguments to the algebraic functions are the value of
the random variable first, then whatever other parameters define the
distribution.  Note these are among the few Calc functions where the
order of the arguments in algebraic form differs from the order of
arguments as found on the stack.  (The random variable comes last on
the stack, so that you can type, e.g., @kbd{2 @key{RET} 1 @key{RET} 2.5
k N M-@key{RET} @key{DEL} 2.8 k N -}, using @kbd{M-@key{RET} @key{DEL}} to
recover the original arguments but substitute a new value for @cite{x}.)
X
@kindex k C
@kindex I k C
@pindex calc-utpc
@tindex utpc
@tindex ltpc
The @samp{utpc(x,v)} function uses the chi-square distribution with
@cite{v} degrees of freedom.  It is the probability that a model is
correct if its chi-square statistic is @cite{x}.
X
@kindex k F
@kindex I k F
@pindex calc-utpf
@tindex utpf
@tindex ltpf
The @samp{utpf(F,v1,v2)} function uses the F distribution, used in
various statistical tests.  The parameters @cite{v1} and @cite{v2}
are the degrees of freedom in the numerator and denominator,
respectively, used in computing the statistic @cite{F}.
X
@kindex k N
@kindex I k N
@pindex calc-utpn
@tindex utpn
@tindex ltpn
The @samp{utpn(x,m,s)} function uses a normal (Gaussian) distribution
with mean @cite{m} and standard deviation @cite{s}.  It is the
probability that such a normal-distributed random variable would
exceed @cite{x}.
X
@kindex k P
@kindex I k P
@pindex calc-utpp
@tindex utpp
@tindex ltpp
The @samp{utpp(n,x)} function uses a Poisson distribution with
mean @cite{x}.  It is the probability that @cite{n} or more such
Poisson random events will occur.
X
@kindex k T
@kindex I k T
@pindex calc-ltpt
@tindex utpt
@tindex ltpt
The @samp{utpt(t,v)} function uses the Student's ``t'' distribution
with @cite{v} degrees of freedom.  It is the probability that a
t-distributed random variable will be greater than @cite{t}.
(Note:  This computes the distribution function @cite{A(t|v)}
where @cite{A(0|v) = 1} and @c{$A(\infty|v) \to 0$}
@cite{A(inf|v) -> 0}.  The
@code{UTPT} operation on the HP-48 uses a different definition
which returns half of Calc's value:  @samp{UTPT(t,v) = .5*utpt(t,v)}.)
X
While Calc does not provide inverses of the probability distribution
functions, the @kbd{a R} command can be used to solve for the inverse.
Since the distribution functions are monotonic, @kbd{a R} is guaranteed
to be able to find a solution given any initial guess.
@xref{Numerical Solutions}.
X
@node Matrix Functions, Algebra, Scientific Functions, Top
@chapter Vector/Matrix Functions
X
@noindent
Many of the commands described here begin with the @kbd{v} prefix.
(For convenience, the shift-@kbd{V} prefix is equivalent to @kbd{v}.)
The commands usually apply to both plain vectors and matrices; some
apply only to matrices or only to square matrices.  If the argument
has the wrong dimensions the operation is left in symbolic form.
X
Vectors are entered and displayed using @samp{[a,b,c]} notation.
Matrices are vectors of which all elements are vectors of equal length.
(Though none of the standard Calc commands use this concept, a
three-dimensional matrix or rank-3 tensor could be defined as a
vector of matrices, and so on.)
X
@menu
* Packing and Unpacking::
* Building Vectors::
* Extracting Elements::
* Manipulating Vectors::
* Vector and Matrix Arithmetic::
* Set Operations::
* Statistical Operations::
* Reducing and Mapping::
* Vector and Matrix Formats::
@end menu
X
@node Packing and Unpacking, Building Vectors, Matrix Functions, Matrix Functions
@section Packing and Unpacking
X
@noindent
Calc's ``pack'' and ``unpack'' commands collect stack entries to build
composite objects such as vectors and complex numbers.  They are
described in this chapter because they are most often used to build
vectors.
X
@kindex v p
@pindex calc-pack
The @kbd{v p} (@code{calc-pack}) [@code{pack}] command collects several
elements from the stack into a matrix, complex number, HMS form, error
form, etc.  It uses a numeric prefix argument to specify the kind of
object to be built; this argument is referred to as the ``packing mode.''
If the packing mode is a nonnegative integer, a vector of that
length is created.  For example, @kbd{C-u 5 v p} will pop the top
five stack elements and push back a single vector of those five
elements.  (@kbd{C-u 0 v p} simply creates an empty vector.)
X
The same effect can be had by pressing @kbd{[} to push an incomplete
vector on the stack, using @code{calc-roll-down} to sneak the
incomplete object up past a certain number of elements, and
then pressing @kbd{]} to complete the vector.
X
Negative packing modes create other kinds of composite objects:
X
@table @cite
@item -1
Two values are collected to build a complex number.  For example,
@kbd{5 @key{RET} 7 C-u -1 v p} creates the complex number
@cite{(5, 7)}.  The result is always a rectangular complex
number.  The two input values must both be real numbers,
i.e., integers, fractions, or floats.  If they are not, Calc
will instead build a formula like @samp{a + (0, 1) b}.  (The
other packing modes also create a symbolic answer if the
components are not suitable.)
X
@item -2
Two values are collected to build a polar complex number.
The first is the magnitude; the second is the phase expressed
in either degrees or radians according to the current angular
mode.
X
@item -3
Three values are collected into an HMS form.  The first
two values (hours and minutes) must be integers or
integer-valued floats.  The third value may be any real
number.
X
@item -4
Two values are collected into an error form.  The inputs
may be real numbers or formulas.
X
@item -5
Two values are collected into a modulo form.  The inputs
must be real numbers.
X
@item -6
Two values are collected into the interval @samp{[a .. b]}.
The inputs may be real numbers, HMS or date forms, or formulas.
X
@item -7
Two values are collected into the interval @samp{[a .. b)}.
X
@item -8
Two values are collected into the interval @samp{(a .. b]}.
X
@item -9
Two values are collected into the interval @samp{(a .. b)}.
X
@item -10
Two integer values are collected into a fraction.
X
@item -11
Two values are collected into a floating-point number.
The first is the mantissa; the second, which must be an
integer, is the exponent.  The result is the mantissa
times ten to the power of the exponent.
X
@item -12
This is treated the same as @i{-11} by the @kbd{v p} command.
When unpacking, @i{-12} specifies that a floating-point mantissa
is desired.
X
@item -13
A real number is converted into a date form.
X
@item -14
Three numbers (year, month, day) are packed into a pure date form.
X
@item -15
Six numbers are packed into a date/time form.
@end table
X
With any of the two-input negative packing modes, either or both
of the inputs may be vectors.  If both are vectors of the same
length, the result is another vector made by packing corresponding
elements of the input vectors.  If one input is a vector and the
other is a plain number, the number is packed along with each vector
element to produce a new vector.  For example, @kbd{C-u -4 v p}
could be used to convert a vector of numbers and a vector of errors
into a single vector of error forms; @kbd{C-u -5 v p} could convert
a vector of numbers and a single number @var{M} into a vector of
numbers modulo @var{M}.
X
If you don't give a prefix argument to @kbd{v p}, it takes
the packing mode from the top of the stack.  The elements to
be packed then begin at stack level 2.  Thus
@kbd{1 @key{RET} 2 @key{RET} 4 n v p} is another way to
enter the error form @samp{1 +/- 2}.
X
If the packing mode taken from the stack is a vector, the result is a
matrix with the dimensions specified by the elements of the vector,
which must each be integers.  For example, if the packing mode is
@samp{[2, 3]}, then six numbers will be taken from the stack and
returned in the form @samp{[[a, b, c], [d, e, f]]}.
X
If any elements of the vector are negative, other kinds of
packing are done at that level as described above.  For
example, @samp{[2, 3, -4]} takes 12 objects and creates a
@c{$2\times3$}
@asis{2x3} matrix of error forms: @samp{[[a +/- b, c +/- d ... ]]}.
Also, @samp{[-4, -10]} will convert four integers into an
error form consisting of two fractions:  @samp{a:b +/- c:d}.
X
@tindex pack
There is an equivalent algebraic function,
@samp{pack(@var{mode}, @var{items})} where @var{mode} is a
packing mode (an integer or a vector of integers) and @var{items}
is a vector of objects to be packed (re-packed, really) according
to that mode.  For example, @samp{pack([3, -4], [a,b,c,d,e,f])}
yields @samp{[a +/- b, c +/- d, e +/- f]}.  The function is
left in symbolic form if the packing mode is illegal, or if the
number of data items does not match the number of items required
by the mode.
X
@kindex v u
@pindex calc-unpack
The @kbd{v u} (@code{calc-unpack}) command takes the vector, complex
number, HMS form, or other composite object on the top of the stack and
``unpacks'' it, pushing each of its elements onto the stack as separate
objects.  Thus, it is the ``inverse'' of @kbd{v p}.  If the value
at the top of the stack is a formula, @kbd{v u} unpacks it by pushing
each of the arguments of the top-level operator onto the stack.
X
You can optionally give a numeric prefix argument to @kbd{v u}
to specify an explicit (un)packing mode.  If the packing mode is
negative and the input is actually a vector or matrix, the result
will be two or three similar vectors or matrices of the elements.
For example, given the vector @samp{[a +/- b, c^2, d +/- 7]},
the result of @kbd{C-u -4 v u} will be the two vectors
@samp{[a, c^2, d]} and @samp{[b, 0, 7]}.
X
Note that the prefix argument can have an effect even when the input is
not a vector.  For example, if the input is the number @i{-5}, then
@kbd{c-u -1 v u} yields @i{-5} and 0 (the components of @i{-5}
when viewed as a rectangular complex number); @kbd{C-u -2 v u} yields 5
and 180 (assuming degrees mode); and @kbd{C-u -10 v u} yields @i{-5}
and 1 (the numerator and denominator of @i{-5}, viewed as a rational
number).  Plain @kbd{v u} with this input would complain that the input
is not a composite object.
X
Unpacking mode @i{-11} converts a float into an integer mantissa and
an integer exponent, where the mantissa is not divisible by 10
(except that 0.0 is represented by a mantissa and exponent of 0).
Unpacking mode @i{-12} converts a float into a floating-point mantissa
and integer exponent, where the mantissa (for non-zero numbers)
is guaranteed to lie in the range [1 .. 10).  In both cases,
the mantissa is shifted left or right (and the exponent adjusted
to compensate) in order to satisfy these constraints.
X
Positive unpacking modes are treated differently than for @kbd{v p}.
A mode of 1 is much like plain @kbd{v u} with no prefix argument,
except that in addition to the components of the input object,
a suitable packing mode to re-pack the object is also pushed.
Thus, @kbd{C-u 1 v u} followed by @kbd{v p} will re-build the
original object.
X
A mode of 2 unpacks two levels of the object; the resulting
re-packing mode will be a vector of length 2.  This might be used
to unpack a matrix, say, or a vector of error forms.  Higher
unpacking modes unpack the input even more deeply.
X
@tindex unpack
There are two algebraic functions analogous to @kbd{v u}.
The @samp{unpack(@var{mode}, @var{item})} function unpacks the
@var{item} using the given @var{mode}, returning the result as
a vector of components.  Here the @var{mode} must be an
integer, not a vector.  For example, @samp{unpack(-4, a +/- b)}
returns @samp{[a, b]}, as does @samp{unpack(1, a +/- b)}.
X
@tindex unpackt
The @code{unpackt} function is like @code{unpack} but instead
of returning a simple vector of items, it returns a vector of
two things:  The mode, and the vector of items.  For example,
@samp{unpackt(1, 2:3 +/- 1:4)} returns @samp{[-4, [2:3, 1:4]]},
and @samp{unpackt(2, 2:3 +/- 1:4)} returns @samp{[[-4, -10], [2, 3, 1, 4]]}.
The identity for re-building the original object is
@samp{apply(pack, unpackt(@var{n}, @var{x})) = @var{x}}.  (The
@code{apply} function builds a function call given the function
name and a vector of arguments.)
X
@cindex Numerator of a fraction, extracting
Subscript notation is a useful way to extract a particular part
of an object.  For example, to get the numerator of a rational
number, you can use @samp{unpack(-10, @var{x})_1}.
X
@node Building Vectors, Extracting Elements, Packing and Unpacking, Matrix Functions
@section Building Vectors
X
@noindent
Vectors and matrices can be added,
subtracted, multiplied, and divided; @pxref{Basic Arithmetic}.@refill
X
@kindex |
@pindex calc-concat
@tindex |
The @kbd{|} (@code{calc-concat}) command ``concatenates'' two vectors
together.  For example, after @kbd{[ 1 , 2 ] [ 3 , 4 ] |}, the stack
will contain the single vector @samp{[1, 2, 3, 4]}.  If the arguments
are matrices, the rows of the first matrix are concatenated with the
rows of the second.  (In other words, two matrices are just two vectors
of row-vectors as far as @kbd{|} is concerned.)
X
If either argument to @kbd{|} is a scalar (a non-vector), it is treated
like a one-element vector for purposes of concatenation:  @kbd{1 [ 2 , 3 ] |}
produces the vector @samp{[1, 2, 3]}.  Likewise, if one argument is a
matrix and the other is a plain vector, the vector is treated as a
one-row matrix.
X
@kindex H |
@tindex append
The @kbd{H |} (@code{calc-append}) [@code{append}] command concatenates
two vectors without any special cases.  Both inputs must be vectors.
Whether or not they are matrices is not taken into account.  If either
argument is a scalar, the @code{append} function is left in symbolic form.
See also @code{cons} and @code{rcons} below.
X
@kindex I |
@kindex H I |
The @kbd{I |} and @kbd{H I |} commands are similar, but they use their
two stack arguments in the opposite order.  Thus @kbd{I |} is equivalent
to @kbd{TAB |}, but possibly more convenient and also a bit faster.
X
@kindex v d
@pindex calc-diag
@tindex diag
The @kbd{v d} (@code{calc-diag}) [@code{diag}] function builds a diagonal
square matrix.  The optional numeric prefix gives the number of rows
and columns in the matrix.  If the value at the top of the stack is a
vector, the elements of the vector are used as the diagonal elements; the
prefix, if specified, must match the size of the vector.  If the value on
the stack is a scalar, it is used for each element on the diagonal, and
the prefix argument is required.
X
To build a constant square matrix, e.g., a @c{$3\times3$}
@asis{3x3} matrix filled with ones,
use @kbd{0 M-3 v d 1 +}, i.e., build a zero matrix first and then add a
constant value to that matrix.  (Another alternative would be to use
@code{calc-build-vector} and @code{calc-arrange-vector}; see below.)
X
@kindex v i
@pindex calc-ident
@tindex idn
The @kbd{v i} (@code{calc-ident}) [@code{idn}] function builds an identity
matrix of the specified size.  It is a convenient form of @code{calc-diag}
where the diagonal element is always one.  If no prefix argument is given,
this command prompts for one.
X
In algebraic notation, @samp{idn(a,n)} acts much like @samp{diag(a,n)},
except that @cite{a} is required to be a scalar (non-vector) quantity.
If @cite{n} is omitted, @samp{idn(a)} represents @cite{a} times an
identity matrix of unknown size.  Calc can operate algebraically on
such generic identity matrices, and if one is combined with a matrix
whose size is known, it is converted automatically to an identity
matrix of a suitable matching size.  The @kbd{v i} command with an
argument of zero creates a generic identity matrix, @samp{idn(1)}.
Note that in dimensioned matrix mode (@pxref{Matrix Mode}), generic
identity matrices are immediately expanded to the current default
dimensions.
X
@kindex v x
@pindex calc-index
@tindex index
The @kbd{v x} (@code{calc-index}) [@code{index}] function builds a vector
of consecutive integers from 1 to @var{n}, where @var{n} is the numeric
prefix argument.  If you do not provide a prefix argument, you will be
prompted to enter a suitable number.  If @var{n} is negative, the result
is a vector of negative integers from @var{n} to @i{-1}.
X
With a prefix argument of just @kbd{C-u}, the @kbd{v x} command takes
three values from the stack: @var{n}, @var{start}, and @var{incr} (with
@var{incr} at top-of-stack).  Counting starts at @var{start} and increases
by @var{incr} for successive vector elements.  If @var{start} or @var{n}
is in floating-point format, the resulting vector elements will also be
floats.  Note that @var{start} and @var{incr} may in fact be any kind
of numbers or formulas.
X
When @var{start} and @var{incr} are specified, a negative @var{n} has a
different interpretation:  It causes a geometric instead of arithmetic
sequence to be generated.  For example, @samp{index(-3, a, b)} produces
@samp{[a, a b, a b^2]}.  If you omit @var{incr} in the algebraic form,
@samp{index(@var{n}, @var{start})}, the default value for @var{incr}
is one for positive @var{n} or two for negative @var{n}.
X
@kindex v b
@pindex calc-build-vector
@tindex cvec
The @kbd{v b} (@code{calc-build-vector}) [@code{cvec}] function builds a
vector of @var{n} copies of the value on the top of the stack, where @var{n}
is the numeric prefix argument.  In algebraic formulas, @samp{cvec(x,n,m)}
can also be used to build an @var{n}-by-@var{m} matrix of copies of @var{x}.
(Interactively, just use @kbd{v b} twice: once to build a row, then again
to build a matrix of copies of that row.)
X
@kindex v h
@kindex I v h
@pindex calc-head
@pindex calc-tail
@tindex head
@tindex tail
The @kbd{v h} (@code{calc-head}) [@code{head}] function returns the first
element of a vector.  The @kbd{I v h} (@code{calc-tail}) [@code{tail}]
function returns the vector with its first element removed.  In both
cases, the argument must be a non-empty vector.
X
@kindex v k
@pindex calc-cons
@tindex cons
The @kbd{v k} (@code{calc-cons}) [@code{cons}] function takes a value @var{h}
and a vector @var{t} from the stack, and produces the vector whose head is
@var{h} and whose tail is @var{t}.  This is similar to @kbd{|}, except
if @var{h} is itself a vector, @kbd{|} will concatenate the two vectors
whereas @code{cons} will insert @var{h} at the front of the vector @var{t}.
X
@kindex H v h
@kindex H I v h
@kindex H v k
@tindex rhead
@tindex rtail
@tindex rcons
Each of these three functions also accepts the Hyperbolic flag [@code{rhead},
@code{rtail}, @code{rcons}] in which case @var{t} instead represents
the @emph{last} single element of the vector, with @var{h}
representing the remainder of the vector.  Thus the vector
@samp{[a, b, c, d] = cons(a, [b, c, d]) = rcons([a, b, c], d)}.
Also, @samp{head([a, b, c, d]) = a}, @samp{tail([a, b, c, d]) = [b, c, d]},
@samp{rhead([a, b, c, d]) = [a, b, c]}, and @samp{rtail([a, b, c, d]) = d}.
X
@node Extracting Elements, Manipulating Vectors, Building Vectors, Matrix Functions
@section Extracting Vector Elements
X
@noindent
@kindex v r
@pindex calc-mrow
@tindex mrow
The @kbd{v r} (@code{calc-mrow}) [@code{mrow}] command extracts one row of
the matrix on the top of the stack, or one element of the plain vector on
the top of the stack.  The row or element is specified by the numeric
prefix argument; the default is to prompt for the row or element number.
The matrix or vector is replaced by the specified row or element in the
form of a vector or scalar, respectively.
X
@cindex Permutations, applying
With a prefix argument of @kbd{C-u} only, @kbd{v r} takes the index of
the element or row from the top of the stack, and the vector or matrix
from the second-to-top position.  If the index is itself a vector of
integers, the result is a vector of the corresponding elements of the
input vector, or a matrix of the corresponding rows of the input matrix.
This command can be used to obtain any permutation of a vector.
X
With @kbd{C-u}, if the index is an interval form with integer components,
it is interpreted as a range of indices and the corresponding subvector or
submatrix is returned.
X
@cindex Subscript notation
@kindex a _
@pindex calc-subscript
@tindex subscr
@tindex _
Subscript notation in algebraic formulas (@samp{a_b}) stands for the
Calc function @code{subscr}, which is synonymous with @code{mrow}.
Thus, @samp{[x, y, z]_k} produces @cite{x}, @cite{y}, or @cite{z} if
@cite{k} is one, two, or three, respectively.  A double subscript
(@samp{M_i_j}, equivalent to @samp{subscr(subscr(M, i), j)}) will
access the element at row @cite{i}, column @cite{j} of a matrix.
The @kbd{a _} [@code{calc-subscript}] command creates a subscript
formula @samp{a_b} out of two stack entries.  (It is on the @kbd{a}
``algebra'' prefix because subscripted variables are often used
purely as an algebraic notation.)
X
@tindex mrrow
Given a negative prefix argument, @kbd{v r} instead deletes one row or
element from the matrix or vector on the top of the stack.  Thus
@kbd{C-u 2 v r} replaces a matrix with its second row, but @kbd{C-u -2 v r}
replaces the matrix with the same matrix with its second row removed.
In algebraic form this function is called @code{mrrow}.
X
@tindex getdiag
Given a prefix argument of zero, @kbd{v r} extracts the diagonal elements
of a square matrix in the form of a vector.  In algebraic form this
function is called @code{getdiag}.
X
@kindex v c
@pindex calc-mcol
@tindex mcol
@tindex mrcol
The @kbd{v c} (@code{calc-mcol}) [@code{mcol} or @code{mrcol}] command is
the analogous operation on columns of a matrix.  Given a plain vector
it extracts (or removes) one element, just like @kbd{v r}.  If the
index in @kbd{C-u v c} is an interval or vector and the argument is a
matrix, the result is a submatrix with only the specified columns
retained (and possibly permuted in the case of a vector index).@refill
X
To extract a matrix element at a given row and column, use @kbd{v r} to
extract the row as a vector, then @kbd{v c} to extract the column element
from that vector.  In algebraic formulas, it is often more convenient to
use subscript notation:  @samp{m_i_j} gives row @cite{i}, column @cite{j}
of matrix @cite{m}.
X
@kindex v s
@pindex calc-subvector
@tindex subvec
The @kbd{v s} (@code{calc-subvector}) [@code{subvec}] command extracts
a subvector of a vector.  The arguments are the vector, the starting
index, and the ending index, with the ending index in the top-of-stack
position.  The starting index indicates the first element of the vector
to take.  The ending index indicates the first element @emph{past} the
range to be taken.  Thus, @samp{subvec([a, b, c, d, e], 2, 4)} produces
the subvector @samp{[b, c]}.  You could get the same result using
@samp{mrow([a, b, c, d, e], [2 .. 4))}.
X
If either the start or the end index is zero or negative, it is
interpreted as relative to the end of the vector.  Thus
@samp{subvec([a, b, c, d, e], 2, -2)} also produces @samp{[b, c]}.  In
the algebraic form, the end index can be omitted in which case it
is taken as zero, i.e., elements from the starting element to the
end of the vector are used.  The infinity symbol, @code{inf}, also
has this effect when used as the ending index.
X
@kindex I v s
@tindex rsubvec
With the Inverse flag, @kbd{I v s} [@code{rsubvec}] removes a subvector
from a vector.  The arguments are interpreted the same as for the
normal @kbd{v s} command.  Thus, @samp{rsubvec([a, b, c, d, e], 2, 4)}
produces @samp{[a, d, e]}.  It is always true that @code{subvec} and
@code{rsubvec} return complementary parts of the input vector.
X
@xref{Selecting Subformulas}, for an alternative way to operate on
vectors one element at a time.
X
@node Manipulating Vectors, Vector and Matrix Arithmetic, Extracting Elements, Matrix Functions
@section Manipulating Vectors
X
@noindent
@kindex v l
@pindex calc-vlength
@tindex vlen
The @kbd{v l} (@code{calc-vlength}) [@code{vlen}] command computes the
length of a vector.  The length of a non-vector is considered to be zero.
Note that matrices are just vectors of vectors for the purposes of this
command.@refill
X
@kindex H v l
@tindex mdims
With the Hyperbolic flag, @kbd{H v l} [@code{mdims}] computes a vector
of the dimensions of a vector, matrix, or higher-order object.  For
example, @samp{mdims([[a,b,c],[d,e,f]])} returns @samp{[2, 3]} since
its argument is a @c{$2\times3$}
@asis{2x3} matrix.
X
@kindex v f
@pindex calc-vector-find
@tindex find
The @kbd{v f} (@code{calc-vector-find}) [@code{find}] command searches
along a vector for the first element equal to a given target.  The target
is on the top of the stack; the vector is in the second-to-top position.
If a match is found, the result is the index of the matching element.
Otherwise, the result is zero.  The numeric prefix argument, if given,
allows you to select any starting index for the search.
X
@kindex v a
@pindex calc-arrange-vector
@tindex arrange
@cindex Arranging a matrix
@cindex Reshaping a matrix
@cindex Flattening a matrix
The @kbd{v a} (@code{calc-arrange-vector}) [@code{arrange}] command
rearranges a vector to have a certain number of columns and rows.  The
numeric prefix argument specifies the number of columns; if you do not
provide an argument, you will be prompted for the number of columns.
The vector or matrix on the top of the stack is @dfn{flattened} into a
plain vector.  If the number of columns is nonzero, this vector is
then formed into a matrix by taking successive groups of @var{n} elements.
If the number of columns does not evenly divide the number of elements
in the vector, the last row will be short and the result will not be
suitable for use as a matrix.  For example, with the matrix
@samp{[[1, 2], [3, 4]]} on the stack, @kbd{v a 4} produces
@samp{[[1, 2, 3, 4]]} (a @c{$1\times4$}
@asis{1x4} matrix), @kbd{v a 1} produces
@samp{[[1], [2], [3], [4]]} (a @c{$4\times1$}
@asis{4x1} matrix), @kbd{v a 2} produces
@samp{[[1, 2], [3, 4]]} (the original @c{$2\times2$}
@asis{2x2} matrix), @kbd{v a 3} produces
@samp{[[1, 2, 3], [4]]} (not a matrix), and @kbd{v a 0} produces
the flattened list @samp{[1, 2, 3, 4]}.
X
@cindex Sorting data
@kindex V S
@kindex I V S
@pindex calc-sort
@tindex sort
@tindex rsort
The @kbd{V S} (@code{calc-sort}) [@code{sort}] command sorts the elements of
a vector into increasing order.  Real numbers, real infinities, and
constant interval forms come first in this ordering; next come other
kinds of numbers, then variables (in alphabetical order), then finally
come formulas and other kinds of objects; these are sorted according
to a kind of lexicographic ordering with the useful property that one
one vector is less or greater than another if the first corresponding
unequal elements are less or greater, respectively.  Since quoted strings
are stored by Calc internally as vectors of ASCII character codes
(@pxref{Strings}), this means strings are also sorted into alphabetical
order by this command.
X
The @kbd{I V S} [@code{rsort}] command sorts a vector into decreasing order.
X
@cindex Permutation, inverse of
@cindex Inverse of permutation
@cindex Index tables
@cindex Rank tables
@kindex V G
@kindex I V G
@pindex calc-grade
@tindex grade
@tindex rgrade
The @kbd{V G} (@code{calc-grade}) [@code{grade}, @code{rgrade}] command
produces an index table or permutation vector which, if applied to the
input vector (as the index of @kbd{C-u v r}, say), would sort the vector.
A permutation vector is just a vector of integers from 1 to @var{n}, where
each integer occurs exactly once.  One application of this is to sort a
matrix of data rows using one column as the sort key; extract that column,
grade it with @kbd{V G}, then use the result to reorder the original matrix
with @kbd{C-u v r}.  Another interesting property of the @code{V G} command
is that, if the input is itself a permutation vector, the result will
be the inverse of the permutation.  The inverse of an index table is
a rank table, whose @var{k}th element says where the @var{k}th original
vector element will rest when the vector is sorted.  To get a rank
table, just use @kbd{V G V G}.
X
With the Inverse flag, @kbd{I V G} produces an index table that would
sort the input into decreasing order.  Note that @kbd{V S} and @kbd{V G}
use a ``stable'' sorting algorithm, i.e., any two elements which are equal
will not be moved out of their original order.  Generally there is no way
to tell with @kbd{V S}, since two elements which are equal look the same,
but with @kbd{V G} this can be an important issue.  In the matrix-of-rows
example, suppose you have names and telephone numbers as two columns and
you wish to sort by phone number primarily, and by name when the numbers
are equal.  You can sort the data matrix by names first, and then again
by phone numbers.  Because the sort is stable, any two rows with equal
phone numbers will remain sorted by name even after the second sort.
X
@cindex Histograms
@kindex V H
@pindex calc-histogram
@tindex histogram
The @kbd{V H} (@code{calc-histogram}) [@code{histogram}] command builds a
histogram of a vector of numbers.  Vector elements are assumed to be
integers or real numbers in the range [0..@var{n}) for some ``number of
bins'' @var{n}, which is the numeric prefix argument given to the
command.  The result is a vector of @var{n} counts of how many times
each value appeared in the original vector.  Non-integers in the input
are rounded down to integers.  Any vector elements outside the specified
range are ignored.  (You can tell if elements have been ignored by noting
that the counts in the result vector don't add up to the length of the
input vector.)
X
@kindex H V H
With the Hyperbolic flag, @kbd{H V H} pulls two vectors from the stack.
The second-to-top vector is the list of numbers as before.  The top
vector is an equal-sized list of ``weights'' to attach to the elements
of the data vector.  For example, if the first data element is 4.2 and
the first weight is 10, then 10 will be added to bin 4 of the result
vector.  Without the hyperbolic flag, every element has a weight of one.
X
@kindex v t
@pindex calc-transpose
@tindex trn
The @kbd{v t} (@code{calc-transpose}) [@code{trn}] command computes
the transpose of the matrix at the top of the stack.  If the argument
is a plain vector, it is treated as a row vector and transposed into
a one-column matrix.
X
@kindex v v
@pindex calc-reverse-vector
@tindex rev
The @kbd{v v} (@code{calc-reverse-vector}) [@code{vec}] command reverses
a vector end-for-end.  Given a matrix, it reverses the order of the rows.
(To reverse the columns instead, just use @kbd{v t v v v t}.  The same
principle can be used to apply other vector commands to the columns of
a matrix.)
X
@kindex v m
@pindex calc-mask-vector
@tindex vmask
The @kbd{v m} (@code{calc-mask-vector}) [@code{vmask}] command uses
one vector as a mask to extract elements of another vector.  The mask
is in the second-to-top position; the target vector is on the top of
the stack.  These vectors must have the same length.  The result is
the same as the target vector, but with all elements which correspond
to zeros in the mask vector deleted.  Thus, for example,
@samp{vmask([1, 0, 1, 0, 1], [a, b, c, d, e])} produces @samp{[a, c, e]}.
X
@kindex v e
@pindex calc-expand-vector
@tindex vexp
The @kbd{v e} (@code{calc-expand-vector}) [@code{vexp}] command
expands a vector according to another mask vector.  The result is a
vector the same length as the mask, but with nonzero elements replaced
by successive elements from the target vector.  The length of the target
vector is normally the number of nonzero elements in the mask.  If the
target vector is longer, its last few elements are lost.  If the target
vector is shorter, the last few nonzero mask elements are left
unreplaced in the result.  Thus @samp{vexp([2, 0, 3, 0, 7], [a, b])}
produces @samp{[a, 0, b, 0, 7]}.
X
@kindex H v e
With the Hyperbolic flag, @kbd{H v e} takes a filler value from the
top of the stack; the mask and target vectors come from the third and
second elements of the stack.  This filler is used where the mask is
zero:  @samp{vexp([2, 0, 3, 0, 7], [a, b], z)} produces
@samp{[a, z, c, z, 7]}.  If the filler value is itself a vector,
then successive values are taken from it, so that the effect is to
interleave two vectors according to the mask:
@samp{vexp([2, 0, 3, 7, 0, 0], [a, b], [x, y])} produces
@samp{[a, x, b, 7, y, 0]}.
X
Another variation on the masking idea is to combine @samp{[a, b, c, d, e]}
with the mask @samp{[1, 0, 1, 0, 1]} to produce @samp{[a, 0, c, 0, e]}.
You can accomplish this with @kbd{V M a &}, mapping the logical ``and''
operation across the two vectors.  @xref{Logical Operations}.  Note that
the @code{? :} operation also discussed there allows other types of
masking using vectors.
X
@node Vector and Matrix Arithmetic, Set Operations, Manipulating Vectors, Matrix Functions
@section Vector and Matrix Arithmetic
X
@noindent
Basic arithmetic operations like addition and multiplication are defined
for vectors and matrices as well as for numbers.  Division of matrices, in
the sense of multiplying by the inverse, is supported.  (Division by a
matrix actually uses LU-decomposition for greater accuracy and speed.)
@xref{Basic Arithmetic}.
X
The following functions are applied element-wise if their arguments are
vectors or matrices: @code{change-sign}, @code{conj}, @code{arg},
@code{re}, @code{im}, @code{polar}, @code{rect}, @code{clean},
@code{float}, @code{frac}.  @xref{Function Index}.@refill
X
@kindex V J
@pindex calc-conj-transpose
@tindex ctrn
The @kbd{V J} (@code{calc-conj-transpose}) [@code{ctrn}] command computes
the conjugate transpose of its argument, i.e., @samp{conj(trn(x))}.
X
@kindex A (vectors)
@pindex calc-abs (vectors)
@tindex abs (vectors)
The @kbd{A} (@code{calc-abs}) [@code{abs}] command computes the
Frobenius norm of a vector or matrix argument.  This is the square
root of the sum of the squares of the absolute values of the
elements of the vector or matrix.  If the vector is interpreted as
a point in two- or three-dimensional space, this is the distance
from that point to the origin.@refill
X
@kindex v n
@pindex calc-rnorm
@tindex rnorm
The @kbd{v n} (@code{calc-rnorm}) [@code{rnorm}] command computes
the row norm, or infinity-norm, of a vector or matrix.  For a plain
vector, this is the maximum of the absolute values of the elements.
For a matrix, this is the maximum of the row-absolute-value-sums,
i.e., of the sums of the absolute values of the elements along the
various rows.
X
@kindex V N
@pindex calc-cnorm
@tindex cnorm
The @kbd{V N} (@code{calc-cnorm}) [@code{cnorm}] command computes
the column norm, or one-norm, of a vector or matrix.  For a plain
vector, this is the sum of the absolute values of the elements.
For a matrix, this is the maximum of the column-absolute-value-sums.
General @cite{k}-norms for @cite{k} other than one or infinity are
not provided.
X
@kindex V C
@pindex calc-cross
@tindex cross
The @kbd{V C} (@code{calc-cross}) [@code{cross}] command computes the
right-handed cross product of two vectors, each of which must have
exactly three elements.
X
@kindex & (matrices)
@pindex calc-inv (matrices)
@tindex inv (matrices)
The @kbd{&} (@code{calc-inv}) [@code{inv}] command computes the
inverse of a square matrix.  If the matrix is singular, the inverse
operation is left in symbolic form.  Matrix inverses are recorded so
that once an inverse (or determinant) of a particular matrix has been
computed, the inverse and determinant of the matrix can be recomputed
quickly in the future.
X
If the argument to @kbd{&} is a plain number @cite{x}, this
command simply computes @cite{1/x}.  This is okay, because the
@samp{/} operator also does a matrix inversion when dividing one
by a matrix.
X
@kindex V D
@pindex calc-mdet
@tindex det
The @kbd{V D} (@code{calc-mdet}) [@code{det}] command computes the
determinant of a square matrix.
X
@kindex V L
@pindex calc-mlud
@tindex lud
The @kbd{V L} (@code{calc-mlud}) [@code{lud}] command computes the
LU decomposition of a matrix.  The result is a list of three matrices
which, when multiplied together left-to-right, form the original matrix.
The first is a permutation matrix that arises from pivoting in the
algorithm, the second is lower-triangular with ones on the diagonal,
and the third is upper-triangular.
X
@kindex V T
@pindex calc-mtrace
@tindex tr
The @kbd{V T} (@code{calc-mtrace}) [@code{tr}] command computes the
trace of a square matrix.  This is defined as the sum of the diagonal
elements of the matrix.
X
@node Set Operations, Statistical Operations, Vector and Matrix Arithmetic, Matrix Functions
@section Set Operations using Vectors
X
@noindent
@cindex Sets, as vectors
Calc includes several commands which interpret vectors as @dfn{sets} of
objects.  A set is a collection of objects; any given object can appear
only once in the set.  Calc stores sets as vectors of objects in
sorted order.  Objects in a Calc set can be any of the usual things,
such as numbers, variables, or formulas.  Two set elements are considered
equal if they are identical, except that numerically equal numbers like
the integer 4 and the float 4.0 are considered equal even though they
are not ``identical.''  Variables are treated like plain symbols without
attached values by the set operations; subtracting the set @samp{[b]}
from @samp{[a, b]} always yields the set @samp{[a]} even though if
the variables @samp{a} and @samp{b} both equalled 17, you might
expect the answer @samp{[]}.
X
If a set contains interval forms, then it is assumed to be a set of
real numbers.  In this case, all set operations require the elements
of the set to be only things that are allowed in intervals:  Real
numbers, plus and minus infinity, HMS forms, and date forms.  If
there are variables or other non-real objects present in a real set,
all set operations on it will be left in unevaluated form.
X
If the input to a set operation is a plain number or interval form
@var{a}, it is treated like the one-element vector @samp{[@var{a}]}.
The result is always a vector, except that if the set consists of a
single interval, the interval itself is returned instead.
X
@xref{Logical Operations}, for the @code{in} function which tests if
a certain value is a member of a given set.  To test if the set @cite{a}
is a subset of the set @cite{b}, use @samp{vdiff(a, b) = []}.
X
@kindex V +
@pindex calc-remove-duplicates
@tindex rdup
The @kbd{V +} (@code{calc-remove-duplicates}) [@code{rdup}] command
converts an arbitrary vector into set notation.  It works by sorting
the vector as if by @kbd{V S}, then removing duplicates.  (For example,
@kbd{[a, 5, 4, a, 4.0]} is sorted to @samp{[4, 4.0, 5, a, a]} and then
reduced to @samp{[4, 5, a]}).  Overlapping intervals are merged as
necessary.  You rarely need to use @kbd{V +} explicitly, since all the
other set-based commands apply @kbd{V +} to their inputs before using
them.
X
@kindex V V
@pindex calc-set-union
@tindex vunion
The @kbd{V V} (@code{calc-set-union}) [@code{vunion}] command computes
the union of two sets.  An object is in the union of two sets if and
only if it is in either (or both) of the input sets.  (You could
accomplish the same thing by concatenating the sets with @kbd{|},
then using @kbd{V +}.)
X
@kindex V ^
@pindex calc-set-intersect
@tindex vint
The @kbd{V ^} (@code{calc-set-intersect}) [@code{vint}] command computes
the intersection of two sets.  An object is in the intersection if
and only if it is in both of the input sets.  Thus if the input
sets are disjoint, i.e., if they share no common elements, the result
will be the empty vector @samp{[]}.  Note that the characters @kbd{V}
and @kbd{^} were chosen to be close to the conventional mathematical
notation for set union@c{ ($A \cup B$)}
@asis{} and intersection@c{ ($A \cap B$)}
@asis{}.
X
@kindex V -
@pindex calc-set-difference
@tindex vdiff
The @kbd{V -} (@code{calc-set-difference}) [@code{vdiff}] command computes
the difference between two sets.  An object is in the difference
@cite{A - B} if and only if it is in @cite{A} but not in @cite{B}.
Thus subtracting @samp{[y,z]} from a set will remove the elements
@samp{y} and @samp{z} if they are present.  You can also think of this
as a general @dfn{set complement} operator; if @cite{A} is the set of
all possible values, then @cite{A - B} is the ``complement'' of @cite{B}.
Obviously this only makes sense if the set of all possible values in
your problem is small enough to list in a Calc vector (or simple
enough to express in a few intervals).
X
@kindex V X
@pindex calc-set-xor
@tindex vxor
The @kbd{V X} (@code{calc-set-xor}) [@code{vxor}] command computes
the ``exclusive-or,'' or ``symmetric difference'' of two sets.
An object is in the symmetric difference of two sets if and only
if it is in one, but @emph{not} both, of the sets.  Objects that
occur in both sets ``cancel out.''
X
@kindex V ~
@pindex calc-set-complement
@tindex vcompl
The @kbd{V ~} (@code{calc-set-complement}) [@code{vcompl}] command
computes the complement of a set with respect to the real numbers.
Thus @samp{vcompl(x)} is equivalent to @samp{vdiff([-inf .. inf], x)}.
For example, @samp{vcompl([2, (3 .. 4]])} evaluates to
@samp{[[-inf .. 2), (2 .. 3], (4 .. inf]]}.
X
@kindex V F
@pindex calc-set-floor
@tindex vfloor
The @kbd{V F} (@code{calc-set-floor}) [@code{vfloor}] command
reinterprets a set as a set of integers.  Any non-integer values,
and intervals that do not enclose any integers, are removed.  Open
intervals are converted to equivalent closed intervals.  Successive
integers are converted into intervals of integers.  For example, the
complement of the set @samp{[2, 6, 7, 8]} is messy, but if you wanted
the complement with respect to the set of integers you could type
@kbd{V ~ V F} to get @samp{[[-inf .. 1], [3 .. 5], [9 .. inf]]}.
X
@kindex V E
@pindex calc-set-enumerate
@tindex venum
The @kbd{V E} (@code{calc-set-enumerate}) [@code{venum}] command
converts a set of integers into an explicit vector.  Intervals in
the set are expanded out to lists of all integers encompassed by
the intervals.  This only works for finite sets (i.e., sets which
do not involve @samp{-inf} or @samp{inf}).
X
@kindex V :
@pindex calc-set-span
@tindex vspan
The @kbd{V :} (@code{calc-set-span}) [@code{vspan}] command converts any
set of reals into an interval form that encompasses all its elements.
The lower limit will be the smallest element in the set; the upper
limit will be the largest element.  For an empty set, @samp{vspan([])}
returns the empty interval @samp{[0 .. 0)}.
X
@kindex V #
@pindex calc-set-cardinality
@tindex vcard
The @kbd{V #} (@code{calc-set-cardinality}) [@code{vcard}] command counts
the number of integers in a set.  The result is the length of the vector
that would be produced by @kbd{V E}, although the computation is much
more efficient than actually producing that vector.
X
@cindex Sets, as binary numbers
Another representation for sets that may be more appropriate in some
cases is binary numbers.  If you are dealing with sets of integers
in the range 0 to 49, you can use a 50-bit binary number where a
particular bit is 1 if the corresponding element is in the set.
@xref{Binary Functions}, for a list of commands that operate on
binary numbers.  Note that many of the above set operations have
direct equivalents in binary arithmetic:  @kbd{b o} (@code{calc-or}),
@kbd{b a} (@code{calc-and}), @kbd{b d} (@code{calc-diff}),
@kbd{b x} (@code{calc-xor}), and @kbd{b n} (@code{calc-not}),
respectively.  You can use whatever representation for sets is most
convenient to you.
X
@kindex b p
@kindex b u
@pindex calc-pack-bits
@pindex calc-unpack-bits
@tindex vpack
@tindex vunpack
The @kbd{b u} (@code{calc-unpack-bits}) [@code{vunpack}] command
converts an integer that represents a set in binary into a set
in vector/interval notation.  For example, @samp{vunpack(67)}
returns @samp{[[0 .. 1], 6]}.  If the input is negative, the set
it represents is semi-infinite: @samp{vunpack(-4) = [2 .. inf)}.
Use @kbd{V E} afterwards to expand intervals to individual
values if you wish.  Note that this command uses the @kbd{b}
(binary) prefix key.
X
The @kbd{b p} (@code{calc-pack-bits}) [@code{vpack}] command
converts the other way, from a vector or interval representing
a set of nonnegative integers into a binary integer describing
the same set.  The set may include positive infinity, but must
not include any negative numbers.  The input is interpreted as a
set of integers in the sense of @kbd{V F} (@code{vfloor}).  Beware
that a simple input like @samp{[100]} can result in a huge integer
representation (@c{$2^{100}$}
@cite{2^100}, a 31-digit integer, in this case).
X
@node Statistical Operations, Reducing and Mapping, Set Operations, Matrix Functions
@section Statistical Operations on Vectors
X
@noindent
@cindex Statistical functions
The commands in this section take vectors as arguments and compute
various statistical measures on the data stored in the vectors.  The
references used in the definitions of these functions are Bevington's
@emph{Data Reduction and Error Analysis for the Physical Sciences},
and @emph{Numerical Recipes} by Press, Flannery, Teukolsky and
Vetterling.
X
The statistical commands use the @kbd{u} prefix key followed by
a shifted letter or other character.
X
@xref{Manipulating Vectors}, for a description of @kbd{V H}
(@code{calc-histogram}).
X
@xref{Curve Fitting}, for the @kbd{a F} command for doing
least-squares fits to statistical data.
X
@xref{Probability Distribution Functions}, for several common
probability distribution functions.
X
@menu
* Single-Variable Statistics::
* Paired-Sample Statistics::
@end menu
X
@node Single-Variable Statistics, Paired-Sample Statistics, Statistical Operations, Statistical Operations
@subsection Single-Variable Statistics
X
@noindent
These functions do various statistical computations on single
vectors.  Given a numeric prefix argument, they actually pop
@var{n} objects from the stack and combine them into a data
vector.  Each object may be either a number or a vector; if a
vector, any sub-vectors inside it are ``flattened'' as if by
@kbd{v a 0}; @pxref{Manipulating Vectors}.  By default one object
is popped, which (in order to be useful) is usually a vector.
X
If an argument is a variable name, and the value stored in that
variable is a vector, then the stored vector is used.  This method
has the advantage that if your data vector is large, you can avoid
the slow process of manipulating it directly on the stack.
X
These functions are left in symbolic form if any of their arguments
are not numbers or vectors, e.g., if an argument is a formula, or
a non-vector variable.  However, formulas embedded within vector
arguments are accepted; the result is a symbolic representation
of the computation, based on the assumption that the formula does
not itself represent a vector.  All varieties of numbers such as
error forms and interval forms are acceptable.
X
Some of the functions in this section also accept a single error form
or interval as an argument.  They then describe a property of the
normal or uniform (respectively) statistical distribution described
by the argument.  The arguments are interpreted in the same way as
the @var{M} argument of the random number function @kbd{k r}.  In
particular, an interval with integer limits is considered an integer
distribution, so that @samp{[2 .. 6)} is the same as @samp{[2 .. 5]}.
An interval with at least one floating-point limit is a continuous
distribution:  @samp{[2.0 .. 6.0)} is @emph{not} the same as
@samp{[2.0 .. 5.0]}!
X
@kindex u #
@pindex calc-vector-count
@tindex vcount
The @kbd{u #} (@code{calc-vector-count}) [@code{vcount}] command
computes the number of data values represented by the inputs.
For example, @samp{vcount(1, [2, 3], [[4, 5], [], x, y])} returns 7.
If the argument is a single vector with no sub-vectors, this
simply computes the length of the vector.
X
@kindex u +
@kindex u *
@pindex calc-vector-sum
@pindex calc-vector-prod
@tindex vsum
@tindex vprod
@cindex Summations (statistical)
The @kbd{u +} (@code{calc-vector-sum}) [@code{vsum}] command
computes the sum of the data values.  The @kbd{u *}
(@code{calc-vector-prod}) [@code{vprod}] command computes the
product of the data values.  If the input is a single flat vector,
these are the same as @kbd{V R +} and @kbd{V R *}
(@pxref{Reducing and Mapping}).@refill
X
@kindex u X
@kindex u N
@pindex calc-vector-max
@pindex calc-vector-min
@tindex vmax
@tindex vmin
The @kbd{u X} (@code{calc-vector-max}) [@code{vmax}] command
computes the maximum of the data values, and the @kbd{u N}
(@code{calc-vector-min}) [@code{vmin}] command computes the minimum.
If the argument is an interval, this finds the minimum or maximum
value in the interval.  (Note that @samp{vmax([2..6)) = 5} as
described above.)  If the argument is an error form, this returns
plus or minus infinity.
X
@kindex u M
@pindex calc-vector-mean
@tindex vmean
@cindex Mean of data values
The @kbd{u M} (@code{calc-vector-mean}) [@code{vmean}] command
computes the average (arithmetic mean) of the data values.
If the inputs are error forms @c{$x$ @code{+/-} $\sigma$}
@samp{x +/- s}, this is the weighted
mean of the @cite{x} values with weights @c{$1 / \sigma^2$}
@cite{1 / s^2}.
@tex
\turnoffactive
$$ \mu = { \displaystyle \sum { x_i \over \sigma_i^2 } \over
X           \displaystyle \sum { 1 \over \sigma_i^2 } } $$
@end tex
If the inputs are not error forms, this is simply the sum of the
values divided by the count of the values.@refill
X
Note that a plain number can be considered an error form with
error @c{$\sigma = 0$}
@cite{s = 0}.  If the input to @kbd{u M} is a mixture of
plain numbers and error forms, the result is the mean of the
plain numbers, ignoring all values with non-zero errors.  (By the
above definitions it's clear that a plain number effectively
has an infinite weight, next to which an error form with a finite
weight is completely negligible.)
X
This function also works for distributions (error forms or
intervals).  The mean of an error form `@i{a} @t{+/-} @i{b}' is simply
@cite{a}.  The mean of an interval is the mean of the minimum
and maximum values of the interval.
X
@kindex I u M
@pindex calc-vector-mean-error
@tindex vmeane
The @kbd{I u M} (@code{calc-vector-mean-error}) [@code{vmeane}]
command computes the mean of the data points expressed as an
SHAR_EOF
true || echo 'restore of calc.texinfo failed'
fi
echo 'End of  part 43'
echo 'File calc.texinfo is continued in part 44'
echo 44 > _shar_seq_.tmp
exit 0
exit 0 # Just in case...
--
Kent Landfield                   INTERNET: [e-mail]
Sterling Software, IMD           UUCP:     uunet!sparky!kent
Phone:    [phone]         FAX:      [phone]
Please send comp.sources.misc-related mail to [e-mail].