Skip to content

Slices

The slice, or layer, of the network provides flexibility over the level of abstraction for the explanation. In a low layer, an explanation may highlight the edges that were most important in identifying an object like a face, while in a higher layer, the explanation might highlight high-level features such as a nose or mouth. By raising the level of abstraction, explanations that generalize over larger sets of samples are possible.

Formally, A network, \(f\), can be broken into a slice, \(f = g \circ h\), where \(h\) can be thought of as a pre-processor that computes features, and \(g\) can be thought of as a sub-model that uses the features computed by \(h\).

Cut

Bases: object

A cut is the primary building block for a slice. It determines an internal component of a network to expose. A slice if formed by two cuts.

Source code in trulens_explain/trulens/nn/slices.py 
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
class Cut(object):
    """
    A cut is the primary building block for a slice. It determines an internal
    component of a network to expose. A slice if formed by two cuts.
    """

    def __init__(
        self,
        name: LayerIdentifier,
        anchor: str = 'out',
        accessor: Optional[Callable] = None
    ):
        """
        Parameters:
            name:
                The name or index of a layer in the model, or a list containing
                the names/indices of mutliple layers.

            anchor: 
                Determines whether input (`'in'`) or the output (`'out'`) tensor
                of the spcified layer should be used.

            accessor:
                An accessor function that operates on the layer, mapping the 
                tensor (or list thereof) corresponding to the layer's 
                input/output to another tensor (or list thereof). This can be 
                used to, e.g., extract a particular output from a layer that 
                produces a sequence of outputs. If `accessor` is `None`, the 
                following accessor function will be used: 
                ```python
                lambda t: t[-1] if isinstance(t, list) else t
                ```
        """
        assert name is None or isinstance(
            name, (list, int, str)
        ), "Cut.name must be one of: layer index, layer name, or list of names/indices of multiple layers"
        if isinstance(name, list):
            for n in name:
                assert isinstance(
                    n, (int, str)
                ), f"Elements in Cut.name must be layer names (str) or indices (int). Got type {type(n)}"
        anchor = str(anchor)
        assert anchor in [
            'in', 'out'
        ], "Cut.anchor must be one of ('in', 'out')"
        assert accessor is None or isinstance(
            accessor, Callable
        ), "Cut.accessor must be callable or None"

        if get_backend().backend == 'pytorch':
            if (isinstance(name, int) or
                (isinstance(name, list) and isinstance(name[0], int))):

                tru_logger.warning(
                    '\n\nPytorch does not have native support for indexed '
                    'layers. Using layer indices is not recommended.\n'
                )

        self.name = name
        self.accessor = accessor
        self.anchor = anchor

    def __str__(self):
        return render_object(self, ['name', 'accessor', 'anchor'])

    # TODO: layer arg might need to be more specific
    def access_layer(self, layer: TensorLike) -> TensorLike:
        """
        Applies `self.accessor` to the result of collecting the relevant 
        tensor(s) associated with a layer's output.

        Parameters:
            layer:
                The tensor output (or input, if so specified by the anchor) of 
                the layer(s) specified by this cut.

        Returns:
            The result of applying `self.accessor` to the given layer.
        """
        if layer is None:
            return layer
        elif self.accessor is None:
            return layer
        else:
            layer = (
                layer[0]
                if isinstance(layer, list) and len(layer) == 1 else layer
            )
            return self.accessor(layer)

__init__(name, anchor='out', accessor=None)

Parameters:

Name Type Description Default
name LayerIdentifier

The name or index of a layer in the model, or a list containing the names/indices of mutliple layers.

 required
anchor str

Determines whether input ('in') or the output ('out') tensor of the spcified layer should be used.

 'out'
accessor Optional[Callable]

An accessor function that operates on the layer, mapping the tensor (or list thereof) corresponding to the layer's input/output to another tensor (or list thereof). This can be used to, e.g., extract a particular output from a layer that produces a sequence of outputs. If accessor is None, the following accessor function will be used: 

lambda t: t[-1] if isinstance(t, list) else t

