class_docstr: Builds a tf.estimator.Estimator for a TF-Ranking model.
  
  An example use case is provided below:
  
  ```python
  import tensorflow as tf
  import tensorflow_ranking as tfr
  
  def scoring_function(context_features, example_features, mode):
    # ...
    # scoring logic
    # ...
    return scores # tensors with shape [batch_size, ...]
  
  context_feature_columns = {
    "c1": tf.feature_column.numeric_column("c1", shape=(1,))
  }
  example_feature_columns = {
    "e1": tf.feature_column.numeric_column("e1", shape=(1,))
  }
  hparams = dict(
      checkpoint_secs=120,
      listwise_inference=False,
      loss="softmax_loss",
      model_dir="/path/to/your/model_dir/",
      num_checkpoints=100)
  ranking_estimator = tfr.estimator.EstimatorBuilder(
        context_feature_columns,
        example_feature_columns,
        scoring_function=scoring_function,
        hparams=hparams).make_estimator()
  ```
  
  If you want to customize certain `EstimatorBuilder` behaviors, please create
  a subclass of `EstimatorBuilder`, and overwrite related functions. Right now,
  we recommend only overwriting the `_eval_metric_fns` for your eval metrics.
  For instance, if you need MAP (Mean Average Precision) as your evaluation
  metric, you can do the following:
  
  ```python
  class MyEstimatorBuilder(tfr.estimator.EstimatorBuilder):
    def _eval_metric_fns(self):
      metric_fns = {}
      metric_fns.update({
          "metric/ndcg@%d" % topn: tfr.metrics.make_ranking_metric_fn(
              tfr.metrics.RankingMetricKey.MAP, topn=topn) for topn in [5, 10]
      })
      return metric_fns
  
  # Then, you can define your estimator with:
  ranking_estimator = MyEstimatorBuilder(
        context_feature_columns,
        example_feature_columns,
        scoring_function=scoring_function,
        hparams=hparams).make_estimator()
  ```
  
  If you really need to overwrite other functions, particularly `_transform_fn`,
  `_group_score_fn` and `model_fn`, please be careful because the passed-in
  parameters might no longer be used.
