1# Copyright 2017 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"""Debug estimators (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 21Debug estimators are bias-only estimators that can be used for debugging 22and as simple baselines. 23 24Example: 25 26``` 27# Build DebugClassifier 28classifier = DebugClassifier() 29 30# Input builders 31def input_fn_train: # returns x, y (where y represents label's class index). 32 pass 33 34def input_fn_eval: # returns x, y (where y represents label's class index). 35 pass 36 37# Fit model. 38classifier.fit(input_fn=input_fn_train) 39 40# Evaluate cross entropy between the test and train labels. 41loss = classifier.evaluate(input_fn=input_fn_eval)["loss"] 42 43# predict_classes outputs the most commonly seen class in training. 44predicted_label = classifier.predict_classes(new_samples) 45 46# predict_proba outputs the class distribution from training. 47label_distribution = classifier.predict_proba(new_samples) 48``` 49""" 50from __future__ import absolute_import 51from __future__ import division 52from __future__ import print_function 53 54from tensorflow.contrib.layers.python.layers import optimizers 55from tensorflow.contrib.learn.python.learn.estimators import estimator 56from tensorflow.contrib.learn.python.learn.estimators import head as head_lib 57from tensorflow.contrib.learn.python.learn.estimators import prediction_key 58from tensorflow.python.framework import ops 59from tensorflow.python.ops import array_ops 60from tensorflow.python.ops import check_ops 61 62 63def _get_feature_dict(features): 64 if isinstance(features, dict): 65 return features 66 return {"": features} 67 68 69def debug_model_fn(features, labels, mode, params, config=None): 70 """Model_fn for debug models. 71 72 Args: 73 features: `Tensor` or dict of `Tensor` (depends on data passed to `fit`). 74 labels: Labels that are compatible with the `_Head` instance in `params`. 75 mode: Defines whether this is training, evaluation or prediction. 76 See `ModeKeys`. 77 params: A dict of hyperparameters containing: 78 * head: A `_Head` instance. 79 config: `RunConfig` object to configure the runtime settings. 80 81 Raises: 82 KeyError: If weight column is specified but not present. 83 ValueError: If features is an empty dictionary. 84 85 Returns: 86 A `ModelFnOps` instance. 87 """ 88 del config # Unused. 89 90 features = _get_feature_dict(features) 91 if not features: 92 raise ValueError("Features cannot be empty.") 93 94 head = params["head"] 95 size_checks = [] 96 batch_size = None 97 98 # The first dimension is assumed to be a batch size and must be consistent 99 # among all of the features. 100 for feature in features.values(): 101 first_dim = array_ops.shape(feature)[0] 102 if batch_size is None: 103 batch_size = first_dim 104 else: 105 size_checks.append(check_ops.assert_equal(batch_size, first_dim)) 106 107 with ops.control_dependencies(size_checks): 108 logits = array_ops.zeros([batch_size, head.logits_dimension]) 109 110 def train_op_fn(loss): 111 return optimizers.optimize_loss( 112 loss, global_step=None, learning_rate=0.3, optimizer="Adagrad") 113 114 return head.create_model_fn_ops( 115 features=features, 116 labels=labels, 117 mode=mode, 118 train_op_fn=train_op_fn, 119 logits=logits) 120 121 122class DebugClassifier(estimator.Estimator): 123 """A classifier for TensorFlow Debug models. 124 125 THIS CLASS IS DEPRECATED. See 126 [contrib/learn/README.md](https://www.tensorflow.org/code/tensorflow/contrib/learn/README.md) 127 for general migration instructions. 128 129 Example: 130 131 ```python 132 133 # Build DebugClassifier 134 classifier = DebugClassifier() 135 136 # Input builders 137 def input_fn_train: # returns x, y (where y represents label's class index). 138 pass 139 140 def input_fn_eval: # returns x, y (where y represents label's class index). 141 pass 142 143 # Fit model. 144 classifier.fit(input_fn=input_fn_train) 145 146 # Evaluate cross entropy between the test and train labels. 147 loss = classifier.evaluate(input_fn=input_fn_eval)["loss"] 148 149 # predict_class outputs the most commonly seen class in training. 150 predicted_label = classifier.predict_class(new_samples) 151 152 # predict_proba outputs the class distribution from training. 153 label_distribution = classifier.predict_proba(new_samples) 154 ``` 155 156 Input of `fit` and `evaluate` should have following features, 157 otherwise there will be a `KeyError`: 158 159 * if `weight_column_name` is not `None`, a feature with 160 `key=weight_column_name` whose value is a `Tensor`. 161 """ 162 163 def __init__(self, 164 model_dir=None, 165 n_classes=2, 166 weight_column_name=None, 167 config=None, 168 feature_engineering_fn=None, 169 label_keys=None): 170 """Initializes a DebugClassifier instance. 171 172 Args: 173 model_dir: Directory to save model parameters, graph and etc. This can 174 also be used to load checkpoints from the directory into a estimator to 175 continue training a previously saved model. 176 n_classes: number of label classes. Default is binary classification. 177 It must be greater than 1. Note: Class labels are integers representing 178 the class index (i.e. values from 0 to n_classes-1). For arbitrary 179 label values (e.g. string labels), convert to class indices first. 180 weight_column_name: A string defining feature column name representing 181 weights. It is used to down weight or boost examples during training. It 182 will be multiplied by the loss of the example. 183 config: `RunConfig` object to configure the runtime settings. 184 feature_engineering_fn: Feature engineering function. Takes features and 185 labels which are the output of `input_fn` and returns 186 features and labels which will be fed into the model. 187 label_keys: Optional list of strings with size `[n_classes]` defining the 188 label vocabulary. Only supported for `n_classes` > 2. 189 Returns: 190 A `DebugClassifier` estimator. 191 192 Raises: 193 ValueError: If `n_classes` < 2. 194 """ 195 params = {"head": 196 head_lib.multi_class_head( 197 n_classes=n_classes, 198 weight_column_name=weight_column_name, 199 enable_centered_bias=True, 200 label_keys=label_keys)} 201 202 super(DebugClassifier, self).__init__( 203 model_fn=debug_model_fn, 204 model_dir=model_dir, 205 config=config, 206 params=params, 207 feature_engineering_fn=feature_engineering_fn) 208 209 def predict_classes(self, input_fn=None, batch_size=None): 210 """Returns predicted classes for given features. 211 212 Args: 213 input_fn: Input function. 214 batch_size: Override default batch size. 215 216 Returns: 217 An iterable of predicted classes. Each predicted class is represented by 218 its class index (i.e. integer from 0 to n_classes-1). 219 """ 220 key = prediction_key.PredictionKey.CLASSES 221 preds = self.predict( 222 input_fn=input_fn, batch_size=batch_size, outputs=[key]) 223 return (pred[key] for pred in preds) 224 225 def predict_proba(self, 226 input_fn=None, 227 batch_size=None): 228 """Returns prediction probabilities for given features. 229 230 Args: 231 input_fn: Input function. 232 batch_size: Override default batch size. 233 234 Returns: 235 An iterable of predicted probabilities with shape [batch_size, n_classes]. 236 """ 237 key = prediction_key.PredictionKey.PROBABILITIES 238 preds = self.predict( 239 input_fn=input_fn, 240 batch_size=batch_size, 241 outputs=[key]) 242 return (pred[key] for pred in preds) 243 244 245class DebugRegressor(estimator.Estimator): 246 """A regressor for TensorFlow Debug models. 247 248 THIS CLASS IS DEPRECATED. See 249 [contrib/learn/README.md](https://www.tensorflow.org/code/tensorflow/contrib/learn/README.md) 250 for general migration instructions. 251 252 Example: 253 254 ```python 255 256 # Build DebugRegressor 257 regressor = DebugRegressor() 258 259 # Input builders 260 def input_fn_train: # returns x, y (where y represents label's class index). 261 pass 262 263 def input_fn_eval: # returns x, y (where y represents label's class index). 264 pass 265 266 # Fit model. 267 regressor.fit(input_fn=input_fn_train) 268 269 # Evaluate squared-loss between the test and train targets. 270 loss = regressor.evaluate(input_fn=input_fn_eval)["loss"] 271 272 # predict_scores outputs mean value seen during training. 273 predicted_targets = regressor.predict_scores(new_samples) 274 ``` 275 276 Input of `fit` and `evaluate` should have following features, 277 otherwise there will be a `KeyError`: 278 279 * if `weight_column_name` is not `None`, a feature with 280 `key=weight_column_name` whose value is a `Tensor`. 281 """ 282 283 def __init__(self, 284 model_dir=None, 285 label_dimension=1, 286 weight_column_name=None, 287 config=None, 288 feature_engineering_fn=None): 289 """Initializes a DebugRegressor instance. 290 291 Args: 292 model_dir: Directory to save model parameters, graph and etc. This can 293 also be used to load checkpoints from the directory into a estimator to 294 continue training a previously saved model. 295 label_dimension: Number of regression targets per example. This is the 296 size of the last dimension of the labels and logits `Tensor` objects 297 (typically, these have shape `[batch_size, label_dimension]`). 298 weight_column_name: A string defining feature column name representing 299 weights. It is used to down weight or boost examples during training. It 300 will be multiplied by the loss of the example. 301 config: `RunConfig` object to configure the runtime settings. 302 feature_engineering_fn: Feature engineering function. Takes features and 303 labels which are the output of `input_fn` and returns 304 features and labels which will be fed into the model. 305 Returns: 306 A `DebugRegressor` estimator. 307 """ 308 309 params = { 310 "head": 311 head_lib.regression_head( 312 weight_column_name=weight_column_name, 313 label_dimension=label_dimension, 314 enable_centered_bias=True) 315 } 316 317 super(DebugRegressor, self).__init__( 318 model_fn=debug_model_fn, 319 model_dir=model_dir, 320 config=config, 321 params=params, 322 feature_engineering_fn=feature_engineering_fn) 323 324 def predict_scores(self, input_fn=None, batch_size=None): 325 """Returns predicted scores for given features. 326 327 Args: 328 input_fn: Input function. 329 batch_size: Override default batch size. 330 331 Returns: 332 An iterable of predicted scores. 333 """ 334 key = prediction_key.PredictionKey.SCORES 335 preds = self.predict( 336 input_fn=input_fn, batch_size=batch_size, outputs=[key]) 337 return (pred[key] for pred in preds) 338