None
Source code in trulens_explain/trulens/nn/slices.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
def __init__(
    self,
    name: LayerIdentifier,
    anchor: str = 'out',
    accessor: Optional[Callable] = None
):
    """
    Parameters:
        name:
            The name or index of a layer in the model, or a list containing
            the names/indices of mutliple layers.

        anchor: 
            Determines whether input (`'in'`) or the output (`'out'`) tensor
            of the spcified layer should be used.

        accessor:
            An accessor function that operates on the layer, mapping the 
            tensor (or list thereof) corresponding to the layer's 
            input/output to another tensor (or list thereof). This can be 
            used to, e.g., extract a particular output from a layer that 
            produces a sequence of outputs. If `accessor` is `None`, the 
            following accessor function will be used: 
            ```python
            lambda t: t[-1] if isinstance(t, list) else t
            ```
    """
    assert name is None or isinstance(
        name, (list, int, str)
    ), "Cut.name must be one of: layer index, layer name, or list of names/indices of multiple layers"
    if isinstance(name, list):
        for n in name:
            assert isinstance(
                n, (int, str)
            ), f"Elements in Cut.name must be layer names (str) or indices (int). Got type {type(n)}"
    anchor = str(anchor)
    assert anchor in [
        'in', 'out'
    ], "Cut.anchor must be one of ('in', 'out')"
    assert accessor is None or isinstance(
        accessor, Callable
    ), "Cut.accessor must be callable or None"

    if get_backend().backend == 'pytorch':
        if (isinstance(name, int) or
            (isinstance(name, list) and isinstance(name[0], int))):

            tru_logger.warning(
                '\n\nPytorch does not have native support for indexed '
                'layers. Using layer indices is not recommended.\n'
            )

    self.name = name
    self.accessor = accessor
    self.anchor = anchor

access_layer(layer)

Applies self.accessor to the result of collecting the relevant tensor(s) associated with a layer's output.

Parameters:

Name Type Description Default
layer TensorLike

The tensor output (or input, if so specified by the anchor) of the layer(s) specified by this cut.

 required

Returns:

Type Description
TensorLike

The result of applying self.accessor to the given layer.
Source code in trulens_explain/trulens/nn/slices.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
def access_layer(self, layer: TensorLike) -> TensorLike:
    """
    Applies `self.accessor` to the result of collecting the relevant 
    tensor(s) associated with a layer's output.

    Parameters:
        layer:
            The tensor output (or input, if so specified by the anchor) of 
            the layer(s) specified by this cut.

    Returns:
        The result of applying `self.accessor` to the given layer.
    """
    if layer is None:
        return layer
    elif self.accessor is None:
        return layer
    else:
        layer = (
            layer[0]
            if isinstance(layer, list) and len(layer) == 1 else layer
        )
        return self.accessor(layer)

InputCut

Bases: Cut

Special cut that selects the input(s) of a model.

Source code in trulens_explain/trulens/nn/slices.py 
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
class InputCut(Cut):
    """
    Special cut that selects the input(s) of a model.
    """

    def __init__(self, anchor: str = 'in', accessor: Optional[Callable] = None):
        """
        Parameters:
            anchor: 
                Determines whether input (`'in'`) or the output (`'out'`) tensor
                of the spcified layer should be used.

            accessor:
                An accessor function that operates on the layer, mapping the 
                tensor (or list thereof) corresponding to the layer's 
                input/output to another tensor (or list thereof). This can be 
                used to, e.g., extract a particular output from a layer that 
                produces a sequence of outputs. If `accessor` is `None`, the 
                following accessor function will be used: 
                ```python
                lambda t: t[-1] if isinstance(t, list) else t
                ```
        """
        super().__init__(None, anchor, accessor)

__init__(anchor='in', accessor=None)

Parameters:

Name Type Description Default
anchor str

Determines whether input ('in') or the output ('out') tensor of the spcified layer should be used.

 'in'
accessor Optional[Callable]

An accessor function that operates on the layer, mapping the tensor (or list thereof) corresponding to the layer's input/output to another tensor (or list thereof). This can be used to, e.g., extract a particular output from a layer that produces a sequence of outputs. If accessor is None, the following accessor function will be used: 

lambda t: t[-1] if isinstance(t, list) else t

