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 """`Trainable` interface.""" 16 17 from __future__ import absolute_import 18 from __future__ import division 19 from __future__ import print_function 20 21 import abc 22 23 24 class Trainable(object): 25 """Interface for objects that are trainable by, e.g., `Experiment`. 26 """ 27 __metaclass__ = abc.ABCMeta 28 29 @abc.abstractmethod 30 def fit(self, 31 x=None, 32 y=None, 33 input_fn=None, 34 steps=None, 35 batch_size=None, 36 monitors=None, 37 max_steps=None): 38 """Trains a model given training data `x` predictions and `y` labels. 39 40 Args: 41 x: Matrix of shape [n_samples, n_features...] or the dictionary of 42 Matrices. 43 Can be iterator that returns arrays of features or dictionary of arrays 44 of features. 45 The training input samples for fitting the model. If set, `input_fn` 46 must be `None`. 47 y: Vector or matrix [n_samples] or [n_samples, n_outputs] or the 48 dictionary of same. 49 Can be iterator that returns array of labels or dictionary of array of 50 labels. 51 The training label values (class labels in classification, real numbers 52 in regression). 53 If set, `input_fn` must be `None`. Note: For classification, label 54 values must 55 be integers representing the class index (i.e. values from 0 to 56 n_classes-1). 57 input_fn: Input function returning a tuple of: 58 features - `Tensor` or dictionary of string feature name to `Tensor`. 59 labels - `Tensor` or dictionary of `Tensor` with labels. 60 If input_fn is set, `x`, `y`, and `batch_size` must be `None`. 61 steps: Number of steps for which to train model. If `None`, train forever. 62 'steps' works incrementally. If you call two times fit(steps=10) then 63 training occurs in total 20 steps. If you don't want to have incremental 64 behavior please set `max_steps` instead. If set, `max_steps` must be 65 `None`. 66 batch_size: minibatch size to use on the input, defaults to first 67 dimension of `x`. Must be `None` if `input_fn` is provided. 68 monitors: List of `BaseMonitor` subclass instances. Used for callbacks 69 inside the training loop. 70 max_steps: Number of total steps for which to train model. If `None`, 71 train forever. If set, `steps` must be `None`. 72 73 Two calls to `fit(steps=100)` means 200 training 74 iterations. On the other hand, two calls to `fit(max_steps=100)` means 75 that the second call will not do any iteration since first call did 76 all 100 steps. 77 78 Returns: 79 `self`, for chaining. 80 """ 81 raise NotImplementedError 82
