maxframe 0.1.0b5__cp310-cp310-macosx_11_0_arm64.whl

maxframe/tensor/random/f.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# Copyright 1999-2024 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import numpy as np
+
+from ... import opcodes
+from ...serialization.serializables import AnyField
+from ..utils import gen_random_seeds
+from .core import TensorDistribution, TensorRandomOperatorMixin, handle_array
+
+
+class TensorF(TensorDistribution, TensorRandomOperatorMixin):
+    _input_fields_ = ["dfnum", "dfden"]
+    _op_type_ = opcodes.RAND_F
+
+    _fields_ = "dfnum", "dfden", "size"
+    dfnum = AnyField("dfnum")
+    dfden = AnyField("dfden")
+    _func_name = "f"
+
+    def __call__(self, dfnum, dfden, chunk_size=None):
+        return self.new_tensor([dfnum, dfden], None, raw_chunk_size=chunk_size)
+
+
+def f(random_state, dfnum, dfden, size=None, chunk_size=None, gpu=None, dtype=None):
+    """
+    Draw samples from an F distribution.
+
+    Samples are drawn from an F distribution with specified parameters,
+    `dfnum` (degrees of freedom in numerator) and `dfden` (degrees of
+    freedom in denominator), where both parameters should be greater than
+    zero.
+
+    The random variate of the F distribution (also known as the
+    Fisher distribution) is a continuous probability distribution
+    that arises in ANOVA tests, and is the ratio of two chi-square
+    variates.
+
+    Parameters
+    ----------
+    dfnum : float or array_like of floats
+        Degrees of freedom in numerator, should be > 0.
+    dfden : float or array_like of float
+        Degrees of freedom in denominator, should be > 0.
+    size : int or tuple of ints, optional
+        Output shape.  If the given shape is, e.g., ``(m, n, k)``, then
+        ``m * n * k`` samples are drawn.  If size is ``None`` (default),
+        a single value is returned if ``dfnum`` and ``dfden`` are both scalars.
+        Otherwise, ``np.broadcast(dfnum, dfden).size`` samples are drawn.
+    chunk_size : int or tuple of int or tuple of ints, optional
+        Desired chunk size on each dimension
+    gpu : bool, optional
+        Allocate the tensor on GPU if True, False as default
+    dtype : data-type, optional
+      Data-type of the returned tensor.
+
+    Returns
+    -------
+    out : Tensor or scalar
+        Drawn samples from the parameterized Fisher distribution.
+
+    See Also
+    --------
+    scipy.stats.f : probability density function, distribution or
+        cumulative density function, etc.
+
+    Notes
+    -----
+    The F statistic is used to compare in-group variances to between-group
+    variances. Calculating the distribution depends on the sampling, and
+    so it is a function of the respective degrees of freedom in the
+    problem.  The variable `dfnum` is the number of samples minus one, the
+    between-groups degrees of freedom, while `dfden` is the within-groups
+    degrees of freedom, the sum of the number of samples in each group
+    minus the number of groups.
+
+    References
+    ----------
+    .. [1] Glantz, Stanton A. "Primer of Biostatistics.", McGraw-Hill,
+           Fifth Edition, 2002.
+    .. [2] Wikipedia, "F-distribution",
+           http://en.wikipedia.org/wiki/F-distribution
+
+    Examples
+    --------
+    An example from Glantz[1], pp 47-40:
+
+    Two groups, children of diabetics (25 people) and children from people
+    without diabetes (25 controls). Fasting blood glucose was measured,
+    case group had a mean value of 86.1, controls had a mean value of
+    82.2. Standard deviations were 2.09 and 2.49 respectively. Are these
+    data consistent with the null hypothesis that the parents diabetic
+    status does not affect their children's blood glucose levels?
+    Calculating the F statistic from the data gives a value of 36.01.
+
+    Draw samples from the distribution:
+
+    >>> import maxframe.tensor as mt
+
+    >>> dfnum = 1. # between group degrees of freedom
+    >>> dfden = 48. # within groups degrees of freedom
+    >>> s = mt.random.f(dfnum, dfden, 1000).execute()
+
+    The lower bound for the top 1% of the samples is :
+
+    >>> sorted(s)[-10]
+    7.61988120985
+
+    So there is about a 1% chance that the F statistic will exceed 7.62,
+    the measured value is 36, so the null hypothesis is rejected at the 1%
+    level.
+    """
+    if dtype is None:
+        dtype = (
+            np.random.RandomState()
+            .f(handle_array(dfnum), handle_array(dfden), size=(0,))
+            .dtype
+        )
+    size = random_state._handle_size(size)
+    seed = gen_random_seeds(1, random_state.to_numpy())[0]
+    op = TensorF(seed=seed, size=size, gpu=gpu, dtype=dtype)
+    return op(dfnum, dfden, chunk_size=chunk_size)

