[TOC]

High level API for learning with TensorFlow.

Train and evaluate TensorFlow models.

Abstract BaseEstimator class to train and evaluate TensorFlow models.

Concrete implementation of this class should provide the following functions:

• _get_train_ops
• _get_eval_ops
• _get_predict_ops

Estimator implemented below is a good example of how to use this class.

Initializes a BaseEstimator instance.

• model_dir: Directory to save model parameters, graph and etc. This can also be used to load checkpoints from the directory into a estimator to continue training a previously saved model.
• config: A RunConfig instance.

See Evaluable. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-12-01. Instructions for updating: Estimator is decoupled from Scikit Learn interface by moving into separate class SKCompat. Arguments x, y and batch_size are only available in the SKCompat class, Estimator will only accept input_fn.

est = Estimator(...) -> est = SKCompat(Estimator(...))

• ValueError: If at least one of x or y is provided, and at least one of input_fn or feed_fn is provided. Or if metrics is not None or dict.

Exports inference graph into given dir. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-09-23. Instructions for updating: The signature of the input_fn accepted by export is changing to be consistent with what's used by tf.Learn Estimator's train/evaluate. input_fn (and in most cases, input_feature_key) will become required args, and use_deprecated_input_fn will default to False and be removed altogether.

• export_dir: A string containing a directory to write the exported graph and checkpoints.
• input_fn: If use_deprecated_input_fn is true, then a function that given Tensor of Example strings, parses it into features that are then passed to the model. Otherwise, a function that takes no argument and returns a tuple of (features, labels), where features is a dict of string key to Tensor and labels is a Tensor that's currently not used (and so can be None).
• input_feature_key: Only used if use_deprecated_input_fn is false. String key into the features dict returned by input_fn that corresponds to a the raw Example strings Tensor that the exported model will take as input. Can only be None if you're using a custom signature_fn that does not use the first arg (examples).
• use_deprecated_input_fn: Determines the signature format of input_fn.
• signature_fn: Function that returns a default signature and a named signature map, given Tensor of Example strings, dict of Tensors for features and Tensor or dict of Tensors for predictions.
• prediction_key: The key for a tensor in the predictions dict (output from the model_fn) to use as the predictions input to the signature_fn. Optional. If None, predictions will pass to signature_fn without filtering.
• default_batch_size: Default batch size of the Example placeholder.
• exports_to_keep: Number of exports to keep.

The string path to the exported directory. NB: this functionality was added ca. 2016/09/25; clients that depend on the return value may need to handle the case where this function returns None because subclasses are not returning a value.

See Trainable. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-12-01. Instructions for updating: Estimator is decoupled from Scikit Learn interface by moving into separate class SKCompat. Arguments x, y and batch_size are only available in the SKCompat class, Estimator will only accept input_fn.

est = Estimator(...) -> est = SKCompat(Estimator(...))

• ValueError: If x or y are not None while input_fn is not None.
• ValueError: If both steps and max_steps are not None.

Get parameters for this estimator.

• deep: boolean, optional

  If True, will return the parameters for this estimator and contained subobjects that are estimators.

params : mapping of string to any Parameter names mapped to their values.

Returns list of all variable names in this model.

List of names.

Returns value of the variable given by name.

• name: string, name of the tensor.

Numpy array - value of the tensor.

Incremental fit on a batch of samples. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-12-01. Instructions for updating: Estimator is decoupled from Scikit Learn interface by moving into separate class SKCompat. Arguments x, y and batch_size are only available in the SKCompat class, Estimator will only accept input_fn.

est = Estimator(...) -> est = SKCompat(Estimator(...))

This method is expected to be called several times consecutively on different or the same chunks of the dataset. This either can implement iterative training or out-of-core/online training.

This is especially useful when the whole dataset is too big to fit in memory at the same time. Or when model is taking long time to converge, and you want to split up training into subparts.

• x: Matrix of shape [n_samples, n_features...]. Can be iterator that returns arrays of features. The training input samples for fitting the model. If set, input_fn must be None.
• y: Vector or matrix [n_samples] or [n_samples, n_outputs]. Can be iterator that returns array of labels. The training label values (class labels in classification, real numbers in regression). If set, input_fn must be None.
• input_fn: Input function. If set, x, y, and batch_size must be None.
• steps: Number of steps for which to train model. If None, train forever.
• batch_size: minibatch size to use on the input, defaults to first dimension of x. Must be None if input_fn is provided.
• monitors: List of BaseMonitor subclass instances. Used for callbacks inside the training loop.

self, for chaining.

• ValueError: If at least one of x and y is provided, and input_fn is provided.

Returns predictions for given features. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-12-01. Instructions for updating: Estimator is decoupled from Scikit Learn interface by moving into separate class SKCompat. Arguments x, y and batch_size are only available in the SKCompat class, Estimator will only accept input_fn.

est = Estimator(...) -> est = SKCompat(Estimator(...))

• x: Matrix of shape [n_samples, n_features...]. Can be iterator that returns arrays of features. The training input samples for fitting the model. If set, input_fn must be None.
• input_fn: Input function. If set, x and 'batch_size' must be None.
• batch_size: Override default batch size. If set, 'input_fn' must be 'None'.
• outputs: list of str, name of the output to predict. If None, returns all.
• as_iterable: If True, return an iterable which keeps yielding predictions for each example until inputs are exhausted. Note: The inputs must terminate if you want the iterable to terminate (e.g. be sure to pass num_epochs=1 if you are using something like read_batch_features).

A numpy array of predicted classes or regression values if the constructor's model_fn returns a Tensor for predictions or a dict of numpy arrays if model_fn returns a dict. Returns an iterable of predictions if as_iterable is True.

• ValueError: If x and input_fn are both provided or both None.

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as pipelines). The former have parameters of the form <component>__<parameter> so that it's possible to update each component of a nested object.

• **params: Parameters.

self

• ValueError: If params contain invalid names.

Estimator class is the basic TensorFlow model trainer/evaluator.

Constructs an Estimator instance.

• model_fn: Model function. Follows the signature:

  • Args:

    • features: single Tensor or dict of Tensors (depending on data passed to fit),
    • labels: Tensor or dict of Tensors (for multi-head models). If mode is ModeKeys.INFER, labels=None will be passed. If the model_fn's signature does not accept mode, the model_fn must still be able to handle labels=None.
    • mode: Optional. Specifies if this training, evaluation or prediction. See ModeKeys.
    • params: Optional dict of hyperparameters. Will receive what is passed to Estimator in params parameter. This allows to configure Estimators from hyper parameter tuning.
    • config: Optional configuration object. Will receive what is passed to Estimator in config parameter, or the default config. Allows updating things in your model_fn based on configuration such as num_ps_replicas.
    • model_dir: Optional directory where model parameters, graph etc are saved. Will receive what is passed to Estimator in model_dir parameter, or the default model_dir. Allows updating things in your model_fn that expect model_dir, such as training hooks.

  • Returns: ModelFnOps

  Also supports a legacy signature which returns tuple of:

  • predictions: Tensor, SparseTensor or dictionary of same. Can also be any type that is convertible to a Tensor or SparseTensor, or dictionary of same.
  • loss: Scalar loss Tensor.
  • train_op: Training update Tensor or Operation.

  Supports next three signatures for the function:

  • (features, labels) -> (predictions, loss, train_op)
  • (features, labels, mode) -> (predictions, loss, train_op)
  • (features, labels, mode, params) -> (predictions, loss, train_op)
  • (features, labels, mode, params, config) -> (predictions, loss, train_op)
  • (features, labels, mode, params, config, model_dir) -> (predictions, loss, train_op)

• model_dir: Directory to save model parameters, graph and etc. This can also be used to load checkpoints from the directory into a estimator to continue training a previously saved model.

• config: Configuration object.

• params: dict of hyper parameters that will be passed into model_fn. Keys are names of parameters, values are basic python types.

• feature_engineering_fn: Feature engineering function. Takes features and labels which are the output of input_fn and returns features and labels which will be fed into model_fn. Please check model_fn for a definition of features and labels.

• ValueError: parameters of model_fn don't match params.

