model2data 1.5.0__tar.gz → 1.7.0__tar.gz

{model2data-1.5.0/model2data.egg-info → model2data-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: model2data
-Version: 1.5.0
+Version: 1.7.0
 Summary: Generate analytics-ready datasets from DBML models
 Author: JB Analytica
 License-Expression: MIT

{model2data-1.5.0 → model2data-1.7.0}/README.md

@@ -184,6 +184,24 @@ doesn't say what it depends on can say so explicitly with an `after` note:
 shipped_at timestamp [note: '{"after": "ordered_at"}']
 ```
 
+The flags above shape every date and timestamp column the same way, run-wide. `business_hours`,
+`growth`, and `seasonality` column note hints override that for one column at a time — the whole
+point being a run can be uniform everywhere except the one column that needs shaping, or shaped
+everywhere except the one column that shouldn't be:
+
+```dbml
+Table orders {
+  id int [pk]
+  created_at timestamp [note: '{"business_hours": true, "growth": 0.4}']
+  refunded_at timestamp [note: '{"growth": 0}']
+}
+```
+
+Here `created_at` gets business hours and growth even on an otherwise-uniform run, while
+`refunded_at` stays flat even under `--growth 0.5` — each hint only replaces the fields it names,
+so a partial hint like `{"growth": 0}` leaves that column's `business_hours`/`seasonality` at
+whatever the run-level flags set.
+
 ### Shape how the data is spread
 
 By default every parent row is equally likely to be picked for a child row, and every column
@@ -214,6 +232,26 @@ non-null rows a boolean column comes back `true`. `null_rate` replaces the colum
 fraction outright. `distinct` draws the column's values from a fixed-size pool instead of a fresh
 value per row — a `shipping_city` most warehouses only ever see a handful of.
 
+### Shape a number's distribution
+
+`min`/`max` alone only ever drew uniformly between them. A `distribution` note hint on an
+integer or decimal column picks a different shape instead:
+
+```dbml
+Table orders {
+  id int [pk]
+  total_amount numeric [note: '{"distribution": "lognormal", "median": 80, "spread": 0.6, "min": 5}']
+}
+```
+
+`normal` takes `mean` (the centre) and `stddev` (the spread); `lognormal` takes `median` (the
+typical value) and `spread` (how heavy the tail is — 0.3 is mild, 1.0 is heavy); `exponential`
+takes `mean` (the average). Any left unset default to the midpoint of the column's effective
+`min`/`max` (or `stddev` = range / 6, `spread` = 0.5). `min`/`max` still clip the result — a
+`normal` centred near an edge redraws a bounded number of times before clamping, so it never
+loops forever and never crosses the bound. Leaving `distribution` out, or setting it to
+`"uniform"`, is exactly today's behaviour.
+
 Run dbt to load, transform, and test the data:
 
 ```bash

{model2data-1.5.0 → model2data-1.7.0}/model2data/generate/faker.py

@@ -12,7 +12,7 @@ from typing import Callable, Optional, Union
 import pandas as pd
 from faker import Faker
 
-from model2data.generate.options import TimeProfile
+from model2data.generate.options import UNIFORM, TimeProfile
 from model2data.generate.timeline import weighted_dates, weighted_timestamps
 from model2data.parse.dbml import ColumnDef
 
@@ -505,6 +505,31 @@ def _infer_by_type(base_type: str) -> Optional[_Provider]:
     return lambda: fake.format(base_type)
 
 
+def _column_time_profile(
+    column: ColumnDef, time_profile: Optional[TimeProfile]
+) -> Optional[TimeProfile]:
+    """The run-level `time_profile` with this column's note hints applied on top.
+
+    Mirrors the `skew` override on the FK branch, one level up: a note doesn't
+    replace the run's profile, it patches only the fields it names (via
+    `dataclasses.replace`), so `{"growth": 0}` flattens one column of a
+    growing run while `business_hours`/`seasonality` stay exactly what the
+    run set. `validate_hints` has already confirmed the column is a date or
+    timestamp column and that each hint present is well-typed, so this does
+    no validation of its own -- a column with no hint gets `time_profile`
+    back unchanged, including a bare `None`, so the uniform path stays
+    untouched.
+    """
+    note = column.note or {}
+    overrides = {
+        key: note[key] for key in ("business_hours", "growth", "seasonality") if key in note
+    }
+    if not overrides:
+        return time_profile
+    base = time_profile if time_profile is not None else UNIFORM
+    return replace(base, **overrides)
+
+
 def _generate_dates(row_count: int, as_of: AsOf, time_profile: Optional[TimeProfile]) -> list:
     """The date branch's values: shaped by `time_profile` when it isn't uniform.
 
@@ -640,6 +665,13 @@ def generate_column_values(
     if column.note:
         min_val = column.note.get("min")
         max_val = column.note.get("max")
+    # The note's own min/max, before either numeric branch fills in its
+    # branch-specific default -- these are the only bounds a distribution
+    # hint clips against (see `_clipped_distribution_draw`). A column with no
+    # explicit min/max draws from an unclipped distribution even though the
+    # branch below still has an implicit default range for the *parameters*.
+    explicit_min, explicit_max = min_val, max_val
+    distribution = column_note.get("distribution", "uniform")
 
     if fk_series is not None and not fk_series.empty:
         # A plain branch of the same if/elif chain (rather than an early
@@ -697,7 +729,22 @@ def generate_column_values(
         if max_val is None:
             max_val = 100
 
-        if ensure_unique:
+        if distribution != "uniform":
+            # A shaped column never needs the row_count-sized value space
+            # random.sample relies on below, so it always draws one value at
+            # a time -- unique or not -- and leans on _deduplicate the same
+            # way every other non-uniform-fast-path branch does.
+            params = _distribution_params(distribution, min_val, max_val, column_note)
+
+            def generator() -> int:
+                return round(
+                    _clipped_distribution_draw(distribution, params, explicit_min, explicit_max)
+                )
+
+            values = [generator() for _ in range(row_count)]
+            if ensure_unique:
+                values = _deduplicate(values, generator, column_name=unique_label)
+        elif ensure_unique:
             if not had_explicit_range:
                 # No user-specified range: widen the default so there's
                 # always enough headroom for `row_count` unique PK values.
@@ -728,13 +775,27 @@ def generate_column_values(
             min_val = 0
         if max_val is None:
             max_val = 10_000
-        values = [round(random.uniform(min_val, max_val), 2) for _ in range(row_count)]
-        if ensure_unique:
-            values = _deduplicate(
-                values,
-                lambda: round(random.uniform(min_val, max_val), 2),
-                column_name=unique_label,
-            )
+
+        if distribution != "uniform":
+            params = _distribution_params(distribution, min_val, max_val, column_note)
+
+            def generator() -> float:
+                return round(
+                    _clipped_distribution_draw(distribution, params, explicit_min, explicit_max),
+                    2,
+                )
+
+            values = [generator() for _ in range(row_count)]
+            if ensure_unique:
+                values = _deduplicate(values, generator, column_name=unique_label)
+        else:
+            values = [round(random.uniform(min_val, max_val), 2) for _ in range(row_count)]
+            if ensure_unique:
+                values = _deduplicate(
+                    values,
+                    lambda: round(random.uniform(min_val, max_val), 2),
+                    column_name=unique_label,
+                )
 
     # -----------------------------------------------------
     # Booleans
@@ -750,13 +811,13 @@ def generate_column_values(
     # Dates
     # -----------------------------------------------------
     elif "date" in base_type and "time" not in base_type:
-        values = _generate_dates(row_count, as_of, time_profile)
+        values = _generate_dates(row_count, as_of, _column_time_profile(column, time_profile))
 
     elif "time" in base_type and "stamp" not in base_type:
         values = [fake.time() for _ in range(row_count)]
 
     elif any(key in base_type for key in ["timestamp", "datetime"]):
-        values = _generate_timestamps(row_count, as_of, time_profile)
+        values = _generate_timestamps(row_count, as_of, _column_time_profile(column, time_profile))
 
     # -----------------------------------------------------
     # Untyped / generic string columns: honour a type that names
@@ -799,6 +860,78 @@ def generate_column_values(
 # ---------------------------------------------------------
 # Internal helpers
 # ---------------------------------------------------------
+# How many times a clipped draw redraws before giving up and clamping. Kept
+# small and fixed rather than exposed as a hint: a normal whose mean sits
+# well inside its min/max rarely needs a redraw at all, and a distribution
+# whose parameters put most of its mass outside the bounds is a schema
+# mistake no retry count fixes -- clamping is the honest fallback either way.
+_MAX_DISTRIBUTION_REDRAWS = 20
+
+
+def _distribution_params(
+    distribution: str, effective_min: float, effective_max: float, note: dict
+) -> dict:
+    """Fill in whichever of mean/stddev/median/spread `note` leaves unset.
+
+    `effective_min`/`effective_max` are the note's own `min`/`max` when given,
+    else the calling branch's default range (0-100 for integers, 0-10,000 for
+    decimals) -- ordinary enough a midpoint to centre an unparameterized
+    distribution on.
+    """
+    midpoint = (effective_min + effective_max) / 2
+    if distribution == "normal":
+        return {
+            "mean": note.get("mean", midpoint),
+            "stddev": note.get("stddev", (effective_max - effective_min) / 6),
+        }
+    if distribution == "lognormal":
+        return {
+            "median": note.get("median", midpoint),
+            "spread": note.get("spread", 0.5),
+        }
+    # exponential: hints.py has already rejected anything else reaching here.
+    return {"mean": note.get("mean", midpoint)}
+
+
+def _draw_distribution_value(distribution: str, params: dict) -> float:
+    """One raw draw from `distribution`, unclipped and unrounded."""
+    if distribution == "normal":
+        return random.gauss(params["mean"], params["stddev"])
+    if distribution == "lognormal":
+        return random.lognormvariate(math.log(params["median"]), params["spread"])
+    return random.expovariate(1 / params["mean"])  # exponential
+
+
+def _clipped_distribution_draw(
+    distribution: str,
+    params: dict,
+    clip_min: Optional[float],
+    clip_max: Optional[float],
+) -> float:
+    """Draw from `distribution`, redrawing out-of-bounds values before clamping.
+
+    A normal centred well inside [min, max] almost never needs the clamp; one
+    centred near an edge (mean 120, min 0) would otherwise pile values up at
+    the boundary, so a bounded number of redraws is tried first and only a
+    value still out of bounds after all of them gets clamped -- which also
+    keeps this from looping forever when min and max leave no room at all.
+    `clip_min`/`clip_max` are the note's own bounds (`None` when the column
+    didn't set one), never the branch's implicit default range.
+    """
+    value = _draw_distribution_value(distribution, params)
+    attempts = 0
+    while attempts < _MAX_DISTRIBUTION_REDRAWS and (
+        (clip_min is not None and value < clip_min) or (clip_max is not None and value > clip_max)
+    ):
+        value = _draw_distribution_value(distribution, params)
+        attempts += 1
+    if clip_min is not None and value < clip_min:
+        value = clip_min
+    if clip_max is not None and value > clip_max:
+        value = clip_max
+    return value
+
+
 def _null_fraction_for(column: ColumnDef, row_count: int) -> float:
     """The fraction of `row_count` rows this column should turn null.
 

