X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fexpressions.texi;h=c530f7a7a839dddd3fe54434bb3e23d43bbff977;hb=19616643b06c6f27463ecbd725ae25be0bf1cfd1;hp=65778d0424188c0db3fc39d3b9183491e6583643;hpb=620d94c8a41811d8dc8ba8a0f500896a9a894a18;p=pspp diff --git a/doc/expressions.texi b/doc/expressions.texi index 65778d0424..c530f7a7a8 100644 --- a/doc/expressions.texi +++ b/doc/expressions.texi @@ -1,3 +1,18 @@ +@c PSPP - a program for statistical analysis. +@c Copyright (C) 2017 Free Software Foundation, Inc. +@c Permission is granted to copy, distribute and/or modify this document +@c under the terms of the GNU Free Documentation License, Version 1.3 +@c or any later version published by the Free Software Foundation; +@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +@c A copy of the license is included in the section entitled "GNU +@c Free Documentation License". +@c +@c Use @func when referring to a function. +@c Use @deftypefn for their definitions +@macro func{NAME} +@code{\NAME\} +@end macro + @node Expressions @chapter Mathematical Expressions @cindex expressions, mathematical @@ -244,9 +259,9 @@ syntax: each is composed of a function name followed by a left parenthesis, one or more arguments, and a right parenthesis. Function names are not reserved. Their names are specially treated -only when followed by a left parenthesis, so that @code{EXP(10)} -refers to the constant value @code{e} raised to the 10th power, but -@code{EXP} by itself refers to the value of variable EXP. +only when followed by a left parenthesis, so that @samp{EXP(10)} +refers to the constant value @math{e} raised to the 10th power, but +@samp{EXP} by itself refers to the value of a variable called @code{EXP}. The sections below describe each function in detail. @@ -256,9 +271,10 @@ The sections below describe each function in detail. * Trigonometry:: ACOS ARCOS ARSIN ARTAN ASIN ATAN COS SIN TAN * Missing Value Functions:: MISSING NMISS NVALID SYSMIS VALUE * Set Membership:: ANY RANGE -* Statistical Functions:: CFVAR MAX MEAN MIN SD SUM VARIANCE +* Statistical Functions:: CFVAR MAX MEAN MEDIAN MIN SD SUM VARIANCE * String Functions:: CONCAT INDEX LENGTH LOWER LPAD LTRIM NUMBER - RINDEX RPAD RTRIM STRING SUBSTR UPCASE + REPLACE RINDEX RPAD RTRIM STRING STRUNC SUBSTR + UPCASE * Time and Date:: CTIME.xxx DATE.xxx TIME.xxx XDATE.xxx DATEDIFF DATESUM * Miscellaneous Functions:: LAG YRMODA VALUELABEL @@ -273,7 +289,7 @@ Advanced mathematical functions take numeric arguments and produce numeric results. @deftypefn {Function} {} EXP (@var{exponent}) -Returns @i{e} (approximately 2.71828) raised to power @var{exponent}. +Returns @math{e} (approximately 2.71828) raised to power @var{exponent}. @end deftypefn @cindex logarithms @@ -283,12 +299,12 @@ not positive, the result is system-missing. @end deftypefn @deftypefn {Function} {} LN (@var{number}) -Takes the base-@i{e} logarithm of @var{number}. If @var{number} is +Takes the base-@math{e} logarithm of @var{number}. If @var{number} is not positive, the result is system-missing. @end deftypefn @deftypefn {Function} {} LNGAMMA (@var{number}) -Yields the base-@i{e} logarithm of the complete gamma of @var{number}. +Yields the base-@math{e} logarithm of the complete gamma of @var{number}. If @var{number} is a negative integer, the result is system-missing. @end deftypefn @@ -325,15 +341,24 @@ Returns the remainder when @var{number} is divided by 10. If @end deftypefn @cindex rounding -@deftypefn {Function} {} RND (@var{number}) -Takes the absolute value of @var{number} and rounds it to an integer. -Then, if @var{number} was negative originally, negates the result. +@deftypefn {Function} {} RND (@var{number} [, @var{mult}[, @var{fuzzbits}]]) +Rounds @var{number} and rounds it to a multiple of @var{mult} (by +default 1). Halves are rounded away from zero, as are values that +fall short of halves by less than @var{fuzzbits} of errors in the +least-significant bits of @var{number}. If @var{fuzzbits} is not +specified then the default is taken from SET FUZZBITS (@pxref{SET +FUZZBITS}), which is 6 unless overridden. @end deftypefn @cindex truncation -@deftypefn {Function} {} TRUNC (@var{number}) -Discards the fractional part of @var{number}; that is, rounds -@var{number} towards zero. +@deftypefn {Function} {} TRUNC (@var{number} [, @var{mult}[, @var{fuzzbits}]]) +Rounds @var{number} to a multiple of @var{mult}, toward zero. For the +default @var{mult} of 1, this is equivalent to discarding the +fractional part of @var{number}. Values that fall short of a multiple +of @var{mult} by less than @var{fuzzbits} of errors in the +least-significant bits of @var{number} are rounded away from zero. If +@var{fuzzbits} is not specified then the default is taken from SET +FUZZBITS (@pxref{SET FUZZBITS}), which is 6 unless overridden. @end deftypefn @node Trigonometry @@ -381,7 +406,7 @@ Takes the sine of @var{angle} which should be in radians. @deftypefn {Function} {} TAN (@var{angle}) Takes the tangent of @var{angle} which should be in radians. Results in system-missing at values -of @var{angle} that are too close to odd multiples of pi/2. +of @var{angle} that are too close to odd multiples of @math{\pi/2}. Portability: none. @end deftypefn @@ -398,7 +423,11 @@ functions. In particular, user-missing values for numeric variables are converted to system-missing values. @deftypefn {Function} {} MISSING (@var{expr}) -Returns 1 if @var{expr} has the system-missing value, 0 otherwise. +When @var{expr} is simply the name of a numeric variable, returns 1 if +the variable has the system-missing value or if it is user-missing. +For any other value 0 is returned. +If @var{expr} takes another form, the function returns 1 if the value is +system-missing, 0 otherwise. @end deftypefn @deftypefn {Function} {} NMISS (@var{expr} [, @var{expr}]@dots{}) @@ -414,10 +443,7 @@ variable ranges using the @code{@var{var1} TO @var{var2}} syntax. @end deftypefn @deftypefn {Function} {} SYSMIS (@var{expr}) -When @var{expr} is simply the name of a numeric variable, returns 1 if -the variable has the system-missing value, 0 if it is user-missing or -not missing. If given @var{expr} takes another form, results in 1 if -the value is system-missing, 0 otherwise. +Returns 1 if @var{expr} has the system-missing value, 0 otherwise. @end deftypefn @deftypefn {Function} {} VALUE (@var{variable}) @@ -443,7 +469,7 @@ String comparisons are performed according to the rules given in Results in true if @var{value} is equal to any of the @var{set} values. Otherwise, results in false. If @var{value} is system-missing, returns system-missing. System-missing values in -@var{set} do not cause ANY to return system-missing. +@var{set} do not cause @func{ANY} to return system-missing. @end deftypefn @deftypefn {Function} {} RANGE (@var{value}, @var{low}, @var{high} [, @var{low}, @var{high}]@dots{}) @@ -452,7 +478,7 @@ Results in true if @var{value} is in any of the intervals bounded by Each @var{low} must be less than or equal to its corresponding @var{high} value. @var{low} and @var{high} must be given in pairs. If @var{value} is system-missing, returns system-missing. -System-missing values in @var{set} do not cause RANGE to return +System-missing values in @var{set} do not cause @func{RANGE} to return system-missing. @end deftypefn @@ -475,10 +501,10 @@ using the @code{@var{var1} TO @var{var2}} syntax. Unlike most functions, statistical functions can return non-missing values even when some of their arguments are missing. Most statistical functions, by default, require only 1 non-missing value to -have a non-missing return, but CFVAR, SD, and VARIANCE require 2. +have a non-missing return, but @func{CFVAR}, @func{SD}, and @func {VARIANCE} require 2. These defaults can be increased (but not decreased) by appending a dot and the minimum number of valid arguments to the function name. For -example, @code{MEAN.3(X, Y, Z)} would only return non-missing if all +example, @subcmd{MEAN.3(X, Y, Z)} would only return non-missing if all of @samp{X}, @samp{Y}, and @samp{Z} were valid. @cindex coefficient of variation @@ -500,6 +526,13 @@ be numeric or string. Results in the mean of the values of @var{number}. @end deftypefn +@cindex median +@deftypefn {Function} {} MEDIAN (@var{number}, @var{number}[, @dots{}]) +Results in the median of the values of @var{number}. Given an even +number of nonmissing arguments, yields the mean of the two middle +values. +@end deftypefn + @cindex minimum @deftypefn {Function} {} MIN (@var{number}, @var{number}[, @dots{}]) Results in the value of the least @var{value}. The @var{value}s may @@ -610,8 +643,17 @@ right-padded with spaces. If @var{string} is not in the correct format for @var{format}, system-missing is returned. @end deftypefn +@cindex strings, replacing substrings +@cindex replacing substrings +@deftypefn {Function} {} REPLACE (@var{haystack}, @var{needle}, @var{replacement}[, @var{n}]) +Returns string @var{haystack} with instances of @var{needle} replaced +by @var{replacement}. If nonnegative integer @var{n} is specified, it +limits the maximum number of replacements; otherwise, all instances of +@var{needle} are replaced. +@end deftypefn + @cindex strings, searching backwards -@deftypefn {Function} {} RINDEX (@var{string}, @var{format}) +@deftypefn {Function} {} RINDEX (@var{haystack}, @var{needle}) Returns a positive integer indicating the position of the last occurrence of @var{needle} in @var{haystack}. Returns 0 if @var{haystack} does not contain @var{needle}. Returns system-missing if @@ -624,7 +666,7 @@ Searches @var{haystack} for the last occurrence of each part, and returns the largest value. Returns 0 if @var{haystack} does not contain any part in @var{needle}. It is an error if @var{needle_len} does not evenly divide the length of @var{needle}. Returns system-missing -if @var{needle} is an empty string. +if @var{needle} is an empty string or if needle_len is less than 1. @end deftypefn @cindex padding strings @@ -665,6 +707,15 @@ format specifier @var{format}. For example, @code{STRING(123.56, F5.1)} has the value @code{"123.6"}. @end deftypefn +@cindex strings, trimming +@cindex strings, truncating +@cindex white space, trimming +@deftypefn {Function} {} STRUNC (@var{string}, @var{n}) +Returns @var{string}, first trimming it to at most @var{n} bytes, then +removing trailing spaces. Returns an empty string if @var{n} is +missing or negative. +@end deftypefn + @cindex substrings @cindex strings, taking substrings of @deftypefn {Function} {} SUBSTR (@var{string}, @var{start}) @@ -1144,7 +1195,7 @@ a probability. Tail probability function for @var{dist}, that is, the probability that a random variate drawn from the distribution is greater than @var{x}. The domain of @var{x} depends @var{dist}. The result is a -probability. Only a few distributions include an SIG function. +probability. Only a few distributions include an @func{SIG} function. @item IDF.@var{dist} (@var{p}[, @var{param}@dots{}]) Inverse distribution function for @var{dist}, the value of @var{x} for @@ -1160,7 +1211,7 @@ distribution. Noncentral probability density function. The result is the density of the given noncentral distribution at @var{x}. The domain of @var{x} depends on @var{dist}. The range is nonnegative real numbers. Only a -few distributions include an NPDF function. +few distributions include an @func{NPDF} function. @item NCDF.@var{dist} (@var{x}[, @var{param}@dots{}]) Noncentral cumulative distribution function for @var{dist}, that is, @@ -1209,12 +1260,12 @@ Cauchy distribution with location parameter @var{a} and scale parameter @var{b}. Constraints: @var{b} > 0, 0 < @var{p} < 1. @end deftypefn -@deftypefn {Function} {} PDF.CHISQ (@var{x}, @var{df}) -@deftypefnx {Function} {} CDF.CHISQ (@var{x}, @var{df}) +@c @deftypefn {Function} {} PDF.CHISQ (@var{x}, @var{df}) +@deftypefn {Function} {} CDF.CHISQ (@var{x}, @var{df}) @deftypefnx {Function} {} SIG.CHISQ (@var{x}, @var{df}) @deftypefnx {Function} {} IDF.CHISQ (@var{p}, @var{df}) @deftypefnx {Function} {} RV.CHISQ (@var{df}) -@deftypefnx {Function} {} NPDF.CHISQ (@var{x}, @var{df}, @var{lambda}) +@c @deftypefnx {Function} {} NPDF.CHISQ (@var{x}, @var{df}, @var{lambda}) @deftypefnx {Function} {} NCDF.CHISQ (@var{x}, @var{df}, @var{lambda}) Chi-squared distribution with @var{df} degrees of freedom. The noncentral distribution takes an additional parameter @var{lambda}. @@ -1244,8 +1295,8 @@ and nonnegative power parameter @var{b}. Constraints: @var{a} > 0, @deftypefnx {Function} {} SIG.F (@var{x}, @var{df1}, @var{df2}) @deftypefnx {Function} {} IDF.F (@var{p}, @var{df1}, @var{df2}) @deftypefnx {Function} {} RV.F (@var{df1}, @var{df2}) -@deftypefnx {Function} {} NPDF.F (@var{x}, @var{df1}, @var{df2}, @var{lambda}) -@deftypefnx {Function} {} NCDF.F (@var{x}, @var{df1}, @var{df2}, @var{lambda}) +@c @deftypefnx {Function} {} NPDF.F (@var{x}, @var{df1}, @var{df2}, @var{lambda}) +@c @deftypefnx {Function} {} NCDF.F (@var{x}, @var{df1}, @var{df2}, @var{lambda}) F-distribution of two chi-squared deviates with @var{df1} and @var{df2} degrees of freedom. The noncentral distribution takes an additional parameter @var{lambda}. Constraints: @var{df1} > 0, @@ -1261,21 +1312,21 @@ Gamma distribution with shape parameter @var{a} and scale parameter @var{p} < 1. @end deftypefn -@deftypefn {Function} {} PDF.HALFNRM (@var{x}, @var{a}, @var{b}) -@deftypefnx {Function} {} CDF.HALFNRM (@var{x}, @var{a}, @var{b}) -@deftypefnx {Function} {} IDF.HALFNRM (@var{p}, @var{a}, @var{b}) -@deftypefnx {Function} {} RV.HALFNRM (@var{a}, @var{b}) -Half-normal distribution with location parameter @var{a} and shape -parameter @var{b}. Constraints: @var{b} > 0, 0 < @var{p} < 1. -@end deftypefn +@c @deftypefn {Function} {} PDF.HALFNRM (@var{x}, @var{a}, @var{b}) +@c @deftypefnx {Function} {} CDF.HALFNRM (@var{x}, @var{a}, @var{b}) +@c @deftypefnx {Function} {} IDF.HALFNRM (@var{p}, @var{a}, @var{b}) +@c @deftypefnx {Function} {} RV.HALFNRM (@var{a}, @var{b}) +@c Half-normal distribution with location parameter @var{a} and shape +@c parameter @var{b}. Constraints: @var{b} > 0, 0 < @var{p} < 1. +@c @end deftypefn -@deftypefn {Function} {} PDF.IGAUSS (@var{x}, @var{a}, @var{b}) -@deftypefnx {Function} {} CDF.IGAUSS (@var{x}, @var{a}, @var{b}) -@deftypefnx {Function} {} IDF.IGAUSS (@var{p}, @var{a}, @var{b}) -@deftypefnx {Function} {} RV.IGAUSS (@var{a}, @var{b}) -Inverse Gaussian distribution with parameters @var{a} and @var{b}. -Constraints: @var{a} > 0, @var{b} > 0, @var{x} > 0, 0 <= @var{p} < 1. -@end deftypefn +@c @deftypefn {Function} {} PDF.IGAUSS (@var{x}, @var{a}, @var{b}) +@c @deftypefnx {Function} {} CDF.IGAUSS (@var{x}, @var{a}, @var{b}) +@c @deftypefnx {Function} {} IDF.IGAUSS (@var{p}, @var{a}, @var{b}) +@c @deftypefnx {Function} {} RV.IGAUSS (@var{a}, @var{b}) +@c Inverse Gaussian distribution with parameters @var{a} and @var{b}. +@c Constraints: @var{a} > 0, @var{b} > 0, @var{x} > 0, 0 <= @var{p} < 1. +@c @end deftypefn @deftypefn {Function} {} PDF.LANDAU (@var{x}) @deftypefnx {Function} {} RV.LANDAU () @@ -1370,26 +1421,26 @@ parameter @var{sigma}. This distribution is a @pspp{} extension. Constraints: @var{a} > 0, @var{sigma} > 0, @var{x} > @var{a}. @end deftypefn -@deftypefn {Function} {} CDF.SMOD (@var{x}, @var{a}, @var{b}) -@deftypefnx {Function} {} IDF.SMOD (@var{p}, @var{a}, @var{b}) -Studentized maximum modulus distribution with parameters @var{a} and -@var{b}. Constraints: @var{a} > 0, @var{b} > 0, @var{x} > 0, 0 <= -@var{p} < 1. -@end deftypefn +@c @deftypefn {Function} {} CDF.SMOD (@var{x}, @var{a}, @var{b}) +@c @deftypefnx {Function} {} IDF.SMOD (@var{p}, @var{a}, @var{b}) +@c Studentized maximum modulus distribution with parameters @var{a} and +@c @var{b}. Constraints: @var{a} > 0, @var{b} > 0, @var{x} > 0, 0 <= +@c @var{p} < 1. +@c @end deftypefn -@deftypefn {Function} {} CDF.SRANGE (@var{x}, @var{a}, @var{b}) -@deftypefnx {Function} {} IDF.SRANGE (@var{p}, @var{a}, @var{b}) -Studentized range distribution with parameters @var{a} and @var{b}. -Constraints: @var{a} >= 1, @var{b} >= 1, @var{x} > 0, 0 <= @var{p} < -1. -@end deftypefn +@c @deftypefn {Function} {} CDF.SRANGE (@var{x}, @var{a}, @var{b}) +@c @deftypefnx {Function} {} IDF.SRANGE (@var{p}, @var{a}, @var{b}) +@c Studentized range distribution with parameters @var{a} and @var{b}. +@c Constraints: @var{a} >= 1, @var{b} >= 1, @var{x} > 0, 0 <= @var{p} < +@c 1. +@c @end deftypefn @deftypefn {Function} {} PDF.T (@var{x}, @var{df}) @deftypefnx {Function} {} CDF.T (@var{x}, @var{df}) @deftypefnx {Function} {} IDF.T (@var{p}, @var{df}) @deftypefnx {Function} {} RV.T (@var{df}) -@deftypefnx {Function} {} NPDF.T (@var{x}, @var{df}, @var{lambda}) -@deftypefnx {Function} {} NCDF.T (@var{x}, @var{df}, @var{lambda}) +@c @deftypefnx {Function} {} NPDF.T (@var{x}, @var{df}, @var{lambda}) +@c @deftypefnx {Function} {} NCDF.T (@var{x}, @var{df}, @var{lambda}) T-distribution with @var{df} degrees of freedom. The noncentral distribution takes an additional parameter @var{lambda}. Constraints: @var{df} > 0, 0 < @var{p} < 1. @@ -1443,9 +1494,9 @@ Bernoulli distribution with probability of success @var{p}. Constraints: @var{x} = 0 or 1, 0 <= @var{p} <= 1. @end deftypefn -@deftypefn {Function} {} PDF.BINOMIAL (@var{x}, @var{n}, @var{p}) -@deftypefnx {Function} {} CDF.BINOMIAL (@var{x}, @var{n}, @var{p}) -@deftypefnx {Function} {} RV.BINOMIAL (@var{n}, @var{p}) +@deftypefn {Function} {} PDF.BINOM (@var{x}, @var{n}, @var{p}) +@deftypefnx {Function} {} CDF.BINOM (@var{x}, @var{n}, @var{p}) +@deftypefnx {Function} {} RV.BINOM (@var{n}, @var{p}) Binomial distribution with @var{n} trials and probability of success @var{p}. Constraints: integer @var{n} > 0, 0 <= @var{p} <= 1, integer @var{x} <= @var{n}.