See Evaluable. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-12-01. Instructions for updating: Estimator is decoupled from Scikit Learn interface by moving into separate class SKCompat. Arguments x, y and batch_size are only available in the SKCompat class, Estimator will only accept input_fn.

est = Estimator(...) -> est = SKCompat(Estimator(...))

• ValueError: If at least one of x or y is provided, and at least one of input_fn or feed_fn is provided. Or if metrics is not None or dict.

Exports inference graph into given dir. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-09-23. Instructions for updating: The signature of the input_fn accepted by export is changing to be consistent with what's used by tf.Learn Estimator's train/evaluate. input_fn (and in most cases, input_feature_key) will become required args, and use_deprecated_input_fn will default to False and be removed altogether.

• export_dir: A string containing a directory to write the exported graph and checkpoints.
• input_fn: If use_deprecated_input_fn is true, then a function that given Tensor of Example strings, parses it into features that are then passed to the model. Otherwise, a function that takes no argument and returns a tuple of (features, labels), where features is a dict of string key to Tensor and labels is a Tensor that's currently not used (and so can be None).
• input_feature_key: Only used if use_deprecated_input_fn is false. String key into the features dict returned by input_fn that corresponds to a the raw Example strings Tensor that the exported model will take as input. Can only be None if you're using a custom signature_fn that does not use the first arg (examples).
• use_deprecated_input_fn: Determines the signature format of input_fn.
• signature_fn: Function that returns a default signature and a named signature map, given Tensor of Example strings, dict of Tensors for features and Tensor or dict of Tensors for predictions.
• prediction_key: The key for a tensor in the predictions dict (output from the model_fn) to use as the predictions input to the signature_fn. Optional. If None, predictions will pass to signature_fn without filtering.
• default_batch_size: Default batch size of the Example placeholder.
• exports_to_keep: Number of exports to keep.

The string path to the exported directory. NB: this functionality was added ca. 2016/09/25; clients that depend on the return value may need to handle the case where this function returns None because subclasses are not returning a value.

Exports inference graph as a SavedModel into given dir. (experimental)

THIS FUNCTION IS EXPERIMENTAL. It may change or be removed at any time, and without warning.

• export_dir_base: A string containing a directory to write the exported graph and checkpoints.
• input_fn: A function that takes no argument and returns an InputFnOps.
• default_output_alternative_key: the name of the head to serve when none is specified.
• assets_extra: A dict specifying how to populate the assets.extra directory within the exported SavedModel. Each key should give the destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
• as_text: whether to write the SavedModel proto in text format.
• exports_to_keep: Number of exports to keep.

The string path to the exported directory.

• ValueError: if an unrecognized export_type is requested.

See Trainable. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-12-01. Instructions for updating: Estimator is decoupled from Scikit Learn interface by moving into separate class SKCompat. Arguments x, y and batch_size are only available in the SKCompat class, Estimator will only accept input_fn.

est = Estimator(...) -> est = SKCompat(Estimator(...))

• ValueError: If x or y are not None while input_fn is not None.
• ValueError: If both steps and max_steps are not None.

Get parameters for this estimator.

• deep: boolean, optional

  If True, will return the parameters for this estimator and contained subobjects that are estimators.

params : mapping of string to any Parameter names mapped to their values.

Returns list of all variable names in this model.

List of names.

Returns value of the variable given by name.

• name: string, name of the tensor.

Numpy array - value of the tensor.

Incremental fit on a batch of samples. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-12-01. Instructions for updating: Estimator is decoupled from Scikit Learn interface by moving into separate class SKCompat. Arguments x, y and batch_size are only available in the SKCompat class, Estimator will only accept input_fn.

est = Estimator(...) -> est = SKCompat(Estimator(...))

This method is expected to be called several times consecutively on different or the same chunks of the dataset. This either can implement iterative training or out-of-core/online training.

This is especially useful when the whole dataset is too big to fit in memory at the same time. Or when model is taking long time to converge, and you want to split up training into subparts.

• x: Matrix of shape [n_samples, n_features...]. Can be iterator that returns arrays of features. The training input samples for fitting the model. If set, input_fn must be None.
• y: Vector or matrix [n_samples] or [n_samples, n_outputs]. Can be iterator that returns array of labels. The training label values (class labels in classification, real numbers in regression). If set, input_fn must be None.
• input_fn: Input function. If set, x, y, and batch_size must be None.
• steps: Number of steps for which to train model. If None, train forever.
• batch_size: minibatch size to use on the input, defaults to first dimension of x. Must be None if input_fn is provided.
• monitors: List of BaseMonitor subclass instances. Used for callbacks inside the training loop.

self, for chaining.

• ValueError: If at least one of x and y is provided, and input_fn is provided.

Returns predictions for given features. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-12-01. Instructions for updating: Estimator is decoupled from Scikit Learn interface by moving into separate class SKCompat. Arguments x, y and batch_size are only available in the SKCompat class, Estimator will only accept input_fn.

est = Estimator(...) -> est = SKCompat(Estimator(...))

• x: Matrix of shape [n_samples, n_features...]. Can be iterator that returns arrays of features. The training input samples for fitting the model. If set, input_fn must be None.
• input_fn: Input function. If set, x and 'batch_size' must be None.
• batch_size: Override default batch size. If set, 'input_fn' must be 'None'.
• outputs: list of str, name of the output to predict. If None, returns all.
• as_iterable: If True, return an iterable which keeps yielding predictions for each example until inputs are exhausted. Note: The inputs must terminate if you want the iterable to terminate (e.g. be sure to pass num_epochs=1 if you are using something like read_batch_features).

A numpy array of predicted classes or regression values if the constructor's model_fn returns a Tensor for predictions or a dict of numpy arrays if model_fn returns a dict. Returns an iterable of predictions if as_iterable is True.

• ValueError: If x and input_fn are both provided or both None.

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as pipelines). The former have parameters of the form <component>__<parameter> so that it's possible to update each component of a nested object.

• **params: Parameters.

self

• ValueError: If params contain invalid names.

Interface for objects that are trainable by, e.g., Experiment.

Trains a model given training data x predictions and y labels.

• x: Matrix of shape [n_samples, n_features...] or the dictionary of Matrices. Can be iterator that returns arrays of features or dictionary of arrays of features. The training input samples for fitting the model. If set, input_fn must be None.

• y: Vector or matrix [n_samples] or [n_samples, n_outputs] or the dictionary of same. Can be iterator that returns array of labels or dictionary of array of labels. The training label values (class labels in classification, real numbers in regression). If set, input_fn must be None. Note: For classification, label values must be integers representing the class index (i.e. values from 0 to n_classes-1).

• input_fn: Input function returning a tuple of: features - Tensor or dictionary of string feature name to Tensor. labels - Tensor or dictionary of Tensor with labels. If input_fn is set, x, y, and batch_size must be None.

• steps: Number of steps for which to train model. If None, train forever. 'steps' works incrementally. If you call two times fit(steps=10) then training occurs in total 20 steps. If you don't want to have incremental behaviour please set max_steps instead. If set, max_steps must be None.

• batch_size: minibatch size to use on the input, defaults to first dimension of x. Must be None if input_fn is provided.

• monitors: List of BaseMonitor subclass instances. Used for callbacks inside the training loop.

• max_steps: Number of total steps for which to train model. If None, train forever. If set, steps must be None.

  Two calls to fit(steps=100) means 200 training iterations. On the other hand, two calls to fit(max_steps=100) means that the second call will not do any iteration since first call did all 100 steps.

self, for chaining.

Interface for objects that are evaluatable by, e.g., Experiment.

Evaluates given model with provided evaluation data.

Stop conditions - we evaluate on the given input data until one of the following:

• If steps is provided, and steps batches of size batch_size are processed.
• If input_fn is provided, and it raises an end-of-input exception (OutOfRangeError or StopIteration).
• If x is provided, and all items in x have been processed.

The return value is a dict containing the metrics specified in metrics, as well as an entry global_step which contains the value of the global step for which this evaluation was performed.

• x: Matrix of shape [n_samples, n_features...] or dictionary of many matrices containing the input samples for fitting the model. Can be iterator that returns arrays of features or dictionary of array of features. If set, input_fn must be None.

