Skip to Content

HYPERGEOM

Overview

The HYPERGEOM function computes values related to the Hypergeometric distribution, a discrete probability distribution that describes the probability of drawing a specific number of Type I objects from a finite population without replacement. This function can return the probability mass function (PMF), cumulative distribution function (CDF), survival function (SF), inverse CDF (quantile/ICDF), inverse SF (ISF), mean, variance, standard deviation, or median for a given value. This function only accepts scalar values for k.

Excel Functions Comparison:

  • HYPGEOM.DIST: Computes the PMF or CDF for the hypergeometric distribution. Only supports scalar input and does not provide the survival function, inverse CDF, inverse SF, or distribution statistics.

Python Code

 
from scipy.stats import hypergeom as scipy_hypergeom
 
def hypergeom(k, M, n, draws, mode="pmf", loc=0):
    """
    Compute Hypergeometric distribution values: PMF, CDF, SF, ICDF, ISF, mean, variance, std, or median.
 
    Args:
        k: Value at which to evaluate (float, scalar only).
        M: Total number of objects in the population (int, >=0).
        n: Number of Type I objects in the population (int, >=0).
        draws: Number of draws (int, >=0).
        mode: Output type: 'pmf', 'cdf', 'sf', 'icdf', 'isf', 'mean', 'var', 'std', or 'median'.
        loc: Location parameter (float, default 0).
 
    Returns:
        Scalar float, or error message (str) if invalid.
    """
    # Validate M, n, draws
    try:
        M_val = int(M)
        n_val = int(n)
        draws_val = int(draws)
        if M_val < 0 or n_val < 0 or draws_val < 0:
            return "Invalid input: M, n, draws must be >= 0."
        if n_val > M_val or draws_val > M_val:
            return "Invalid input: n and draws must be <= M."
    except Exception:
        return "Invalid input: M, n, draws must be integers."
    # Validate loc
    try:
        loc_val = float(loc)
    except Exception:
        return "Invalid input: loc must be a number."
    # Validate mode
    valid_modes = ["pmf", "cdf", "sf", "icdf", "isf", "mean", "var", "std", "median"]
    if not isinstance(mode, str) or mode not in valid_modes:
        return f"Invalid input: mode must be one of {valid_modes}."
    # Validate k is scalar
    if isinstance(k, list):
        return "Invalid input: k must be a scalar (float or int)."
    try:
        kval = float(k)
    except Exception:
        return "Invalid input: k must be a number."
    # Handle statistics
    if mode == "mean":
        return scipy_hypergeom.mean(M_val, n_val, draws_val, loc=loc_val)
    if mode == "var":
        return scipy_hypergeom.var(M_val, n_val, draws_val, loc=loc_val)
    if mode == "std":
        return scipy_hypergeom.std(M_val, n_val, draws_val, loc=loc_val)
    if mode == "median":
        return scipy_hypergeom.median(M_val, n_val, draws_val, loc=loc_val)
    # PMF, CDF, SF, ICDF, ISF
    if mode == "pmf":
        return float(scipy_hypergeom.pmf(kval, M_val, n_val, draws_val, loc=loc_val))
    elif mode == "cdf":
        return float(scipy_hypergeom.cdf(kval, M_val, n_val, draws_val, loc=loc_val))
    elif mode == "sf":
        return float(scipy_hypergeom.sf(kval, M_val, n_val, draws_val, loc=loc_val))
    elif mode == "icdf":
        return float(scipy_hypergeom.ppf(kval, M_val, n_val, draws_val, loc=loc_val))
    elif mode == "isf":
        return float(scipy_hypergeom.isf(kval, M_val, n_val, draws_val, loc=loc_val))

Live Demo

Example Workbook

Link to Workbook 

Last updated on
GEOMLOGSER