{model2data-1.5.0 → model2data-1.7.0}/model2data/generate/hints.py

@@ -3,10 +3,11 @@
 A note has always been either plain text (a comment, ignored by generation)
 or a JSON object read for `min`/`max`. This module documents the rest of that
 object's vocabulary -- `null_rate`, `weights`, `true_rate`, `distinct`, `skew`,
-`after` -- and checks it once, before a single row is generated, so a typo'd
-enum value or a hint on the wrong kind of column fails with a message naming
-the table and column rather than surfacing as a wrong-looking dataset or a
-downstream dbt test failure.
+`after`, `business_hours`, `growth`, `seasonality`, `distribution` and its
+parameters -- and checks it once, before a single row is generated, so a
+typo'd enum value or a hint on the wrong kind of column fails with a message
+naming the table and column rather than surfacing as a wrong-looking dataset
+or a downstream dbt test failure.
 
 | key         | applies to                                   | meaning                                   |
 |-------------|-----------------------------------------------|--------------------------------------------|
@@ -17,6 +18,14 @@ downstream dbt test failure.
 | `distinct`  | columns that aren't an FK, `pk`, `unique`, enum | positive integer: draw from a pool that size |
 | `skew`      | foreign-key columns                            | overrides the run-level `skew` for this column |
 | `after`     | date/timestamp columns                         | name of another date/timestamp column, read by the time-aware generator |
