org.deeplearning4j.nn.layers.convolution

Class CnnLossLayer

java.lang.Object

org.deeplearning4j.nn.layers.AbstractLayer<LayerConfT>

org.deeplearning4j.nn.layers.BaseLayer<CnnLossLayer>

org.deeplearning4j.nn.layers.convolution.CnnLossLayer

All Implemented Interfaces:

Serializable, Cloneable, Classifier, Layer, IOutputLayer, Model

public class CnnLossLayer
extends BaseLayer<CnnLossLayer>
implements IOutputLayer

Convolutional Neural Network Loss Layer.
Handles calculation of gradients etc for various objective functions.
NOTE: CnnLossLayer does not have any parameters. Consequently, the output activations size is equal to the input size.
Input and output activations are same as other CNN layers: 4 dimensions with shape [miniBatchSize,channels,height,width]
CnnLossLayer has support for a built-in activation function (tanh, softmax etc) - if this is not required, set activation function to Activation.IDENTITY. For activations such as softmax, note that this is applied channels-wise: that is, softmax is applied along dimension 1 (channels) for each minibatch, and x/y location separately.

Note that 3 types of masking are supported: (n=minibatchSize, c=channels, h=height, w=width)
- Per example masking: Where an example is present or not (and all outputs are masked by it). Mask shape [n,1]
- Per x/y location masking: where each spatial X/Y location is present or not (all channels at a given x/y are masked by it). Mask shape: [n,h,w].
- Per output masking: Where each output activation value is present or not - mask shape [n,c,h,w] (same as output)

Author:

Alex Black

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface org.deeplearning4j.nn.api.Layer

Layer.TrainingMode, Layer.Type

Field Summary

Fields

Modifier and Type	Field and Description
protected org.nd4j.linalg.api.ndarray.INDArray	labels

Fields inherited from class org.deeplearning4j.nn.layers.BaseLayer

gradient, gradientsFlattened, gradientViews, optimizer, params, paramsFlattened, score, solver, weightNoiseParams

Fields inherited from class org.deeplearning4j.nn.layers.AbstractLayer

cacheMode, conf, dropoutApplied, dropoutMask, epochCount, index, input, iterationCount, maskArray, maskState, preOutput, trainingListeners

Constructor Summary

Constructors

Constructor and Description
CnnLossLayer(NeuralNetConfiguration conf)

Method Summary

Modifier and Type	Method and Description
org.nd4j.linalg.api.ndarray.INDArray	activate(boolean training, LayerWorkspaceMgr workspaceMgr) Perform forward pass and return the activations array with the last set input
org.nd4j.linalg.primitives.Pair<Gradient,org.nd4j.linalg.api.ndarray.INDArray>	backpropGradient(org.nd4j.linalg.api.ndarray.INDArray epsilon, LayerWorkspaceMgr workspaceMgr) Calculate the gradient relative to the error in the next layer
double	calcL1(boolean backpropParamsOnly) Calculate the l1 regularization term 0.0 if regularization is not used.
double	calcL2(boolean backpropParamsOnly) Calculate the l2 regularization term 0.0 if regularization is not used.
double	computeScore(double fullNetworkL1, double fullNetworkL2, boolean training, LayerWorkspaceMgr workspaceMgr) Compute score after labels and input have been set.
org.nd4j.linalg.api.ndarray.INDArray	computeScoreForExamples(double fullNetworkL1, double fullNetworkL2, LayerWorkspaceMgr workspaceMgr) Compute the score for each example individually, after labels and input have been set.
double	f1Score(org.nd4j.linalg.dataset.api.DataSet data) Sets the input and labels and returns a score for the prediction wrt true labels
double	f1Score(org.nd4j.linalg.api.ndarray.INDArray examples, org.nd4j.linalg.api.ndarray.INDArray labels) Returns the f1 score for the given examples.
org.nd4j.linalg.primitives.Pair<org.nd4j.linalg.api.ndarray.INDArray,MaskState>	feedForwardMaskArray(org.nd4j.linalg.api.ndarray.INDArray maskArray, MaskState currentMaskState, int minibatchSize) Feed forward the input mask array, setting in in the layer as appropriate.
void	fit(org.nd4j.linalg.dataset.api.DataSet data) Fit the model
void	fit(org.nd4j.linalg.dataset.api.iterator.DataSetIterator iter) Train the model based on the datasetiterator
void	fit(org.nd4j.linalg.api.ndarray.INDArray examples, org.nd4j.linalg.api.ndarray.INDArray labels) Fit the model
void	fit(org.nd4j.linalg.api.ndarray.INDArray examples, int[] labels) Fit the model
boolean	isPretrainLayer() Returns true if the layer can be trained in an unsupervised/pretrain manner (AE, VAE, etc)
org.nd4j.linalg.api.ndarray.INDArray	labelProbabilities(org.nd4j.linalg.api.ndarray.INDArray examples) Returns the probabilities for each label for each example row wise
boolean	needsLabels() Returns true if labels are required for this output layer
int	numLabels() Returns the number of possible labels
List<String>	predict(org.nd4j.linalg.dataset.api.DataSet dataSet) Takes in a DataSet of examples For each row, returns a label
int[]	predict(org.nd4j.linalg.api.ndarray.INDArray examples) Takes in a list of examples For each row, returns a label
void	setMaskArray(org.nd4j.linalg.api.ndarray.INDArray maskArray) Set the mask array.
Layer.Type	type() Returns the layer type

