Skip to content

Faker Synthesizer

ydata.synthesizers.FakerSynthesizer

A synthesizer for generating synthetic data based on user-defined configurations.

The FakerSynthesizer allows users to create synthetic tabular data without needing an existing dataset. Instead, it generates data based on user-provided metadata or manually defined column configurations. This approach is useful for:

  • Creating mock datasets for testing and development.
  • Generating data prototypes before real data is available.
  • Ensuring privacy-preserving synthetic data without reference to actual records.

Key Features:

  • Metadata-Driven Generation: Generates synthetic data based on predefined Metadata.
  • Customizable Column Types: Supports user-defined column structures.
  • Multi-Language Support: Uses locale settings to generate realistic names, addresses, etc.

Example Usage:

from ydata.synthesizers import FakerSynthesizer

# Initialize the synthesizer with a specific locale
faker_synth = FakerSynthesizer(locale="en")  # English data generation

faker_synth.fit(metadata)

# Generate synthetic data
synthetic_data = faker_synth.sample(n_samples=1000)

fit(metadata, calculated_features=None, scaffold=None, reference_data=None, distributions=None, conditions=None)

Configure the FakerSynthesizer using provided metadata.

This method sets up the synthesizer by defining the structure of the synthetic dataset based on the given Metadata. The metadata can either be:

  • Computed: Automatically extracted from an existing dataset.
  • User-Defined: Manually constructed to specify custom column types and distributions.

Once fit() is called, the synthesizer will use this metadata to generate structured synthetic data that adheres to the defined schema.

Parameters:

Name Type Description Default
metadata Metadata

A metadata object describing the structure of the synthetic dataset, including: - Column names and data types. - Faker-based data generators (e.g., names, addresses, emails). - Value constraints (e.g., numeric ranges, categorical options).

 required
calculated_features list[dict] | None

Optional. Columns computed deterministically from other columns AFTER sampling — exact identities, sign rules, derived flags. Same single-table convention as :class:RegularSynthesizer (bare column names)::

[{
    "calculated_features": "vat_value",
    "function": lambda net: (net * 0.20).round(2),
    "calculated_from": ["net_value"],
}]

Features are applied in list order (later features may consume earlier outputs) and are excluded from generation. Cross-table reference_keys are not supported by this single-table synthesizer.

 None
scaffold dict | ScaffoldConfig | None

Optional. A declarative structural grid (:class:~ydata.dataset.schemas.mock_schema.ScaffoldConfig or its dict form): the cross product of the declared dimensions (date_range, static values, or from_table sourced from reference_data), optionally filtered by density rules, becomes the table's seed rows. Scaffold columns are emitted verbatim; every other metadata column is generated per seed row, and sample(sample_size=...) is ignored (the scaffold defines the row count). Example::

scaffold={
    "dimensions": [
        {"column": "product_id", "from_table": "products",
         "from_column": "product_id"},
        {"column": "date", "date_range": {"start": "2026-03-01",
                                          "end": "2026-03-31"}},
    ],
}
None
reference_data dict[str, DataFrame] | None

Optional. Named DataFrames backing the scaffold's from_table dimensions and density lookups.

 None
distributions dict[str, dict] | None

Optional. Per-column distribution overrides for numerical columns (default: uniform within the declared domain). Pure data, so it can also live in the YAML configuration::

distributions={
    "amount": {"distribution": "lognormal", "mean": 3.0, "sigma": 0.5},
    "score": {"distribution": "normal", "loc": 50, "scale": 10, "min": 0},
}

Supported: uniform, normal, lognormal, exponential, poisson, triangular, beta. min/max clip (falling back to the column's domain); integer columns are rounded.

 None
conditions list[dict] | None

Optional. Conditional generation rules: a column's values are sampled per segment defined by when predicates over one or MORE other columns (equality / is-in, AND semantics; first matching rule wins; unmatched rows use default or the column's base sampling)::

conditions=[{
    "column": "amount",
    "rules": [
        {"when": {"category": "fuel"},
         "distribution": {"distribution": "lognormal", "mean": 8.6, "sigma": 0.55}},
        {"when": {"category": ["shop", "commission"], "channel": "online"},
         "distribution": {"distribution": "lognormal", "mean": 6.9, "sigma": 0.7}},
    ],
    "default": {"distribution": {"distribution": "uniform", "low": 1, "high": 50}},
}, {
    "column": "doc_type",
    "rules": [
        {"when": {"category": "fuel"},
         "values": {"Invoice": 0.9, "Credit Note": 0.1}},
    ],
    "default": {"values": {"Invoice": 0.7, "Debit Note": 0.2, "Credit Note": 0.1}},
}]

when columns may be other metadata columns, scaffold dimensions, or other conditioned columns (ordered automatically; cycles are rejected). Rules carry either a distribution (numerical columns) or values (weighted categorical values, any column type).

 None

sample(sample_size=1000, random_state=None)

Generate a synthetic dataset based on the configured metadata.

This method produces synthetic data according to the schema defined in the fit() step. The generated data adheres to the column types, constraints, and distributions specified in the provided Metadata.

When a scaffold was configured in fit(), the scaffold grid defines both the structural columns (emitted verbatim) and the row count — sample_size is then ignored. Calculated features configured in fit() are computed after sampling, in list order, and are never generated.

Parameters:

Name Type Description Default
sample_size int

The number of synthetic records/rows to generate. Defaults to 1000. Ignored when a scaffold is configured.

 1000
random_state int | None

Seed for reproducible sampling (column draws and the scaffold's density filtering). Defaults to None.

 None

Returns:

Name Type Description
dataset Dataset

A Dataset object with the generated synthetic records/rows.

save(path)

Saves the SYNTHESIZER and the model fitted per variable.