• y: Vector or matrix [n_samples] or [n_samples, n_outputs] containing the label values (class labels in classification, real numbers in regression) or dictionary of multiple vectors/matrices. Can be iterator that returns array of targets or dictionary of array of targets. If set, input_fn must be None. Note: For classification, label values must be integers representing the class index (i.e. values from 0 to n_classes-1).

• input_fn: Input function returning a tuple of: features - Dictionary of string feature name to Tensor or Tensor. labels - Tensor or dictionary of Tensor with labels. If input_fn is set, x, y, and batch_size must be None. If steps is not provided, this should raise OutOfRangeError or StopIteration after the desired amount of data (e.g., one epoch) has been provided. See "Stop conditions" above for specifics.

• feed_fn: Function creating a feed dict every time it is called. Called once per iteration. Must be None if input_fn is provided.

• batch_size: minibatch size to use on the input, defaults to first dimension of x, if specified. Must be None if input_fn is provided.

• steps: Number of steps for which to evaluate model. If None, evaluate until x is consumed or input_fn raises an end-of-input exception. See "Stop conditions" above for specifics.

• metrics: Dict of metrics to run. If None, the default metric functions are used; if {}, no metrics are used. Otherwise, metrics should map friendly names for the metric to a MetricSpec object defining which model outputs to evaluate against which labels with which metric function.

  Metric ops should support streaming, e.g., returning update_op and value tensors. For example, see the options defined in ../../../metrics/python/ops/metrics_ops.py.

• name: Name of the evaluation if user needs to run multiple evaluations on different data sets, such as on training data vs test data.

• checkpoint_path: Path of a specific checkpoint to evaluate. If None, the latest checkpoint in model_dir is used.

• hooks: List of SessionRunHook subclass instances. Used for callbacks inside the evaluation call.

Returns dict with evaluation results.

Returns a path in which the eval process will look for checkpoints.

Standard names for model modes.

The following standard keys are defined:

• TRAIN: training mode.
• EVAL: evaluation mode.
• INFER: inference mode.

A classifier for TensorFlow DNN models.

Example:

sparse_feature_a = sparse_column_with_hash_bucket(...)
sparse_feature_b = sparse_column_with_hash_bucket(...)

sparse_feature_a_emb = embedding_column(sparse_id_column=sparse_feature_a,
                                        ...)
sparse_feature_b_emb = embedding_column(sparse_id_column=sparse_feature_b,
                                        ...)

estimator = DNNClassifier(
    feature_columns=[sparse_feature_a_emb, sparse_feature_b_emb],
    hidden_units=[1024, 512, 256])

# Or estimator using the ProximalAdagradOptimizer optimizer with
# regularization.
estimator = DNNClassifier(
    feature_columns=[sparse_feature_a_emb, sparse_feature_b_emb],
    hidden_units=[1024, 512, 256],
    optimizer=tf.train.ProximalAdagradOptimizer(
      learning_rate=0.1,
      l1_regularization_strength=0.001
    ))

# Input builders
def input_fn_train: # returns x, y (where y represents label's class index).
  pass
estimator.fit(input_fn=input_fn_train)

def input_fn_eval: # returns x, y (where y represents label's class index).
  pass
estimator.evaluate(input_fn=input_fn_eval)
estimator.predict(x=x) # returns predicted labels (i.e. label's class index).

Input of fit and evaluate should have following features, otherwise there will be a KeyError:

• if weight_column_name is not None, a feature with key=weight_column_name whose value is a Tensor.
• for each column in feature_columns:
  • if column is a SparseColumn, a feature with key=column.name whose value is a SparseTensor.
  • if column is a WeightedSparseColumn, two features: the first with key the id column name, the second with key the weight column name. Both features' value must be a SparseTensor.
  • if column is a RealValuedColumn, a feature with key=column.name whose value is a Tensor.

Initializes a DNNClassifier instance.

• hidden_units: List of hidden units per layer. All layers are fully connected. Ex. [64, 32] means first layer has 64 nodes and second one has 32.
• feature_columns: An iterable containing all the feature columns used by the model. All items in the set should be instances of classes derived from FeatureColumn.
• model_dir: Directory to save model parameters, graph and etc. This can also be used to load checkpoints from the directory into a estimator to continue training a previously saved model.
• n_classes: number of label classes. Default is binary classification. It must be greater than 1. Note: Class labels are integers representing the class index (i.e. values from 0 to n_classes-1). For arbitrary label values (e.g. string labels), convert to class indices first.
• weight_column_name: A string defining feature column name representing weights. It is used to down weight or boost examples during training. It will be multiplied by the loss of the example.
• optimizer: An instance of tf.Optimizer used to train the model. If None, will use an Adagrad optimizer.
• activation_fn: Activation function applied to each layer. If None, will use tf.nn.relu.
• dropout: When not None, the probability we will drop out a given coordinate.
• gradient_clip_norm: A float > 0. If provided, gradients are clipped to their global norm with this clipping ratio. See tf.clip_by_global_norm for more details.
• enable_centered_bias: A bool. If True, estimator will learn a centered bias variable for each class. Rest of the model structure learns the residual after centered bias.
• config: RunConfig object to configure the runtime settings.
• feature_engineering_fn: Feature engineering function. Takes features and labels which are the output of input_fn and returns features and labels which will be fed into the model.
• embedding_lr_multipliers: Optional. A dictionary from EmbeddingColumn to a float multiplier. Multiplier will be used to multiply with learning rate for the embedding variables.
• input_layer_min_slice_size: Optional. The min slice size of input layer partitions. If not provided, will use the default of 64M.

A DNNClassifier estimator.

• ValueError: If n_classes < 2.

DEPRECATED FUNCTION

THIS FUNCTION IS DEPRECATED. It will be removed after 2016-10-30. Instructions for updating: This method will be removed after the deprecation date. To inspect variables, use get_variable_names() and get_variable_value().

See Evaluable. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-12-01. Instructions for updating: Estimator is decoupled from Scikit Learn interface by moving into separate class SKCompat. Arguments x, y and batch_size are only available in the SKCompat class, Estimator will only accept input_fn.

est = Estimator(...) -> est = SKCompat(Estimator(...))

• ValueError: If at least one of x or y is provided, and at least one of input_fn or feed_fn is provided. Or if metrics is not None or dict.

See BaseEstimator.export.

Exports inference graph as a SavedModel into given dir. (experimental)

THIS FUNCTION IS EXPERIMENTAL. It may change or be removed at any time, and without warning.

• export_dir_base: A string containing a directory to write the exported graph and checkpoints.
• input_fn: A function that takes no argument and returns an InputFnOps.
• default_output_alternative_key: the name of the head to serve when none is specified.
• assets_extra: A dict specifying how to populate the assets.extra directory within the exported SavedModel. Each key should give the destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
• as_text: whether to write the SavedModel proto in text format.
• exports_to_keep: Number of exports to keep.

The string path to the exported directory.

• ValueError: if an unrecognized export_type is requested.

See Trainable. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-12-01. Instructions for updating: Estimator is decoupled from Scikit Learn interface by moving into separate class SKCompat. Arguments x, y and batch_size are only available in the SKCompat class, Estimator will only accept input_fn.

est = Estimator(...) -> est = SKCompat(Estimator(...))

• ValueError: If x or y are not None while input_fn is not None.
• ValueError: If both steps and max_steps are not None.

Get parameters for this estimator.

• deep: boolean, optional

  If True, will return the parameters for this estimator and contained subobjects that are estimators.

params : mapping of string to any Parameter names mapped to their values.

Returns list of all variable names in this model.

List of names.

Returns value of the variable given by name.

• name: string, name of the tensor.

Numpy array - value of the tensor.

Incremental fit on a batch of samples. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-12-01. Instructions for updating: Estimator is decoupled from Scikit Learn interface by moving into separate class SKCompat. Arguments x, y and batch_size are only available in the SKCompat class, Estimator will only accept input_fn.

est = Estimator(...) -> est = SKCompat(Estimator(...))

This method is expected to be called several times consecutively on different or the same chunks of the dataset. This either can implement iterative training or out-of-core/online training.

This is especially useful when the whole dataset is too big to fit in memory at the same time. Or when model is taking long time to converge, and you want to split up training into subparts.