Methods inherited from class org.deeplearning4j.nn.layers.BaseLayer

accumulateScore, clear, clearNoiseWeightParams, clone, computeGradientAndScore, fit, fit, getGradientsViewArray, getOptimizer, getParam, getParamWithNoise, gradient, hasBias, initParams, layerConf, numParams, params, paramTable, paramTable, preOutput, score, setBackpropGradientsViewArray, setParam, setParams, setParams, setParamsViewArray, setParamTable, setScoreWithZ, toString, transpose, update, update

Methods inherited from class org.deeplearning4j.nn.layers.AbstractLayer

activate, addListeners, applyConstraints, applyDropOutIfNecessary, applyMask, assertInputSet, batchSize, conf, getIndex, getInput, getInputMiniBatchSize, getListeners, getMaskArray, gradientAndScore, init, input, layerId, numParams, setCacheMode, setConf, setIndex, setInput, setInputMiniBatchSize, setListeners, setListeners, validateInput

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.deeplearning4j.nn.api.layers.IOutputLayer

getLabels, setLabels

Methods inherited from interface org.deeplearning4j.nn.api.Layer

activate, clearNoiseWeightParams, clone, getEpochCount, getIndex, getInputMiniBatchSize, getIterationCount, getListeners, getMaskArray, setCacheMode, setEpochCount, setIndex, setInput, setInputMiniBatchSize, setIterationCount, setListeners, setListeners, transpose

Methods inherited from interface org.deeplearning4j.nn.api.Model

accumulateScore, addListeners, applyConstraints, batchSize, clear, computeGradientAndScore, conf, fit, fit, getGradientsViewArray, getOptimizer, getParam, gradient, gradientAndScore, init, initParams, input, numParams, numParams, params, paramTable, paramTable, score, setBackpropGradientsViewArray, setConf, setParam, setParams, setParamsViewArray, setParamTable, update, update, validateInput

Field Detail

labels

protected org.nd4j.linalg.api.ndarray.INDArray labels

Constructor Detail

CnnLossLayer

public CnnLossLayer(NeuralNetConfiguration conf)

Method Detail

backpropGradient

public org.nd4j.linalg.primitives.Pair<Gradient,org.nd4j.linalg.api.ndarray.INDArray> backpropGradient(org.nd4j.linalg.api.ndarray.INDArray epsilon,
                                                                                                       LayerWorkspaceMgr workspaceMgr)

Description copied from interface: Layer

Calculate the gradient relative to the error in the next layer

Specified by:

backpropGradient in interface Layer

Overrides:

backpropGradient in class BaseLayer<CnnLossLayer>

Parameters:

epsilon - w^(L+1)*delta^(L+1). Or, equiv: dC/da, i.e., (dC/dz)*(dz/da) = dC/da, where C is cost function a=sigma(z) is activation.

workspaceMgr - Workspace manager

Returns:

Pair where Gradient is gradient for this layer, INDArray is epsilon (activation gradient) needed by next layer, but before element-wise multiply by sigmaPrime(z). So for standard feed-forward layer, if this layer is L, then return.getSecond() == dL/dIn = (w^(L)*(delta^(L))^T)^T. Note that the returned array should be placed in the ArrayType.ACTIVATION_GRAD workspace via the workspace manager

