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"""Sparse feature column (deprecated).
16
17This module and all its submodules are deprecated. To UPDATE or USE linear
18optimizers, please check its latest version in core:
19tensorflow_estimator/python/estimator/canned/linear_optimizer/.
20"""
21
22from __future__ import absolute_import
23from __future__ import division
24from __future__ import print_function
25
26from tensorflow.python.framework import dtypes
27from tensorflow.python.framework.ops import internal_convert_to_tensor
28from tensorflow.python.framework.ops import name_scope
29from tensorflow.python.util import deprecation
30
31
32class SparseFeatureColumn(object):
33  """Represents a sparse feature column.
34
35  Contains three tensors representing a sparse feature column, they are
36  example indices (`int64`), feature indices (`int64`), and feature
37  values (`float`).
38  Feature weights are optional, and are treated as `1.0f` if missing.
39
40  For example, consider a batch of 4 examples, which contains the following
41  features in a particular `SparseFeatureColumn`:
42
43  * Example 0: feature 5, value 1
44  * Example 1: feature 6, value 1 and feature 10, value 0.5
45  * Example 2: no features
46  * Example 3: two copies of feature 2, value 1
47
48  This SparseFeatureColumn will be represented as follows:
49
50  ```
51   <0, 5,  1>
52   <1, 6,  1>
53   <1, 10, 0.5>
54   <3, 2,  1>
55   <3, 2,  1>
56  ```
57
58  For a batch of 2 examples below:
59
60  * Example 0: feature 5
61  * Example 1: feature 6
62
63  is represented by `SparseFeatureColumn` as:
64
65  ```
66   <0, 5,  1>
67   <1, 6,  1>
68
69  ```
70
71  @@__init__
72  @@example_indices
73  @@feature_indices
74  @@feature_values
75  """
76
77  @deprecation.deprecated(
78      None, 'This class is deprecated. To UPDATE or USE linear optimizers, '
79      'please check its latest version in core: '
80      'tensorflow_estimator/python/estimator/canned/linear_optimizer/.')
81  def __init__(self, example_indices, feature_indices, feature_values):
82    """Creates a `SparseFeatureColumn` representation.
83
84    Args:
85      example_indices: A 1-D int64 tensor of shape `[N]`. Also, accepts
86      python lists, or numpy arrays.
87      feature_indices: A 1-D int64 tensor of shape `[N]`. Also, accepts
88      python lists, or numpy arrays.
89      feature_values: An optional 1-D tensor float tensor of shape `[N]`. Also,
90      accepts python lists, or numpy arrays.
91
92    Returns:
93      A `SparseFeatureColumn`
94    """
95    with name_scope(None, 'SparseFeatureColumn',
96                    [example_indices, feature_indices]):
97      self._example_indices = internal_convert_to_tensor(
98          example_indices, name='example_indices', dtype=dtypes.int64)
99      self._feature_indices = internal_convert_to_tensor(
100          feature_indices, name='feature_indices', dtype=dtypes.int64)
101    self._feature_values = None
102    if feature_values is not None:
103      with name_scope(None, 'SparseFeatureColumn', [feature_values]):
104        self._feature_values = internal_convert_to_tensor(
105            feature_values, name='feature_values', dtype=dtypes.float32)
106
107  @property
108  def example_indices(self):
109    """The example indices represented as a dense tensor.
110
111    Returns:
112      A 1-D Tensor of int64 with shape `[N]`.
113    """
114    return self._example_indices
115
116  @property
117  def feature_indices(self):
118    """The feature indices represented as a dense tensor.
119
120    Returns:
121      A 1-D Tensor of int64 with shape `[N]`.
122    """
123    return self._feature_indices
124
125  @property
126  def feature_values(self):
127    """The feature values represented as a dense tensor.
128
129    Returns:
130      May return None, or a 1-D Tensor of float32 with shape `[N]`.
131    """
132    return self._feature_values
133