• x: Matrix of shape [n_samples, n_features...]. Can be iterator that returns arrays of features. The training input samples for fitting the model. If set, input_fn must be None.
• y: Vector or matrix [n_samples] or [n_samples, n_outputs]. Can be iterator that returns array of labels. The training label values (class labels in classification, real numbers in regression). If set, input_fn must be None.
• input_fn: Input function. If set, x, y, and batch_size must be None.
• steps: Number of steps for which to train model. If None, train forever.
• batch_size: minibatch size to use on the input, defaults to first dimension of x. Must be None if input_fn is provided.
• monitors: List of BaseMonitor subclass instances. Used for callbacks inside the training loop.

self, for chaining.

• ValueError: If at least one of x and y is provided, and input_fn is provided.

Returns predicted classes for given features. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-09-15. Instructions for updating: The default behavior of predict() is changing. The default value for as_iterable will change to True, and then the flag will be removed altogether. The behavior of this flag is described below.

• x: features.
• input_fn: Input function. If set, x must be None.
• batch_size: Override default batch size.
• as_iterable: If True, return an iterable which keeps yielding predictions for each example until inputs are exhausted. Note: The inputs must terminate if you want the iterable to terminate (e.g. be sure to pass num_epochs=1 if you are using something like read_batch_features).

Numpy array of predicted classes with shape [batch_size] (or an iterable of predicted classes if as_iterable is True). Each predicted class is represented by its class index (i.e. integer from 0 to n_classes-1).

Returns predicted classes for given features. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-09-15. Instructions for updating: The default behavior of predict() is changing. The default value for as_iterable will change to True, and then the flag will be removed altogether. The behavior of this flag is described below.

• x: features.
• input_fn: Input function. If set, x must be None.
• batch_size: Override default batch size.
• as_iterable: If True, return an iterable which keeps yielding predictions for each example until inputs are exhausted. Note: The inputs must terminate if you want the iterable to terminate (e.g. be sure to pass num_epochs=1 if you are using something like read_batch_features).

Numpy array of predicted classes with shape [batch_size] (or an iterable of predicted classes if as_iterable is True). Each predicted class is represented by its class index (i.e. integer from 0 to n_classes-1).

Returns prediction probabilities for given features. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-09-15. Instructions for updating: The default behavior of predict() is changing. The default value for as_iterable will change to True, and then the flag will be removed altogether. The behavior of this flag is described below.

• x: features.
• input_fn: Input function. If set, x and y must be None.
• batch_size: Override default batch size.
• as_iterable: If True, return an iterable which keeps yielding predictions for each example until inputs are exhausted. Note: The inputs must terminate if you want the iterable to terminate (e.g. be sure to pass num_epochs=1 if you are using something like read_batch_features).

Numpy array of predicted probabilities with shape [batch_size, n_classes] (or an iterable of predicted probabilities if as_iterable is True).

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as pipelines). The former have parameters of the form <component>__<parameter> so that it's possible to update each component of a nested object.

• **params: Parameters.

self

• ValueError: If params contain invalid names.

DEPRECATED FUNCTION

THIS FUNCTION IS DEPRECATED. It will be removed after 2016-10-30. Instructions for updating: This method will be removed after the deprecation date. To inspect variables, use get_variable_names() and get_variable_value().

A regressor for TensorFlow DNN models.

Example:

sparse_feature_a = sparse_column_with_hash_bucket(...)
sparse_feature_b = sparse_column_with_hash_bucket(...)

sparse_feature_a_emb = embedding_column(sparse_id_column=sparse_feature_a,
                                        ...)
sparse_feature_b_emb = embedding_column(sparse_id_column=sparse_feature_b,
                                        ...)

estimator = DNNRegressor(
    feature_columns=[sparse_feature_a, sparse_feature_b],
    hidden_units=[1024, 512, 256])

# Or estimator using the ProximalAdagradOptimizer optimizer with
# regularization.
estimator = DNNRegressor(
    feature_columns=[sparse_feature_a, sparse_feature_b],
    hidden_units=[1024, 512, 256],
    optimizer=tf.train.ProximalAdagradOptimizer(
      learning_rate=0.1,
      l1_regularization_strength=0.001
    ))

# Input builders
def input_fn_train: # returns x, y
  pass
estimator.fit(input_fn=input_fn_train)

def input_fn_eval: # returns x, y
  pass
estimator.evaluate(input_fn=input_fn_eval)
estimator.predict(x=x)

Input of fit and evaluate should have following features, otherwise there will be a KeyError:

• if weight_column_name is not None, a feature with key=weight_column_name whose value is a Tensor.
• for each column in feature_columns:
  • if column is a SparseColumn, a feature with key=column.name whose value is a SparseTensor.
  • if column is a WeightedSparseColumn, two features: the first with key the id column name, the second with key the weight column name. Both features' value must be a SparseTensor.
  • if column is a RealValuedColumn, a feature with key=column.name whose value is a Tensor.

Initializes a DNNRegressor instance.

• hidden_units: List of hidden units per layer. All layers are fully connected. Ex. [64, 32] means first layer has 64 nodes and second one has 32.
• feature_columns: An iterable containing all the feature columns used by the model. All items in the set should be instances of classes derived from FeatureColumn.
• model_dir: Directory to save model parameters, graph and etc. This can also be used to load checkpoints from the directory into a estimator to continue training a previously saved model.
• weight_column_name: A string defining feature column name representing weights. It is used to down weight or boost examples during training. It will be multiplied by the loss of the example.
• optimizer: An instance of tf.Optimizer used to train the model. If None, will use an Adagrad optimizer.
• activation_fn: Activation function applied to each layer. If None, will use tf.nn.relu.
• dropout: When not None, the probability we will drop out a given coordinate.
• gradient_clip_norm: A float > 0. If provided, gradients are clipped to their global norm with this clipping ratio. See tf.clip_by_global_norm for more details.
• enable_centered_bias: A bool. If True, estimator will learn a centered bias variable for each class. Rest of the model structure learns the residual after centered bias.
• config: RunConfig object to configure the runtime settings.
• feature_engineering_fn: Feature engineering function. Takes features and labels which are the output of input_fn and returns features and labels which will be fed into the model.
• label_dimension: Dimension of the label for multilabels. Defaults to 1.
• embedding_lr_multipliers: Optional. A dictionary from EbeddingColumn to a float multiplier. Multiplier will be used to multiply with learning rate for the embedding variables.
• input_layer_min_slice_size: Optional. The min slice size of input layer partitions. If not provided, will use the default of 64M.

A DNNRegressor estimator.

See evaluable.Evaluable.

See BaseEstimator.export.

Exports inference graph as a SavedModel into given dir. (experimental)

THIS FUNCTION IS EXPERIMENTAL. It may change or be removed at any time, and without warning.

• export_dir_base: A string containing a directory to write the exported graph and checkpoints.
• input_fn: A function that takes no argument and returns an InputFnOps.
• default_output_alternative_key: the name of the head to serve when none is specified.
• assets_extra: A dict specifying how to populate the assets.extra directory within the exported SavedModel. Each key should give the destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
• as_text: whether to write the SavedModel proto in text format.
• exports_to_keep: Number of exports to keep.

The string path to the exported directory.

• ValueError: if an unrecognized export_type is requested.

See Trainable. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-12-01. Instructions for updating: Estimator is decoupled from Scikit Learn interface by moving into separate class SKCompat. Arguments x, y and batch_size are only available in the SKCompat class, Estimator will only accept input_fn.

est = Estimator(...) -> est = SKCompat(Estimator(...))

• ValueError: If x or y are not None while input_fn is not None.
• ValueError: If both steps and max_steps are not None.

Get parameters for this estimator.

• deep: boolean, optional

  If True, will return the parameters for this estimator and contained subobjects that are estimators.

params : mapping of string to any Parameter names mapped to their values.

Returns list of all variable names in this model.

List of names.

Returns value of the variable given by name.

• name: string, name of the tensor.

Numpy array - value of the tensor.

Incremental fit on a batch of samples. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-12-01. Instructions for updating: Estimator is decoupled from Scikit Learn interface by moving into separate class SKCompat. Arguments x, y and batch_size are only available in the SKCompat class, Estimator will only accept input_fn.

est = Estimator(...) -> est = SKCompat(Estimator(...))