calcL2

public double calcL2(boolean backpropParamsOnly)

Description copied from interface: Layer

Calculate the l2 regularization term
0.0 if regularization is not used. Or 0.5 * l2Coeff * l2Magnitude otherwise.
Note that this does not divide by mini-batch size

Specified by:

calcL2 in interface Layer

Overrides:

calcL2 in class BaseLayer<CnnLossLayer>

Parameters:

backpropParamsOnly - If true: calculate L2 based on backprop params only. If false: calculate based on all params (including pretrain params, if any)

Returns:

the l2 regularization term for this layer.

calcL1

public double calcL1(boolean backpropParamsOnly)

Description copied from interface: Layer

Calculate the l1 regularization term
0.0 if regularization is not used. Or l1Coeff * l1Magnitude otherwise.
Note that this does not divide by mini-batch size

Specified by:

calcL1 in interface Layer

Overrides:

calcL1 in class BaseLayer<CnnLossLayer>

Parameters:

backpropParamsOnly - If true: calculate L1 based on backprop params only. If false: calculate based on all params (including pretrain params, if any)

Returns:

the l1 regularization term for this layer.

f1Score

public double f1Score(org.nd4j.linalg.dataset.api.DataSet data)

Description copied from interface: Classifier

Sets the input and labels and returns a score for the prediction wrt true labels

Specified by:

f1Score in interface Classifier

Parameters:

data - the data to score

Returns:

the score for the given input,label pairs

f1Score

public double f1Score(org.nd4j.linalg.api.ndarray.INDArray examples,
                      org.nd4j.linalg.api.ndarray.INDArray labels)

Returns the f1 score for the given examples. Think of this to be like a percentage right. The higher the number the more it got right. This is on a scale from 0 to 1.

Specified by:

f1Score in interface Classifier

Parameters:

examples - te the examples to classify (one example in each row)

labels - the true labels

Returns:

the scores for each ndarray

numLabels

public int numLabels()

Description copied from interface: Classifier

Returns the number of possible labels

Specified by:

numLabels in interface Classifier

Returns:

the number of possible labels for this classifier

fit

public void fit(org.nd4j.linalg.dataset.api.iterator.DataSetIterator iter)

Description copied from interface: Classifier

Train the model based on the datasetiterator

Specified by:

fit in interface Classifier

Parameters:

iter - the iterator to train on

predict

public int[] predict(org.nd4j.linalg.api.ndarray.INDArray examples)

Description copied from interface: Classifier

Takes in a list of examples For each row, returns a label

Specified by:

predict in interface Classifier

Parameters:

examples - the examples to classify (one example in each row)

Returns:

the labels for each example

predict

public List<String> predict(org.nd4j.linalg.dataset.api.DataSet dataSet)

Description copied from interface: Classifier

Takes in a DataSet of examples For each row, returns a label

Specified by:

predict in interface Classifier

Parameters:

dataSet - the examples to classify

Returns:

the labels for each example

labelProbabilities

public org.nd4j.linalg.api.ndarray.INDArray labelProbabilities(org.nd4j.linalg.api.ndarray.INDArray examples)

Description copied from interface: Classifier

Returns the probabilities for each label for each example row wise

Specified by:

labelProbabilities in interface Classifier

Parameters:

examples - the examples to classify (one example in each row)

Returns:

the likelihoods of each example and each label

fit

public void fit(org.nd4j.linalg.api.ndarray.INDArray examples,
                org.nd4j.linalg.api.ndarray.INDArray labels)

Description copied from interface: Classifier

Fit the model

Specified by:

fit in interface Classifier

Parameters:

examples - the examples to classify (one example in each row)

labels - the example labels(a binary outcome matrix)

fit

public void fit(org.nd4j.linalg.dataset.api.DataSet data)

Description copied from interface: Classifier

Fit the model

Specified by:

fit in interface Classifier

Parameters:

data - the data to train on

fit

public void fit(org.nd4j.linalg.api.ndarray.INDArray examples,
                int[] labels)

Description copied from interface: Classifier

Fit the model

Specified by:

fit in interface Classifier

Parameters:

examples - the examples to classify (one example in each row)

