merlin.models.tf.PopularityBasedSampler

class merlin.models.tf.PopularityBasedSampler(*args, **kwargs)[source]

Bases: merlin.models.tf.blocks.sampling.base.ItemSampler

Provides a popularity-based negative sampling for the softmax layer to ensure training efficiency when the catalog of items is very large. The capacity of the queue is fixed and is equal to the catalog size. For each batch, we sample max_num_samples unique negatives.

This implementation does not require the actual item frequencies/probabilities distribution, but instead tries to approximate the item probabilities using the log_uniform (zipfian) distribution. The only requirement is that the item ids are decreasingly sorted by their count frequency. We use the default log-uniform (zipfian) sampler given by Tensorflow:

[log_uniform_candidate_sampler](https://www.tensorflow.org/api_docs/python/tf/random/log_uniform_candidate_sampler)

The Categorify op provided by nvtabular supports the frequency-based encoding as default.

P.s. Ignoring the false negatives (negative items equal to the positive ones) is managed by ItemRetrievalScorer(…, sampling_downscore_false_negatives=True)

Parameters

max_num_samples (int) – The number of unique negatives to sample at each batch.
max_id (int) – The maximum id value to be sampled. It should be equal to the categorical feature cardinality
min_id (int) – The minimum id value to be sampled. Useful to ignore the first categorical encoded ids, which are usually reserved for <nulls>, out-of-vocabulary or padding. Defaults to 0.
seed (int) – Fix the random values returned by the sampler to ensure reproducibility Defaults to None
item_id_feature_name (str) – Name of the column containing the item ids Defaults to item_id

__init__(max_id: int, min_id: int = 0, max_num_samples: int = 100, seed: Optional[int] = None, item_id_feature_name: str = 'item_id', **kwargs)[source]

Methods

`__init__`(max_id[, min_id, max_num_samples, …])
`add`(embeddings, items_metadata[, training])
`add_loss`(losses, **kwargs)	Add loss tensor(s), potentially dependent on layer inputs.
`add_metric`(value[, name])	Adds metric tensor to the layer.
`add_update`(updates)	Add update op(s), potentially dependent on layer inputs.
`add_variable`(args, *kwargs)	Deprecated, do NOT use! Alias for add_weight.
`add_weight`([name, shape, dtype, …])	Adds a new variable to the layer.
`build`(input_shape)	Creates the variables of the layer (optional, for subclass implementers).
`call`(inputs, item_weights[, training])
`compute_mask`(inputs[, mask])	Computes an output mask tensor.
`compute_output_shape`(input_shape)	Computes the output shape of the layer.
`compute_output_signature`(input_signature)	Compute the output tensor signature of the layer based on the inputs.
`count_params`()	Count the total number of scalars composing the weights.
`finalize_state`()	Finalizes the layers state after updating layer weights.
`from_config`(config)	Creates a layer from its config.
`get_config`()	Returns the config of the layer.
`get_distribution_probs`()	Tries to approximate the log uniform (zipfian) distribution used by tf.random.log_uniform_candidate_sampler (https://www.tensorflow.org/api_docs/python/tf/random/log_uniform_candidate_sampler)
`get_input_at`(node_index)	Retrieves the input tensor(s) of a layer at a given node.
`get_input_mask_at`(node_index)	Retrieves the input mask tensor(s) of a layer at a given node.
`get_input_shape_at`(node_index)	Retrieves the input shape(s) of a layer at a given node.
`get_output_at`(node_index)	Retrieves the output tensor(s) of a layer at a given node.
`get_output_mask_at`(node_index)	Retrieves the output mask tensor(s) of a layer at a given node.
`get_output_shape_at`(node_index)	Retrieves the output shape(s) of a layer at a given node.
`get_weights`()	Returns the current weights of the layer, as NumPy arrays.
`sample`(item_weights)
`set_max_num_samples`(value)
`set_weights`(weights)	Sets the weights of the layer, from NumPy arrays.
`with_name_scope`(method)	Decorator to automatically enter the module name scope.

Attributes

`activity_regularizer`	Optional regularizer function for the output of this layer.
`compute_dtype`	The dtype of the layer’s computations.
`dtype`	The dtype of the layer weights.
`dtype_policy`	The dtype policy associated with this layer.
`dynamic`	Whether the layer is dynamic (eager-only); set in the constructor.
`inbound_nodes`	Return Functional API nodes upstream of this layer.
`input`	Retrieves the input tensor(s) of a layer.
`input_mask`	Retrieves the input mask tensor(s) of a layer.
`input_shape`	Retrieves the input shape(s) of a layer.
`input_spec`	InputSpec instance(s) describing the input format for this layer.
`losses`	List of losses added using the add_loss() API.
`max_num_samples`
`metrics`	List of metrics added using the add_metric() API.
`name`	Name of the layer (string), set in the constructor.
`name_scope`	Returns a tf.name_scope instance for this class.
`non_trainable_variables`
`non_trainable_weights`	List of all non-trainable weights tracked by this layer.
`outbound_nodes`	Return Functional API nodes downstream of this layer.
`output`	Retrieves the output tensor(s) of a layer.
`output_mask`	Retrieves the output mask tensor(s) of a layer.
`output_shape`	Retrieves the output shape(s) of a layer.
`required_features`
`stateful`
`submodules`	Sequence of all sub-modules.
`supports_masking`	Whether this layer supports computing a mask using compute_mask.
`trainable`
`trainable_variables`
`trainable_weights`	List of all trainable weights tracked by this layer.
`updates`
`variable_dtype`	Alias of Layer.dtype, the dtype of the weights.
`variables`	Returns the list of all layer variables/weights.
`weights`	Returns the list of all layer variables/weights.

add(embeddings: tensorflow.python.framework.ops.Tensor, items_metadata: Dict[str, tensorflow.python.framework.ops.Tensor], training=True)[source]

call(inputs: Dict[str, tensorflow.python.framework.ops.Tensor], item_weights: tensorflow.python.framework.ops.Tensor, training=True) → merlin.models.tf.blocks.core.base.EmbeddingWithMetadata[source]

sample(item_weights) → merlin.models.tf.blocks.core.base.EmbeddingWithMetadata[source]

get_distribution_probs()[source]

Tries to approximate the log uniform (zipfian) distribution used by tf.random.log_uniform_candidate_sampler (https://www.tensorflow.org/api_docs/python/tf/random/log_uniform_candidate_sampler)

Returns: A tensor with the expected probability distribution of item ids assuming log-uniform (zipfian) distribution
Return type: tf.Tensor