This method is expected to be called several times consecutively on different or the same chunks of the dataset. This either can implement iterative training or out-of-core/online training.

This is especially useful when the whole dataset is too big to fit in memory at the same time. Or when model is taking long time to converge, and you want to split up training into subparts.

• x: Matrix of shape [n_samples, n_features...]. Can be iterator that returns arrays of features. The training input samples for fitting the model. If set, input_fn must be None.
• y: Vector or matrix [n_samples] or [n_samples, n_outputs]. Can be iterator that returns array of labels. The training label values (class labels in classification, real numbers in regression). If set, input_fn must be None.
• input_fn: Input function. If set, x, y, and batch_size must be None.
• steps: Number of steps for which to train model. If None, train forever.
• batch_size: minibatch size to use on the input, defaults to first dimension of x. Must be None if input_fn is provided.
• monitors: List of BaseMonitor subclass instances. Used for callbacks inside the training loop.

self, for chaining.

• ValueError: If at least one of x and y is provided, and input_fn is provided.

Returns predicted scores for given features. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-09-15. Instructions for updating: The default behavior of predict() is changing. The default value for as_iterable will change to True, and then the flag will be removed altogether. The behavior of this flag is described below.

• x: features.
• input_fn: Input function. If set, x must be None.
• batch_size: Override default batch size.
• as_iterable: If True, return an iterable which keeps yielding predictions for each example until inputs are exhausted. Note: The inputs must terminate if you want the iterable to terminate (e.g. be sure to pass num_epochs=1 if you are using something like read_batch_features).

Numpy array of predicted scores (or an iterable of predicted scores if as_iterable is True). If label_dimension == 1, the shape of the output is [batch_size], otherwise the shape is [batch_size, label_dimension].

Returns predicted scores for given features. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-09-15. Instructions for updating: The default behavior of predict() is changing. The default value for as_iterable will change to True, and then the flag will be removed altogether. The behavior of this flag is described below.

• x: features.
• input_fn: Input function. If set, x must be None.
• batch_size: Override default batch size.
• as_iterable: If True, return an iterable which keeps yielding predictions for each example until inputs are exhausted. Note: The inputs must terminate if you want the iterable to terminate (e.g. be sure to pass num_epochs=1 if you are using something like read_batch_features).

Numpy array of predicted scores (or an iterable of predicted scores if as_iterable is True). If label_dimension == 1, the shape of the output is [batch_size], otherwise the shape is [batch_size, label_dimension].

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as pipelines). The former have parameters of the form <component>__<parameter> so that it's possible to update each component of a nested object.

• **params: Parameters.

self

• ValueError: If params contain invalid names.

Linear classifier model.

Train a linear model to classify instances into one of multiple possible classes. When number of possible classes is 2, this is binary classification.

Example:

sparse_column_a = sparse_column_with_hash_bucket(...)
sparse_column_b = sparse_column_with_hash_bucket(...)

sparse_feature_a_x_sparse_feature_b = crossed_column(...)

# Estimator using the default optimizer.
estimator = LinearClassifier(
    feature_columns=[sparse_column_a, sparse_feature_a_x_sparse_feature_b])

# Or estimator using the FTRL optimizer with regularization.
estimator = LinearClassifier(
    feature_columns=[sparse_column_a, sparse_feature_a_x_sparse_feature_b],
    optimizer=tf.train.FtrlOptimizer(
      learning_rate=0.1,
      l1_regularization_strength=0.001
    ))

# Or estimator using the SDCAOptimizer.
estimator = LinearClassifier(
   feature_columns=[sparse_column_a, sparse_feature_a_x_sparse_feature_b],
   optimizer=tf.contrib.linear_optimizer.SDCAOptimizer(
     example_id_column='example_id',
     num_loss_partitions=...,
     symmetric_l2_regularization=2.0
   ))

# Input builders
def input_fn_train: # returns x, y (where y represents label's class index).
  ...
def input_fn_eval: # returns x, y (where y represents label's class index).
  ...
estimator.fit(input_fn=input_fn_train)
estimator.evaluate(input_fn=input_fn_eval)
estimator.predict(x=x) # returns predicted labels (i.e. label's class index).

Input of fit and evaluate should have following features, otherwise there will be a KeyError:

• if weight_column_name is not None, a feature with key=weight_column_name whose value is a Tensor.
• for each column in feature_columns:
  • if column is a SparseColumn, a feature with key=column.name whose value is a SparseTensor.
  • if column is a WeightedSparseColumn, two features: the first with key the id column name, the second with key the weight column name. Both features' value must be a SparseTensor.
  • if column is a RealValuedColumn, a feature with key=column.name whose value is a Tensor.

Construct a LinearClassifier estimator object.

• feature_columns: An iterable containing all the feature columns used by the model. All items in the set should be instances of classes derived from FeatureColumn.

• model_dir: Directory to save model parameters, graph and etc. This can also be used to load checkpoints from the directory into a estimator to continue training a previously saved model.

• n_classes: number of label classes. Default is binary classification. Note that class labels are integers representing the class index (i.e. values from 0 to n_classes-1). For arbitrary label values (e.g. string labels), convert to class indices first.

• weight_column_name: A string defining feature column name representing weights. It is used to down weight or boost examples during training. It will be multiplied by the loss of the example.

• optimizer: The optimizer used to train the model. If specified, it should be either an instance of tf.Optimizer or the SDCAOptimizer. If None, the Ftrl optimizer will be used.

• gradient_clip_norm: A float > 0. If provided, gradients are clipped to their global norm with this clipping ratio. See tf.clip_by_global_norm for more details.

• enable_centered_bias: A bool. If True, estimator will learn a centered bias variable for each class. Rest of the model structure learns the residual after centered bias. _joint_weight: If True, the weights for all columns will be stored in a single (possibly partitioned) variable. It's more efficient, but it's incompatible with SDCAOptimizer, and requires all feature columns are sparse and use the 'sum' combiner.

• config: RunConfig object to configure the runtime settings.

• feature_engineering_fn: Feature engineering function. Takes features and labels which are the output of input_fn and returns features and labels which will be fed into the model.

A LinearClassifier estimator.

• ValueError: if n_classes < 2.

DEPRECATED FUNCTION

THIS FUNCTION IS DEPRECATED. It will be removed after 2016-10-30. Instructions for updating: This method will be removed after the deprecation date. To inspect variables, use get_variable_names() and get_variable_value().

See Evaluable. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-12-01. Instructions for updating: Estimator is decoupled from Scikit Learn interface by moving into separate class SKCompat. Arguments x, y and batch_size are only available in the SKCompat class, Estimator will only accept input_fn.

est = Estimator(...) -> est = SKCompat(Estimator(...))

• ValueError: If at least one of x or y is provided, and at least one of input_fn or feed_fn is provided. Or if metrics is not None or dict.

See BaseEstimator.export.

Exports inference graph as a SavedModel into given dir. (experimental)

THIS FUNCTION IS EXPERIMENTAL. It may change or be removed at any time, and without warning.

• export_dir_base: A string containing a directory to write the exported graph and checkpoints.
• input_fn: A function that takes no argument and returns an InputFnOps.
• default_output_alternative_key: the name of the head to serve when none is specified.
• assets_extra: A dict specifying how to populate the assets.extra directory within the exported SavedModel. Each key should give the destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
• as_text: whether to write the SavedModel proto in text format.
• exports_to_keep: Number of exports to keep.

The string path to the exported directory.

• ValueError: if an unrecognized export_type is requested.

See Trainable. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-12-01. Instructions for updating: Estimator is decoupled from Scikit Learn interface by moving into separate class SKCompat. Arguments x, y and batch_size are only available in the SKCompat class, Estimator will only accept input_fn.

est = Estimator(...) -> est = SKCompat(Estimator(...))

• ValueError: If x or y are not None while input_fn is not None.
• ValueError: If both steps and max_steps are not None.

Get parameters for this estimator.

• deep: boolean, optional

  If True, will return the parameters for this estimator and contained subobjects that are estimators.

params : mapping of string to any Parameter names mapped to their values.

Returns list of all variable names in this model.

List of names.

Returns value of the variable given by name.

• name: string, name of the tensor.

Numpy array - value of the tensor.