None
Source code in trulens_explain/trulens/nn/slices.py 
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
def __init__(self, anchor: str = 'in', accessor: Optional[Callable] = None):
    """
    Parameters:
        anchor: 
            Determines whether input (`'in'`) or the output (`'out'`) tensor
            of the spcified layer should be used.

        accessor:
            An accessor function that operates on the layer, mapping the 
            tensor (or list thereof) corresponding to the layer's 
            input/output to another tensor (or list thereof). This can be 
            used to, e.g., extract a particular output from a layer that 
            produces a sequence of outputs. If `accessor` is `None`, the 
            following accessor function will be used: 
            ```python
            lambda t: t[-1] if isinstance(t, list) else t
            ```
    """
    super().__init__(None, anchor, accessor)

LogitCut

Bases: Cut

Special cut that selects the logit layer of a model. The logit layer must be named 'logits' or otherwise specified by the user to the model wrapper.

Source code in trulens_explain/trulens/nn/slices.py 
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
class LogitCut(Cut):
    """
    Special cut that selects the logit layer of a model. The logit layer must be
    named `'logits'` or otherwise specified by the user to the model wrapper.
    """

    def __init__(
        self, anchor: str = 'out', accessor: Optional[Callable] = None
    ):
        """
        Parameters:
            anchor: 
                Determines whether input (`'in'`) or the output (`'out'`) tensor
                of the spcified layer should be used.

            accessor:
                An accessor function that operates on the layer, mapping the 
                tensor (or list thereof) corresponding to the layer's 
                input/output to another tensor (or list thereof). This can be 
                used to, e.g., extract a particular output from a layer that 
                produces a sequence of outputs. If `accessor` is `None`, the 
                following accessor function will be used: 
                ```python
                lambda t: t[-1] if isinstance(t, list) else t
                ```
        """
        super(LogitCut, self).__init__(None, anchor, accessor)

__init__(anchor='out', accessor=None)

Parameters:

Name Type Description Default
anchor str

Determines whether input ('in') or the output ('out') tensor of the spcified layer should be used.

 'out'
accessor Optional[Callable]

An accessor function that operates on the layer, mapping the tensor (or list thereof) corresponding to the layer's input/output to another tensor (or list thereof). This can be used to, e.g., extract a particular output from a layer that produces a sequence of outputs. If accessor is None, the following accessor function will be used: 

lambda t: t[-1] if isinstance(t, list) else t

None
Source code in trulens_explain/trulens/nn/slices.py 
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
def __init__(
    self, anchor: str = 'out', accessor: Optional[Callable] = None
):
    """
    Parameters:
        anchor: 
            Determines whether input (`'in'`) or the output (`'out'`) tensor
            of the spcified layer should be used.

        accessor:
            An accessor function that operates on the layer, mapping the 
            tensor (or list thereof) corresponding to the layer's 
            input/output to another tensor (or list thereof). This can be 
            used to, e.g., extract a particular output from a layer that 
            produces a sequence of outputs. If `accessor` is `None`, the 
            following accessor function will be used: 
            ```python
            lambda t: t[-1] if isinstance(t, list) else t
            ```
    """
    super(LogitCut, self).__init__(None, anchor, accessor)

OutputCut

Bases: Cut

Special cut that selects the output(s) of a model.

Source code in trulens_explain/trulens/nn/slices.py 
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
class OutputCut(Cut):
    """
    Special cut that selects the output(s) of a model.
    """

    def __init__(
        self, anchor: str = 'out', accessor: Optional[Callable] = None
    ):
        """
        Parameters:
            anchor: 
                Determines whether input (`'in'`) or the output (`'out'`) tensor
                of the spcified layer should be used.

            accessor:
                An accessor function that operates on the layer, mapping the 
                tensor (or list thereof) corresponding to the layer's 
                input/output to another tensor (or list thereof). This can be 
                used to, e.g., extract a particular output from a layer that 
                produces a sequence of outputs. If `accessor` is `None`, the 
                following accessor function will be used: 
                ```python
                lambda t: t[-1] if isinstance(t, list) else t
                ```
        """
        super(OutputCut, self).__init__(None, anchor, accessor)

__init__(anchor='out', accessor=None)

Parameters:

Name Type Description Default
anchor str

Determines whether input ('in') or the output ('out') tensor of the spcified layer should be used.

 'out'
accessor Optional[Callable]

An accessor function that operates on the layer, mapping the tensor (or list thereof) corresponding to the layer's input/output to another tensor (or list thereof). This can be used to, e.g., extract a particular output from a layer that produces a sequence of outputs. If accessor is None, the following accessor function will be used: 

lambda t: t[-1] if isinstance(t, list) else t