labels - the labels for each example (the number of labels must match the number of rows in the example

type

public Layer.Type type()

Description copied from interface: Layer

Returns the layer type

Specified by:

type in interface Layer

Overrides:

type in class AbstractLayer<CnnLossLayer>

Returns:

activate

public org.nd4j.linalg.api.ndarray.INDArray activate(boolean training,
                                                     LayerWorkspaceMgr workspaceMgr)

Description copied from interface: Layer

Perform forward pass and return the activations array with the last set input

Specified by:

activate in interface Layer

Overrides:

activate in class BaseLayer<CnnLossLayer>

Parameters:

training - training or test mode

workspaceMgr - Workspace manager

Returns:

the activation (layer output) of the last specified input. Note that the returned array should be placed in the ArrayType.ACTIVATIONS workspace via the workspace manager

setMaskArray

public void setMaskArray(org.nd4j.linalg.api.ndarray.INDArray maskArray)

Description copied from interface: Layer

Set the mask array. Note: In general, Layer.feedForwardMaskArray(INDArray, MaskState, int) should be used in preference to this.

Specified by:

setMaskArray in interface Layer

Overrides:

setMaskArray in class AbstractLayer<CnnLossLayer>

Parameters:

maskArray - Mask array to set

isPretrainLayer

public boolean isPretrainLayer()

Description copied from interface: Layer

Returns true if the layer can be trained in an unsupervised/pretrain manner (AE, VAE, etc)

Specified by:

isPretrainLayer in interface Layer

Returns:

true if the layer can be pretrained (using fit(INDArray), false otherwise

feedForwardMaskArray

public org.nd4j.linalg.primitives.Pair<org.nd4j.linalg.api.ndarray.INDArray,MaskState> feedForwardMaskArray(org.nd4j.linalg.api.ndarray.INDArray maskArray,
                                                                                                            MaskState currentMaskState,
                                                                                                            int minibatchSize)

Description copied from interface: Layer

Feed forward the input mask array, setting in in the layer as appropriate. This allows different layers to handle masks differently - for example, bidirectional RNNs and normal RNNs operate differently with masks (the former sets activations to 0 outside of the data present region (and keeps the mask active for future layers like dense layers), whereas normal RNNs don't zero out the activations/errors )instead relying on backpropagated error arrays to handle the variable length case.
This is also used for example for networks that contain global pooling layers, arbitrary preprocessors, etc.

Specified by:

feedForwardMaskArray in interface Layer

Overrides:

feedForwardMaskArray in class AbstractLayer<CnnLossLayer>

Parameters:

maskArray - Mask array to set

currentMaskState - Current state of the mask - see MaskState

minibatchSize - Current minibatch size. Needs to be known as it cannot always be inferred from the activations array due to reshaping (such as a DenseLayer within a recurrent neural network)

Returns:

New mask array after this layer, along with the new mask state.

needsLabels

public boolean needsLabels()

Description copied from interface: IOutputLayer

Returns true if labels are required for this output layer

Specified by:

needsLabels in interface IOutputLayer

Returns:

true if this output layer needs labels or not

computeScore

public double computeScore(double fullNetworkL1,
                           double fullNetworkL2,
                           boolean training,
                           LayerWorkspaceMgr workspaceMgr)

Description copied from interface: IOutputLayer

Compute score after labels and input have been set.

Specified by:

computeScore in interface IOutputLayer

Parameters:

fullNetworkL1 - L1 regularization term for the entire network

fullNetworkL2 - L2 regularization term for the entire network

training - whether score should be calculated at train or test time (this affects things like application of dropout, etc)

Returns:

score (loss function)

computeScoreForExamples

public org.nd4j.linalg.api.ndarray.INDArray computeScoreForExamples(double fullNetworkL1,
                                                                    double fullNetworkL2,
                                                                    LayerWorkspaceMgr workspaceMgr)

Compute the score for each example individually, after labels and input have been set.

Specified by:

computeScoreForExamples in interface IOutputLayer

Parameters:

fullNetworkL1 - L1 regularization term for the entire network (or, 0.0 to not include regularization)

fullNetworkL2 - L2 regularization term for the entire network (or, 0.0 to not include regularization)

Returns:

A column INDArray of shape [numExamples,1], where entry i is the score of the ith example