GAMMA.DIST

What it does

GAMMA.DIST(x, alpha, beta, cumulative)

GAMMA.DIST(x,alpha,beta,cumulative) evaluates a gamma distribution with positive shape alpha and positive scale beta at nonnegative x. TRUE returns a cumulative probability; FALSE returns a density. Scale beta has the same units as x.

Shape one has the exponential distribution with rate 1/beta. A shape n/2 for positive integer n, with scale two, has the chi-square distribution with n degrees of freedom. These are mathematical relations; particular worksheet compositions still have their own stores.

Try it

=GAMMA.DIST(2,1,2,TRUE) is about 0.6321205588. The scale ratio is one, giving the exponential CDF 1-exp(-1).

=GAMMA.DIST(2,1,2,FALSE) is about 0.1839397206. That is a density, mathematically exp(-1)/2; it is not the probability of observing exactly the real-valued point two.

Quirks

Microsoft documents #VALUE! for nonnumeric x or shape/scale, and #NUM! for negative x or a nonpositive shape or scale. Beta is a scale, so replacing it by an exponential rate without taking a reciprocal changes the distribution.

At x=0 the mathematical density’s right-hand limit is zero for alpha>1, 1/beta for alpha=1 and unbounded for smaller positive alpha. The current fallback produces zero in the first case but #NUM! for the other two. Those are code facts; a mathematical limit alone is not evidence of Excel’s actual boundary return.

The cumulative half-shape branch currently uses an ordinary binary64 square root after dividing by beta. Its retained public-composition controls do not settle every root precision boundary. Large finite parameters can also overflow an intermediate ratio; finite inputs do not by themselves prove a successful candidate result.

How to implement

Use D for ordinary binary64 storage and R for the stored 64-bit-significand operation.

For the current cumulative route, validate x and the two positive parameters, then store y=D(x/beta):

1. At alpha=0.5, compute the ordinary binary64 square root of y and pass it to ERF.PRECISE. Keep divide before square root. Do not silently replace this code’s root by a separately staged public SQRT call at unmeasured boundaries.
2. At alpha=1, call EXPON.DIST with (y,1,TRUE), retaining its corrected exponential-difference stages. Calling it with (x,1/beta,TRUE) changes a ratio into a stored reciprocal/product.
3. For other shapes, evaluate the generic regularized lower gamma ratio P(alpha,y). Integer alpha does not select a finite-sum shortcut in the current code.

The source retains 68 half-shape composition controls on scales one, two and four, and shape-one controls including non-dyadic scales three and five. Those observations constrain the named compositions, rather than every inner approximation or scale.

For the current density candidate at positive x and alpha other than one:

y = R(x/beta)
t = R(alpha*LN(y))
G = stored GAMMALN(alpha+1)
prefix = current exponential-of-difference candidate(t,y,G)
ratio = R(alpha/x)
density = R(prefix*ratio)

The prefix corresponds mathematically to exp(t-y-G). Its producer and return stage are not fully identified; the current source retains a particular extended difference/exponential candidate. The independently stored alpha/x ratio and final multiplication are a separately measured consumer. Shapes one and x=0 retain a log-density fallback, rather than this branch.

For the cumulative example, y is exactly one; the CDF is about 1-exp(-1). Its density is a separate calculation. Do not transfer a supported CDF composition into the density merely because both come from the same distribution.

The notes retain earlier integer-shape prefactor findings and their scope. General gamma ratios, GAMMALN, the density prefix, endpoint publication and remaining report mismatches remain open. No published Handbook suite establishes whole-function agreement.

Rust code

54 gamma_dist "GAMMA.DIST" (4, 4) [V "x", V "alpha", V "beta", V "cumulative"] |s, a, sv| {
    let [x, alpha, beta] = nums::<3>(s, a)?;
    out(s, bg::gamma_dist_kernel(x, alpha, beta, flag(s, a, 3)?))
}

No implementation has been published with a Handbook test suite for this function.

Version differences

The recorded environments below distinguish a reading from a same-input comparison. Counts describe captured inputs in each environment; overlapping captures and comparisons are not totals of unique worksheet calls.

The record contains no same-input comparison between these environments. Reading different inputs on different builds does not establish either a version change or cross-build agreement.

Recorded environments and comparison details.

Alternatives

GAMMADIST is the compatibility spelling. GAMMA.INV finds a quantile; EXPON.DIST covers shape one; CHISQ.DIST selects shape n/2 and scale two. GAMMA and GAMMALN evaluate related special functions rather than a CDF.

Named variants

No named variants are recorded yet.