class_docstr_tok: ["Builds","a","tf.estimator.Estimator","for","a","TF-Ranking","model",".","An","example","use","case","is","provided","below",":","``","`","python","import","tensorflow","as","tf","import","tensorflow_ranking","as","tfr","def","scoring_function","(","context_features",",","example_features",",","mode",")",":","#","...","#","scoring","logic","#","...","return","scores","#","tensors","with","shape","[","batch_size",",","...","]","context_feature_columns","=","{","``","c1","''",":","tf.feature_column.numeric_column","(","``","c1","''",",","shape=","(","1",",",")",")","}","example_feature_columns","=","{","``","e1","''",":","tf.feature_column.numeric_column","(","``","e1","''",",","shape=","(","1",",",")",")","}","hparams","=","dict","(","checkpoint_secs=120",",","listwise_inference=False",",","loss=","''","softmax_loss","''",",","model_dir=","''","\/path\/to\/your\/model_dir\/","''",",","num_checkpoints=100",")","ranking_estimator","=","tfr.estimator.EstimatorBuilder","(","context_feature_columns",",","example_feature_columns",",","scoring_function=scoring_function",",","hparams=hparams",")",".make_estimator","(",")","``","`","If","you","want","to","customize","certain","`","EstimatorBuilder","`","behaviors",",","please","create","a","subclass","of","`","EstimatorBuilder","`",",","and","overwrite","related","functions",".","Right","now",",","we","recommend","only","overwriting","the","`","_eval_metric_fns","`","for","your","eval","metrics",".","For","instance",",","if","you","need","MAP","(","Mean","Average","Precision",")","as","your","evaluation","metric",",","you","can","do","the","following",":","``","`","python","class","MyEstimatorBuilder","(","tfr.estimator.EstimatorBuilder",")",":","def","_eval_metric_fns","(","self",")",":","metric_fns","=","{","}","metric_fns.update","(","{","``","metric\/ndcg","@","%","d","''","%","topn",":","tfr.metrics.make_ranking_metric_fn","(","tfr.metrics.RankingMetricKey.MAP",",","topn=topn",")","for","topn","in","[","5",",","10","]","}",")","return","metric_fns","#","Then",",","you","can","define","your","estimator","with",":","ranking_estimator","=","MyEstimatorBuilder","(","context_feature_columns",",","example_feature_columns",",","scoring_function=scoring_function",",","hparams=hparams",")",".make_estimator","(",")","``","`","If","you","really","need","to","overwrite","other","functions",",","particularly","`","_transform_fn","`",",","`","_group_score_fn","`","and","`","model_fn","`",",","please","be","careful","because","the","passed-in","parameters","might","no","longer","be","used","."]
docstr: Constructor.
  
  Args:
    context_feature_columns: (dict) Context (aka, query) feature columns.
    example_feature_columns: (dict) Example (aka, document) feature columns.
    scoring_function: (function) A user-provided scoring function with the
      below signatures:
      * Args:
        `context_features`: (dict) A dict of Tensors with the shape
          [batch_size, ...].
        `example_features`: (dict) A dict of Tensors with the shape
          [batch_size, ...].
        `mode`: (`estimator.ModeKeys`) Specifies if this is for training,
          evaluation or inference. See ModeKeys.
      * Returns: The computed logits, a Tensor of shape [batch_size, 1].
    transform_function: (function) A user-provided function that transforms
      raw features into dense Tensors with the following signature:
      * Args:
        `features`: (dict) A dict of Tensors or SparseTensors containing the
          raw features from an `input_fn`.
        `mode`: (`estimator.ModeKeys`) Specifies if this is for training,
          evaluation or inference. See ModeKeys.
      * Returns:
        `context_features`: (dict) A dict of Tensors with the shape
          [batch_size, ...].
        `example_features`: (dict) A dict of Tensors with the shape
          [batch_size, list_size, ...].
    optimizer: (`tf.Optimizer`) An `Optimizer` object for model optimzation.
    loss_reduction: (str) An enum of strings indicating the loss reduction
      type. See type definition in the `tf.compat.v1.losses.Reduction`.
    hparams: (dict) A dict containing model hyperparameters.
  
  Raises:
    ValueError: If the `example_feature_columns` is None.
    ValueError: If the `scoring_function` is None..
    ValueError: If both the `optimizer` and the `hparams["learning_rate"]`
      are not specified.
