tf_agents.bandits.agents.neural_linucb_agent.NeuralLinUCBAgent

An agent implementing the LinUCB algorithm on top of a neural network.

Inherits From: TFAgent

tf_agents.bandits.agents.neural_linucb_agent.NeuralLinUCBAgent(
    time_step_spec: tf_agents.typing.types.TimeStep,
    action_spec: tf_agents.typing.types.BoundedTensorSpec,
    encoding_network: tf_agents.typing.types.Network,
    encoding_network_num_train_steps: int,
    encoding_dim: int,
    optimizer: tf_agents.typing.types.Optimizer,
    variable_collection: Optional[tf_agents.bandits.agents.neural_linucb_agent.NeuralLinUCBVariableCollection] = None,
    alpha: float = 1.0,
    gamma: float = 1.0,
    epsilon_greedy: float = 0.0,
    observation_and_action_constraint_splitter: Optional[types.Splitter] = None,
    accepts_per_arm_features: bool = False,
    distributed_train_encoding_network: bool = False,
    error_loss_fn: tf_agents.typing.types.LossFn = tf.compat.v1.losses.mean_squared_error,
    gradient_clipping: Optional[float] = None,
    debug_summaries: bool = False,
    summarize_grads_and_vars: bool = False,
    train_step_counter: Optional[tf.Variable] = None,
    emit_policy_info: Sequence[Text] = (),
    emit_log_probability: bool = False,
    dtype: tf.DType = tf.float64,
    name: Optional[Text] = 'neural_linucb_agent'
)

time_step_spec A TimeStep spec describing the expected TimeSteps.
action_spec A scalar BoundedTensorSpec with int32 or int64 dtype describing the number of actions for this agent.
encoding_network a Keras network that encodes the observations.
encoding_network_num_train_steps how many training steps to run for training the encoding network before switching to LinUCB. If negative, the encoding network is assumed to be already trained.
encoding_dim the dimension of encoded observations.
optimizer The optimizer to use for training.
variable_collection Instance of NeuralLinUCBVariableCollection. Collection of variables to be updated by the agent. If None, a new instance of LinearBanditVariables will be created. Note that this collection excludes the variables owned by the encoding network.
alpha (float) positive scalar. This is the exploration parameter that multiplies the confidence intervals.
gamma a float forgetting factor in [0.0, 1.0]. When set to 1.0, the algorithm does not forget.
epsilon_greedy A float representing the probability of choosing a random action instead of the greedy action.
observation_and_action_constraint_splitter A function used for masking valid/invalid actions with each state of the environment. The function takes in a full observation and returns a tuple consisting of 1) the part of the observation intended as input to the bandit agent and policy, and 2) the boolean mask. This function should also work with a TensorSpec as input, and should output TensorSpec objects for the observation and mask.
accepts_per_arm_features (bool) Whether the policy accepts per-arm features.
distributed_train_encoding_network (bool) whether to train the encoding network or not. This applies only in distributed training setting. When set to true this agent will train the encoding network. Otherwise, it will assume the encoding network is already trained and will train LinUCB on top of it.
error_loss_fn A function for computing the error loss, taking parameters labels, predictions, and weights (any function from tf.losses would work). The default is tf.losses.mean_squared_error.
gradient_clipping A float representing the norm length to clip gradients (or None for no clipping.)
debug_summaries A Python bool, default False. When True, debug summaries are gathered.
summarize_grads_and_vars A Python bool, default False. When True, gradients and network variable summaries are written during training.
train_step_counter An optional tf.Variable to increment every time the train op is run. Defaults to the global_step.
emit_policy_info (tuple of strings) what side information we want to get as part of the policy info. Allowed values can be found in policy_utilities.PolicyInfo.
emit_log_probability Whether the NeuralLinUCBPolicy emits log-probabilities or not. Since the policy is deterministic, the probability is just 1.
dtype The type of the parameters stored and updated by the agent. Should be one of tf.float32 and tf.float64. Defaults to tf.float64.
name a name for this instance of NeuralLinUCBAgent.

TypeError if variable_collection is not an instance of NeuralLinUCBVariableCollection. ValueError if dtype is not one of tf.float32 or tf.float64.

action_spec TensorSpec describing the action produced by the agent.
actions_from_reward_layer

alpha

collect_data_context

collect_data_spec Returns a Trajectory spec, as expected by the collect_policy.
collect_policy Return a policy that can be used to collect data from the environment.
cov_matrix

data_context

data_vector

debug_summaries

num_actions

num_samples

policy Return the current policy held by the agent.
summaries_enabled

summarize_grads_and_vars

time_step_spec Describes the TimeStep tensors expected by the agent.
train_sequence_length The number of time steps needed in experience tensors passed to train.

Train requires experience to be a Trajectory containing tensors shaped [B, T, ...]. This argument describes the value of T required.

For example, for non-RNN DQN training, T=2 because DQN requires single transitions.

If this value is None, then train can handle an unknown T (it can be determined at runtime from the data). Most RNN-based agents fall into this category.

train_step_counter

training_data_spec Returns a trajectory spec, as expected by the train() function.
update_alpha

Methods

compute_loss_using_linucb

View source

