rtbgym.envs.simulator.base#

Abstract Base Class for Simulation.

Classes

BaseClickAndConversionRate

Base class to Class to define ground-truth CTR/CVR.

BaseSimulator

Base class to calculate the outcome probability and stochastically determine auction result.

BaseWinningPriceDistribution

Base class to sample the winning price (i.e., second price) and compare it with the given bid price.
class rtbgym.envs.simulator.base.BaseSimulator[source]#

Base class to calculate the outcome probability and stochastically determine auction result.

Imported as: rtbgym.envs.simulator.BaseSimulator

Methods

calc_and_sample_outcome(timestep, ad_ids, ...)

Simulate bidding auction for given queries.

generate_auction(search_volume)

Sample ad and user pair for each auction.

map_idx_to_features(ad_ids, user_ids)

Map the ad and the user index into feature vectors.
abstract generate_auction(search_volume)[source]#

Sample ad and user pair for each auction.

Parameters:

search_volume (int, default=None (> 0)) – Total number of auctions to generate.

Returns:

  • ad_ids (ndarray of shape (search_volume, )) – IDs of the ads.

  • user_ids (ndarray of shape (search_volume, )) – IDs of the users.

Return type:

Tuple[ndarray]

abstract map_idx_to_features(ad_ids, user_ids)[source]#

Map the ad and the user index into feature vectors.

Parameters:

  • ad_ids (array-like of shape (search_volume, )) – IDs of the ads. (search_volume is determined in RL environment.)

  • user_ids (array-like of shape (search_volume, )) – IDs of the users. (search_volume is determined in RL environment.)

Returns:

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

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

Return type:

ndarray

abstract calc_and_sample_outcome(timestep, ad_ids, user_ids, bid_prices)[source]#

Simulate bidding auction for given queries.

Parameters:

  • timestep (int (> 0)) – Timestep in the RL environment.

  • ad_ids (array-like of shape (search_volume, )) – IDs of the ads.

  • user_ids (array-like of shape (search_volume, )) – IDs of the users.

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

Returns:

  • costs (ndarray of shape (search_volume, )) – Cost raised (i.e., second price) for each auction.

  • impressions (ndarray of shape (search_volume, )) – Binary indicator of whether impression occurred or not for each auction.

  • clicks (ndarray of shape (search_volume, )) – Binary indicator of whether click occurred or not for each auction.

  • conversions (ndarray of shape (search_volume, )) – Binary indicator of whether conversion occurred or not for each auction.

Return type:

Tuple[ndarray]

class rtbgym.envs.simulator.base.BaseWinningPriceDistribution[source]#

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

Imported as: class:rtbgym.BaseWinningPriceDistribution

Methods

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

Stochastically determine impression and second price for each auction.
abstract sample_outcome(bid_prices, ad_ids, user_ids, ad_feature_vector, user_feature_vector, timestep)[source]#

Stochastically determine impression and second price for each auction.

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.

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

  • 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.base.BaseClickAndConversionRate[source]#

Base class to Class to define ground-truth CTR/CVR.

Imported as: class:rtbgym.BaseClickAndConversionRate

Methods

calc_prob(ad_ids, user_ids, ...)

Calculate Click Through Rate (CTR) / Conversion Rate (CVR).

sample_outcome(ad_ids, user_ids, ...)

Stochastically determine whether click/conversion occurs or not.
abstract calc_prob(ad_ids, user_ids, ad_feature_vector, user_feature_vector, timestep)[source]#

Calculate Click Through Rate (CTR) / Conversion Rate (CVR).

Parameters:

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

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

  • 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/cvrs – Ground-truth CTR (i.e., click per impression) or CVR (i.e., conversion per click) for each auction.

Return type:

ndarray of shape (search_volume/n_samples, )

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

Stochastically determine whether click/conversion occurs or not.

Parameters:

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

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

  • 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/conversions – Whether click occurs (when impression=True) or whether conversion occurs (when click=True).

Return type:

array-like of shape (search_volume/n_samples, )