None
Source code in trulens_explain/trulens/nn/slices.py 
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
def __init__(
    self, anchor: str = 'out', accessor: Optional[Callable] = None
):
    """
    Parameters:
        anchor: 
            Determines whether input (`'in'`) or the output (`'out'`) tensor
            of the spcified layer should be used.

        accessor:
            An accessor function that operates on the layer, mapping the 
            tensor (or list thereof) corresponding to the layer's 
            input/output to another tensor (or list thereof). This can be 
            used to, e.g., extract a particular output from a layer that 
            produces a sequence of outputs. If `accessor` is `None`, the 
            following accessor function will be used: 
            ```python
            lambda t: t[-1] if isinstance(t, list) else t
            ```
    """
    super(OutputCut, self).__init__(None, anchor, accessor)

Slice

Bases: object

Class representing a slice of a network. A network, \(f\), can be broken into a slice, \(f = g \circ h\), where \(h\) can be thought of as a pre-processor that computes features, and \(g\) can be thought of as a sub-model that uses the features computed by \(h\).

A Slice object represents a slice as two Cuts, from_cut and to_cut, which are the layers corresponding to the output of \(h\) and \(g\), respectively.

Source code in trulens_explain/trulens/nn/slices.py 
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
class Slice(object):
    """
    Class representing a slice of a network. A network, $f$, can be broken
    into a slice, $f = g \\circ h$, where $h$ can be thought of as a 
    pre-processor that computes features, and $g$ can be thought of as a 
    sub-model that uses the features computed by $h$.

    A `Slice` object represents a slice as two `Cut`s, `from_cut` and `to_cut`,
    which are the layers corresponding to the output of $h$ and $g$, 
    respectively.
    """

    def __init__(self, from_cut: Cut, to_cut: Cut):
        """
        Parameters:
            from_cut:
                Cut representing the output of the preprocessing function, $h$,
                in slice, $f = g \\circ h$.

            to_cut:
                Cut representing the output of the sub-model, $g$, in slice, 
                $f = g \\circ h$.
        """
        self._from_cut = from_cut
        self._to_cut = to_cut

    @property
    def from_cut(self) -> Cut:
        """
        Cut representing the output of the preprocessing function, $h$, in 
        slice, $f = g \\circ h$.
        """
        return self._from_cut

    @property
    def to_cut(self) -> Cut:
        """
        Cut representing the output of the sub-model, $g$, in slice, 
        $f = g \\circ h$.
        """
        return self._to_cut

    @staticmethod
    def full_network():
        """
        Returns
        -------
        Slice
            A slice representing the entire model, i.e., :math:`f = g \\circ h`,
            where :math:`h` is the identity function and :math:`g = f`.
        """
        return Slice(InputCut(), OutputCut())

from_cut: Cut property

Cut representing the output of the preprocessing function, \(h\), in slice, \(f = g \circ h\).

to_cut: Cut property

Cut representing the output of the sub-model, \(g\), in slice, \(f = g \circ h\).

__init__(from_cut, to_cut)

Parameters:

Name Type Description Default
from_cut Cut

Cut representing the output of the preprocessing function, \(h\), in slice, \(f = g \circ h\).

 required
to_cut Cut

Cut representing the output of the sub-model, \(g\), in slice, \(f = g \circ h\).

 required
Source code in trulens_explain/trulens/nn/slices.py 
211
212
213
214
215
216
217
218
219
220
221
222
223
def __init__(self, from_cut: Cut, to_cut: Cut):
    """
    Parameters:
        from_cut:
            Cut representing the output of the preprocessing function, $h$,
            in slice, $f = g \\circ h$.

        to_cut:
            Cut representing the output of the sub-model, $g$, in slice, 
            $f = g \\circ h$.
    """
    self._from_cut = from_cut
    self._to_cut = to_cut

full_network() staticmethod

Returns

Slice A slice representing the entire model, i.e., :math:f = g \circ h, where :math:h is the identity function and :math:g = f.

Source code in trulens_explain/trulens/nn/slices.py 
241
242
243
244
245
246
247
248
249
250
@staticmethod
def full_network():
    """
    Returns
    -------
    Slice
        A slice representing the entire model, i.e., :math:`f = g \\circ h`,
        where :math:`h` is the identity function and :math:`g = f`.
    """
    return Slice(InputCut(), OutputCut())