torch.special.gammainc
function gammainc<S1 extends Shape, S2 extends Shape>(input: Tensor<S1, 'float32'>, other: Tensor<S2, 'float32'>, _options?: SpecialBinaryOptions): Tensor<DynamicShape, 'float32'>Computes the regularized lower incomplete gamma function, P(a, x) = γ(a, x) / Γ(a).
The incomplete gamma function γ(a, x) = ∫₀ˣ tᵃ⁻¹ exp(-t) dt measures the integral of the gamma PDF from 0 to x. The regularized version P(a, x) normalizes by dividing by Γ(a), resulting in a cumulative distribution function (CDF) that ranges from 0 to 1. Essential for:
- Probability: CDF of the gamma distribution (degrees of freedom, shape parameter a)
- Statistics: chi-squared test p-values (chi² is gamma with a = df/2)
- Hypothesis testing: upper tail probabilities for goodness-of-fit tests
- Risk modeling: Bayesian prior on variances (inverse gamma related)
- Machine learning: prior distributions for precision/scale parameters
- Quality control: failure time analysis (Weibull approximation via gamma)
Key Properties:
- P(a, 0) = 0 (no mass below 0)
- P(a, ∞) = 1 (total probability mass)
- P(a, x) increases monotonically from 0 to 1
- For integer a: P(a, x) = Q(a, x/e^(x)) * (a-1)! = Poisson CDF
- Relationship: P(a, x) + Q(a, x) = 1 (lower + upper = total)
- Complement: Q(a, x) = gammaincc(a, x) = 1 - P(a, x)
- Special: P(a, a) ≈ 0.5 (median approximately at shape parameter)
- Lower incomplete: Integral from 0 to x (lower tail)
- Regularized form: Normalized CDF, ranges from 0 to 1
- Gamma distribution CDF: P(a, x) is the CDF of Gamma(a, 1)
- Chi-squared connection: Chi-squared test uses gamma incomplete
- Monotonic increasing: Strictly increases from 0 to 1
- Complement: Q(a, x) = gammaincc(a, x) = 1 - P(a, x)
- Poisson connection: Related to Poisson probabilities for integer a
- Shape parameter a 0: Required, typically positive
- Argument x ≥ 0: Negative x not supported, physical domain is [0, ∞)
- Numerical precision: For large a, incomplete gamma can lose precision
- Symmetry missing: Unlike error function, no simple symmetry property
Parameters
inputTensor<S1, 'float32'>- Input tensor a (shape parameter, must be 0, typically positive integers)
otherTensor<S2, 'float32'>- Input tensor x (argument, must be ≥ 0, typically ≥ 0)
_optionsSpecialBinaryOptionsoptional
Returns
Tensor<DynamicShape, 'float32'>– Tensor with P(a, x) values in [0, 1] (CDF of gamma distribution)Examples
// Gamma CDF: cumulative probability
const a = torch.tensor([1, 2, 3, 5, 10]); // Shape parameters
const x = torch.tensor([1, 2, 3, 5, 10]); // Argument
const cdf = torch.special.gammainc(a, x); // P(a, x) in [0, 1]
// Values gradually increase from ~0.63 to ~0.99// Chi-squared test p-value: testing goodness-of-fit
const chi2_stat = 8.5; // Computed test statistic
const df = 4; // Degrees of freedom
const p_value = 1 - torch.special.gammainc(
torch.tensor([df / 2]),
torch.tensor([chi2_stat / 2])
); // Right-tail probability
// P-value represents probability of observing worse fit under null hypothesis// Bayesian hierarchical model: variance prior
const shape_param = torch.tensor([2, 3, 5]); // Shape for prior
const scales = torch.linspace(0.1, 5, 100); // Scale values to evaluate
const prior_cdf = torch.special.gammainc(shape_param.unsqueeze(1), scales);
// Prior cumulative probability for different variance scales// Failure time analysis: time until a devices fail
const num_failures = torch.tensor([3.0, 5.0, 7.0]); // Number of failures (shape)
const time_elapsed = torch.tensor([100, 150, 200]); // Elapsed time (scale)
const prob_time = torch.special.gammainc(num_failures, time_elapsed);
// Probability that we've seen enough failures by the elapsed timeSee Also
- PyTorch torch.special.gammainc()
- torch.special.gammaincc - Upper incomplete gamma: Q(a,x) = 1 - P(a,x)
- torch.special.logit - Related statistical transformations
- torch.special.ndtr - Normal CDF (similar role for normal distribution)