MINI MINI MANI MO

%
% Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved.
%
\name{ore.summary}
\alias{ore.summary}
\title{Oracle R Enterprsie Data Summary}
\description{
  Generates descriptive statistics for
  \code{\link[OREbase:ore.frame-class]{ore.frame}} objects within
  flexible row aggregations.
}
\usage{
  ore.summary(data, var, stats = c("n", "mean", "min", "max"),
              class = NULL, types = NULL, ways = NULL, weight = NULL,
              order = NULL, maxid = NULL, minid = NULL, mu = 0,
              no.type = FALSE, no.freq = FALSE) 
}
\arguments{
  \item{data}{An \code{\link[OREbase:ore.frame-class]{ore.frame}} object
    of data.}
  
  \item{var}{A vector of character strings specifying the names of
    numeric columns in argument \code{data} to which to apply all of the
    statistical calculations in argument \code{stats}, or a list of
    character string vectors. If the \code{var} argument is a list, then
    the length of the list must be either 1 or the same as the length of
    \code{stats}. If it's a list of length 1, it's equivalent to a vector of
    strings. If it's a list of length greater than 1, each element of the
    \code{var} list specifies the columns of \code{data} to which to apply
    the statistical calculation in the corresponding position in \code{stats}.}

  \item{stats}{A vector of character strings specifying the
    statistical calculations for argument \code{var}. If the name of the
    vector element is specified, the name becomes the output column name. 

    The values of this argument can be one or more of the following:

   \code{"n"} or \code{"freq"} (Count of non-missing values),
   
   \code{"count"} or \code{"cnt"} (Count of all observations),

   \code{"nmiss"} (Count of missing values),

   \code{"mean"} or \code{"avg"} (Average of values),

   \code{"min"} (Minimum of values)

   \code{"max"} (Maximum of values),

   \code{"css"} (Corrected sum of squares),

   \code{"uss"} (Uncorrected sum of squares),

   \code{"cv"} (Coefficient of variation),

   \code{"sum"} (Sum of values),

   \code{"sumwgt"} (Weighted sum of values),
   
   \code{"range"} (Range of values),

   \code{"stddev"} or \code{"std"} (Standard deviation of values),

   \code{"stderr"} or \code{"stdmean"} (Standard error for the mean),

   \code{"variance"} or \code{"var"} (Variance of values),

   \code{"kurtosis"} or \code{"kurt"} (Kurtosis),

   \code{"skewness"} or \code{"skew"} (Skewness),

   \code{"loccount<"} or \code{"loc<"} (Number of observations whose
   values are less than the supplied \code{mu}),

   \code{"loccount>"} or \code{"loc>"} (Number of observations whose
   values are greater than the supplied \code{mu}),

   \code{"loccount!"} or \code{"loc!"} (Number of observations whose
   values are not equal to the supplied \code{mu}),

   \code{"loccount"} or \code{"loc"} (Number of observations whose
   values are equal to the supplied \code{mu}),

   Percentiles Types: \code{"p0"}, \code{"p1"}, \code{"p5"},
   \code{"p10"}, \code{"p25"} or \code{"q1"}, 
   \code{"p50"} or \code{"q2"} or \code{"median"},
   \code{"p75"} or \code{"q3"},
   \code{"p90"}, \code{"p95"}, \code{"p99"}, \code{"p100"} (Percentile
   or quantile),
              
   \code{"qrange"} or \code{"iqr"} (Interquartile range, Q3-Q1),

   \code{"mode"} (Most frequently occurring value),

   \code{"lclm"} (Two-sided left confidence limit with confidence level
   of the interval equal to 0.95),
   
   \code{"rclm"} (Two-sided right confidence limit with confidence level
   of the interval equal to 0.95),
   
   \code{"clm"} (Two-sided confidence interval with confidence level of
   the interval equal to 0.95),

   \code{"t"} (Student's t-test statistic),
      
   \code{"probt"} or \code{"prt"} (Two-tailed p-value for student's t-test)
 }
 
  \item{class}{A vector of character strings specifying the names of
    categorical columns within argument \code{data}. If not specified,
    the aggregation of the entire data is returned.}

  \item{types}{A list of character string vectors specifying the
    combinations of the column names in \code{class} within which the
    aggregations will be executed in the returning summary.}

  \item{ways}{A vector of integers with each value indicating the number
    of columns in \code{class} that are used to generate types. With
    one integer number, it generates types of all possible combinations
    with the specified number of columns in \code{class}. The types
    generated by \code{ways} will be combined with the types specified
    in \code{types} with redundency removed automatically.}
  
  \item{weight}{An optional single character string specifying a numeric
    column within \code{data} to use as analytic weights. By default, the
    weight for each non-missing observation is 1. The statistics in
    \code{stats} that can take \code{weight} are \code{"sum"},
    \code{"sumwgt"}, \code{"mean"}, \code{"css"}, \code{"uss"}, \code{"cv"},
    \code{"stddev"}, \code{"variance"}, and \code{"stderr"}. The
    \code{weight} argument is ignored when specified with other statistics.}

  \item{order}{A vector of character strings specifying the sorting
    criteria. The values of this argument can be one or more of the following:

    \code{"freq"} or \code{"-freq"} (Ascending or descending sorts based on
    count statistics), 

    \code{"type"} or \code{"-type"} (Ascending or descending sorts based
    on type),

    \code{"class"} or \code{"-class"} (Ascending or descending sorts based on
    the columns in \code{class}).}

  \item{maxid}{A named vector of character strings, each element of
    which specifies two columns in \code{data}. The name of an element
    specifies an \code{over-column} and the value of the element
    specifies an \code{id-column}. Each element results in an additional
    column in the returned \code{\link[OREbase:ore.frame-class]{ore.frame}}
    object. Each additional column contains the value from the \code{id-column}
    that corresponds to the observation that has the maximum value in the
    \code{over-column}.}

  \item{minid}{A named vector of character strings, each element of
    which specifies two columns in \code{data}. The name of an element
    specifies an \code{over-column} and the value of the element
    specifies an \code{id-column}. Each element results in an additional
    column in the returned \code{\link[OREbase:ore.frame-class]{ore.frame}}
    object. Each additional column contains the value from the \code{id-column}
    that corresponds to the observation that has the minimum value in the
    \code{over-column}.}  

  \item{mu}{A single number or a vector of numbers whose elements
    correspond to each value in \code{var}, to supply additional
    numeric parameters for some statistics. The default value is 0. The
    statistics that use \code{mu} are \code{"loccount<"},
    \code{"loccount>"}, \code{"loccount"}, \code{"loccount!"},
    \code{"t"}, and \code{"probt"}. The \code{mu} argument is ignored
    when specified with other statistics.}
  
  \item{no.type}{A logical value indicating whether to drop the
    \code{TYPE} column from the output.}

  \item{no.freq}{A logical value indicating whether to drop the
    \code{FREQ} column from the output.}
}
\details{
  The function \code{ore.summary} generates descriptive statistics for
\code{\link[OREbase:ore.frame-class]{ore.frame}} objects within user
specified aggregation sub-groups.

  The argument \code{class} specifies the columns to be used to define
  aggregation sub-groups. The arguments \code{types} and \code{ways}
  define the sub-groups. If \code{class} is NULL, the function
  aggregates the entire data without sub-groups. If \code{class} is
  specified, but both \code{types} and \code{ways} are NULL, the
  function returns aggregations of all possible sub-groups by the
  columns in \code{class}. The number of sub-groups increases 
  exponentially over the number of \code{class} columns. Oracle recommands 
  using \code{types} and \code{ways} to specify the sub-groups of interest.
}
\value{
  Returns an \code{\link[OREbase:ore.frame-class]{ore.frame}} object.
}
\references{
  \href{http://www.oracle.com/technetwork/database/database-technologies/r/r-enterprise/documentation/index.html}{Oracle R Enterprise}
}
\author{
  Oracle \email{oracle-r-enterprise@oracle.com}
}
\examples{
  IRIS <- ore.push(iris)

  ore.summary(IRIS, c("Sepal.Length", "Petal.Length"))

  ore.summary(IRIS, c("Sepal.Length", "Petal.Length"), c("mean", "std", "p10"),
    class="Species")

  ore.summary(IRIS, list(c("Sepal.Length", "Petal.Length"),
    "Sepal.Width"), c(AVG="mean", "std"), class="Species")

  ore.summary(IRIS, c("Sepal.Length", "Petal.Length"), c("mean", "std"),
    class="Species", weight="Sepal.Width")

  ore.summary(IRIS, c("Sepal.Length", "Petal.Length"), c("mean", "std"),
    class=c("Species", "Petal.Width"),
    types=list("Species", c("Species", "Petal.Width")),
    order=c("type", "-freq", "class"))

  ore.summary(IRIS, c("Sepal.Length", "Petal.Length"), c("mean", "std"),
    class=c("Species", "Petal.Width"),
    ways=1, order=c("type", "-freq", "class"))

  ore.summary(IRIS, c("Sepal.Length", "Petal.Length"), c("mean", "prt"),
    class="Species", mu=c(5.8, 3.7))

  ore.summary(IRIS, c("Sepal.Length", "Petal.Length"), "mean",
    class="Species",
    maxid=c(Sepal.Length="Sepal.Width", Petal.Length="Petal.Width"))
}
\keyword{category}
\keyword{summary}