X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fexpressions.texi;h=65778d0424188c0db3fc39d3b9183491e6583643;hb=refs%2Fbuilds%2F20120402030503%2Fpspp;hp=b781ec1afc4b6337f9f7cb58a15f623b64ef4f60;hpb=ba603abd11a12e12b1a7c6adc48afaf9cdec7a6b;p=pspp diff --git a/doc/expressions.texi b/doc/expressions.texi index b781ec1afc..65778d0424 100644 --- a/doc/expressions.texi +++ b/doc/expressions.texi @@ -1,9 +1,9 @@ -@node Expressions, Data Input and Output, Language, Top +@node Expressions @chapter Mathematical Expressions @cindex expressions, mathematical @cindex mathematical expressions -Expressions share a common syntax each place they appear in PSPP +Expressions share a common syntax each place they appear in @pspp{} commands. Expressions are made up of @dfn{operands}, which can be numbers, strings, or variable names, separated by @dfn{operators}. There are five types of operators: grouping, arithmetic, logical, @@ -15,14 +15,14 @@ strings or numbers as operands. With few exceptions, operands may be full-fledged expressions in themselves. @menu -* Boolean Values:: Boolean values. -* Missing Values in Expressions:: Using missing values in expressions. -* Grouping Operators:: parentheses -* Arithmetic Operators:: add sub mul div pow -* Logical Operators:: AND NOT OR -* Relational Operators:: EQ GE GT LE LT NE -* Functions:: More-sophisticated operators. -* Order of Operations:: Operator precedence. +* Boolean Values:: Boolean values +* Missing Values in Expressions:: Using missing values in expressions +* Grouping Operators:: parentheses +* Arithmetic Operators:: add sub mul div pow +* Logical Operators:: AND NOT OR +* Relational Operators:: EQ GE GT LE LT NE +* Functions:: More-sophisticated operators +* Order of Operations:: Operator precedence @end menu @node Boolean Values @@ -30,7 +30,7 @@ full-fledged expressions in themselves. @cindex Boolean @cindex values, Boolean -Some PSPP operators and expressions work with Boolean values, which +Some @pspp{} operators and expressions work with Boolean values, which represent true/false conditions. Booleans have only three possible values: 0 (false), 1 (true), and system-missing (unknown). System-missing is neither true nor false and indicates that the true @@ -238,7 +238,7 @@ True if @var{a} is not equal to @var{b}. @cindex @code{(} @cindex @code{)} @cindex names, of functions -PSPP functions provide mathematical abilities above and beyond +@pspp{} functions provide mathematical abilities above and beyond those possible using simple operators. Functions have a common syntax: each is composed of a function name followed by a left parenthesis, one or more arguments, and a right parenthesis. @@ -259,8 +259,9 @@ The sections below describe each function in detail. * Statistical Functions:: CFVAR MAX MEAN MIN SD SUM VARIANCE * String Functions:: CONCAT INDEX LENGTH LOWER LPAD LTRIM NUMBER RINDEX RPAD RTRIM STRING SUBSTR UPCASE -* Time & Date:: CTIME.xxx DATE.xxx TIME.xxx XDATE.xxx -* Miscellaneous Functions:: LAG YRMODA +* Time and Date:: CTIME.xxx DATE.xxx TIME.xxx XDATE.xxx + DATEDIFF DATESUM +* Miscellaneous Functions:: LAG YRMODA VALUELABEL * Statistical Distribution Functions:: PDF CDF SIG IDF RV NPDF NCDF @end menu @@ -348,7 +349,7 @@ results. @deftypefnx {Function} {} ACOS (@var{number}) Takes the arccosine, in radians, of @var{number}. Results in system-missing if @var{number} is not between -1 and 1 inclusive. -This function is a PSPP extension. +This function is a @pspp{} extension. @end deftypefn @cindex arcsine @@ -690,33 +691,34 @@ has value @code{"cd"}; @code{SUBSTR("nonsense", 4, 10)} has the value Returns @var{string}, changing lowercase letters to uppercase letters. @end deftypefn -@node Time & Date +@node Time and Date @subsection Time & Date Functions @cindex functions, time & date @cindex times @cindex dates @cindex dates, valid -For compatibility, PSPP considers dates before 15 Oct 1582 invalid. +For compatibility, @pspp{} considers dates before 15 Oct 1582 invalid. Most time and date functions will not accept earlier dates. @menu -* Time & Date Concepts:: How times & dates are defined and represented +* Time and Date Concepts:: How times & dates are defined and represented * Time Construction:: TIME.@{DAYS HMS@} * Time Extraction:: CTIME.@{DAYS HOURS MINUTES SECONDS@} * Date Construction:: DATE.@{DMY MDY MOYR QYR WKYR YRDAY@} * Date Extraction:: XDATE.@{DATE HOUR JDAY MDAY MINUTE MONTH QUARTER SECOND TDAY TIME WEEK WKDAY YEAR@} +* Time and Date Arithmetic:: DATEDIFF DATESUM @end menu -@node Time & Date Concepts +@node Time and Date Concepts @subsubsection How times & dates are defined and represented @cindex time, concepts @cindex time, intervals -Times and dates are handled by PSPP as single numbers. A -@dfn{time} is an interval. PSPP measures times in seconds. +Times and dates are handled by @pspp{} as single numbers. A +@dfn{time} is an interval. @pspp{} measures times in seconds. Thus, the following intervals correspond with the numeric values given: @example @@ -729,9 +731,9 @@ Thus, the following intervals correspond with the numeric values given: @cindex dates, concepts @cindex time, instants of A @dfn{date}, on the other hand, is a particular instant in the past -or the future. PSPP represents a date as a number of seconds since +or the future. @pspp{} represents a date as a number of seconds since midnight preceding 14 Oct 1582. Because midnight preceding the dates -given below correspond with the numeric PSPP dates given: +given below correspond with the numeric @pspp{} dates given: @example 15 Oct 1582 86,400 @@ -741,27 +743,6 @@ given below correspond with the numeric PSPP dates given: 24 Aug 1995 13,028,601,600 @end example -@cindex time, mathematical properties of -@cindex mathematics, applied to times & dates -@cindex dates, mathematical properties of -@noindent -Ordinary arithmetic operations on dates and times often produce -sensible results. Adding a time to, or subtracting one from, a date -produces a new date that much earlier or later. The difference of two -dates yields the time between those dates. Adding two times produces -the combined time. Multiplying a time by a scalar produces a time -that many times longer. Since times and dates are just numbers, the -ordinary addition and subtraction operators are employed for these -purposes. - -Adding two dates does not produce a useful result. - -As the table shows, dates and times may have very large values. Thus, -it is not a good idea to take powers of these values; also, the -accuracy of some procedures may be affected. If necessary, convert -times or dates in seconds to some other unit, like days or years, -before performing analysis. - @node Time Construction @subsubsection Functions that Produce Times @cindex times, constructing @@ -792,7 +773,7 @@ vice versa. @cindex examination, of times @cindex time, lengths of -These functions take numeric arguments in PSPP time format and +These functions take numeric arguments in @pspp{} time format and give numeric results. @cindex days @@ -905,18 +886,18 @@ Results in a date value corresponding to the day @cindex date examination @cindex arguments, of date extraction functions -These functions take numeric arguments in PSPP date or time +These functions take numeric arguments in @pspp{} date or time format and give numeric results. These names are used for arguments: @table @var @item date -A numeric value in PSPP date format. +A numeric value in @pspp{} date format. @item time -A numeric value in PSPP time format. +A numeric value in @pspp{} time format. @item time-or-date -A numeric value in PSPP time or date format. +A numeric value in @pspp{} time or date format. @end table @cindex days @@ -1020,6 +1001,68 @@ Returns the year (as an integer 1582 or greater) corresponding to @var{date}. @end deftypefn +@node Time and Date Arithmetic +@subsubsection Time and Date Arithmetic + +@cindex time, mathematical properties of +@cindex mathematics, applied to times & dates +@cindex dates, mathematical properties of +@noindent +Ordinary arithmetic operations on dates and times often produce +sensible results. Adding a time to, or subtracting one from, a date +produces a new date that much earlier or later. The difference of two +dates yields the time between those dates. Adding two times produces +the combined time. Multiplying a time by a scalar produces a time +that many times longer. Since times and dates are just numbers, the +ordinary addition and subtraction operators are employed for these +purposes. + +Adding two dates does not produce a useful result. + +Dates and times may have very large values. Thus, +it is not a good idea to take powers of these values; also, the +accuracy of some procedures may be affected. If necessary, convert +times or dates in seconds to some other unit, like days or years, +before performing analysis. + +@pspp{} supplies a few functions for date arithmetic: + +@deftypefn {Function} {} DATEDIFF (@var{date2}, @var{date1}, @var{unit}) +Returns the span of time from @var{date1} to @var{date2} in terms of +@var{unit}, which must be a quoted string, one of @samp{years}, +@samp{quarters}, @samp{months}, @samp{weeks}, @samp{days}, +@samp{hours}, @samp{minutes}, and @samp{seconds}. The result is an +integer, truncated toward zero. + +One year is considered to span from a given date to the same month, +day, and time of day the next year. Thus, from Jan.@tie{}1 of one +year to Jan.@tie{}1 the next year is considered to be a full year, but +Feb.@tie{}29 of a leap year to the following Feb.@tie{}28 is not. +Similarly, one month spans from a given day of the month to the same +day of the following month. Thus, there is never a full month from +Jan.@tie{}31 of a given year to any day in the following February. +@end deftypefn + +@deftypefn {Function} {} DATESUM (@var{date}, @var{quantity}, @var{unit}[, @var{method}]) +Returns @var{date} advanced by the given @var{quantity} of the +specified @var{unit}, which must be one of the strings @samp{years}, +@samp{quarters}, @samp{months}, @samp{weeks}, @samp{days}, +@samp{hours}, @samp{minutes}, and @samp{seconds}. + +When @var{unit} is @samp{years}, @samp{quarters}, or @samp{months}, +only the integer part of @var{quantity} is considered. Adding one of +these units can cause the day of the month to exceed the number of +days in the month. In this case, the @var{method} comes into +play: if it is omitted or specified as @samp{closest} (as a quoted +string), then the resulting day is the last day of the month; +otherwise, if it is specified as @samp{rollover}, then the extra days +roll over into the following month. + +When @var{unit} is @samp{weeks}, @samp{days}, @samp{hours}, +@samp{minutes}, or @samp{seconds}, the @var{quantity} is not rounded +to an integer and @var{method}, if specified, is ignored. +@end deftypefn + @node Miscellaneous Functions @subsection Miscellaneous Functions @cindex functions, miscellaneous @@ -1034,7 +1077,8 @@ yields the value of that variable for the case @var{n} before the current one. Results in system-missing (for numeric variables) or blanks (for string variables) for the first @var{n} cases. -@code{LAG} obtains values from the cases that become the new active file +@code{LAG} obtains values from the cases that become the new active +dataset after a procedure executes. Thus, @code{LAG} will not return values from cases dropped by transformations such as @cmd{SELECT IF}, and transformations like @cmd{COMPUTE} that modify data will change the @@ -1054,7 +1098,7 @@ use of a large value will increase memory consumption. @cindex Julian date @deftypefn {Function} {} YRMODA (@var{year}, @var{month}, @var{day}) @var{year} is a year, either between 0 and 99 or at least 1582. -Unlike other PSPP date functions, years between 0 and 99 always +Unlike other @pspp{} date functions, years between 0 and 99 always correspond to 1900 through 1999. @var{month} is a month between 1 and 13. @var{day} is a day between 0 and 31. A @var{day} of 0 refers to the last day of the previous month, and a @var{month} of 13 refers to @@ -1066,10 +1110,18 @@ the date specified, plus one. The date passed to @code{YRMODA} must be on or after 15 Oct 1582. 15 Oct 1582 has a value of 1. @end deftypefn +@cindex value label +@deftypefn {Function} VALUELABEL (@var{variable}) +Returns a string matching the label associated with the current value +of @var{variable}. If the current value of @var{variable} has no +associated label, then this function returns the empty string. +@var{variable} may be a numeric or string variable. +@end deftypefn + @node Statistical Distribution Functions @subsection Statistical Distribution Functions -PSPP can calculate several functions of standard statistical +@pspp{} can calculate several functions of standard statistical distributions. These functions are named systematically based on the function and the distribution. The table below describes the statistical distribution functions in general: @@ -1184,7 +1236,7 @@ Exponential distribution with scale parameter @var{a}. The inverse of Exponential power distribution with positive scale parameter @var{a} and nonnegative power parameter @var{b}. Constraints: @var{a} > 0, @var{b} >= 0, @var{x} >= 0, 0 <= @var{p} <= 1. This distribution is a -PSPP extension. +@pspp{} extension. @end deftypefn @deftypefn {Function} {} PDF.F (@var{x}, @var{df1}, @var{df2}) @@ -1289,7 +1341,7 @@ Equivalent to RV.NORMAL(0, @var{sigma}). @deftypefn {Function} {} PDF.NTAIL (@var{x}, @var{a}, @var{sigma}) @deftypefnx {Function} {} RV.NTAIL (@var{a}, @var{sigma}) Normal tail distribution with lower limit @var{a} and standard -deviation @var{sigma}. This distribution is a PSPP extension. +deviation @var{sigma}. This distribution is a @pspp{} extension. Constraints: @var{a} > 0, @var{x} > @var{a}, 0 < @var{p} < 1. @end deftypefn @@ -1307,14 +1359,14 @@ parameter @var{b}. Constraints: @var{a} > 0, @var{b} > 0, @var{x} >= @deftypefnx {Function} {} IDF.RAYLEIGH (@var{p}, @var{sigma}) @deftypefnx {Function} {} RV.RAYLEIGH (@var{sigma}) Rayleigh distribution with scale parameter @var{sigma}. This -distribution is a PSPP extension. Constraints: @var{sigma} > 0, +distribution is a @pspp{} extension. Constraints: @var{sigma} > 0, @var{x} > 0. @end deftypefn @deftypefn {Function} {} PDF.RTAIL (@var{x}, @var{a}, @var{sigma}) @deftypefnx {Function} {} RV.RTAIL (@var{a}, @var{sigma}) Rayleigh tail distribution with lower limit @var{a} and scale -parameter @var{sigma}. This distribution is a PSPP extension. +parameter @var{sigma}. This distribution is a @pspp{} extension. Constraints: @var{a} > 0, @var{sigma} > 0, @var{x} > @var{a}. @end deftypefn @@ -1347,14 +1399,14 @@ distribution takes an additional parameter @var{lambda}. Constraints: @deftypefnx {Function} {} CDF.T1G (@var{x}, @var{a}, @var{b}) @deftypefnx {Function} {} IDF.T1G (@var{p}, @var{a}, @var{b}) Type-1 Gumbel distribution with parameters @var{a} and @var{b}. This -distribution is a PSPP extension. Constraints: 0 < @var{p} < 1. +distribution is a @pspp{} extension. Constraints: 0 < @var{p} < 1. @end deftypefn @deftypefn {Function} {} PDF.T2G (@var{x}, @var{a}, @var{b}) @deftypefnx {Function} {} CDF.T2G (@var{x}, @var{a}, @var{b}) @deftypefnx {Function} {} IDF.T2G (@var{p}, @var{a}, @var{b}) Type-2 Gumbel distribution with parameters @var{a} and @var{b}. This -distribution is a PSPP extension. Constraints: @var{x} > 0, 0 < +distribution is a @pspp{} extension. Constraints: @var{x} > 0, 0 < @var{p} < 1. @end deftypefn @@ -1424,7 +1476,7 @@ Constraints: 0 <= @var{p} < 1, @var{x} >= 1. @deftypefn {Function} {} PDF.NEGBIN (@var{x}, @var{n}, @var{p}) @deftypefnx {Function} {} CDF.NEGBIN (@var{x}, @var{n}, @var{p}) @deftypefnx {Function} {} RV.NEGBIN (@var{n}, @var{p}) -Negative binomial distribution with number of successes paramter +Negative binomial distribution with number of successes parameter @var{n} and probability of success parameter @var{p}. Constraints: integer @var{n} >= 0, 0 < @var{p} <= 1, integer @var{x} >= 1. @end deftypefn @@ -1465,4 +1517,3 @@ subtraction. @item @code{AND NOT OR} @end enumerate -@setfilename ignored