API reference

polars-random exposes the same set of distributions through four interchangeable entry points. Pick whichever fits your pipeline; the underlying Rust kernel is the same.

Top-level functions

Returns a pl.Expr by default, or a pl.Series of length size when size= is given.

Uniform [low, high) random draws.

Parameters:

Name	Type	Description	Default
low	float, str (column name), pl.Expr, or None	Distribution bounds. Must both be scalars or both be column-like. Defaults to [0.0, 1.0).	None
high	float, str (column name), pl.Expr, or None	Distribution bounds. Must both be scalars or both be column-like. Defaults to [0.0, 1.0).	None
seed	int or None	Reproducible draws.	None
size	(int or None, keyword - only)	If given, eagerly evaluate and return a Series of that length. Otherwise returns a polars Expr to be used in a select/with_columns.	None

Returns:

Type	Description
Expr or Series

Source code in polars_random/__init__.py

def rand(
    low: FloatParam = None,
    high: FloatParam = None,
    seed: int | None = None,
    *,
    size: int | None = None,
) -> pl.Expr | pl.Series:
    """
    Uniform `[low, high)` random draws.

    Parameters
    ----------
    low, high : float, str (column name), pl.Expr, or None
        Distribution bounds. Must both be scalars or both be column-like.
        Defaults to ``[0.0, 1.0)``.
    seed : int or None, optional
        Reproducible draws.
    size : int or None, keyword-only
        If given, eagerly evaluate and return a Series of that length.
        Otherwise returns a polars Expr to be used in a select/with_columns.

    Returns
    -------
    pl.Expr or pl.Series
    """
    _check_size(size)
    if size is None:
        return _rand_expr(low=low, high=high, seed=seed)
    over = pl.int_range(0, size).cast(pl.Float64)
    return _eager(_rand_expr(low=low, high=high, seed=seed, over=over).alias("rand"), size)

Normal (Gaussian) random draws.

Parameters:

Name	Type	Description	Default
mean	float, str (column name), pl.Expr, or None	Distribution parameters. Must both be scalars or both be column-like.	0.0
std	float, str (column name), pl.Expr, or None	Distribution parameters. Must both be scalars or both be column-like.	0.0
seed	int or None		None
size	(int or None, keyword - only)	If given, eagerly evaluate and return a Series of that length.	None

Returns:

Type	Description
Expr or Series

Source code in polars_random/__init__.py

def normal(
    mean: FloatParam = 0.0,
    std: FloatParam = 1.0,
    seed: int | None = None,
    *,
    size: int | None = None,
) -> pl.Expr | pl.Series:
    """
    Normal (Gaussian) random draws.

    Parameters
    ----------
    mean, std : float, str (column name), pl.Expr, or None
        Distribution parameters. Must both be scalars or both be column-like.
    seed : int or None, optional
    size : int or None, keyword-only
        If given, eagerly evaluate and return a Series of that length.

    Returns
    -------
    pl.Expr or pl.Series
    """
    _check_size(size)
    if size is None:
        return _normal_expr(mean=mean, std=std, seed=seed)
    over = pl.int_range(0, size).cast(pl.Float64)
    return _eager(_normal_expr(mean=mean, std=std, seed=seed, over=over).alias("normal"), size)

Binomial random draws.

Parameters:

Name	Type	Description	Default
n	int, str (column name), or pl.Expr	Number of trials.	required
p	float, str (column name), or pl.Expr	Probability of success.	required
seed	int or None		None
size	(int or None, keyword - only)	If given, eagerly evaluate and return a Series of that length.	None

Returns:

Type	Description
Expr or Series

Source code in polars_random/__init__.py

def binomial(
    n: IntParam,
    p: FloatParam,
    seed: int | None = None,
    *,
    size: int | None = None,
) -> pl.Expr | pl.Series:
    """
    Binomial random draws.

    Parameters
    ----------
    n : int, str (column name), or pl.Expr
        Number of trials.
    p : float, str (column name), or pl.Expr
        Probability of success.
    seed : int or None, optional
    size : int or None, keyword-only
        If given, eagerly evaluate and return a Series of that length.

    Returns
    -------
    pl.Expr or pl.Series
    """
    _check_size(size)
    if size is None:
        return _binomial_expr(n=n, p=p, seed=seed)
    over = pl.int_range(0, size).cast(pl.Float64)
    return _eager(_binomial_expr(n=n, p=p, seed=seed, over=over).alias("binomial"), size)