maxframe/tensor/random/gamma.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# Copyright 1999-2024 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import numpy as np
+
+from ... import opcodes
+from ...serialization.serializables import AnyField
+from ..utils import gen_random_seeds
+from .core import TensorDistribution, TensorRandomOperatorMixin, handle_array
+
+
+class TensorRandGamma(TensorDistribution, TensorRandomOperatorMixin):
+    _input_fields_ = ["shape", "scale"]
+    _op_type_ = opcodes.RAND_GAMMA
+
+    _fields_ = "shape", "scale", "size"
+    shape = AnyField("shape")
+    scale = AnyField("scale")
+    _func_name = "gamma"
+
+    def __call__(self, shape, scale, chunk_size=None):
+        return self.new_tensor([shape, scale], None, raw_chunk_size=chunk_size)
+
+
+def gamma(
+    random_state, shape, scale=1.0, size=None, chunk_size=None, gpu=None, dtype=None
+):
+    r"""
+    Draw samples from a Gamma distribution.
+
+    Samples are drawn from a Gamma distribution with specified parameters,
+    `shape` (sometimes designated "k") and `scale` (sometimes designated
+    "theta"), where both parameters are > 0.
+
+    Parameters
+    ----------
+    shape : float or array_like of floats
+        The shape of the gamma distribution. Should be greater than zero.
+    scale : float or array_like of floats, optional
+        The scale of the gamma distribution. Should be greater than zero.
+        Default is equal to 1.
+    size : int or tuple of ints, optional
+        Output shape.  If the given shape is, e.g., ``(m, n, k)``, then
+        ``m * n * k`` samples are drawn.  If size is ``None`` (default),
+        a single value is returned if ``shape`` and ``scale`` are both scalars.
+        Otherwise, ``np.broadcast(shape, scale).size`` samples are drawn.
+    chunk_size : int or tuple of int or tuple of ints, optional
+        Desired chunk size on each dimension
+    gpu : bool, optional
+        Allocate the tensor on GPU if True, False as default
+    dtype : data-type, optional
+      Data-type of the returned tensor.
+
+    Returns
+    -------
+    out : Tensor or scalar
+        Drawn samples from the parameterized gamma distribution.
+
+    See Also
+    --------
+    scipy.stats.gamma : probability density function, distribution or
+        cumulative density function, etc.
+
+    Notes
+    -----
+    The probability density for the Gamma distribution is
+
+    .. math:: p(x) = x^{k-1}\frac{e^{-x/\theta}}{\theta^k\Gamma(k)},
+
+    where :math:`k` is the shape and :math:`\theta` the scale,
+    and :math:`\Gamma` is the Gamma function.
+
+    The Gamma distribution is often used to model the times to failure of
+    electronic components, and arises naturally in processes for which the
+    waiting times between Poisson distributed events are relevant.
+
+    References
+    ----------
+    .. [1] Weisstein, Eric W. "Gamma Distribution." From MathWorld--A
+           Wolfram Web Resource.
+           http://mathworld.wolfram.com/GammaDistribution.html
+    .. [2] Wikipedia, "Gamma distribution",
+           http://en.wikipedia.org/wiki/Gamma_distribution
+
+    Examples
+    --------
+    Draw samples from the distribution:
+
+    >>> import maxframe.tensor as mt
+
+    >>> shape, scale = 2., 2.  # mean=4, std=2*sqrt(2)
+    >>> s = mt.random.gamma(shape, scale, 1000).execute()
+
+    Display the histogram of the samples, along with
+    the probability density function:
+
+    >>> import matplotlib.pyplot as plt
+    >>> import scipy.special as sps
+    >>> import numpy as np
+    >>> count, bins, ignored = plt.hist(s, 50, normed=True)
+    >>> y = bins**(shape-1)*(np.exp(-bins/scale) /
+    ...                      (sps.gamma(shape)*scale**shape))
+    >>> plt.plot(bins, y, linewidth=2, color='r')
+    >>> plt.show()
+    """
+    if dtype is None:
+        dtype = (
+            np.random.RandomState()
+            .gamma(handle_array(shape), handle_array(scale), size=(0,))
+            .dtype
+        )
+    size = random_state._handle_size(size)
+    seed = gen_random_seeds(1, random_state.to_numpy())[0]
+    op = TensorRandGamma(seed=seed, size=size, gpu=gpu, dtype=dtype)
+    return op(shape, scale, chunk_size=chunk_size)

