Configuration

Handlers

Handlers provide a framework for specifiying the inputs to a simulation, critically providing validation checks for each handler that will notify the user if inputs validate global tolerances.

class pysimmmulator.param_handlers.AdSpendParameters(campaign_spend_mean: int, campaign_spend_std: int, max_min_proportion_on_each_channel: dict)

Handler for loading in parameters used by simmmulate class to generate ad spend approximation. After init, this class will also preform logic checks for the values of the parameters. Also provided is a check function that when passed basic_params from input to simmmulate, will provide futher validation checks.

Parameters:

campaign_spend_mean (int) – The average amount of money spent on a campaign.
campaign_spend_std (int) – The standard deviation of money spent on a campaign
max_min_proportion_on_each_channel (dict) – Specifies the minimum and maximum percentages of total spend allocated to each channel.

campaign_spend_mean: int

campaign_spend_std: int

check(basic_params: BasicParameters)

Validates ad spend parameters agianst previously constructed basic parameter values.

Parameters:: basic_params (basic_parameters) – Previously submitted parameters as required by the simmmulate class

max_min_proportion_on_each_channel: dict

class pysimmmulator.param_handlers.AdstockParameters(adstock: dict, saturation: dict)

Handler for loading in parameters used by simmmulate class to augment adstock data. Provided is a check function that when passed basic_params from input to simmmulate, will provide validation checks.

Parameters:

adstock (dict) – Nested dictionary specifying the adstock type and parameters per channel.
saturation (dict) – Nested dictionary specifying the saturation type and parameters per channel.

adstock: dict

check(basic_params: BasicParameters)

Validates ad stock parameters agianst previously constructed basic parameter values.

Parameters:: basic_params (basic_parameters) – Previously submitted parameters as required by the simmmulate class

saturation: dict

class pysimmmulator.param_handlers.BaselineParameters(basic_params: BasicParameters, base_p: int, trend_p: int, temp_var: int, temp_coef_mean: int, temp_coef_sd: int, error_std: int)

Handler for loading in parameters used by simmmulate class to generate a baseline of sales. After init, this class will also preform logic checks for the values of the parameters.

Parameters:

basic_params (basic_parameters) – Number of years you want to generate data for.
base_p (int) – Amount of baseline sales we get in a day (sales not due to ads)
trend_p (int) – How much baseline sales is going to grow over the whole period of our data.
temp_var (int) – How big the height of the sine function is for temperature – i.e. how much temperature varies (used to inject seasonality into our data)
temp_coef_mean (int) – The average of how important seasonality is in our data (the larger this number, the more important seasonality is for sales)
temp_coef_sd (int) – The standard deviation of how important seasonality is in our data (the larger this number, the more variable the importance of seasonality is for sales)
error_std (int) – Amount of statistical noise added to baseline sales (the larger this number, the noisier baseline sales will be).

base_p: int

basic_params: BasicParameters

error_std: int

temp_coef_mean: int

temp_coef_sd: int

temp_var: int

trend_p: int

class pysimmmulator.param_handlers.BasicParameters(years: int, channels_impressions: list[str], channels_clicks: list[str], frequency_of_campaigns: int, start_date: str | datetime, true_cvr: list | None = None, revenue_per_conv: float | None = None)

Handler for loading in basic parameters used by simmmulate class. After init, this class will also preform logic checks for the values of the parameters.

Parameters:

years (int) – Number of years you want to generate data for.
channels_impressions (list[int]) – names of media channels that use impressions as their metric of activity (Examples: Amazon, TV, etc)
channels_clicks (list[int]) – names of media channels that use clicks as their metric of activity (Examples: Search)
frequency_of_campaigns (int) – how often campaigns occur (for example, frequency of 1 would yield a new campaign every 1 day with each campaign lasting 1 day).
start_date (str) – format yyyy/mm/dd that determines when your daily data set starts on
true_cvr (list) – what the underlying conversion rates of all the channels are, statistical noise will be added on top of this.
revenue_per_conv (float) – How much money we make from a conversion (i.e. profit from a unit of sale).

channels_clicks: list[str]

channels_impressions: list[str]

check()

frequency_of_campaigns: int

revenue_per_conv: float | None = None

