synthetic-tabular 0.1.0__tar.gz

synthetic_tabular-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pranay Mahendrakar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

synthetic_tabular-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.5
+Name: synthetic-tabular
+Version: 0.1.0
+Summary: Generate realistic synthetic tabular data that preserves distributions and correlations, without a GPU
+Project-URL: Homepage, https://pypi.org/project/synthetic-tabular/
+Project-URL: Author, https://pypi.org/user/pranaymahendrakar/
+Author: Pranay Mahendrakar
+License-Expression: MIT
+License-File: LICENSE
+Keywords: data augmentation,gaussian copula,pandas,privacy,synthetic data,tabular data,test data
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: scipy>=1.9
+Provides-Extra: dev
+Requires-Dist: pyarrow>=12; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=12; extra == 'parquet'
+Description-Content-Type: text/markdown
+
+# synthetic-tabular
+
+Generate realistic synthetic tabular data that keeps the distributions and correlations of your real table, so you can share, test and prototype without handing out the original rows, and without a GPU.
+
+## Install
+
+```
+pip install synthetic-tabular
+```
+
+## Quickstart
+
+```python
+import pandas as pd
+import synthetic_tabular as st
+
+df = pd.DataFrame({"age": [23, 35, 41, 29, 52, 38, 45, 31],
+                   "city": ["Pune", "Delhi", "Pune", "Mumbai", "Delhi", "Pune", "Mumbai", "Delhi"],
+                   "spend": [120.5, 340.0, 410.2, 210.0, 620.9, 380.4, 455.0, 290.7]})
+synthetic = st.generate(df, n=100, random_state=0)  # same columns and dtypes, 100 new rows
+print(st.evaluate(df, synthetic).summary())         # how close are the distributions?
+```
+
+## What it does
+
+- Fits a **Gaussian copula**: every column is rank-transformed to standard-normal
+  scores, the correlation matrix of those scores is learned (repaired to the nearest
+  positive-definite matrix when needed), new correlated normals are sampled and mapped
+  back through each column's own distribution.
+- **Numeric columns** are inverted through their empirical quantile function, so the
+  output has the same shape, stays inside the observed min/max, keeps integer columns
+  integer and keeps the number of decimals seen in the input.
+- **Categorical, boolean and string columns** are sampled by their observed
+  frequencies; booleans stay boolean, `category` dtypes keep their categories.
+- **Datetime and timedelta columns** are modelled as nanoseconds, converted back to the
+  original dtype (time zone included) and rounded to the finest resolution seen in the
+  column (days stay days, seconds stay seconds).
+- **Missing values** are reinjected per column at the rate seen in the input.
+- **Constant columns** and columns with a single category are copied as-is.
+- **High-cardinality text** (more than 50% unique strings, for example names or free
+  text) cannot be modelled by frequency: those columns are sampled with replacement
+  from the original values and flagged with a `UserWarning`. Raise `text_threshold` to
+  model them as categories instead.
+- Output columns and dtypes match the input; `n` can be larger than the input.
+- Paths are accepted wherever a DataFrame is: `.csv`, `.tsv` and `.parquet`
+  (`pip install synthetic-tabular[parquet]`). CSV columns whose every value is an
+  ISO-8601 date (`2024-03-31`, `2024-03-31 10:15:00`) are parsed as datetimes so they
+  are modelled as dates rather than treated as text.
+- Deterministic: the same `random_state` always gives the same rows.
+- Ships an `evaluate()` fidelity check: per-column KS statistic (numeric) or total
+  variation distance (categorical), correlation-matrix difference and a 0-100 score.
+
+Limits worth knowing: a Gaussian copula captures monotone dependence between columns,
+not arbitrary non-linear or multi-modal joint structure, and it is not a privacy
+guarantee. Text columns that are resampled contain original values verbatim.
+
+## API
+
+```python
+synthetic_tabular.generate(df, n=None, *, random_state=0, preserve=("marginals", "correlations")) -> DataFrame
+```
+One-liner for the common case. `df` is a DataFrame or a path to a `.csv` / `.parquet`
+file; `n` defaults to `len(df)`. `preserve` chooses what to keep: drop
+`"correlations"` to sample columns independently, drop `"marginals"` to replace the
+empirical numeric distributions with a smooth fitted normal (clipped to the observed range).
+
+```python
+synthesizer = synthetic_tabular.Synthesizer(random_state=0, *, preserve=..., text_threshold=0.5)
+synthesizer.fit(df)                               # returns self
+synthesizer.sample(n=None, *, random_state=None)  # DataFrame; same rows on repeat, new seed for a new batch
+synthesizer.summary()                             # text: what was learned per column
+synthesizer.to_dict()                             # JSON-safe version of the above
+```
+After `fit`: `columns_`, `column_kinds_` (`numeric`, `datetime`, `timedelta`,
+`categorical`, `bool`, `text`, `constant`), `high_cardinality_columns_`,
+`correlation_` (DataFrame of the fitted normal-score correlations) and `n_rows_`.
+
+```python
+synthetic_tabular.evaluate(real, synthetic) -> FidelityReport
+```
+`FidelityReport` fields: `score` (0-100), `marginal_score`, `correlation_score`,
+`correlation_mad` (mean absolute difference of the Spearman correlation matrices,
+`None` with fewer than two non-constant columns), `columns` (dict of
+`ColumnFidelity`: `name`, `kind`, `metric` `"ks"`/`"tvd"`, `value`, `score`,
+`missing_rate_real`, `missing_rate_synthetic`), `n_real`, `n_synthetic`,
+`missing_columns`. Methods: `summary()` (text) and `to_dict()` (JSON-safe).
+
+## CLI
+
+```
+synthetic-tabular data.csv                          # generate a synthetic copy and print the fidelity report
+synthetic-tabular data.csv --n 1000 -o synth.csv    # write 1000 synthetic rows (csv, tsv or parquet)
+synthetic-tabular data.csv --evaluate synth.csv     # score an existing synthetic file
+synthetic-tabular data.csv --json                   # report as JSON
+synthetic-tabular --help
+```
+Options: `--random-state SEED`, `--no-correlations` (marginals only), `--quiet`.
+Flagged text columns are reported on stderr as `note:` lines.
+
+## License
+
+MIT

