1# Copyright 2015 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# pylint: disable=g-short-docstring-punctuation 16"""Histograms. 17""" 18 19from tensorflow.python.framework import dtypes 20from tensorflow.python.framework import ops 21from tensorflow.python.ops import array_ops 22from tensorflow.python.ops import clip_ops 23from tensorflow.python.ops import control_flow_ops 24from tensorflow.python.ops import gen_math_ops 25from tensorflow.python.ops import math_ops 26from tensorflow.python.util import dispatch 27from tensorflow.python.util.tf_export import tf_export 28 29 30@tf_export('histogram_fixed_width_bins') 31@dispatch.add_dispatch_support 32def histogram_fixed_width_bins(values, 33 value_range, 34 nbins=100, 35 dtype=dtypes.int32, 36 name=None): 37 """Bins the given values for use in a histogram. 38 39 Given the tensor `values`, this operation returns a rank 1 `Tensor` 40 representing the indices of a histogram into which each element 41 of `values` would be binned. The bins are equal width and 42 determined by the arguments `value_range` and `nbins`. 43 44 Args: 45 values: Numeric `Tensor`. 46 value_range: Shape [2] `Tensor` of same `dtype` as `values`. 47 values <= value_range[0] will be mapped to hist[0], 48 values >= value_range[1] will be mapped to hist[-1]. 49 nbins: Scalar `int32 Tensor`. Number of histogram bins. 50 dtype: dtype for returned histogram. 51 name: A name for this operation (defaults to 'histogram_fixed_width'). 52 53 Returns: 54 A `Tensor` holding the indices of the binned values whose shape matches 55 `values`. 56 57 Raises: 58 TypeError: If any unsupported dtype is provided. 59 tf.errors.InvalidArgumentError: If value_range does not 60 satisfy value_range[0] < value_range[1]. 61 62 Examples: 63 64 >>> # Bins will be: (-inf, 1), [1, 2), [2, 3), [3, 4), [4, inf) 65 ... 66 >>> nbins = 5 67 >>> value_range = [0.0, 5.0] 68 >>> new_values = [-1.0, 0.0, 1.5, 2.0, 5.0, 15] 69 >>> indices = tf.histogram_fixed_width_bins(new_values, value_range, nbins=5) 70 >>> indices.numpy() 71 array([0, 0, 1, 2, 4, 4], dtype=int32) 72 """ 73 with ops.name_scope(name, 'histogram_fixed_width_bins', 74 [values, value_range, nbins]): 75 values = ops.convert_to_tensor(values, name='values') 76 shape = array_ops.shape(values) 77 78 values = array_ops.reshape(values, [-1]) 79 value_range = ops.convert_to_tensor(value_range, name='value_range') 80 nbins = ops.convert_to_tensor(nbins, dtype=dtypes.int32, name='nbins') 81 check = control_flow_ops.Assert( 82 math_ops.greater(nbins, 0), ['nbins %s must > 0' % nbins]) 83 nbins = control_flow_ops.with_dependencies([check], nbins) 84 nbins_float = math_ops.cast(nbins, values.dtype) 85 86 # Map tensor values that fall within value_range to [0, 1]. 87 scaled_values = math_ops.truediv( 88 values - value_range[0], 89 value_range[1] - value_range[0], 90 name='scaled_values') 91 92 # map tensor values within the open interval value_range to {0,.., nbins-1}, 93 # values outside the open interval will be zero or less, or nbins or more. 94 indices = math_ops.floor(nbins_float * scaled_values, name='indices') 95 96 # Clip edge cases (e.g. value = value_range[1]) or "outliers." 97 indices = math_ops.cast( 98 clip_ops.clip_by_value(indices, 0, nbins_float - 1), dtypes.int32) 99 return array_ops.reshape(indices, shape) 100 101 102@tf_export('histogram_fixed_width') 103@dispatch.add_dispatch_support 104def histogram_fixed_width(values, 105 value_range, 106 nbins=100, 107 dtype=dtypes.int32, 108 name=None): 109 """Return histogram of values. 110 111 Given the tensor `values`, this operation returns a rank 1 histogram counting 112 the number of entries in `values` that fell into every bin. The bins are 113 equal width and determined by the arguments `value_range` and `nbins`. 114 115 Args: 116 values: Numeric `Tensor`. 117 value_range: Shape [2] `Tensor` of same `dtype` as `values`. 118 values <= value_range[0] will be mapped to hist[0], 119 values >= value_range[1] will be mapped to hist[-1]. 120 nbins: Scalar `int32 Tensor`. Number of histogram bins. 121 dtype: dtype for returned histogram. 122 name: A name for this operation (defaults to 'histogram_fixed_width'). 123 124 Returns: 125 A 1-D `Tensor` holding histogram of values. 126 127 Raises: 128 TypeError: If any unsupported dtype is provided. 129 tf.errors.InvalidArgumentError: If value_range does not 130 satisfy value_range[0] < value_range[1]. 131 132 Examples: 133 134 >>> # Bins will be: (-inf, 1), [1, 2), [2, 3), [3, 4), [4, inf) 135 ... 136 >>> nbins = 5 137 >>> value_range = [0.0, 5.0] 138 >>> new_values = [-1.0, 0.0, 1.5, 2.0, 5.0, 15] 139 >>> hist = tf.histogram_fixed_width(new_values, value_range, nbins=5) 140 >>> hist.numpy() 141 array([2, 1, 1, 0, 2], dtype=int32) 142 """ 143 with ops.name_scope(name, 'histogram_fixed_width', 144 [values, value_range, nbins]) as name: 145 # pylint: disable=protected-access 146 return gen_math_ops._histogram_fixed_width( 147 values, value_range, nbins, dtype=dtype, name=name) 148 # pylint: enable=protected-access 149