maxframe/tensor/random/geometric.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# Copyright 1999-2024 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import numpy as np
+
+from ... import opcodes
+from ...serialization.serializables import AnyField
+from ..utils import gen_random_seeds
+from .core import TensorDistribution, TensorRandomOperatorMixin, handle_array
+
+
+class TensorGeometric(TensorDistribution, TensorRandomOperatorMixin):
+    _input_fields_ = ["p"]
+    _op_type_ = opcodes.RAND_GEOMETRIC
+
+    _fields_ = "p", "size"
+    p = AnyField("p")
+    _func_name = "geometric"
+
+    def __call__(self, p, chunk_size=None):
+        return self.new_tensor([p], None, raw_chunk_size=chunk_size)
+
+
+def geometric(random_state, p, size=None, chunk_size=None, gpu=None, dtype=None):
+    """
+    Draw samples from the geometric distribution.
+
+    Bernoulli trials are experiments with one of two outcomes:
+    success or failure (an example of such an experiment is flipping
+    a coin).  The geometric distribution models the number of trials
+    that must be run in order to achieve success.  It is therefore
+    supported on the positive integers, ``k = 1, 2, ...``.
+
+    The probability mass function of the geometric distribution is
+
+    .. math:: f(k) = (1 - p)^{k - 1} p
+
+    where `p` is the probability of success of an individual trial.
+
+    Parameters
+    ----------
+    p : float or array_like of floats
+        The probability of success of an individual trial.
+    size : int or tuple of ints, optional
+        Output shape.  If the given shape is, e.g., ``(m, n, k)``, then
+        ``m * n * k`` samples are drawn.  If size is ``None`` (default),
+        a single value is returned if ``p`` is a scalar.  Otherwise,
+        ``mt.array(p).size`` samples are drawn.
+    chunk_size : int or tuple of int or tuple of ints, optional
+        Desired chunk size on each dimension
+    gpu : bool, optional
+        Allocate the tensor on GPU if True, False as default
+    dtype : data-type, optional
+      Data-type of the returned tensor.
+
+    Returns
+    -------
+    out : Tensor or scalar
+        Drawn samples from the parameterized geometric distribution.
+
+    Examples
+    --------
+    Draw ten thousand values from the geometric distribution,
+    with the probability of an individual success equal to 0.35:
+
+    >>> import maxframe.tensor as mt
+
+    >>> z = mt.random.geometric(p=0.35, size=10000)
+
+    How many trials succeeded after a single run?
+
+    >>> ((z == 1).sum() / 10000.).execute()
+    0.34889999999999999 #random
+    """
+    if dtype is None:
+        dtype = np.random.RandomState().geometric(handle_array(p), size=(0,)).dtype
+    size = random_state._handle_size(size)
+    seed = gen_random_seeds(1, random_state.to_numpy())[0]
+    op = TensorGeometric(seed=seed, size=size, gpu=gpu, dtype=dtype)
+    return op(p, chunk_size=chunk_size)