synthetic_tabular-0.1.0/README.md

@@ -0,0 +1,102 @@
+# synthetic-tabular
+
+Generate realistic synthetic tabular data that keeps the distributions and correlations of your real table, so you can share, test and prototype without handing out the original rows, and without a GPU.
+
+## Install
+
+```
+pip install synthetic-tabular
+```
+
+## Quickstart
+
+```python
+import pandas as pd
+import synthetic_tabular as st
+
+df = pd.DataFrame({"age": [23, 35, 41, 29, 52, 38, 45, 31],
+                   "city": ["Pune", "Delhi", "Pune", "Mumbai", "Delhi", "Pune", "Mumbai", "Delhi"],
+                   "spend": [120.5, 340.0, 410.2, 210.0, 620.9, 380.4, 455.0, 290.7]})
+synthetic = st.generate(df, n=100, random_state=0)  # same columns and dtypes, 100 new rows
+print(st.evaluate(df, synthetic).summary())         # how close are the distributions?
+```
+
+## What it does
+
+- Fits a **Gaussian copula**: every column is rank-transformed to standard-normal
+  scores, the correlation matrix of those scores is learned (repaired to the nearest
+  positive-definite matrix when needed), new correlated normals are sampled and mapped
+  back through each column's own distribution.
+- **Numeric columns** are inverted through their empirical quantile function, so the
+  output has the same shape, stays inside the observed min/max, keeps integer columns
+  integer and keeps the number of decimals seen in the input.
+- **Categorical, boolean and string columns** are sampled by their observed
+  frequencies; booleans stay boolean, `category` dtypes keep their categories.
+- **Datetime and timedelta columns** are modelled as nanoseconds, converted back to the
+  original dtype (time zone included) and rounded to the finest resolution seen in the
+  column (days stay days, seconds stay seconds).
+- **Missing values** are reinjected per column at the rate seen in the input.
+- **Constant columns** and columns with a single category are copied as-is.
+- **High-cardinality text** (more than 50% unique strings, for example names or free
+  text) cannot be modelled by frequency: those columns are sampled with replacement
+  from the original values and flagged with a `UserWarning`. Raise `text_threshold` to
+  model them as categories instead.
+- Output columns and dtypes match the input; `n` can be larger than the input.
+- Paths are accepted wherever a DataFrame is: `.csv`, `.tsv` and `.parquet`
+  (`pip install synthetic-tabular[parquet]`). CSV columns whose every value is an
+  ISO-8601 date (`2024-03-31`, `2024-03-31 10:15:00`) are parsed as datetimes so they
+  are modelled as dates rather than treated as text.
+- Deterministic: the same `random_state` always gives the same rows.
+- Ships an `evaluate()` fidelity check: per-column KS statistic (numeric) or total
+  variation distance (categorical), correlation-matrix difference and a 0-100 score.
+
+Limits worth knowing: a Gaussian copula captures monotone dependence between columns,
+not arbitrary non-linear or multi-modal joint structure, and it is not a privacy
+guarantee. Text columns that are resampled contain original values verbatim.
+
+## API
+
+```python
+synthetic_tabular.generate(df, n=None, *, random_state=0, preserve=("marginals", "correlations")) -> DataFrame
+```
+One-liner for the common case. `df` is a DataFrame or a path to a `.csv` / `.parquet`
+file; `n` defaults to `len(df)`. `preserve` chooses what to keep: drop
+`"correlations"` to sample columns independently, drop `"marginals"` to replace the
+empirical numeric distributions with a smooth fitted normal (clipped to the observed range).
+
+```python
+synthesizer = synthetic_tabular.Synthesizer(random_state=0, *, preserve=..., text_threshold=0.5)
+synthesizer.fit(df)                               # returns self
+synthesizer.sample(n=None, *, random_state=None)  # DataFrame; same rows on repeat, new seed for a new batch
+synthesizer.summary()                             # text: what was learned per column
+synthesizer.to_dict()                             # JSON-safe version of the above
+```
+After `fit`: `columns_`, `column_kinds_` (`numeric`, `datetime`, `timedelta`,
+`categorical`, `bool`, `text`, `constant`), `high_cardinality_columns_`,
+`correlation_` (DataFrame of the fitted normal-score correlations) and `n_rows_`.
+
+```python
+synthetic_tabular.evaluate(real, synthetic) -> FidelityReport
+```
+`FidelityReport` fields: `score` (0-100), `marginal_score`, `correlation_score`,
+`correlation_mad` (mean absolute difference of the Spearman correlation matrices,
+`None` with fewer than two non-constant columns), `columns` (dict of
+`ColumnFidelity`: `name`, `kind`, `metric` `"ks"`/`"tvd"`, `value`, `score`,
+`missing_rate_real`, `missing_rate_synthetic`), `n_real`, `n_synthetic`,
+`missing_columns`. Methods: `summary()` (text) and `to_dict()` (JSON-safe).
+
+## CLI
+
+```
+synthetic-tabular data.csv                          # generate a synthetic copy and print the fidelity report
+synthetic-tabular data.csv --n 1000 -o synth.csv    # write 1000 synthetic rows (csv, tsv or parquet)
+synthetic-tabular data.csv --evaluate synth.csv     # score an existing synthetic file
+synthetic-tabular data.csv --json                   # report as JSON
+synthetic-tabular --help
+```
+Options: `--random-state SEED`, `--no-correlations` (marginals only), `--quiet`.
+Flagged text columns are reported on stderr as `note:` lines.
+
+## License
+
+MIT

