Next: svd() Up: MacAnova Help File Previous: subscripts   Contents

sum()

Usage:
sum(x [,squeeze:T] [,silent:T,undefval:U]), x REAL or LOGICAL or a
  structure with REAL or LOGICAL components, U a REAL scalar
sum(x, dimensions:J [,squeeze:T] [,silent:T,undefval:U]), vector of
  positive integers J
sum(x, margins:K [,squeeze:F] [,silent:T,undefval:U]), vector of
  positive integers K
sum(x1,x2,... [,silent:T,undefval:U]), x1, x2, ... REAL or LOGICAL
  vectors, all the same type.



Keywords: descriptive statistics
sum(x) computes the sum of the elements of a REAL or LOGICAL vector x.

If x is LOGICAL, True is interpreted as 1.0 and False as 0.0 and sum(x)
is the number of elements of x that are True.

If x is a m by n matrix, sum(x) computes a row vector (1 by n matrix)
consisting of the sum of the elements in each column of x.

If x is an array with dimensions n1, n2, n3, ..., y <- sum(x) computes
an array with dimensions 1, n2, n3, ... such that y[1,j,k,...] =
sum(x[i,j,k,...], i=1,...,n1).  This is consistent with what happens
when x is a matrix.  Note: MacAnova3.35 and earlier produced a result
with dimensions n2, n3, ... .

sum(x, squeeze:T) does the same, except the first dimension of the
result (of length 1) is squeezed out unless the result is a scalar.  In
particular, if x is a matrix, sum(x,squeeze:T) will be identical to
vector(sum(x)), and if x is an array, sum(x,squeeze:T) will be identical
to array(sum(x),dim(x)[-1]).

sum(NULL) is NULL.  See topic 'NULL'.

sum(a,b,c,...) is equivalent to sum(vector(a,b,c,...)) if a, b, c,
... are all vectors.  They must all have the same type, REAL or LOGICAL
or be NULL.  sum(NULL, NULL, ..., NULL) is NULL.

sum(x, silent:T) or sum(a,b,c,...,silent:T) does the same but suppresses
warning messages about MISSING values or overflows.

If all the elements of a vector x are MISSING, sum(x) is 0.0.

sum(x, undefval:U), where U is a REAL scalar does the same, except the
returned value is U when all the elements of x are MISSING.

sum(x, dimensions:J [,squeeze:T] [,silent:T] [,undefval:U]) sums over
the dimensions in J = vector(j1,j2,...,jn) where j1, ..., jn are
distinct positive integers <= ndims(x).  Without 'squeeze:T', the result
has the same number of dimensions as x, with dimensions j1, j2, ..., jn
of length 1.  With 'squeeze:T', these dimensions are removed from the
result.  The order of j1, j2, ... is ignored.

It is an error if max(J) > ndims(x) or if there are duplicate elements
in J.

For example, if x is a matrix, sum(x, dimensions:2) computes the row
sums as a nrows(x) by 1 matrix and sum(x, dimensions:2,squeeze:T)
computes them as a one dimensional vector.

sum(x, margins:K [,squeeze:F] [,silent:T] [,undefval:U]) sums over the
dimensions not in K = vector(k1, k2, ..., km), where k1, ..., km are
distinct positive integers <= ndims(x).  This computes marginal totals
for the margins specified in K.

Without 'squeeze:F', only the dimensions in K are retained in the
result.  Otherwise the other dimensions are retained but have length 1.
This is opposite from the default with 'dimensions:J'.

It is an error if max(K) > ndims(x) or if there are duplicate elements
in K.

If x is a structure, sum(x [,dimensions:J or margins:K] [,squeeze:T or
F] [,silent:T] [,undefval:U]) computes a structure, each of whose
components is sum() applied to that component of x.  All the components
of x be of the same type, REAL or LOGICAL.

Examples:
If x is a n by m matrix

  Cmd> r <- x - sum(x)/sum(!ismissing(x))

computes the matrix of the residuals of x[i,j] from the column means.
When there are no MISSING values, divide by nrows(x)

If x is a n by 4 by 5 array,

  Cmd r <- x - sum(x)/sum(!ismissing(x))

computes an array with r[i,j,k] = the residual of x[i,j,k] from the
mean of all x[i,j,k] with the same values for j and k.  That is, it
treats x analogously to a 4 by 5 array of vectors of length n.  See
topic 'arithmetic'.  When there are no MISSING values, divide by
dim(x)[1].

If z is a vector of integers,

  Cmd> sum(z == run(min(z),max(z))')

computes a row vector giving the frequency distribution of the values in
z.

  Cmd> a # 2 by 2 by 3 array with labels
                 C1          C2          C3
  A1 B1           9           5           7
     B2           9          12          11
  A2 B1           4          11          10
     B2          11          15           9

  Cmd> sum(a,dimensions:2) # sum over dimension 2; 2 by 1 by 3 result
                  C1          C2          C3
  A1 (1)          18          17          18
  A2 (1)          15          26          19

  Cmd> sum(a,margins:vector(1,3),squeeze:F) # same as preceding
                  C1          C2          C3
  A1 (1)          18          17          18
  A2 (1)          15          26          19

  Cmd> sum(a,dimensions:2,squeeze:T) # sum over dim 2; 2 by 3 result
              C1          C2          C3
  A1          18          17          18
  A2          15          26          19

  Cmd> sum(a,margins:vector(1,3)) # same as preceding
              C1          C2          C3
  A1          18          17          18
  A2          15          26          19

See also prod(), tabs()


Gary Oehlert 2003-01-15