maxframe/tensor/random/gumbel.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# Copyright 1999-2024 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import numpy as np
+
+from ... import opcodes
+from ...serialization.serializables import AnyField
+from ..utils import gen_random_seeds
+from .core import TensorDistribution, TensorRandomOperatorMixin, handle_array
+
+
+class TensorGumbel(TensorDistribution, TensorRandomOperatorMixin):
+    _input_fields_ = ["loc", "scale"]
+    _op_type_ = opcodes.RAND_GUMBEL
+
+    _fields_ = "loc", "scale", "size"
+    loc = AnyField("loc")
+    scale = AnyField("scale")
+    _func_name = "gumbel"
+
+    def __call__(self, loc, scale, chunk_size=None):
+        return self.new_tensor([loc, scale], None, raw_chunk_size=chunk_size)
+
+
+def gumbel(
+    random_state, loc=0.0, scale=1.0, size=None, chunk_size=None, gpu=None, dtype=None
+):
+    r"""
+    Draw samples from a Gumbel distribution.
+
+    Draw samples from a Gumbel distribution with specified location and
+    scale.  For more information on the Gumbel distribution, see
+    Notes and References below.
+
+    Parameters
+    ----------
+    loc : float or array_like of floats, optional
+        The location of the mode of the distribution. Default is 0.
+    scale : float or array_like of floats, optional
+        The scale parameter of the distribution. Default is 1.
+    size : int or tuple of ints, optional
+        Output shape.  If the given shape is, e.g., ``(m, n, k)``, then
+        ``m * n * k`` samples are drawn.  If size is ``None`` (default),
+        a single value is returned if ``loc`` and ``scale`` are both scalars.
+        Otherwise, ``np.broadcast(loc, scale).size`` samples are drawn.
+    chunk_size : int or tuple of int or tuple of ints, optional
+        Desired chunk size on each dimension
+    gpu : bool, optional
+        Allocate the tensor on GPU if True, False as default
+    dtype : data-type, optional
+      Data-type of the returned tensor.
+
+    Returns
+    -------
+    out : Tensor or scalar
+        Drawn samples from the parameterized Gumbel distribution.
+
+    See Also
+    --------
+    scipy.stats.gumbel_l
+    scipy.stats.gumbel_r
+    scipy.stats.genextreme
+    weibull
+
+    Notes
+    -----
+    The Gumbel (or Smallest Extreme Value (SEV) or the Smallest Extreme
+    Value Type I) distribution is one of a class of Generalized Extreme
+    Value (GEV) distributions used in modeling extreme value problems.
+    The Gumbel is a special case of the Extreme Value Type I distribution
+    for maximums from distributions with "exponential-like" tails.
+
+    The probability density for the Gumbel distribution is
+
+    .. math:: p(x) = \frac{e^{-(x - \mu)/ \beta}}{\beta} e^{ -e^{-(x - \mu)/
+              \beta}},
+
+    where :math:`\mu` is the mode, a location parameter, and
+    :math:`\beta` is the scale parameter.
+
+    The Gumbel (named for German mathematician Emil Julius Gumbel) was used
+    very early in the hydrology literature, for modeling the occurrence of
+    flood events. It is also used for modeling maximum wind speed and
+    rainfall rates.  It is a "fat-tailed" distribution - the probability of
+    an event in the tail of the distribution is larger than if one used a
+    Gaussian, hence the surprisingly frequent occurrence of 100-year
+    floods. Floods were initially modeled as a Gaussian process, which
+    underestimated the frequency of extreme events.
+
+    It is one of a class of extreme value distributions, the Generalized
+    Extreme Value (GEV) distributions, which also includes the Weibull and
+    Frechet.
+
+    The function has a mean of :math:`\mu + 0.57721\beta` and a variance
+    of :math:`\frac{\pi^2}{6}\beta^2`.
+
+    References
+    ----------
+    .. [1] Gumbel, E. J., "Statistics of Extremes,"
+           New York: Columbia University Press, 1958.
+    .. [2] Reiss, R.-D. and Thomas, M., "Statistical Analysis of Extreme
+           Values from Insurance, Finance, Hydrology and Other Fields,"
+           Basel: Birkhauser Verlag, 2001.
+
+    Examples
+    --------
+    Draw samples from the distribution:
+
+    >>> import maxframe.tensor as mt
+
+    >>> mu, beta = 0, 0.1 # location and scale
+    >>> s = mt.random.gumbel(mu, beta, 1000).execute()
+
+    Display the histogram of the samples, along with
+    the probability density function:
+
+    >>> import matplotlib.pyplot as plt
+    >>> import numpy as np
+    >>> count, bins, ignored = plt.hist(s, 30, normed=True)
+    >>> plt.plot(bins, (1/beta)*np.exp(-(bins - mu)/beta)
+    ...          * np.exp( -np.exp( -(bins - mu) /beta) ),
+    ...          linewidth=2, color='r')
+    >>> plt.show()
+
+    Show how an extreme value distribution can arise from a Gaussian process
+    and compare to a Gaussian:
+
+    >>> means = []
+    >>> maxima = []
+    >>> for i in range(0,1000) :
+    ...    a = mt.random.normal(mu, beta, 1000)
+    ...    means.append(a.mean().execute())
+    ...    maxima.append(a.max().execute())
+    >>> count, bins, ignored = plt.hist(maxima, 30, normed=True)
+    >>> beta = mt.std(maxima) * mt.sqrt(6) / mt.pi
+    >>> mu = mt.mean(maxima) - 0.57721*beta
+    >>> plt.plot(bins, ((1/beta)*mt.exp(-(bins - mu)/beta)
+    ...          * mt.exp(-mt.exp(-(bins - mu)/beta))).execute(),
+    ...          linewidth=2, color='r')
+    >>> plt.plot(bins, (1/(beta * mt.sqrt(2 * mt.pi))
+    ...          * mt.exp(-(bins - mu)**2 / (2 * beta**2))).execute(),
+    ...          linewidth=2, color='g')
+    >>> plt.show()
+    """
+    if dtype is None:
+        dtype = (
+            np.random.RandomState()
+            .gumbel(handle_array(loc), handle_array(scale), size=(0,))
+            .dtype
+        )
+    size = random_state._handle_size(size)
+    seed = gen_random_seeds(1, random_state.to_numpy())[0]
+    op = TensorGumbel(seed=seed, size=size, gpu=gpu, dtype=dtype)
+    return op(loc, scale, chunk_size=chunk_size)

