rtbgym.envs.simulator.function#

Mathematical Functions used in Real-Time Bidding (RTB) Simulation.

Classes

ClickThroughRate

Class to calculate ground-truth CTR (i.e., click per impression).

ConversionRate

Class to calculate ground-truth CVR (i.e., conversion per click).

WinningPriceDistribution

Class to sample the winning price (i.e., second price) and compare it with the given bid price.
class rtbgym.envs.simulator.function.WinningPriceDistribution(n_ads, n_users, ad_feature_dim, user_feature_dim, step_per_episode, standard_bid_price_distribution=(None,), minimum_standard_bid_price=None, random_state=None)[source]#

Class to sample the winning price (i.e., second price) and compare it with the given bid price.

Imported as: rtbgym.envs.simulator.WinningDistribution

Note

Winning price distribution follows gamma distribution.

\[p(x) = x^{k-1} \frac{\exp(- x / \theta)}{\theta^k \Gamma(k)},\]

where \(\Gamma(k) := (k-1)!\) and \(k\) and \(\theta\) are hyperparameters.

Tip

Use BaseWinningPriceDistribution to define a custom WinningPriceDistribution.

Parameters:

  • n_ads (int (> 0)) – Number of ads.

  • n_users (int (> 0)) – Number of users. (This is for API consistency)

  • ad_feature_dim (int (> 0)) – Dimension of the ad feature vectors. (This is for API consistency)

  • user_feature_dim (int (> 0)) – Dimension of the user feature vectors. (This is for API consistency)

  • step_per_episode (int (> 0)) – Length of the CTR trend cycle. (This is for API consistency)

  • standard_bid_price_distribution (NormalDistribution, default=None) – Distribution of the bid price whose average impression probability is expected to be 0.5.

  • minimum_standard_bid_price ({int, float}, default=None (> 0)) – Minimum value for standard bid price. If None, minimum_standard_bid_price is set to standard_bid_price_distribution.mean / 2.

  • random_state (int, default=None (>= 0)) – Random state.

References

Wen-Yuan Zhu, Wen-Yueh Shih, Ying-Hsuan Lee, Wen-Chih Peng, and Jiun-Long Huang. “A Gamma-based Regression for Winning Price Estimation in Real-Time Bidding Advertising.” 2017.

Attributes:
minimum_standard_bid_price
random_state
standard_bid_price

Methods

sample_outcome(bid_prices, ad_ids, user_ids, ...)

Calculate impression probability for given bid price.
sample_outcome(bid_prices, ad_ids, user_ids, ad_feature_vector, user_feature_vector, timestep)[source]#

Calculate impression probability for given bid price.

Parameters:

  • bid_prices (array-like of shape (search_volume, )) – Bid price for each auction.

  • ad_ids (array-like of shape (search_volume/n_samples, )) – Ad ids used for each auction. (This is for API consistency)

  • user_ids (array-like of shape (search_volume/n_samples, )) – User ids used for each auction. (This is for API consistency)

  • ad_feature_vector (array-like of shape (search_volume/n_samples, ad_feature_dim)) – Ad feature vector for each auction.

  • user_feature_vector (array-like of shape (search_volume/n_samples, user_feature_dim)) – User feature vector for each auction.

  • timestep ({int, array-like of shape (n_samples, )}) – Timestep in the RL environment.

Returns:

  • impressions (ndarray of shape (search_volume, )) – Whether impression occurred for each auction.

  • winning_prices (ndarray of shape (search_volume, )) – Sampled winning price for each auction.

Return type:

Tuple[ndarray]

class rtbgym.envs.simulator.function.ClickThroughRate(n_ads, n_users, ad_feature_dim, user_feature_dim, step_per_episode, random_state=None)[source]#

Class to calculate ground-truth CTR (i.e., click per impression).

Imported as: rtbgym.envs.simulator.ClickThroughRate

Note

We define two coefficient, context coefficient (coef) and time coefficient (time_coef). First, the value is calculated linearly from context vector and coef by inner product. Then, we multiply the value with time_coef and gain (ground-truth) CTR.

In short, CTR is calculated as follows.

CTR = (context @ coef) * time_coef, where @ denotes inner product.

Tip

Use BaseClickAndConversionRate to define a custom ClickThroughRate.

Parameters:

  • n_ads (int (> 0)) – Number of ads. (This is for API consistency)

  • n_users (int (> 0)) – Number of users. (This is for API consistency)

  • ad_feature_dim (int (> 0)) – Dimension of the ad feature vectors.

  • user_feature_dim (int (> 0)) – Dimension of the user feature vectors.

  • step_per_episode (int (> 0)) – Length of the CTR trend cycle.

  • random_state (int, default=None (>= 0)) – Random state.

Attributes:
random_state

Methods

calc_prob(ad_ids, user_ids, ...)

Calculate CTR (i.e., click per impression).

sample_outcome(ad_ids, user_ids, ...)

Stochastically determine whether click occurs in impression=True case.
calc_prob(ad_ids, user_ids, ad_feature_vector, user_feature_vector, timestep)[source]#

Calculate CTR (i.e., click per impression).

Note

CTR is calculated using both context coefficient (coef) and time coefficient (time_coef).

