cleverly.datasets.make_clustered

cleverly.datasets.make_clustered(n: int = 1000, *, seed: int | Generator | None = None, cluster_size: int = 10, backend: Literal['pandas', 'polars'] | str | None = None, family: str = 'gaussian') → tuple[Any, dict[str, float]]

Clustered data with an unobserved shared effect modifying the treatment effect.

The third latent variable is shared within a cluster and is deliberately not included among the covariates, so the influence curves are correlated within clusters. Ignoring cluster= here understates the standard error – which is exactly what the cluster-variance test checks.

It moves Y and, being independent of A, leaves the ATE identified from the covariates that are emitted; see clustered_dgp() for why both of those are necessary and why an additive shared effect would give neither.

family="binomial" gives a 0/1 outcome with the same cluster structure, so the risk ratio and the odds ratio have a clustered law to be checked on.

Parameters:

nint

Number of observations.

seedint, Generator, or None

Seed or NumPy random generator.

cluster_sizeint

Number of rows per cluster.

backend{“pandas”, “polars”, “pyarrow”} or None, default=None

Dataframe backend. None uses pandas when installed, then the first available backend.

family{“gaussian”, “binomial”}

Outcome family of the generated outcome.

Returns:

dataframe

Simulated observations with a cluster column naming each row’s cluster.

truthdict of str to float

Exact causal parameters for the data-generating process.