rankseg.distribution

Classes

RefinedNormalPB	Refined Normal distribution to approximate Poisson binomial distribution.
RefinedNormal	Refined Normal distribution to approximate Poisson binomial distribution.

Module Contents

class rankseg.distribution.RefinedNormalPB(dim: torch.Tensor | int, loc: torch.Tensor | float, scale: torch.Tensor | float, skew: torch.Tensor | float, validate_args: bool | None = None)

Bases: torch.distributions.Distribution

Refined Normal distribution to approximate Poisson binomial distribution.

The CDF is defined as:

\[F(k; skew) = G( (k + 0.5 - loc) / scale ); \quad G(x) = \Phi(x) + skew * (1 - x^2) * \phi(x) / 6\]

where:

• Phi(x) is the standard normal CDF

• phi(x) is the standard normal PDF

• skew is the skewness parameter

The PDF is defined as:

\[f(k; skew) = \frac{\phi(x)}{scale} \left[1 + \frac{skew}{6}(x^3 - 3x)\right], \quad x = \frac{k + 0.5 - loc}{scale}.\]

Parameters:

• dim (torch.Tensor or int) – Finite, nonnegative integer upper bound used when clipping integer confidence intervals.

• loc (torch.Tensor or float) – Finite location parameter of the refined normal approximation.

• scale (torch.Tensor or float) – Finite, strictly positive scale parameter of the refined normal approximation.

• skew (torch.Tensor or float) – Finite skewness parameter controlling the third-moment correction term.

• validate_args (bool, optional) – Whether to validate arguments through torch.distributions.Distribution. Explicitly setting this to False bypasses parameter validation.

expand(batch_shape, _instance=None)

Returns a new distribution instance (or populates an existing instance provided by a derived class) with batch dimensions expanded to batch_shape. This method calls expand on the distribution’s parameters. As such, this does not allocate new memory for the expanded distribution instance. Additionally, this does not repeat any args checking or parameter broadcasting in __init__.py, when an instance is first created.

Parameters:

• batch_shape (torch.Size) – the desired expanded size.

• _instance – new instance provided by subclasses that need to override .expand.

Returns:

New distribution instance with batch dimensions expanded to batch_shape.

cdf(value)

Returns the cumulative density/mass function evaluated at value.

Parameters:

value (Tensor)

pdf(value)

pmf(value)

icdf(p, max_iter=1000, tol=1e-06)

Inverse CDF (quantile function) using bracketed bisection.

Parameters:

• p (torch.Tensor) – Probability values (0 < p < 1)

• max_iter (int, optional) – Positive maximum number of bisection iterations (default: 1000).

• tol (float, optional) – Finite, strictly positive convergence tolerance (default: 1e-6). Bisection also stops when finite-precision rounding leaves no representable midpoint between the current bounds.

Returns:

Quantile values corresponding to probabilities p

Return type:

torch.Tensor

Notes

This numerical root-finding operation is not differentiable. Gradient recording is disabled internally, even when the probabilities or distribution parameters require gradients.

interval(p)

Compute an inclusive confidence interval with retained mass 1 - p.

p may be a real scalar or an array-like/Tensor of real values in [0, 1]. Every value must be finite.

SciPy evaluates the refined-normal quantiles on the CPU. Tensor inputs are detached for this non-differentiable calculation, and the integer endpoints are returned on the same device as the distribution parameters.

class rankseg.distribution.RefinedNormal(momtype=1, a=None, b=None, xtol=1e-14, badvalue=None, name=None, longname=None, shapes=None, seed=None)

Bases: scipy.stats.rv_continuous

Refined Normal distribution to approximate Poisson binomial distribution.

This class extends the continuous random variable class from SciPy to implement a modified normal distribution with a skewness correction term. The distribution is particularly effective for approximating the Poisson binomial distribution (the sum of independent but non-identical Bernoulli random variables).

The CDF is defined as: F(x; skew) = Φ(x) + skew * (1 - x²) * φ(x) / 6

where:

• Φ(x) is the standard normal CDF

• φ(x) is the standard normal PDF

• skew is the skewness parameter

Parameters:

skew (float) – Skewness parameter controlling the third moment correction term. Must be a finite value.

Notes

This refined approximation offers improved accuracy over the standard normal approximation by incorporating a skewness correction term [3].

In the context of RankSEG, this distribution is used to efficiently approximate the Poisson binomial distribution.

References

[3] Volkova, A.Y., 1996. A refinement of the central limit theorem for sums of independent random indicators. Theory of Probability and its Applications 40, 791-794.