CTR = (context @ coef) * time_coef, where @ denotes inner product.

Parameters:

  • ad_ids (array-like of shape (search_volume/n_samples, )) – Ad ids used for each auction. (not used, but for API consistency)

  • user_ids (array-like of shape (search_volume/n_samples, )) – User ids used for each auction. (not used, but for API consistency)

  • ad_feature_vector (array-like of shape (search_volume/n_samples, ad_feature_dim)) – Ad feature vector for each auction.

  • user_feature_vector (array-like of shape (search_volume/n_samples, user_feature_dim)) – User feature vector for each auction.

  • timestep ({int, array-like of shape (n_samples, )}) – Timestep in the RL environment.

Returns:

ctrs – Ground-truth CTR (i.e., click per impression) for each auction.

Return type:

ndarray of shape (search_volume/n_samples, )

sample_outcome(ad_ids, user_ids, ad_feature_vector, user_feature_vector, timestep)[source]#

Stochastically determine whether click occurs in impression=True case.

Parameters:

  • ad_ids (array-like of shape (search_volume/n_samples, )) – Ad ids used for each auction. (not used, but for API consistency)

  • user_ids (array-like of shape (search_volume/n_samples, )) – User ids used for each auction. (not used, but for API consistency)

  • ad_feature_vector (array-like of shape (search_volume/n_samples, ad_feature_dim)) – Ad feature vector for each auction.

  • user_feature_vector (array-like of shape (search_volume/n_samples, user_feature_dim)) – User feature vector for each auction.

  • timestep ({int, array-like of shape (n_samples, )}) – Timestep in the RL environment.

Returns:

clicks – Whether click occurs when impression=True.

Return type:

array-like of shape (search_volume/n_samples, )

class rtbgym.envs.simulator.function.ConversionRate(n_ads, n_users, ad_feature_dim, user_feature_dim, step_per_episode, random_state=None)[source]#

Class to calculate ground-truth CVR (i.e., conversion per click).

Imported as: rtbgym.envs.simulator.ConversionRate

Note

We define two coefficient, context coefficient (coef) and time coefficient (time_coef). First, the value is calculated linearly from context vector and coef by inner product. Then, we multiply the value with time_coef and gain (ground-truth) CVR.

In short, CVR is calculated as follows.

CVR = (context @ coef) * time_coef, where @ denotes inner product.

Tip

Use BaseClickAndConversionRate to define a custom ConversionRate.

Parameters:

  • n_ads (int (> 0)) – Number of ads. (This is for API consistency)

  • n_users (int (> 0)) – Number of users. (This is for API consistency)

  • ad_feature_dim (int (> 0)) – Dimension of the ad feature vectors.

  • user_feature_dim (int (> 0)) – Dimension of the user feature vectors.

  • step_per_episode (int (> 0)) – Length of the CVR trend cycle.

  • random_state (int, default=None (>= 0)) – Random state.

Attributes:
random_state

Methods

calc_prob(ad_ids, user_ids, ...)

Calculate CVR (i.e., conversion per click) using context vectors.

sample_outcome(ad_ids, user_ids, ...)

Stochastically determine whether conversion occurs in click=True case.
calc_prob(ad_ids, user_ids, ad_feature_vector, user_feature_vector, timestep)[source]#

Calculate CVR (i.e., conversion per click) using context vectors.

Note

CVR is calculated using both context coefficient (coef) and time coefficient (time_coef).

CVR = (context @ coef) * time_coef, where @ denotes inner product.

Parameters:

  • ad_ids (array-like of shape (search_volume/n_samples, )) – Ad ids used for each auction. (not used, but for API consistency)

  • user_ids (array-like of shape (search_volume/n_samples, )) – User ids used for each auction. (not used, but for API consistency)

  • ad_feature_vector (array-like of shape (search_volume/n_samples, ad_feature_dim)) – Ad feature vector for each auction.

  • user_feature_vector (array-like of shape (search_volume/n_samples, user_feature_dim)) – User feature vector for each auction.

  • timestep ({int, array-like of shape (n_samples, )}) – Timestep in the RL environment.

Returns:

cvrs – Ground-truth CVR (i.e., conversion per click) for each auction.

Return type:

ndarray of shape (search_volume/n_samples, )

sample_outcome(ad_ids, user_ids, ad_feature_vector, user_feature_vector, timestep)[source]#

Stochastically determine whether conversion occurs in click=True case.

Parameters:

  • ad_ids (array-like of shape (search_volume/n_samples, )) – Ad ids used for each auction. (not used, but for API consistency)

  • user_ids (array-like of shape (search_volume/n_samples, )) – User ids used for each auction. (not used, but for API consistency)

  • ad_feature_vector (array-like of shape (search_volume/n_samples, ad_feature_dim)) – Ad feature vector for each auction.

  • user_feature_vector (array-like of shape (search_volume/n_samples, user_feature_dim)) – User feature vector for each auction.

  • timestep ({int, array-like of shape (n_samples, )}) – Timestep in the RL environment.

Returns:

conversions – Whether conversion occurs when click=True.

Return type:

ndarray of shape (search_volume/n_samples, )