Incremental fit on a batch of samples. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-12-01. Instructions for updating: Estimator is decoupled from Scikit Learn interface by moving into separate class SKCompat. Arguments x, y and batch_size are only available in the SKCompat class, Estimator will only accept input_fn.

est = Estimator(...) -> est = SKCompat(Estimator(...))

This method is expected to be called several times consecutively on different or the same chunks of the dataset. This either can implement iterative training or out-of-core/online training.

This is especially useful when the whole dataset is too big to fit in memory at the same time. Or when model is taking long time to converge, and you want to split up training into subparts.

• x: Matrix of shape [n_samples, n_features...]. Can be iterator that returns arrays of features. The training input samples for fitting the model. If set, input_fn must be None.
• y: Vector or matrix [n_samples] or [n_samples, n_outputs]. Can be iterator that returns array of labels. The training label values (class labels in classification, real numbers in regression). If set, input_fn must be None.
• input_fn: Input function. If set, x, y, and batch_size must be None.
• steps: Number of steps for which to train model. If None, train forever.
• batch_size: minibatch size to use on the input, defaults to first dimension of x. Must be None if input_fn is provided.
• monitors: List of BaseMonitor subclass instances. Used for callbacks inside the training loop.

self, for chaining.

• ValueError: If at least one of x and y is provided, and input_fn is provided.

Runs inference to determine the predicted class (i.e. class index). (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-09-15. Instructions for updating: The default behavior of predict() is changing. The default value for as_iterable will change to True, and then the flag will be removed altogether. The behavior of this flag is described below.

Runs inference to determine the predicted class (i.e. class index). (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-09-15. Instructions for updating: The default behavior of predict() is changing. The default value for as_iterable will change to True, and then the flag will be removed altogether. The behavior of this flag is described below.

Runs inference to determine the class probability predictions. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-09-15. Instructions for updating: The default behavior of predict() is changing. The default value for as_iterable will change to True, and then the flag will be removed altogether. The behavior of this flag is described below.

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as pipelines). The former have parameters of the form <component>__<parameter> so that it's possible to update each component of a nested object.

• **params: Parameters.

self

• ValueError: If params contain invalid names.

DEPRECATED FUNCTION

THIS FUNCTION IS DEPRECATED. It will be removed after 2016-10-30. Instructions for updating: This method will be removed after the deprecation date. To inspect variables, use get_variable_names() and get_variable_value().

Linear regressor model.

Train a linear regression model to predict label value given observation of feature values.

Example:

sparse_column_a = sparse_column_with_hash_bucket(...)
sparse_column_b = sparse_column_with_hash_bucket(...)

sparse_feature_a_x_sparse_feature_b = crossed_column(...)

estimator = LinearRegressor(
    feature_columns=[sparse_column_a, sparse_feature_a_x_sparse_feature_b])

# Input builders
def input_fn_train: # returns x, y
  ...
def input_fn_eval: # returns x, y
  ...
estimator.fit(input_fn=input_fn_train)
estimator.evaluate(input_fn=input_fn_eval)
estimator.predict(x=x)

Input of fit and evaluate should have following features, otherwise there will be a KeyError:

• if weight_column_name is not None: key=weight_column_name, value=a Tensor
• for column in feature_columns:
  • if isinstance(column, SparseColumn): key=column.name, value=a SparseTensor
  • if isinstance(column, WeightedSparseColumn): {key=id column name, value=a SparseTensor, key=weight column name, value=a SparseTensor}
  • if isinstance(column, RealValuedColumn): key=column.name, value=a Tensor

Construct a LinearRegressor estimator object.

• feature_columns: An iterable containing all the feature columns used by the model. All items in the set should be instances of classes derived from FeatureColumn.

• model_dir: Directory to save model parameters, graph, etc. This can also be used to load checkpoints from the directory into a estimator to continue training a previously saved model.

• weight_column_name: A string defining feature column name representing weights. It is used to down weight or boost examples during training. It will be multiplied by the loss of the example.

• optimizer: An instance of tf.Optimizer used to train the model. If None, will use an Ftrl optimizer.

• gradient_clip_norm: A float > 0. If provided, gradients are clipped to their global norm with this clipping ratio. See tf.clip_by_global_norm for more details.

• enable_centered_bias: A bool. If True, estimator will learn a centered bias variable for each class. Rest of the model structure learns the residual after centered bias.

• label_dimension: Dimension of the label for multilabels. Defaults to 1. _joint_weights: If True use a single (possibly partitioned) variable to store the weights. It's faster, but requires all feature columns are sparse and have the 'sum' combiner. Incompatible with SDCAOptimizer.

• config: RunConfig object to configure the runtime settings.

• feature_engineering_fn: Feature engineering function. Takes features and labels which are the output of input_fn and returns features and labels which will be fed into the model.

A LinearRegressor estimator.

DEPRECATED FUNCTION

THIS FUNCTION IS DEPRECATED. It will be removed after 2016-10-30. Instructions for updating: This method will be removed after the deprecation date. To inspect variables, use get_variable_names() and get_variable_value().

See Evaluable. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-12-01. Instructions for updating: Estimator is decoupled from Scikit Learn interface by moving into separate class SKCompat. Arguments x, y and batch_size are only available in the SKCompat class, Estimator will only accept input_fn.

est = Estimator(...) -> est = SKCompat(Estimator(...))

• ValueError: If at least one of x or y is provided, and at least one of input_fn or feed_fn is provided. Or if metrics is not None or dict.

See BaseEstimator.export.

Exports inference graph as a SavedModel into given dir. (experimental)

THIS FUNCTION IS EXPERIMENTAL. It may change or be removed at any time, and without warning.

• export_dir_base: A string containing a directory to write the exported graph and checkpoints.
• input_fn: A function that takes no argument and returns an InputFnOps.
• default_output_alternative_key: the name of the head to serve when none is specified.
• assets_extra: A dict specifying how to populate the assets.extra directory within the exported SavedModel. Each key should give the destination path (including the filename) relative to the assets.extra directory. The corresponding value gives the full path of the source file to be copied. For example, the simple case of copying a single file without renaming it is specified as {'my_asset_file.txt': '/path/to/my_asset_file.txt'}.
• as_text: whether to write the SavedModel proto in text format.
• exports_to_keep: Number of exports to keep.

The string path to the exported directory.

• ValueError: if an unrecognized export_type is requested.

See Trainable. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-12-01. Instructions for updating: Estimator is decoupled from Scikit Learn interface by moving into separate class SKCompat. Arguments x, y and batch_size are only available in the SKCompat class, Estimator will only accept input_fn.

est = Estimator(...) -> est = SKCompat(Estimator(...))

• ValueError: If x or y are not None while input_fn is not None.
• ValueError: If both steps and max_steps are not None.

Get parameters for this estimator.

• deep: boolean, optional

  If True, will return the parameters for this estimator and contained subobjects that are estimators.

params : mapping of string to any Parameter names mapped to their values.

Returns list of all variable names in this model.

List of names.

Returns value of the variable given by name.

• name: string, name of the tensor.

Numpy array - value of the tensor.

Incremental fit on a batch of samples. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-12-01. Instructions for updating: Estimator is decoupled from Scikit Learn interface by moving into separate class SKCompat. Arguments x, y and batch_size are only available in the SKCompat class, Estimator will only accept input_fn.

est = Estimator(...) -> est = SKCompat(Estimator(...))

This method is expected to be called several times consecutively on different or the same chunks of the dataset. This either can implement iterative training or out-of-core/online training.

This is especially useful when the whole dataset is too big to fit in memory at the same time. Or when model is taking long time to converge, and you want to split up training into subparts.

• x: Matrix of shape [n_samples, n_features...]. Can be iterator that returns arrays of features. The training input samples for fitting the model. If set, input_fn must be None.
• y: Vector or matrix [n_samples] or [n_samples, n_outputs]. Can be iterator that returns array of labels. The training label values (class labels in classification, real numbers in regression). If set, input_fn must be None.
• input_fn: Input function. If set, x, y, and batch_size must be None.
• steps: Number of steps for which to train model. If None, train forever.
• batch_size: minibatch size to use on the input, defaults to first dimension of x. Must be None if input_fn is provided.
• monitors: List of BaseMonitor subclass instances. Used for callbacks inside the training loop.

self, for chaining.

• ValueError: If at least one of x and y is provided, and input_fn is provided.

Runs inference to determine the predicted scores. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-09-15. Instructions for updating: The default behavior of predict() is changing. The default value for as_iterable will change to True, and then the flag will be removed altogether. The behavior of this flag is described below.

Runs inference to determine the predicted scores. (deprecated arguments)

SOME ARGUMENTS ARE DEPRECATED. They will be removed after 2016-09-15. Instructions for updating: The default behavior of predict() is changing. The default value for as_iterable will change to True, and then the flag will be removed altogether. The behavior of this flag is described below.

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as pipelines). The former have parameters of the form <component>__<parameter> so that it's possible to update each component of a nested object.