docstr_tok: ["Constructor",".","Args",":","context_feature_columns",":","(","dict",")","Context","(","aka",",","query",")","feature","columns",".","example_feature_columns",":","(","dict",")","Example","(","aka",",","document",")","feature","columns",".","scoring_function",":","(","function",")","A","user-provided","scoring","function","with","the","below","signatures",":","*","Args",":","`","context_features","`",":","(","dict",")","A","dict","of","Tensors","with","the","shape","[","batch_size",",","...","]",".","`","example_features","`",":","(","dict",")","A","dict","of","Tensors","with","the","shape","[","batch_size",",","...","]",".","`","mode","`",":","(","`","estimator.ModeKeys","`",")","Specifies","if","this","is","for","training",",","evaluation","or","inference",".","See","ModeKeys",".","*","Returns",":","The","computed","logits",",","a","Tensor","of","shape","[","batch_size",",","1","]",".","transform_function",":","(","function",")","A","user-provided","function","that","transforms","raw","features","into","dense","Tensors","with","the","following","signature",":","*","Args",":","`","features","`",":","(","dict",")","A","dict","of","Tensors","or","SparseTensors","containing","the","raw","features","from","an","`","input_fn","`",".","`","mode","`",":","(","`","estimator.ModeKeys","`",")","Specifies","if","this","is","for","training",",","evaluation","or","inference",".","See","ModeKeys",".","*","Returns",":","`","context_features","`",":","(","dict",")","A","dict","of","Tensors","with","the","shape","[","batch_size",",","...","]",".","`","example_features","`",":","(","dict",")","A","dict","of","Tensors","with","the","shape","[","batch_size",",","list_size",",","...","]",".","optimizer",":","(","`","tf.Optimizer","`",")","An","`","Optimizer","`","object","for","model","optimzation",".","loss_reduction",":","(","str",")","An","enum","of","strings","indicating","the","loss","reduction","type",".","See","type","definition","in","the","`","tf.compat.v1.losses.Reduction","`",".","hparams",":","(","dict",")","A","dict","containing","model","hyperparameters",".","Raises",":","ValueError",":","If","the","`","example_feature_columns","`","is","None",".","ValueError",":","If","the","`","scoring_function","`","is","None","..","ValueError",":","If","both","the","`","optimizer","`","and","the","`","hparams","[","``","learning_rate","''","]","`","are","not","specified","."]
code: def __init__(
      self,
      context_feature_columns,
      example_feature_columns,
      scoring_function,
      transform_function=None,
      optimizer=None,
      loss_reduction=None,
      hparams=None,
  ):
      """Constructor.
  
      Args:
        context_feature_columns: (dict) Context (aka, query) feature columns.
        example_feature_columns: (dict) Example (aka, document) feature columns.
        scoring_function: (function) A user-provided scoring function with the
          below signatures:
          * Args:
            `context_features`: (dict) A dict of Tensors with the shape
              [batch_size, ...].
            `example_features`: (dict) A dict of Tensors with the shape
              [batch_size, ...].
            `mode`: (`estimator.ModeKeys`) Specifies if this is for training,
              evaluation or inference. See ModeKeys.
          * Returns: The computed logits, a Tensor of shape [batch_size, 1].
        transform_function: (function) A user-provided function that transforms
          raw features into dense Tensors with the following signature:
          * Args:
            `features`: (dict) A dict of Tensors or SparseTensors containing the
              raw features from an `input_fn`.
            `mode`: (`estimator.ModeKeys`) Specifies if this is for training,
              evaluation or inference. See ModeKeys.
          * Returns:
            `context_features`: (dict) A dict of Tensors with the shape
              [batch_size, ...].
            `example_features`: (dict) A dict of Tensors with the shape
              [batch_size, list_size, ...].
        optimizer: (`tf.Optimizer`) An `Optimizer` object for model optimzation.
        loss_reduction: (str) An enum of strings indicating the loss reduction
          type. See type definition in the `tf.compat.v1.losses.Reduction`.
        hparams: (dict) A dict containing model hyperparameters.
  
      Raises:
        ValueError: If the `example_feature_columns` is None.
        ValueError: If the `scoring_function` is None..
        ValueError: If both the `optimizer` and the `hparams["learning_rate"]`
          are not specified.
      """
      if example_feature_columns is None:
          raise ValueError(
              "The `example_feature_columns` is not specified!"
          )
  
      if scoring_function is None:
          raise ValueError(
              "The `scoring_function` needs to be specified!"
          )
  
      self._context_feature_columns = context_feature_columns
      self._example_feature_columns = example_feature_columns
      self._scoring_function = scoring_function
      self._transform_function = transform_function
      self._hparams = hparams
      self._validate_function_args_and_hparams()
  
      if not optimizer and not hparams.get("learning_rate"):
          raise ValueError(
              "Please specify either the `optimizer` or the "
              "`learning_rate` in `hparams`!"
          )
      if optimizer and hparams.get("learning_rate"):
          tf.compat.v1.logging.warning(
              "`learning_rate` from `hparams` is ignored "
              "as the `optimizer` has been specified!"
          )
      self._optimizer = (
          optimizer
          or tf.compat.v1.train.AdagradOptimizer(
              learning_rate=hparams.get("learning_rate")
          )
      )
  
      self._loss_reduction = (
          loss_reduction or tf.compat.v1.losses.Reduction.SUM
      )
  
imports: import tensorflow
  from tensorflow import estimator
  from tensorflow.python.util import function_utils
  from tensorflow_ranking.python import feature
  from tensorflow_ranking.python import head
  from tensorflow_ranking.python import losses
  from tensorflow_ranking.python import metrics
  from tensorflow_ranking.python import model
  from tensorflow_ranking.python import utils
label_desc: Use image node_id 1 to create a new EstimatorBuilder object from inherited base classes: object with example: obj = EstimatorBuilder(context_feature_columns, example_feature_columns, scoring_function, transform_function, optimizer, loss_reduction, hparams)