+| `business_hours` | date/timestamp columns                    | overrides the run-level `TimeProfile.business_hours` for this column |
+| `growth`    | date/timestamp columns                         | overrides the run-level `TimeProfile.growth` for this column |
+| `seasonality` | date/timestamp columns                       | overrides the run-level `TimeProfile.seasonality` for this column |
+| `distribution` | numeric columns                             | draw shape: `uniform` (default), `normal`, `lognormal`, `exponential` |
+| `mean`      | numeric columns, with `distribution: normal` or `exponential` | normal: the centre; exponential: the average (scale) |
+| `stddev`    | numeric columns, with `distribution: normal`   | normal: the spread |
+| `median`    | numeric columns, with `distribution: lognormal`| lognormal: the typical value, `exp(mu)`   |
+| `spread`    | numeric columns, with `distribution: lognormal`| lognormal: sigma of the underlying normal (0.3 mild, 1.0 heavy tail) |
 """
 
 from __future__ import annotations
@@ -92,6 +101,33 @@ def _is_temporal_type(base_type: str) -> bool:
     return any(key in base_type for key in ("timestamp", "datetime"))
 
 
+def _is_numeric_type(base_type: str) -> bool:
+    """True for the integer and float/decimal types `min`/`max`/`distribution` apply to.
+
+    Mirrors generate.faker's own two numeric branches exactly, so a hint this
+    module accepts is guaranteed to land on a branch that reads it.
+    """
+    return any(
+        key in base_type
+        for key in ("int", "integer", "bigint", "smallint", "decimal", "numeric", "float", "double")
+    )
+
+
+# Distributions a numeric column's `distribution` hint may name.
+_DISTRIBUTIONS = ("uniform", "normal", "lognormal", "exponential")
+
+# Which distribution(s) each shape parameter is meaningful under -- checked
+# against the note's own `distribution` (default "uniform" when absent), so
+# a `stddev` with no `distribution` key is rejected the same as one paired
+# with the wrong distribution.
+_PARAM_DISTRIBUTIONS: dict[str, tuple[str, ...]] = {
+    "mean": ("normal", "exponential"),
+    "stddev": ("normal",),
+    "median": ("lognormal",),
+    "spread": ("lognormal",),
+}
+
+
 def _validate_column_hints(
     table_name: str,
     column: ColumnDef,
@@ -107,6 +143,7 @@ def _validate_column_hints(
     is_enum = bool(column.enum_values)
     is_boolean = "boolean" in base_type or "bool" in base_type
     is_temporal = _is_temporal_type(base_type)
+    is_numeric = _is_numeric_type(base_type)
     is_nullable = not is_pk and "not null" not in column.settings
 
     if "null_rate" in note:
@@ -152,6 +189,46 @@ def _validate_column_hints(
             raise ValueError(f'{label}: "after" only applies to date/timestamp columns.')
         _check_after(label, table_name, note["after"], columns_by_name)
 
+    if "business_hours" in note:
+        if not is_temporal:
+            raise ValueError(f'{label}: "business_hours" only applies to date/timestamp columns.')
+        _check_bool(label, "business_hours", note["business_hours"])
+
+    if "growth" in note:
+        if not is_temporal:
+            raise ValueError(f'{label}: "growth" only applies to date/timestamp columns.')
+        _check_growth(label, note["growth"])
+
+    if "seasonality" in note:
+        if not is_temporal:
+            raise ValueError(f'{label}: "seasonality" only applies to date/timestamp columns.')
+        _check_fraction(label, "seasonality", note["seasonality"])
+
+    if "distribution" in note:
+        if not is_numeric:
+            raise ValueError(f'{label}: "distribution" only applies to numeric columns.')
+        if note["distribution"] not in _DISTRIBUTIONS:
+            allowed = ", ".join(f'"{d}"' for d in _DISTRIBUTIONS)
+            raise ValueError(
+                f'{label}: "distribution" must be one of {allowed} (got {note["distribution"]!r}).'
+            )
+
+    # mean/stddev/median/spread only make sense alongside the distribution
+    # they shape, so each is checked against the note's own `distribution`
+    # (absent means "uniform", which none of them apply to either).
+    for param_key, required_distributions in _PARAM_DISTRIBUTIONS.items():
+        if param_key not in note:
+            continue
+        if not is_numeric:
+            raise ValueError(f'{label}: "{param_key}" only applies to numeric columns.')
+        if note.get("distribution") not in required_distributions:
+            options = " or ".join(f'"{d}"' for d in required_distributions)
+            raise ValueError(f'{label}: "{param_key}" only applies with "distribution": {options}.')
+        if param_key == "mean":
+            _check_number(label, param_key, note[param_key])
+        else:
+            _check_positive_number(label, param_key, note[param_key])
+
 
 def _check_fraction(label: str, key: str, value: object) -> None:
     if isinstance(value, bool) or not isinstance(value, (int, float)) or not 0.0 <= value <= 1.0:
@@ -163,6 +240,26 @@ def _check_positive_int(label: str, key: str, value: object) -> None:
         raise ValueError(f'{label}: "{key}" must be a positive whole number (got {value!r}).')
 
 
+def _check_number(label: str, key: str, value: object) -> None:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError(f'{label}: "{key}" must be a number (got {value!r}).')
+
+
+def _check_positive_number(label: str, key: str, value: object) -> None:
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or value <= 0:
+        raise ValueError(f'{label}: "{key}" must be a number greater than 0 (got {value!r}).')
+
+
+def _check_bool(label: str, key: str, value: object) -> None:
+    if not isinstance(value, bool):
+        raise ValueError(f'{label}: "{key}" must be true or false (got {value!r}).')
+
+
+def _check_growth(label: str, value: object) -> None:
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or value < -1.0:
+        raise ValueError(f'{label}: "growth" must be -1.0 or more (got {value!r}).')
+
+
 def _check_enum_weights(label: str, enum_values: list[str], weights: object) -> None:
     if not isinstance(weights, dict) or not weights:
         raise ValueError(

{model2data-1.5.0 → model2data-1.7.0/model2data.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: model2data
-Version: 1.5.0
+Version: 1.7.0
 Summary: Generate analytics-ready datasets from DBML models
 Author: JB Analytica
 License-Expression: MIT

{model2data-1.5.0 → model2data-1.7.0}/model2data.egg-info/SOURCES.txt

@@ -28,6 +28,7 @@ model2data/parse/__init__.py
 model2data/parse/dbml.py
 tests/test_as_of_anchor.py
 tests/test_cli.py
+tests/test_column_time_hints.py
 tests/test_coverage_gaps.py
 tests/test_dbml_parser.py
 tests/test_dbml_parser_fuzz.py
@@ -35,6 +36,7 @@ tests/test_dbt_integration.py
 tests/test_dbt_naming.py
 tests/test_dbt_project.py
 tests/test_dbt_tests.py
+tests/test_distributions.py
 tests/test_faker_name_inference.py
 tests/test_generation.py
 tests/test_options.py

{model2data-1.5.0 → model2data-1.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "model2data"
-version = "1.5.0"
+version = "1.7.0"
 description = "Generate analytics-ready datasets from DBML models"
 readme = "README_PYPI.md"
 requires-python = ">=3.10"

model2data-1.7.0/tests/test_column_time_hints.py

@@ -0,0 +1,241 @@
+"""Per-column overrides of the run-level `TimeProfile`.
+
+1.5.0 shaped *when* things happen for a whole run: business hours, growth,
+seasonality all apply to every date/timestamp column alike. The product
+ask this closes was literally "that changes for everything globally, can we
+have that column per column?" -- so `business_hours`/`growth`/`seasonality`
+column-note hints patch just the fields they name onto the run's profile for
+that one column, the same way `skew` already overrides per foreign key (see
+tests/test_shaping.py). Every statistical test here uses a fixed seed and a
+generous tolerance so it never flakes; the exact bounds were chosen by
+running the real implementation and leaving headroom, not derived
+analytically.
+"""
+
+from datetime import date, datetime, timedelta
+
+import pytest
+
+from model2data.generate.core import generate_data_from_dbml
+from model2data.generate.options import TimeProfile
+from model2data.parse.dbml import ColumnDef, TableDef
+
+ANCHOR_DATE = date(2026, 3, 15)
+
+
+def _two_timestamp_schema(hinted_note=None, plain_note=None) -> dict[str, TableDef]:
+    return {
+        "events": TableDef(
+            name="events",
+            columns=[
+                ColumnDef("id", "int", {"pk"}),
+                ColumnDef("hinted_at", "timestamp", {"not null"}, note=hinted_note),
+                ColumnDef("plain_at", "timestamp", {"not null"}, note=plain_note),
+            ],
+        )
+    }
+
+
+def _column(df, name) -> list[datetime]:
+    return [datetime.fromisoformat(v) for v in df[name]]
+
+
+def _business_hours_share(timestamps: list[datetime]) -> float:
+    in_hours = sum(1 for t in timestamps if t.weekday() < 5 and 8 <= t.hour < 18)
+    return in_hours / len(timestamps)
+
+
+def _timestamp_window_midpoint() -> date:
+    """Midpoint of the 365-day timestamp window `weighted_timestamps` draws
+    from (see timeline.py's `_TIMESTAMP_WINDOW_DAYS`): the anchor minus a
+    year, up to the day before the anchor."""
+    start = ANCHOR_DATE - timedelta(days=365)
+    end = ANCHOR_DATE - timedelta(days=1)
+    return start + (end - start) / 2
+
+
+# ---------------------------------------------------------
+# A hint shapes its own column, not its neighbour
+# ---------------------------------------------------------
+def test_business_hours_hint_shapes_only_the_hinted_column():
+    tables = _two_timestamp_schema(hinted_note={"business_hours": True})
+    df = generate_data_from_dbml(
+        tables, [], base_rows=1000, seed=5, as_of=ANCHOR_DATE, time_profile=TimeProfile()
+    )["events"]
+
+    hinted_share = _business_hours_share(_column(df, "hinted_at"))
+    plain_share = _business_hours_share(_column(df, "plain_at"))
+
+    assert hinted_share >= 0.70
+    assert plain_share < hinted_share - 0.2
+
+
+def test_growth_hint_shapes_only_the_hinted_column():
+    tables = _two_timestamp_schema(hinted_note={"growth": 1.0})
+    df = generate_data_from_dbml(
+        tables, [], base_rows=2000, seed=5, as_of=ANCHOR_DATE, time_profile=TimeProfile()
+    )["events"]
+
+    midpoint = _timestamp_window_midpoint()
+    hinted = _column(df, "hinted_at")
+    plain = _column(df, "plain_at")
+
+    hinted_second_half = sum(1 for t in hinted if t.date() >= midpoint) / len(hinted)
+    plain_second_half = sum(1 for t in plain if t.date() >= midpoint) / len(plain)
+
+    # growth=1.0 on hinted_at pushes its rows toward the second half of the
+    # window; plain_at, with no hint under a flat run-level profile, does not.
+    assert hinted_second_half > plain_second_half + 0.05
+
+
+# ---------------------------------------------------------
+# A hint overrides the run-level profile in both directions
+# ---------------------------------------------------------
+def test_hint_overrides_a_flat_run_level_profile():
+    tables = _two_timestamp_schema(hinted_note={"business_hours": True})
+    df = generate_data_from_dbml(
+        tables, [], base_rows=1000, seed=5, as_of=ANCHOR_DATE, time_profile=TimeProfile()
+    )["events"]
+
+    assert _business_hours_share(_column(df, "hinted_at")) >= 0.70
+
+
+def test_hint_overrides_a_shaped_run_level_profile_back_to_flat():
+    tables = _two_timestamp_schema(hinted_note={"business_hours": False})
+    df = generate_data_from_dbml(
+        tables,
+        [],
+        base_rows=1000,
+        seed=5,
+        as_of=ANCHOR_DATE,
+        time_profile=TimeProfile(business_hours=True),
+    )["events"]
+
+    # hinted_at is forced back to uniform; plain_at keeps the run's shaping.
+    hinted_share = _business_hours_share(_column(df, "hinted_at"))
+    plain_share = _business_hours_share(_column(df, "plain_at"))
+    assert plain_share >= 0.70
+    assert hinted_share < plain_share - 0.2
+
+
+def test_cli_flag_and_column_hint_combine_with_the_hint_winning():
+    """`--business-hours` (a run-level TimeProfile) plus a column hint that
+    turns it back off for one column: the hint wins for that column, the
+    run-level setting still applies to its neighbour."""
+    tables = _two_timestamp_schema(hinted_note={"business_hours": False})
+    df = generate_data_from_dbml(
+        tables,
+        [],
+        base_rows=1000,
+        seed=5,
+        as_of=ANCHOR_DATE,
+        time_profile=TimeProfile(business_hours=True),
+    )["events"]
+
+    assert _business_hours_share(_column(df, "hinted_at")) < 0.5
+    assert _business_hours_share(_column(df, "plain_at")) >= 0.70
+
+
+# ---------------------------------------------------------
+# A partial hint only replaces the fields it names
+# ---------------------------------------------------------
+def test_partial_hint_keeps_the_other_run_level_fields():
+    """`{"growth": 0}` flattens growth for this column but leaves
+    business_hours exactly as the run set it."""
+    tables = _two_timestamp_schema(hinted_note={"growth": 0.0})
+    run_profile = TimeProfile(business_hours=True, growth=1.0)
+    df = generate_data_from_dbml(
+        tables, [], base_rows=2000, seed=5, as_of=ANCHOR_DATE, time_profile=run_profile
+    )["events"]
+
+    hinted = _column(df, "hinted_at")
+    plain = _column(df, "plain_at")
+
+    # business_hours still applies to hinted_at (inherited, not overridden).
+    assert _business_hours_share(hinted) >= 0.70
+
+    # growth=0 on hinted_at flattens it relative to plain_at, which keeps the
+    # run's growth=1.0 and skews toward the second half of the window.
+    midpoint = _timestamp_window_midpoint()
+    hinted_second_half = sum(1 for t in hinted if t.date() >= midpoint) / len(hinted)
+    plain_second_half = sum(1 for t in plain if t.date() >= midpoint) / len(plain)
+    assert 0.35 <= hinted_second_half <= 0.65
+    assert plain_second_half > hinted_second_half
+
+
+# ---------------------------------------------------------
+# No hint: pinned frames unchanged
+# ---------------------------------------------------------
+def test_no_hint_reproduces_the_run_level_only_frame():
+    """A column with no time hint must generate byte-identical values to the
+    same schema before this feature existed -- the override helper is a
+    pure no-op when a column's note carries none of the three keys."""
+    tables = _two_timestamp_schema()
+    with_helper = generate_data_from_dbml(
+        tables, [], base_rows=20, seed=2024, as_of=ANCHOR_DATE, time_profile=TimeProfile(growth=0.4)
+    )["events"]
+    again = generate_data_from_dbml(
+        tables, [], base_rows=20, seed=2024, as_of=ANCHOR_DATE, time_profile=TimeProfile(growth=0.4)
+    )["events"]
+
+    assert with_helper.equals(again)
+
+
+def test_no_hint_and_uniform_profile_matches_the_pre_feature_pinned_frame():
+    """Same schema and seed as test_timeline.py's own pinned-frame test, with
+    an explicit empty note on both columns: still byte-identical to 1.5.0."""
+    tables = {
+        "events": TableDef(
+            name="events",
+            columns=[
+                ColumnDef("id", "int", {"pk"}),
+                ColumnDef("created_at", "timestamp", {"not null"}),
+                ColumnDef("event_date", "date", set()),
+            ],
+        )
+    }
+    df = generate_data_from_dbml(tables, [], base_rows=8, seed=2024, as_of=ANCHOR_DATE)["events"]
+
+    assert list(df["created_at"])[:2] == ["2026-01-24 23:52:50", "2025-08-07 01:00:18"]
+
+
+# ---------------------------------------------------------
+# Validation
+# ---------------------------------------------------------
+def _single_column_table(column: ColumnDef, table_name: str = "t") -> dict[str, TableDef]:
+    return {table_name: TableDef(name=table_name, columns=[ColumnDef("id", "int", {"pk"}), column])}
+
+
+@pytest.mark.parametrize(
+    "key, value", [("business_hours", True), ("growth", 0.5), ("seasonality", 0.5)]
+)
+def test_hint_on_a_non_temporal_column_is_rejected(key, value):
+    tables = _single_column_table(ColumnDef("label", "varchar", note={key: value}))
+    with pytest.raises(ValueError, match=r"t\.label"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+def test_growth_below_negative_one_is_rejected():
+    tables = _single_column_table(ColumnDef("happened_at", "timestamp", note={"growth": -1.5}))
+    with pytest.raises(ValueError, match=r"t\.happened_at.*growth"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+def test_growth_as_a_bool_is_rejected():
+    tables = _single_column_table(ColumnDef("happened_at", "timestamp", note={"growth": True}))
+    with pytest.raises(ValueError, match=r"t\.happened_at"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+def test_seasonality_out_of_range_is_rejected():
+    tables = _single_column_table(ColumnDef("happened_at", "timestamp", note={"seasonality": 1.5}))
+    with pytest.raises(ValueError, match=r"t\.happened_at"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+def test_business_hours_as_a_non_bool_is_rejected():
+    tables = _single_column_table(
+        ColumnDef("happened_at", "timestamp", note={"business_hours": "yes"})
+    )
+    with pytest.raises(ValueError, match=r"t\.happened_at"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)

model2data-1.7.0/tests/test_distributions.py

@@ -0,0 +1,258 @@
+"""Numeric distribution hints: `distribution` and its `mean`/`stddev`/`median`/`spread`
+parameters on integer and decimal columns.
+
+The product ask this closes was "can I make a normal distribution or another kind
+of distribution as well?" on a numeric column -- `min`/`max` alone could only shape
+a uniform spread. Every statistical test here uses a fixed seed and a generous
+tolerance so it never flakes; the exact bounds were chosen by running the real
+implementation and leaving headroom, not derived analytically.
+"""
+
+import statistics
+
+import pytest
+
+from model2data.generate.core import generate_data_from_dbml
+from model2data.parse.dbml import ColumnDef, TableDef
+
+
+def _single_column_table(column: ColumnDef, table_name: str = "t") -> dict[str, TableDef]:
+    return {table_name: TableDef(name=table_name, columns=[ColumnDef("id", "int", {"pk"}), column])}
+
+
+# ---------------------------------------------------------
+# Step 0: pin today's (uniform) behaviour before touching it
+# ---------------------------------------------------------
+def test_no_distribution_hint_reproduces_pre_1_7_frames():
+    """A numeric column with no `distribution` key must still produce exactly
+    what 1.6.0 produced with the same seed -- the guard rail every distribution
+    added here works against."""
+    tables = {
+        "t": TableDef(
+            name="t",
+            columns=[
+                ColumnDef("id", "int", {"pk"}),
+                ColumnDef("amount", "numeric", {"not null"}),
+                ColumnDef("qty", "int", {"not null"}),
+            ],
+        )
+    }
+    data = generate_data_from_dbml(tables, [], base_rows=8, seed=777)
+    assert data["t"]["amount"].tolist() == [
+        4169.09,
+        3848.52,
+        5163.13,
+        3006.66,
+        25.14,
+        4363.61,
+        685.34,
+        8357.29,
+    ]
+    assert data["t"]["qty"].tolist() == [7, 89, 51, 52, 82, 100, 97, 9]
+
+
+# ---------------------------------------------------------
+# Shape: each distribution draws roughly what it says it does
+# ---------------------------------------------------------
+def test_normal_distribution_matches_mean_and_stddev():
+    tables = _single_column_table(
+        ColumnDef(
+            "amount",
+            "numeric",
+            {"not null"},
+            note={"distribution": "normal", "mean": 100, "stddev": 10},
+        )
+    )
+    data = generate_data_from_dbml(tables, [], base_rows=5000, seed=1)
+    values = data["t"]["amount"].tolist()
+    assert 97 <= statistics.mean(values) <= 103
+    assert 8 <= statistics.stdev(values) <= 12
+
+
+def test_lognormal_distribution_median_and_mean():
+    tables = _single_column_table(
+        ColumnDef(
+            "amount",
+            "numeric",
+            {"not null"},
+            note={"distribution": "lognormal", "median": 80, "spread": 0.5},
+        )
+    )
+    data = generate_data_from_dbml(tables, [], base_rows=5000, seed=2)
+    values = data["t"]["amount"].tolist()
+    sample_median = statistics.median(values)
+    assert 70 <= sample_median <= 90
+    assert statistics.mean(values) > sample_median
+
+
+def test_exponential_distribution_matches_mean():
+    tables = _single_column_table(
+        ColumnDef(
+            "amount", "numeric", {"not null"}, note={"distribution": "exponential", "mean": 30}
+        )
+    )
+    data = generate_data_from_dbml(tables, [], base_rows=5000, seed=3)
+    values = data["t"]["amount"].tolist()
+    assert 26 <= statistics.mean(values) <= 34
+
+
+def test_missing_parameters_default_to_midpoint_and_derived_spread():
+    """No `mean`/`stddev` at all: normal centres on the midpoint of the
+    default int range (0-100 -> 50) with stddev (max-min)/6."""
+    tables = _single_column_table(
+        ColumnDef("qty", "int", {"not null"}, note={"distribution": "normal"})
+    )
+    data = generate_data_from_dbml(tables, [], base_rows=5000, seed=7)
+    values = data["t"]["qty"].tolist()
+    assert 45 <= statistics.mean(values) <= 55
+    assert 12 <= statistics.stdev(values) <= 21
+
+
+def test_missing_lognormal_parameters_default_to_midpoint_and_half_spread():
+    """No `median`/`spread`: lognormal centres on the midpoint of the default
+    decimal range (0-10,000 -> 5,000)."""
+    tables = _single_column_table(
+        ColumnDef("amount", "numeric", {"not null"}, note={"distribution": "lognormal"})
+    )
+    data = generate_data_from_dbml(tables, [], base_rows=5000, seed=8)
+    values = data["t"]["amount"].tolist()
+    assert 4000 <= statistics.median(values) <= 6000
+
+
+def test_missing_exponential_mean_defaults_to_midpoint():
+    """No `mean`: exponential's scale defaults to the midpoint of the default
+    int range (0-100 -> 50)."""
+    tables = _single_column_table(
+        ColumnDef("qty", "int", {"not null"}, note={"distribution": "exponential"})
+    )
+    data = generate_data_from_dbml(tables, [], base_rows=5000, seed=9)
+    values = data["t"]["qty"].tolist()
+    assert 40 <= statistics.mean(values) <= 60
+
+
+# ---------------------------------------------------------
+# Clipping and typing
+# ---------------------------------------------------------
+def test_clipping_with_explicit_min_leaves_no_negatives():
+    """A normal whose mean sits close to an explicit `min` would otherwise
+    draw negatives; redraw-then-clamp keeps every value in bounds."""
+    tables = _single_column_table(
+        ColumnDef(
+            "amount",
+            "numeric",
+            {"not null"},
+            note={"distribution": "normal", "mean": 5, "stddev": 10, "min": 0},
+        )
+    )
+    data = generate_data_from_dbml(tables, [], base_rows=2000, seed=4)
+    values = data["t"]["amount"].tolist()
+    assert min(values) >= 0
+
+
+def test_integer_columns_stay_ints_under_a_distribution():
+    tables = _single_column_table(
+        ColumnDef(
+            "qty", "int", {"not null"}, note={"distribution": "normal", "mean": 50, "stddev": 10}
+        )
+    )
+    data = generate_data_from_dbml(tables, [], base_rows=200, seed=5)
+    values = data["t"]["qty"].tolist()
+    assert all(isinstance(v, int) for v in values)
+
+
+def test_unique_normal_column_stays_unique():
+    """`ensure_unique` still resolves collisions when the generator draws
+    from a distribution instead of `random.sample` -- given a spread wide
+    enough to hold that many distinct values."""
+    tables = {
+        "t": TableDef(
+            name="t",
+            columns=[
+                ColumnDef(
+                    "id",
+                    "int",
+                    {"pk"},
+                    note={"distribution": "normal", "mean": 5000, "stddev": 500},
+                )
+            ],
+        )
+    }
+    data = generate_data_from_dbml(tables, [], base_rows=200, seed=6)
+    values = data["t"]["id"].tolist()
+    assert len(set(values)) == len(values)
+
+
+# ---------------------------------------------------------
+# Validation: every error names the column
+# ---------------------------------------------------------
+def test_distribution_on_a_non_numeric_column_is_rejected():
+    tables = _single_column_table(ColumnDef("label", "varchar", note={"distribution": "normal"}))
+    with pytest.raises(ValueError, match=r"t\.label"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+def test_distribution_rejects_an_unknown_value():
+    tables = _single_column_table(ColumnDef("total", "numeric", note={"distribution": "gaussian"}))
+    with pytest.raises(ValueError, match=r"t\.total"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+def test_stddev_without_distribution_is_rejected():
+    tables = _single_column_table(ColumnDef("total", "numeric", note={"stddev": 5}))
+    with pytest.raises(
+        ValueError, match=r't\.total: "stddev" only applies with "distribution": "normal"\.'
+    ):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+def test_stddev_with_the_wrong_distribution_is_rejected():
+    tables = _single_column_table(
+        ColumnDef("total", "numeric", note={"distribution": "exponential", "stddev": 5})
+    )
+    with pytest.raises(ValueError, match=r"t\.total"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+def test_median_with_the_wrong_distribution_is_rejected():
+    tables = _single_column_table(
+        ColumnDef("total", "numeric", note={"distribution": "normal", "median": 5})
+    )
+    with pytest.raises(ValueError, match=r"t\.total"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+def test_spread_with_the_wrong_distribution_is_rejected():
+    tables = _single_column_table(
+        ColumnDef("total", "numeric", note={"distribution": "normal", "spread": 0.5})
+    )
+    with pytest.raises(ValueError, match=r"t\.total"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+def test_mean_without_a_matching_distribution_is_rejected():
+    tables = _single_column_table(ColumnDef("total", "numeric", note={"mean": 5}))
+    with pytest.raises(ValueError, match=r"t\.total"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+@pytest.mark.parametrize(
+    "note",
+    [
+        {"distribution": "normal", "stddev": -1},
+        {"distribution": "normal", "stddev": 0},
+        {"distribution": "lognormal", "median": -5},
+        {"distribution": "lognormal", "spread": 0},
+    ],
+)
+def test_non_positive_stddev_median_spread_is_rejected(note):
+    tables = _single_column_table(ColumnDef("total", "numeric", note=note))
+    with pytest.raises(ValueError, match=r"t\.total"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+def test_a_bool_value_is_rejected_where_a_number_is_expected():
+    tables = _single_column_table(
+        ColumnDef("total", "numeric", note={"distribution": "normal", "mean": True})
+    )
+    with pytest.raises(ValueError, match=r"t\.total"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)