synthetic_tabular-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "synthetic-tabular"
+version = "0.1.0"
+description = "Generate realistic synthetic tabular data that preserves distributions and correlations, without a GPU"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Pranay Mahendrakar" }]
+keywords = [
+  "synthetic data",
+  "tabular data",
+  "gaussian copula",
+  "pandas",
+  "data augmentation",
+  "test data",
+  "privacy",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Operating System :: OS Independent",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "pandas>=1.5",
+  "numpy>=1.23",
+  "scipy>=1.9",
+]
+
+[project.optional-dependencies]
+# heavy or niche deps go here, never in `dependencies`
+parquet = ["pyarrow>=12"]
+dev = ["pytest>=7", "pyarrow>=12"]
+
+[project.scripts]
+synthetic-tabular = "synthetic_tabular.cli:main"
+
+[project.urls]
+Homepage = "https://pypi.org/project/synthetic-tabular/"
+Author = "https://pypi.org/user/pranaymahendrakar/"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/synthetic_tabular"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

synthetic_tabular-0.1.0/src/synthetic_tabular/__init__.py

@@ -0,0 +1,18 @@
+"""synthetic-tabular: realistic synthetic tabular data from a pandas DataFrame.
+
+A Gaussian copula learns each column's distribution and the correlations between
+columns, then samples new rows that look like the original without copying it.
+"""
+from .evaluate import ColumnFidelity, FidelityReport, evaluate
+from .synthesizer import Synthesizer, generate
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Synthesizer",
+    "generate",
+    "evaluate",
+    "FidelityReport",
+    "ColumnFidelity",
+    "__version__",
+]

