Peer-compatible baseline

Version 1.0.0 meaning

Baseline version 1.0.0 is the stable benchmark under ZheyuanWu/simulations/baseline/. “Baseline” means it keeps the project team's original campaign-level ideas—traffic scale, prices, advertising touchpoints, path sizes, conversion effects, seasonality, and random variation—without adding national economic inputs.

The version number refers to the generator family recorded in dataset_manifest.json, not to Amazon software. It makes three promises:

1. the finalized 9-column Amazon Marketing Cloud path schema and 16-column Amazon Ads performance schema are unchanged;
2. the baseline configuration contains no internet reach, target-audience density, economic-willingness, or Gini fields;
3. future regional experimentation must not silently change baseline output.

The peer-compatible benchmark is not byte-for-byte equivalent to every legacy file. It preserves the peer model's scope while correcting reproducibility, finalized-schema, key-matching, validation, and storage problems.

Parameter map

Each parameter has one first-definition page. Later pages link back to that definition:

• Control Parameters: seed, reporting dates, advertiser identifier, price, and baseline conversion tendency.
• Global Behavior Parameters: weekly traffic, trend, noise, extra units, and repeat purchases.
• Marketplace Parameters: marketplace code, currency, traffic scale, and price conversion.
• Touchpoint Parameters: normalized advertising dimensions, rates, billing, and response effects.
• Path Parameters: ordered journeys, path audience, and adjacent interaction.

The full formula sequence is in Dataset Generation Flow, and every mathematical symbol is in Mathematical Notation.

Baseline behavior equations

The baseline marketplace volume adjustment is deliberately simple:

$$\text{marketplace volume multiplier}=\text{traffic multiplier}$$

It adds no marketplace-specific conversion shift:

$$\text{marketplace conversion log-odds adjustment}=0$$

It uses the configured global daily noise spread unchanged:

$$\begin{array}{rl}\text{marketplace conversion noise standard deviation}& =\text{conversion probability daily noise}\\ & \text{standard deviation}\end{array}$$

These three equations are the boundary that separates the baseline from regional version 0.1.0.

Source excerpt: baseline behavior

This function is copied from simulations/baseline/mta_dataset/behavior.py:

def baseline_marketplace_behavior(
    marketplace: MarketplaceConfiguration,
    behavior: GlobalBehaviorConfiguration,
) -> MarketplaceBehaviorAdjustment:
    """Return the neutral peer-compatible adjustment for one marketplace.

    Args:
        marketplace: Baseline marketplace scale and currency parameters.
        behavior: Global daily variation parameters.

    Returns:
        Traffic uses ``traffic_multiplier`` directly, conversion log odds
        receive no regional shift, and noise uses the global configured spread.
    """

    return MarketplaceBehaviorAdjustment(
        volume_multiplier=marketplace.traffic_multiplier,
        conversion_log_odds_adjustment=0.0,
        conversion_noise_standard_deviation=(
            behavior.conversion_probability_daily_noise_standard_deviation
        ),
    )

The row generator accepts this function through an explicit behavior-provider argument. That seam is the only mechanism used by the regional extension; storage and schemas are shared.

Module responsibilities

configuration.py

Resolves relative configuration inheritance, applies touchpoint overrides, constructs immutable Python objects, and rejects invalid dates, probabilities, billing combinations, structural nulls, or missing touchpoint references.

behavior.py

Defines the three values row generation may vary by marketplace. The default provider implements the baseline equations above.

simulation.py

Creates path rows, daily performance rows, and evaluation-only Shapley ground-truth rows in memory. It does not write files.

schemas.py

Owns exact column order and the in-memory dataset bundle.

validation.py

Checks schemas, non-negative values, converted_users <= users, normalized-key structure, path-to-performance matching, and ground-truth credit conservation.

storage.py

Implements the common writer protocol. Comma-Separated Values is the default; SQLite proves that storage can change without rewriting simulation logic.

pipeline.py

Coordinates load, simulation, validation, persistence, validation report, and deterministic manifest.

command.py and __main__.py

Expose the baseline as python -m simulations.baseline.mta_dataset.

Source excerpt: shared row generator seam

This signature is copied from simulations/baseline/mta_dataset/simulation.py:

def simulate_dataset(
    configuration: SimulationConfiguration,
    marketplace_behavior_provider: MarketplaceBehaviorProvider = (
        baseline_marketplace_behavior
    ),
) -> DatasetBundle:

The default is explicit. Running the baseline entry point cannot accidentally activate regional behavior.

Differences from the original code

Reproducibility

The legacy amazonTestData/generate_sk2_mock_data.py has no fixed seed. Version 1.0.0 stores the seed, resolved-configuration hash, generator version, and output hashes.

Finalized schemas

The legacy performance output has 20 columns and uses five-segment keys. Version 1.0.0 enforces the finalized 16-column performance schema, 9-column path schema, and four-segment normalized key.

Shared touchpoint catalog

Legacy path and performance product names can disagree. The baseline builds both from one touchpoint catalog and validates every match.

Structural nulls

Legacy code places UNSPECIFIED in raw fields. The baseline preserves raw nulls and uses UNSPECIFIED only inside normalizedTouchpoint.

Count generation

Legacy conversions use fixed scenario rates and integer truncation. The baseline samples explicit binomial counts, so clicks cannot exceed impressions and conversions cannot exceed their trial counts.

Conversion response and evaluation

Legacy code has no explicit causal response function or known attribution truth. The baseline uses a documented logistic response and writes exact Shapley marginal contributions to a separate evaluation-only table.

Storage and validation

Legacy code writes Comma-Separated Values directly into its process directory. The baseline separates simulation from storage, supports SQLite, and validates before persistence.

Economic context

The original peer scope has no national economic layer. Version 1.0.0 deliberately keeps that absence. The optional variables now live only under simulations/regional/.

Baseline configuration values

configs/default.json simulates July 1–31, 2026 for United States and Canada scenarios. The seed is 20260729, the reference product price is 125.0, and baseline conversion log odds are -4.0.

Those values are transparent scenario assumptions. They are not presented as Amazon measurements. Review the linked parameter pages before changing any value, because they explain the effect, relationships, reasoning, and confidence.

Run baseline version 1.0.0

From ZheyuanWu/:

python -m simulations.baseline.mta_dataset `
  --config simulations/baseline/configs/default.json `
  --output generated/baseline `
  --storage both

Linux:

python -m simulations.baseline.mta_dataset \
  --config simulations/baseline/configs/default.json \
  --output generated/baseline \
  --storage both

The command writes both storage formats only because --storage both is selected. Use --storage csv for the current default workflow.

Baseline limitations

The baseline is an aggregated algorithm-testing dataset. It has no person-level events, event timestamps, randomized holdouts, organic purchases, competitor exposure, real campaign calibration, or observed causal truth. Synthetic ground truth measures recovery of the simulator's equation, not effectiveness on real customers.

Continue with Regional Overview for the separated economic extension or Recommendations for possible future versions.