maxframe/tensor/random/hypergeometric.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# Copyright 1999-2024 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import numpy as np
+
+from ... import opcodes
+from ...serialization.serializables import AnyField
+from ..utils import gen_random_seeds
+from .core import TensorDistribution, TensorRandomOperatorMixin, handle_array
+
+
+class TensorHypergeometric(TensorDistribution, TensorRandomOperatorMixin):
+    _input_fields_ = ["ngood", "nbad", "nsample"]
+    _op_type_ = opcodes.RAND_HYPERGEOMETRIC
+
+    _fields_ = "ngood", "nbad", "nsample", "size"
+    ngood = AnyField("ngood")
+    nbad = AnyField("nbad")
+    nsample = AnyField("nsample")
+    _func_name = "hypergeometric"
+
+    def __call__(self, ngood, nbad, nsample, chunk_size=None):
+        return self.new_tensor([ngood, nbad, nsample], None, raw_chunk_size=chunk_size)
+
+
+def hypergeometric(
+    random_state, ngood, nbad, nsample, size=None, chunk_size=None, gpu=None, dtype=None
+):
+    r"""
+    Draw samples from a Hypergeometric distribution.
+
+    Samples are drawn from a hypergeometric distribution with specified
+    parameters, ngood (ways to make a good selection), nbad (ways to make
+    a bad selection), and nsample = number of items sampled, which is less
+    than or equal to the sum ngood + nbad.
+
+    Parameters
+    ----------
+    ngood : int or array_like of ints
+        Number of ways to make a good selection.  Must be nonnegative.
+    nbad : int or array_like of ints
+        Number of ways to make a bad selection.  Must be nonnegative.
+    nsample : int or array_like of ints
+        Number of items sampled.  Must be at least 1 and at most
+        ``ngood + nbad``.
+    size : int or tuple of ints, optional
+        Output shape.  If the given shape is, e.g., ``(m, n, k)``, then
+        ``m * n * k`` samples are drawn.  If size is ``None`` (default),
+        a single value is returned if ``ngood``, ``nbad``, and ``nsample``
+        are all scalars.  Otherwise, ``np.broadcast(ngood, nbad, nsample).size``
+        samples are drawn.
+    chunk_size : int or tuple of int or tuple of ints, optional
+        Desired chunk size on each dimension
+    gpu : bool, optional
+        Allocate the tensor on GPU if True, False as default
+    dtype : data-type, optional
+      Data-type of the returned tensor.
+
+    Returns
+    -------
+    out : Tensor or scalar
+        Drawn samples from the parameterized hypergeometric distribution.
+
+    See Also
+    --------
+    scipy.stats.hypergeom : probability density function, distribution or
+        cumulative density function, etc.
+
+    Notes
+    -----
+    The probability density for the Hypergeometric distribution is
+
+    .. math:: P(x) = \frac{\binom{m}{n}\binom{N-m}{n-x}}{\binom{N}{n}},
+
+    where :math:`0 \le x \le m` and :math:`n+m-N \le x \le n`
+
+    for P(x) the probability of x successes, n = ngood, m = nbad, and
+    N = number of samples.
+
+    Consider an urn with black and white marbles in it, ngood of them
+    black and nbad are white. If you draw nsample balls without
+    replacement, then the hypergeometric distribution describes the
+    distribution of black balls in the drawn sample.
+
+    Note that this distribution is very similar to the binomial
+    distribution, except that in this case, samples are drawn without
+    replacement, whereas in the Binomial case samples are drawn with
+    replacement (or the sample space is infinite). As the sample space
+    becomes large, this distribution approaches the binomial.
+
+    References
+    ----------
+    .. [1] Lentner, Marvin, "Elementary Applied Statistics", Bogden
+           and Quigley, 1972.
+    .. [2] Weisstein, Eric W. "Hypergeometric Distribution." From
+           MathWorld--A Wolfram Web Resource.
+           http://mathworld.wolfram.com/HypergeometricDistribution.html
+    .. [3] Wikipedia, "Hypergeometric distribution",
+           http://en.wikipedia.org/wiki/Hypergeometric_distribution
+
+    Examples
+    --------
+    Draw samples from the distribution:
+
+    >>> import maxframe.tensor as mt
+
+    >>> ngood, nbad, nsamp = 100, 2, 10
+    # number of good, number of bad, and number of samples
+    >>> s = mt.random.hypergeometric(ngood, nbad, nsamp, 1000)
+    >>> hist(s)
+    #   note that it is very unlikely to grab both bad items
+
+    Suppose you have an urn with 15 white and 15 black marbles.
+    If you pull 15 marbles at random, how likely is it that
+    12 or more of them are one color?
+
+    >>> s = mt.random.hypergeometric(15, 15, 15, 100000)
+    >>> (mt.sum(s>=12)/100000. + mt.sum(s<=3)/100000.).execute()
+    #   answer = 0.003 ... pretty unlikely!
+    """
+    if dtype is None:
+        dtype = (
+            np.random.RandomState()
+            .hypergeometric(
+                handle_array(ngood),
+                handle_array(nbad),
+                handle_array(nsample),
+                size=(0,),
+            )
+            .dtype
+        )
+    size = random_state._handle_size(size)
+    seed = gen_random_seeds(1, random_state.to_numpy())[0]
+    op = TensorHypergeometric(seed=seed, size=size, gpu=gpu, dtype=dtype)
+    return op(ngood, nbad, nsample, chunk_size=chunk_size)