synthetic_tabular-0.1.0/src/synthetic_tabular/_columns.py

@@ -0,0 +1,311 @@
+"""Per-column marginal models used by the Gaussian copula.
+
+Each model knows how to turn its column into standard-normal scores for fitting
+(``scores``) and how to turn uniform draws back into values (``inverse``), or, for
+columns that stay outside the copula, how to draw values directly (``resample``).
+"""
+from __future__ import annotations
+
+from typing import Any, List, Optional, Tuple
+
+import numpy as np
+import pandas as pd
+from pandas.api import types as ptypes
+from scipy import stats
+
+# Candidate time resolutions, coarsest first, in nanoseconds.
+_TIME_STEPS_NS: Tuple[Tuple[str, int], ...] = (
+    ("day", 86_400_000_000_000),
+    ("hour", 3_600_000_000_000),
+    ("minute", 60_000_000_000),
+    ("second", 1_000_000_000),
+    ("millisecond", 1_000_000),
+    ("microsecond", 1_000),
+    ("nanosecond", 1),
+)
+
+
+def temporal_int64(series: pd.Series) -> Tuple[np.ndarray, np.ndarray]:
+    """Datetime/timedelta values as int64 nanoseconds (UTC when tz-aware) plus a validity mask."""
+    dtype = series.dtype
+    if ptypes.is_datetime64_any_dtype(dtype):
+        if getattr(dtype, "tz", None) is not None:
+            series = series.dt.tz_convert("UTC").dt.tz_localize(None)
+        values = series.to_numpy(dtype="datetime64[ns]")
+    else:
+        values = series.to_numpy(dtype="timedelta64[ns]")
+    return values.astype("int64"), ~np.isnat(values)
+
+
+def to_float_array(series: pd.Series) -> np.ndarray:
+    """Numeric, boolean, datetime or timedelta values as float64 with NaN where missing."""
+    dtype = series.dtype
+    if ptypes.is_datetime64_any_dtype(dtype) or ptypes.is_timedelta64_dtype(dtype):
+        raw, valid = temporal_int64(series)
+        out = raw.astype("float64")
+        out[~valid] = np.nan
+        return out
+    return series.to_numpy(dtype="float64", na_value=np.nan)
+
+
+def normal_scores(x: np.ndarray) -> np.ndarray:
+    """Rank-transform the finite entries of ``x`` to standard-normal scores (NaN stays NaN)."""
+    z = np.full(x.shape, np.nan)
+    mask = np.isfinite(x)
+    m = int(mask.sum())
+    if m:
+        ranks = stats.rankdata(x[mask], method="average")
+        z[mask] = stats.norm.ppf(ranks / (m + 1.0))
+    return z
+
+
+def infer_decimals(values: np.ndarray, max_decimals: int = 6) -> Optional[int]:
+    """Fewest decimals that reproduce every value, or None when more than ``max_decimals`` are needed."""
+    if len(values) == 0:
+        return None
+    tolerance = 1e-9 * np.maximum(1.0, np.abs(values))
+    for decimals in range(max_decimals + 1):
+        if np.all(np.abs(np.round(values, decimals) - values) <= tolerance):
+            return decimals
+    return None
+
+
+def infer_time_step(relative_ns: np.ndarray) -> Tuple[str, int]:
+    """Coarsest resolution (name, nanoseconds) that every value is a whole multiple of."""
+    for name, step in _TIME_STEPS_NS:
+        if step == 1 or not np.any(relative_ns % step):
+            return name, step
+    return "nanosecond", 1
+
+
+class ColumnModel:
+    """Base class holding a column's name, original dtype and missing rate."""
+
+    kind: str = "column"
+    modeled: bool = False  # True when the column takes part in the copula
+
+    def __init__(self, name: Any, series: pd.Series) -> None:
+        self.name = name
+        self.dtype = series.dtype
+        self.missing_rate = float(series.isna().mean()) if len(series) else 0.0
+        self.scores: Optional[np.ndarray] = None
+
+    def describe(self) -> str:
+        """One-line human description of what was learned."""
+        return self.kind
+
+
+class NumericColumn(ColumnModel):
+    """Numeric column: empirical quantile marginal (or a fitted normal when ``smooth``)."""
+
+    kind = "numeric"
+    modeled = True
+
+    def __init__(self, name: Any, series: pd.Series, *, smooth: bool = False) -> None:
+        super().__init__(name, series)
+        self.smooth = smooth
+        x = self._encode(series)
+        observed = x[np.isfinite(x)]
+        self.sorted_values = np.sort(observed)
+        self.vmin = float(self.sorted_values[0])
+        self.vmax = float(self.sorted_values[-1])
+        self.mean = float(observed.mean())
+        self.std = float(observed.std()) or 1.0
+        self.n_unique = int(len(np.unique(observed)))
+        self.decimals: Optional[int] = self._infer_decimals(observed)
+        self.scores = normal_scores(x)
+
+    def _encode(self, series: pd.Series) -> np.ndarray:
+        return series.to_numpy(dtype="float64", na_value=np.nan)
+
+    def _infer_decimals(self, observed: np.ndarray) -> Optional[int]:
+        if ptypes.is_integer_dtype(self.dtype):
+            return 0
+        return infer_decimals(observed)
+
+    def inverse(self, u: np.ndarray) -> Any:
+        """Map uniform draws in (0, 1) back to column values."""
+        if self.smooth:
+            values = self.mean + self.std * stats.norm.ppf(u)
+        else:
+            m = len(self.sorted_values)
+            values = np.interp(u * (m - 1), np.arange(m), self.sorted_values)
+        return self._decode(np.clip(values, self.vmin, self.vmax))
+
+    def _decode(self, values: np.ndarray) -> Any:
+        if self.decimals is not None:
+            values = np.round(values, self.decimals)
+        return np.clip(values, self.vmin, self.vmax)
+
+    def describe(self) -> str:
+        if self.decimals == 0:
+            shape = "integer"
+        elif self.decimals is None:
+            shape = "float"
+        else:
+            shape = f"{self.decimals} decimals"
+        return f"{shape}, {self.n_unique} unique, range {self.vmin:g} to {self.vmax:g}"
+
+
+class TemporalColumn(NumericColumn):
+    """Datetime or timedelta column, modelled as nanoseconds since its earliest value."""
+
+    def __init__(self, name: Any, series: pd.Series, *, smooth: bool = False) -> None:
+        self.kind = "datetime" if ptypes.is_datetime64_any_dtype(series.dtype) else "timedelta"
+        self.tz = getattr(series.dtype, "tz", None)
+        super().__init__(name, series, smooth=smooth)
+        decoded = self._decode(np.array([self.vmin, self.vmax]))
+        self.first = decoded.iloc[0]
+        self.last = decoded.iloc[1]
+
+    def _encode(self, series: pd.Series) -> np.ndarray:
+        raw, valid = temporal_int64(series)
+        self.offset = int(raw[valid].min()) if valid.any() else 0
+        relative = raw - self.offset
+        self.step_name, self.step = infer_time_step(relative[valid])
+        out = relative.astype("float64")
+        out[~valid] = np.nan
+        return out
+
+    def _infer_decimals(self, observed: np.ndarray) -> Optional[int]:
+        return None
+
+    def _decode(self, values: np.ndarray) -> pd.Series:
+        ticks = np.rint(values / self.step).astype("int64") * self.step + self.offset
+        if self.kind == "timedelta":
+            return pd.Series(pd.to_timedelta(ticks, unit="ns"))
+        index = pd.to_datetime(ticks, unit="ns")
+        if self.tz is not None:
+            index = index.tz_localize("UTC").tz_convert(self.tz)
+        return pd.Series(index)
+
+    def describe(self) -> str:
+        return (
+            f"{self.step_name} resolution, {self.n_unique} unique, "
+            f"range {self.first} to {self.last}"
+        )
+
+
+class CategoricalColumn(ColumnModel):
+    """Categorical or boolean column: categories ordered by frequency, sampled by thresholds."""
+
+    modeled = True
+
+    def __init__(self, name: Any, series: pd.Series, *, kind: str = "categorical") -> None:
+        super().__init__(name, series)
+        self.kind = kind
+        present = ~series.isna().to_numpy()
+        non_null = series[present]
+        counts = non_null.value_counts(sort=False)
+        counts = counts[counts > 0]
+        order = np.lexsort((np.arange(len(counts)), -counts.to_numpy(dtype="int64")))
+        self.categories: List[Any] = [counts.index[i] for i in order]
+        probabilities = counts.to_numpy(dtype="float64")[order]
+        self.probabilities = probabilities / probabilities.sum()
+        self.cumulative = np.cumsum(self.probabilities)
+        self.cumulative[-1] = 1.0
+        self._values = np.empty(len(self.categories), dtype=object)
+        for i, category in enumerate(self.categories):
+            self._values[i] = category
+        codes = pd.Categorical(non_null, categories=self.categories).codes
+        x = np.full(len(series), np.nan)
+        x[present] = codes
+        self.scores = normal_scores(x)
+
+    def inverse(self, u: np.ndarray) -> np.ndarray:
+        """Map uniform draws in (0, 1) to categories via cumulative frequency thresholds."""
+        idx = np.searchsorted(self.cumulative, u, side="right")
+        idx = np.minimum(idx, len(self.categories) - 1)
+        values = self._values[idx]
+        if self.kind == "bool":
+            return values.astype(bool)
+        return values
+
+    def describe(self) -> str:
+        top = self.categories[0]
+        if isinstance(top, np.generic):  # plain Python repr, not np.True_ / np.int64(3)
+            top = top.item()
+        return (
+            f"{len(self.categories)} categories, most common {top!r} "
+            f"({self.probabilities[0]:.0%})"
+        )
+
+
+class TextColumn(ColumnModel):
+    """High-cardinality text column: values are resampled with replacement from the originals."""
+
+    kind = "text"
+
+    def __init__(self, name: Any, series: pd.Series, *, unique_ratio: float) -> None:
+        super().__init__(name, series)
+        self.values = series.dropna().to_numpy(dtype=object)
+        self.unique_ratio = float(unique_ratio)
+
+    def resample(self, n: int, rng: np.random.Generator) -> Any:
+        if len(self.values) == 0:
+            return pd.Series([None] * n, dtype=object)
+        return self.values[rng.integers(0, len(self.values), size=n)]
+
+    def describe(self) -> str:
+        ratio = "unhashable values" if np.isnan(self.unique_ratio) else f"{self.unique_ratio:.0%} unique"
+        return f"{ratio}, resampled from the {len(self.values)} original values"
+
+
+class ConstantColumn(ColumnModel):
+    """Column with at most one distinct value (possibly all missing)."""
+
+    kind = "constant"
+
+    def __init__(self, name: Any, series: pd.Series, *, value: Any = None) -> None:
+        super().__init__(name, series)
+        self.value = value
+
+    def resample(self, n: int, rng: np.random.Generator) -> pd.Series:
+        return pd.Series([self.value] * n, dtype=object)
+
+    def describe(self) -> str:
+        return "all missing" if self.value is None else f"constant {self.value!r}"
+
+
+def build_column_model(
+    name: Any, series: pd.Series, *, smooth: bool = False, text_threshold: float = 0.5
+) -> ColumnModel:
+    """Pick and fit the right model for one column."""
+    dtype = series.dtype
+    non_null = series.dropna()
+    if ptypes.is_bool_dtype(dtype):
+        kind = "bool"
+    elif ptypes.is_datetime64_any_dtype(dtype) or ptypes.is_timedelta64_dtype(dtype):
+        kind = "temporal"
+    elif ptypes.is_numeric_dtype(dtype):
+        kind = "numeric"
+    elif isinstance(dtype, pd.CategoricalDtype):
+        kind = "categorical"
+    else:
+        kind = "categorical"
+        try:
+            n_unique = int(non_null.nunique())
+        except TypeError:  # unhashable values such as lists: only resampling makes sense
+            return TextColumn(name, series, unique_ratio=float("nan"))
+        if n_unique > 1 and ptypes.infer_dtype(non_null, skipna=True) == "string":
+            ratio = n_unique / len(non_null)
+            if ratio > text_threshold:
+                return TextColumn(name, series, unique_ratio=ratio)
+
+    if kind == "numeric":
+        values = to_float_array(series)
+        finite = values[np.isfinite(values)]
+        if len(np.unique(finite)) <= 1:
+            if len(finite):
+                value: Any = finite[0]
+            else:
+                value = non_null.iloc[0] if len(non_null) else None
+            return ConstantColumn(name, series, value=value)
+        return NumericColumn(name, series, smooth=smooth)
+
+    if non_null.nunique() <= 1:
+        value = non_null.iloc[0] if len(non_null) else None
+        return ConstantColumn(name, series, value=value)
+    if kind == "temporal":
+        return TemporalColumn(name, series, smooth=smooth)
+    return CategoricalColumn(name, series, kind=kind)