compute_loss_using_linucb(
    observation: tf_agents.typing.types.NestedTensor,
    action: tf_agents.typing.types.Tensor,
    reward: tf_agents.typing.types.Tensor,
    weights: Optional[types.Float] = None,
    training: bool = False
) -> tf_agents.agents.tf_agent.LossInfo

Computes the loss using LinUCB.

Args
observation A batch of observations.
action A batch of actions.
reward A batch of rewards.
weights unused weights.
training Whether the loss is being used to train.

Returns
loss A LossInfo containing the loss for the training step.

compute_loss_using_linucb_distributed

View source

compute_loss_using_linucb_distributed(
    observation: tf_agents.typing.types.NestedTensor,
    action: tf_agents.typing.types.Tensor,
    reward: tf_agents.typing.types.Tensor,
    weights: Optional[types.Float] = None,
    training: bool = False
) -> tf_agents.agents.tf_agent.LossInfo

Computes the loss using LinUCB distributively.

Args
observation A batch of observations.
action A batch of actions.
reward A batch of rewards.
weights unused weights.
training Whether the loss is being used to train.

Returns
loss A LossInfo containing the loss for the training step.

compute_loss_using_reward_layer

View source

compute_loss_using_reward_layer(
    observation: tf_agents.typing.types.NestedTensor,
    action: tf_agents.typing.types.Tensor,
    reward: tf_agents.typing.types.Tensor,
    weights: Optional[types.Float] = None,
    training: bool = False
) -> tf_agents.agents.tf_agent.LossInfo

Computes loss using the reward layer.

Args
observation A batch of observations.
action A batch of actions.
reward A batch of rewards.
weights Optional scalar or elementwise (per-batch-entry) importance weights. The output batch loss will be scaled by these weights, and the final scalar loss is the mean of these values.
training Whether the loss is being used for training.

Returns
loss A LossInfo containing the loss for the training step.

compute_summaries

View source

compute_summaries(
    loss
)

initialize

View source

initialize() -> Optional[tf.Operation]

Initializes the agent.

Returns
An operation that can be used to initialize the agent.

Raises
RuntimeError If the class was not initialized properly (super.__init__ was not called).

loss

View source

loss(
    experience: tf_agents.typing.types.NestedTensor,
    weights: Optional[types.Tensor] = None,
    training: bool = False,
    **kwargs
) -> tf_agents.agents.tf_agent.LossInfo

Gets loss from the agent.

If the user calls this from _train, it must be in a tf.GradientTape scope in order to apply gradients to trainable variables. If intermediate gradient steps are needed, _loss and _train will return different values since _loss only supports updating all gradients at once after all losses have been calculated.

Args
experience A batch of experience data in the form of a Trajectory. The structure of experience must match that of self.training_data_spec. All tensors in experience must be shaped [batch, time, ...] where time must be equal to self.train_step_length if that property is not None.
weights (optional). A Tensor, either 0-D or shaped [batch], containing weights to be used when calculating the total train loss. Weights are typically multiplied elementwise against the per-batch loss, but the implementation is up to the Agent.
training Explicit argument to pass to loss. This typically affects network computation paths like dropout and batch normalization.
**kwargs Any additional data as args to loss.

Returns
A LossInfo loss tuple containing loss and info tensors.

Raises
RuntimeError If the class was not initialized properly (super.__init__ was not called).

post_process_policy

View source

post_process_policy() -> tf_agents.policies.TFPolicy

Post process policies after training.

The policies of some agents require expensive post processing after training before they can be used. e.g. A Recommender agent might require rebuilding an index of actions. For such agents, this method will return a post processed version of the policy. The post processing may either update the existing policies in place or create a new policy, depnding on the agent. The default implementation for agents that do not want to override this method is to return agent.policy.

Returns
The post processed policy.

preprocess_sequence

View source

preprocess_sequence(
    experience: tf_agents.typing.types.NestedTensor
) -> tf_agents.typing.types.NestedTensor

Defines preprocess_sequence function to be fed into replay buffers.

This defines how we preprocess the collected data before training. Defaults to pass through for most agents. Structure of experience must match that of self.collect_data_spec.

Args
experience a Trajectory shaped [batch, time, ...] or [time, ...] which represents the collected experience data.

Returns
A post processed Trajectory with the same shape as the input.

train

View source

train(
    experience: tf_agents.typing.types.NestedTensor,
    weights: Optional[types.Tensor] = None,
    **kwargs
) -> tf_agents.agents.tf_agent.LossInfo

Trains the agent.

Args
experience A batch of experience data in the form of a Trajectory. The structure of experience must match that of self.training_data_spec. All tensors in experience must be shaped [batch, time, ...] where time must be equal to self.train_step_length if that property is not None.
weights (optional). A Tensor, either 0-D or shaped [batch], containing weights to be used when calculating the total train loss. Weights are typically multiplied elementwise against the per-batch loss, but the implementation is up to the Agent.
**kwargs Any additional data to pass to the subclass.

Returns
A LossInfo loss tuple containing loss and info tensors.

  • In eager mode, the loss values are first calculated, then a train step is performed before they are returned.
  • In graph mode, executing any or all of the loss tensors will first calculate the loss value(s), then perform a train step, and return the pre-train-step LossInfo.

Raises
RuntimeError If the class was not initialized properly (super.__init__ was not called).