• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Copyright 2016 The TensorFlow Authors. All Rights Reserved.
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7#     http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14# ==============================================================================
15"""`Evaluable` interface (deprecated).
16
17This module and all its submodules are deprecated. See
18[contrib/learn/README.md](https://www.tensorflow.org/code/tensorflow/contrib/learn/README.md)
19for migration instructions.
20"""
21
22from __future__ import absolute_import
23from __future__ import division
24from __future__ import print_function
25
26import abc
27
28import six
29
30
31@six.add_metaclass(abc.ABCMeta)
32class Evaluable(object):
33  """Interface for objects that are evaluatable by, e.g., `Experiment`.
34
35  THIS CLASS IS DEPRECATED. See
36  [contrib/learn/README.md](https://www.tensorflow.org/code/tensorflow/contrib/learn/README.md)
37  for general migration instructions.
38  """
39
40  @abc.abstractproperty
41  def model_dir(self):
42    """Returns a path in which the eval process will look for checkpoints."""
43    raise NotImplementedError
44
45  @abc.abstractmethod
46  def evaluate(self,
47               x=None,
48               y=None,
49               input_fn=None,
50               feed_fn=None,
51               batch_size=None,
52               steps=None,
53               metrics=None,
54               name=None,
55               checkpoint_path=None,
56               hooks=None):
57    """Evaluates given model with provided evaluation data.
58
59    Stop conditions - we evaluate on the given input data until one of the
60    following:
61    - If `steps` is provided, and `steps` batches of size `batch_size` are
62    processed.
63    - If `input_fn` is provided, and it raises an end-of-input
64    exception (`OutOfRangeError` or `StopIteration`).
65    - If `x` is provided, and all items in `x` have been processed.
66
67    The return value is a dict containing the metrics specified in `metrics`, as
68    well as an entry `global_step` which contains the value of the global step
69    for which this evaluation was performed.
70
71    Args:
72      x: Matrix of shape [n_samples, n_features...] or dictionary of many
73        matrices
74        containing the input samples for fitting the model. Can be iterator that
75          returns
76        arrays of features or dictionary of array of features. If set,
77          `input_fn` must
78        be `None`.
79      y: Vector or matrix [n_samples] or [n_samples, n_outputs] containing the
80        label values (class labels in classification, real numbers in
81        regression) or dictionary of multiple vectors/matrices. Can be iterator
82        that returns array of targets or dictionary of array of targets. If set,
83        `input_fn` must be `None`. Note: For classification, label values must
84        be integers representing the class index (i.e. values from 0 to
85        n_classes-1).
86      input_fn: Input function returning a tuple of:
87        features - Dictionary of string feature name to `Tensor` or `Tensor`.
88        labels - `Tensor` or dictionary of `Tensor` with labels.
89        If input_fn is set, `x`, `y`, and `batch_size` must be `None`. If
90        `steps` is not provided, this should raise `OutOfRangeError` or
91        `StopIteration` after the desired amount of data (e.g., one epoch) has
92        been provided. See "Stop conditions" above for specifics.
93      feed_fn: Function creating a feed dict every time it is called. Called
94        once per iteration. Must be `None` if `input_fn` is provided.
95      batch_size: minibatch size to use on the input, defaults to first
96        dimension of `x`, if specified. Must be `None` if `input_fn` is
97        provided.
98      steps: Number of steps for which to evaluate model. If `None`, evaluate
99        until `x` is consumed or `input_fn` raises an end-of-input exception.
100        See "Stop conditions" above for specifics.
101      metrics: Dict of metrics to run. If None, the default metric functions
102        are used; if {}, no metrics are used. Otherwise, `metrics` should map
103        friendly names for the metric to a `MetricSpec` object defining which
104        model outputs to evaluate against which labels with which metric
105        function.
106        Metric ops should support streaming, e.g., returning `update_op` and
107        `value` tensors. For example, see the options defined in
108        `../../../metrics/python/ops/metrics_ops.py`.
109      name: Name of the evaluation if user needs to run multiple evaluations on
110        different data sets, such as on training data vs test data.
111      checkpoint_path: Path of a specific checkpoint to evaluate. If `None`, the
112        latest checkpoint in `model_dir` is used.
113      hooks: List of `SessionRunHook` subclass instances. Used for callbacks
114        inside the evaluation call.
115
116    Returns:
117      Returns `dict` with evaluation results.
118    """
119    raise NotImplementedError
120