• **params: Parameters.

self

• ValueError: If params contain invalid names.

DEPRECATED FUNCTION

THIS FUNCTION IS DEPRECATED. It will be removed after 2016-10-30. Instructions for updating: This method will be removed after the deprecation date. To inspect variables, use get_variable_names() and get_variable_value().

Builds a logistic regression Estimator for binary classification.

This method provides a basic Estimator with some additional metrics for custom binary classification models, including AUC, precision/recall and accuracy.

Example:

  # See tf.contrib.learn.Estimator(...) for details on model_fn structure
  def my_model_fn(...):
    pass

  estimator = LogisticRegressor(model_fn=my_model_fn)

  # Input builders
  def input_fn_train:
    pass

  estimator.fit(input_fn=input_fn_train)
  estimator.predict(x=x)

• model_fn: Model function with the signature: (features, labels, mode) -> (predictions, loss, train_op). Expects the returned predictions to be probabilities in [0.0, 1.0].
• thresholds: List of floating point thresholds to use for accuracy, precision, and recall metrics. If None, defaults to [0.5].
• model_dir: Directory to save model parameters, graphs, etc. This can also be used to load checkpoints from the directory into a estimator to continue training a previously saved model.
• config: A RunConfig configuration object.
• feature_engineering_fn: Feature engineering function. Takes features and labels which are the output of input_fn and returns features and labels which will be fed into the model.

A tf.contrib.learn.Estimator instance.

Perform various training, evaluation, and inference actions on a graph.

This class specifies the configurations for an Estimator run.

If you're a Google-internal user using command line flags with learn_runner.py (for instance, to do distributed training or to use parameter servers), you probably want to use learn_runner.EstimatorConfig instead.

Constructor.

Note that the superclass ClusterConfig may set properties like cluster_spec, is_chief, master (if None in the args), num_ps_replicas, task_id, and task_type based on the TF_CONFIG environment variable. See ClusterConfig for more details.

• master: TensorFlow master. Defaults to empty string for local.
• num_cores: Number of cores to be used. If 0, the system picks an appropriate number (default: 0).
• log_device_placement: Log the op placement to devices (default: False).
• gpu_memory_fraction: Fraction of GPU memory used by the process on each GPU uniformly on the same machine.
• tf_random_seed: Random seed for TensorFlow initializers. Setting this value allows consistency between reruns.
• save_summary_steps: Save summaries every this many steps.
• save_checkpoints_secs: Save checkpoints every this many seconds. Can not be specified with save_checkpoints_steps.
• save_checkpoints_steps: Save checkpoints every this many steps. Can not be specified with save_checkpoints_secs.
• keep_checkpoint_max: The maximum number of recent checkpoint files to keep. As new files are created, older files are deleted. If None or 0, all checkpoint files are kept. Defaults to 5 (that is, the 5 most recent checkpoint files are kept.)
• keep_checkpoint_every_n_hours: Number of hours between each checkpoint to be saved. The default value of 10,000 hours effectively disables the feature.
• evaluation_master: the master on which to perform evaluation.

Returns task index from TF_CONFIG environmental variable.

If you have a ClusterConfig instance, you can just access its task_id property instead of calling this function and re-parsing the environmental variable.

TF_CONFIG['task']['index']. Defaults to 0.

Evaluate a model loaded from a checkpoint. (deprecated)

THIS FUNCTION IS DEPRECATED. It will be removed after 2017-02-15. Instructions for updating: graph_actions.py will be deleted. Use tf.train.* utilities instead. You can use learn/estimators/estimator.py as an example.

Given graph, a directory to write summaries to (output_dir), a checkpoint to restore variables from, and a dict of Tensors to evaluate, run an eval loop for max_steps steps, or until an exception (generally, an end-of-input signal from a reader operation) is raised from running eval_dict.