Uniform random integers in [low, high).

Parameters:

Name	Type	Description	Default
low	int, str (column name), or pl.Expr	Bounds; high is exclusive. Must both be scalars or both be column-like.	0
high	int, str (column name), or pl.Expr	Bounds; high is exclusive. Must both be scalars or both be column-like.	0
seed	int or None		None
size	(int or None, keyword - only)	If given, eagerly evaluate and return a Series of that length.	None

Returns:

Type	Description
Expr or Series

Source code in polars_random/__init__.py

def randint(
    low: IntParam = 0,
    high: IntParam = 2,
    seed: int | None = None,
    *,
    size: int | None = None,
) -> pl.Expr | pl.Series:
    """
    Uniform random integers in ``[low, high)``.

    Parameters
    ----------
    low, high : int, str (column name), or pl.Expr
        Bounds; ``high`` is exclusive. Must both be scalars or both be column-like.
    seed : int or None, optional
    size : int or None, keyword-only
        If given, eagerly evaluate and return a Series of that length.

    Returns
    -------
    pl.Expr or pl.Series
    """
    _check_size(size)
    if size is None:
        return _randint_expr(low=low, high=high, seed=seed)
    over = pl.int_range(0, size).cast(pl.Float64)
    return _eager(_randint_expr(low=low, high=high, seed=seed, over=over).alias("randint"), size)

pl.col(...).random — expression namespace

Use inside any expression context (select, with_columns, lazy queries, group-by aggregations, …). The parent expression provides the row count.

import polars as pl
import polars_random  # registers the namespace

df.with_columns(noise=pl.col("id").random.normal(mean=0, std=1, seed=42))

Available methods: rand / uniform, normal, binomial, randint. Same parameters as the top-level functions, minus size.

df.random — DataFrame namespace

Namespace for adding columns of random draws to a DataFrame.

Parameters:

Name	Type	Description	Default
df	DataFrame	The dataframe to apply the random functions on.	required

Source code in polars_random/__init__.py

@pl.api.register_dataframe_namespace("random")
class Random:
    """
    Namespace for adding columns of random draws to a ``DataFrame``.

    Parameters
    ----------
    df : pl.DataFrame
        The dataframe to apply the random functions on.
    """

    def __init__(self, df: pl.DataFrame) -> None:
        self._df = df

    def rand(
        self,
        low: FloatParam = None,
        high: FloatParam = None,
        seed: int | None = None,
        name: str | None = None,
    ) -> pl.DataFrame:
        return self._df.with_columns(
            _rand_expr(low=low, high=high, seed=seed).alias(name or "rand")
        )

    uniform = rand

    def normal(
        self,
        mean: FloatParam = 0.0,
        std: FloatParam = 1.0,
        seed: int | None = None,
        name: str | None = None,
    ) -> pl.DataFrame:
        return self._df.with_columns(
            _normal_expr(mean=mean, std=std, seed=seed).alias(name or "normal")
        )

    def binomial(
        self,
        n: IntParam,
        p: FloatParam,
        seed: int | None = None,
        name: str | None = None,
    ) -> pl.DataFrame:
        return self._df.with_columns(_binomial_expr(n=n, p=p, seed=seed).alias(name or "binomial"))

    def randint(
        self,
        low: IntParam = 0,
        high: IntParam = 2,
        seed: int | None = None,
        name: str | None = None,
    ) -> pl.DataFrame:
        return self._df.with_columns(
            _randint_expr(low=low, high=high, seed=seed).alias(name or "randint")
        )

lf.random — LazyFrame namespace

Same API as df.random but returns a pl.LazyFrame. Lets the random draws stay inside a lazy plan and be optimized alongside the rest of your query.

(
    df.lazy()
      .filter(pl.col("active"))
      .random.normal(seed=42, name="noise")
      .collect()
)

Null handling

When a parameter is supplied as a column or expression, any null in that column is propagated to the output as null instead of raising. Scalar parameters are validated up front (seed >= 0, 0 <= p <= 1, valid distribution params) and raise ValueError / PolarsError if invalid.