start_date: str | datetime

true_cvr: list | None = None

years: int

class pysimmmulator.param_handlers.CVRParameters(noisy_cvr: dict)

Handler for loading in parameters used by simmmulate class to generate cvr data. Provided is a check function that when passed basic_params from input to simmmulate, will provide validation checks.

Parameters:: noisy_cpm_cpc (dict) – Specifies the bias and scale of noise added to the true value CVR for each channel.

check(basic_params: BasicParameters)

Validates CVR parameters agianst previously constructed basic parameter values.

Parameters:: basic_params (basic_parameters) – Previously submitted parameters as required by the simmmulate class

noisy_cvr: dict

class pysimmmulator.param_handlers.GeoParameters(total_population: int, geo_specs: dict | None = None, universal_scale: float = 1.0, count: int = 250, dist_spec: tuple[float, float] = (0.0, 0.25), media_cost_spec: tuple[float, float] = (0.0, 0.069), perf_spec: tuple[float, float] = (0.0, 0.069))

Handler for loading in parameters used by simmmulate class to generate geographic distribution data.

Parameters:

total_population (int) – Total population to distribute across geos.
geo_specs (Optional[dict]) – Geography names coupled with a dict of parameters for the normal distribution of that geos population.
universal_scale (Optional[float]) – Scale parameter to be used universally for all geographies.
count (int) – in the absense of specified geographies, this is the number of geos to be created.
dist_spec (tuple[float, float]) – Parameters to control the normal distribution function for populations of the geographies.
media_cost_spec (tuple[float, float]) – Parameters to control the normal distribution function for allocation of spend across geographies.
perf_spec (tuple[float, float]) – Parameters to control the normal distribution function for allocation of performance across geographies.

count: int = 250

dist_spec: tuple[float, float] = (0.0, 0.25)

geo_specs: dict | None = None

media_cost_spec: tuple[float, float] = (0.0, 0.069)

perf_spec: tuple[float, float] = (0.0, 0.069)

total_population: int

universal_scale: float = 1.0

class pysimmmulator.param_handlers.MediaParameters(true_cpm: dict, true_cpc: dict, noisy_cpm_cpc: dict)

Handler for loading in parameters used by simmmulate class to generate media data. After init, this class will also preform logic checks for the values of the parameters. Also provided is a check function that when passed basic_params from input to simmmulate, will provide futher validation checks.

Parameters:

true_cpm (dict) – Specifies the true Cost per Impression (CPM) of each channel (noise will be added to this to simulate number of impressions)
true_cpc (dict) – Specifies the true Cost per Click (CPC) of each channel (noise will be added to this to simulate number of clicks)
noisy_cpm_cpc (dict) – Specifies the bias and scale of noise added to the true value CPM or CPC for each channel.

check(basic_params: BasicParameters)

Validates media parameters parameters agianst previously constructed basic parameter values.

Parameters:: basic_params (basic_parameters) – Previously submitted parameters as required by the simmmulate class

noisy_cpm_cpc: dict

true_cpc: dict

true_cpm: dict

class pysimmmulator.param_handlers.OutputParameters(aggregation_level: str)

Handler for loading in parameters used by simmmulate class to generate final output data.

Parameters:: aggregation_level (str) – Specifies the aggregation level of final output data. choose between [daily, weekly].

aggregation_level: str

Loaders

Functions which automate steps within the parameter workflow. Most notably providing a load from file option load_config as well as a comprehensive validation function validate_config.

pysimmmulator.load_parameters.define_basic_params(years, channels_clicks, channels_impressions, frequency_of_campaigns, start_date, true_cvr, revenue_per_conv): Takes in requirements for basic_params and loads with dataclass for validation as precursor

pysimmmulator.load_parameters.load_config(config_path: str) → dict

pysimmmulator.load_parameters.validate_config(config_path: str, return_individual_results: bool = False)

Loads and validates the parameters against individual

Parameters:

config_path (os.pathlike) – path to the configuration file
return_individual_results (bool) – control for if a detailed param by param result is returned. Default is for a single bool value return

Returns:

results of the validation check. Default will return a bool indicating overall valid or invalid status.

Return type:

(Union[bool, dict])