In each step of evaluation, all tensors in the eval_dict are evaluated, and every log_every_steps steps, they are logged. At the very end of evaluation, a summary is evaluated (finding the summary ops using Supervisor's logic) and written to output_dir.

• graph: A Graph to train. It is expected that this graph is not in use elsewhere.
• output_dir: A string containing the directory to write a summary to.
• checkpoint_path: A string containing the path to a checkpoint to restore. Can be None if the graph doesn't require loading any variables.
• eval_dict: A dict mapping string names to tensors to evaluate. It is evaluated in every logging step. The result of the final evaluation is returned. If update_op is None, then it's evaluated in every step. If max_steps is None, this should depend on a reader that will raise an end-of-input exception when the inputs are exhausted.
• update_op: A Tensor which is run in every step.
• global_step_tensor: A Variable containing the global step. If None, one is extracted from the graph using the same logic as in Supervisor. Used to place eval summaries on training curves.
• supervisor_master: The master string to use when preparing the session.
• log_every_steps: Integer. Output logs every log_every_steps evaluation steps. The logs contain the eval_dict and timing information.
• feed_fn: A function that is called every iteration to produce a feed_dict passed to session.run calls. Optional.
• max_steps: Integer. Evaluate eval_dict this many times.

A tuple (eval_results, global_step):

• eval_results: A dict mapping string to numeric values (int, float) that are the result of running eval_dict in the last step. None if no eval steps were run.
• global_step: The global step this evaluation corresponds to.

• ValueError: if output_dir is empty.

Restore graph from restore_checkpoint_path and run output_dict tensors. (deprecated)

THIS FUNCTION IS DEPRECATED. It will be removed after 2017-02-15. Instructions for updating: graph_actions.py will be deleted. Use tf.train.* utilities instead. You can use learn/estimators/estimator.py as an example.

If restore_checkpoint_path is supplied, restore from checkpoint. Otherwise, init all variables.

• restore_checkpoint_path: A string containing the path to a checkpoint to restore.
• output_dict: A dict mapping string names to Tensor objects to run. Tensors must all be from the same graph.
• feed_dict: dict object mapping Tensor objects to input values to feed.

Dict of values read from output_dict tensors. Keys are the same as output_dict, values are the results read from the corresponding Tensor in output_dict.

• ValueError: if output_dict or feed_dicts is None or empty.

See run_feeds_iter(). Returns a list instead of an iterator. (deprecated)

THIS FUNCTION IS DEPRECATED. It will be removed after 2017-02-15. Instructions for updating: graph_actions.py will be deleted. Use tf.train.* utilities instead. You can use learn/estimators/estimator.py as an example.

Run output_dict tensors n times, with the same feed_dict each run. (deprecated)

THIS FUNCTION IS DEPRECATED. It will be removed after 2017-02-15. Instructions for updating: graph_actions.py will be deleted. Use tf.train.* utilities instead. You can use learn/estimators/estimator.py as an example.

• output_dict: A dict mapping string names to tensors to run. Must all be from the same graph.
• feed_dict: dict of input values to feed each run.
• restore_checkpoint_path: A string containing the path to a checkpoint to restore.
• n: Number of times to repeat.

A list of n dict objects, each containing values read from output_dict tensors.

Train a model. (deprecated)

THIS FUNCTION IS DEPRECATED. It will be removed after 2017-02-15. Instructions for updating: graph_actions.py will be deleted. Use tf.train.* utilities instead. You can use learn/estimators/estimator.py as an example.

Given graph, a directory to write outputs to (output_dir), and some ops, run a training loop. The given train_op performs one step of training on the model. The loss_op represents the objective function of the training. It is expected to increment the global_step_tensor, a scalar integer tensor counting training steps. This function uses Supervisor to initialize the graph (from a checkpoint if one is available in output_dir), write summaries defined in the graph, and write regular checkpoints as defined by supervisor_save_model_secs.

Training continues until global_step_tensor evaluates to max_steps, or, if fail_on_nan_loss, until loss_op evaluates to NaN. In that case the program is terminated with exit code 1.

• graph: A graph to train. It is expected that this graph is not in use elsewhere.
• output_dir: A directory to write outputs to.
• train_op: An op that performs one training step when run.
• loss_op: A scalar loss tensor.
• global_step_tensor: A tensor representing the global step. If none is given, one is extracted from the graph using the same logic as in Supervisor.
• init_op: An op that initializes the graph. If None, use Supervisor's default.
• init_feed_dict: A dictionary that maps Tensor objects to feed values. This feed dictionary will be used when init_op is evaluated.
• init_fn: Optional callable passed to Supervisor to initialize the model.
• log_every_steps: Output logs regularly. The logs contain timing data and the current loss.
• supervisor_is_chief: Whether the current process is the chief supervisor in charge of restoring the model and running standard services.
• supervisor_master: The master string to use when preparing the session.
• supervisor_save_model_secs: Save a checkpoint every supervisor_save_model_secs seconds when training.
• keep_checkpoint_max: The maximum number of recent checkpoint files to keep. As new files are created, older files are deleted. If None or 0, all checkpoint files are kept. This is simply passed as the max_to_keep arg to tf.Saver constructor.
• supervisor_save_summaries_steps: Save summaries every supervisor_save_summaries_steps seconds when training.
• feed_fn: A function that is called every iteration to produce a feed_dict passed to session.run calls. Optional.
• steps: Trains for this many steps (e.g. current global step + steps).
• fail_on_nan_loss: If true, raise NanLossDuringTrainingError if loss_op evaluates to NaN. If false, continue training as if nothing happened.
• monitors: List of BaseMonitor subclass instances. Used for callbacks inside the training loop.
• max_steps: Number of total steps for which to train model. If None, train forever. Two calls fit(steps=100) means 200 training iterations. On the other hand two calls of fit(max_steps=100) means, second call will not do any iteration since first call did all 100 steps.

The final loss value.

• ValueError: If output_dir, train_op, loss_op, or global_step_tensor is not provided. See tf.contrib.framework.get_global_step for how we look up the latter if not provided explicitly.
• NanLossDuringTrainingError: If fail_on_nan_loss is True, and loss ever evaluates to NaN.
• ValueError: If both steps and max_steps are not None.

Queue and read batched input data.

Extract data from dask.Series or dask.DataFrame for predictors.

Given a distributed dask.DataFrame or dask.Series containing columns or names for one or more predictors, this operation returns a single dask.DataFrame or dask.Series that can be iterated over.

• data: A distributed dask.DataFrame or dask.Series.

A dask.DataFrame or dask.Series that can be iterated over. If the supplied argument is neither a dask.DataFrame nor a dask.Series this operation returns it without modification.

Extract data from dask.Series or dask.DataFrame for labels.

Given a distributed dask.DataFrame or dask.Series containing exactly one column or name, this operation returns a single dask.DataFrame or dask.Series that can be iterated over.

• labels: A distributed dask.DataFrame or dask.Series with exactly one column or name.

A dask.DataFrame or dask.Series that can be iterated over. If the supplied argument is neither a dask.DataFrame nor a dask.Series this operation returns it without modification.

• ValueError: If the supplied dask.DataFrame contains more than one column or the supplied dask.Series contains more than one name.

Extract data from pandas.DataFrame for predictors.

Given a DataFrame, will extract the values and cast them to float. The DataFrame is expected to contain values of type int, float or bool.

• data: pandas.DataFrame containing the data to be extracted.

A numpy ndarray of the DataFrame's values as floats.

• ValueError: if data contains types other than int, float or bool.

Extract data from pandas.DataFrame for labels.

• labels: pandas.DataFrame or pandas.Series containing one column of labels to be extracted.

A numpy ndarray of labels from the DataFrame.

• ValueError: if more than one column is found or type is not int, float or bool.

Extracts numpy matrix from pandas DataFrame.

• data: pandas.DataFrame containing the data to be extracted.

A numpy ndarray of the DataFrame's values.

Creates FeatureColumn objects for inputs defined by input x.

This interprets all inputs as dense, fixed-length float values.

• x: Real-valued matrix of shape [n_samples, n_features...]. Can be iterator that returns arrays of features.

List of FeatureColumn objects.

Creates FeatureColumn objects for inputs defined by input_fn.

This interprets all inputs as dense, fixed-length float values. This creates a local graph in which it calls input_fn to build the tensors, then discards it.

• input_fn: Input function returning a tuple of: features - Dictionary of string feature name to Tensor or Tensor. labels - Tensor of label values.

List of FeatureColumn objects.

Adds operations to read, queue, batch Example protos.

Given file pattern (or list of files), will setup a queue for file names, read Example proto using provided reader, use batch queue to create batches of examples of size batch_size.

All queue runners are added to the queue runners collection, and may be started via start_queue_runners.

All ops are added to the default graph.

Use parse_fn if you need to do parsing / processing on single examples.

• file_pattern: List of files or pattern of file paths containing Example records. See tf.gfile.Glob for pattern rules.
• batch_size: An int or scalar Tensor specifying the batch size to use.
• reader: A function or class that returns an object with read method, (filename tensor) -> (example tensor).
• randomize_input: Whether the input should be randomized.
• num_epochs: Integer specifying the number of times to read through the dataset. If None, cycles through the dataset forever. NOTE - If specified, creates a variable that must be initialized, so call tf.global_variables_initializer() as shown in the tests.
• queue_capacity: Capacity for input queue.
• num_threads: The number of threads enqueuing examples.
• read_batch_size: An int or scalar Tensor specifying the number of records to read at once
• parse_fn: Parsing function, takes Example Tensor returns parsed representation. If None, no parsing is done.
• name: Name of resulting op.

String Tensor of batched Example proto.

• ValueError: for invalid inputs.

Adds operations to read, queue, batch and parse Example protos.

Given file pattern (or list of files), will setup a queue for file names, read Example proto using provided reader, use batch queue to create batches of examples of size batch_size and parse example given features specification.

All queue runners are added to the queue runners collection, and may be started via start_queue_runners.

All ops are added to the default graph.

• file_pattern: List of files or pattern of file paths containing Example records. See tf.gfile.Glob for pattern rules.
• batch_size: An int or scalar Tensor specifying the batch size to use.
• features: A dict mapping feature keys to FixedLenFeature or VarLenFeature values.
• reader: A function or class that returns an object with read method, (filename tensor) -> (example tensor).
• randomize_input: Whether the input should be randomized.
• num_epochs: Integer specifying the number of times to read through the dataset. If None, cycles through the dataset forever. NOTE - If specified, creates a variable that must be initialized, so call tf.local_variables_initializer() as shown in the tests.
• queue_capacity: Capacity for input queue.
• feature_queue_capacity: Capacity of the parsed features queue. Set this value to a small number, for example 5 if the parsed features are large.
• reader_num_threads: The number of threads to read examples.
• parse_fn: Parsing function, takes Example Tensor returns parsed representation. If None, no parsing is done.
• name: Name of resulting op.

A dict of Tensor or SparseTensor objects for each in features.

• ValueError: for invalid inputs.

Reads TFRecord, queues, batches and parses Example proto.

See more detailed description in read_examples.

• file_pattern: List of files or pattern of file paths containing Example records. See tf.gfile.Glob for pattern rules.
• batch_size: An int or scalar Tensor specifying the batch size to use.
• features: A dict mapping feature keys to FixedLenFeature or VarLenFeature values.
• randomize_input: Whether the input should be randomized.
• num_epochs: Integer specifying the number of times to read through the dataset. If None, cycles through the dataset forever. NOTE - If specified, creates a variable that must be initialized, so call tf.local_variables_initializer() as shown in the tests.
• queue_capacity: Capacity for input queue.
• reader_num_threads: The number of threads to read examples.
• name: Name of resulting op.

A dict of Tensor or SparseTensor objects for each in features.

• ValueError: for invalid inputs.