ConvolutionLayer¶
A 1/2/3/N-D standard convolution layer.
A convolution sweeps a learned kernel array over the input data, along one or more dimensions, using a given step size. For each valid position of the kernel, the node computes a "matching score" between the data and the kernel as an inner product, i.e., an elementwise product of the two arrays followed by a sum over all product terms. This way, each kernel effectively learns a translation-invariant pattern in the data, and a typical convolution layer will learn multiple such kernels, each yielding a different feature (which are collected in an output feature axis). The output array is arranged to have the same spatial dimensions as the input, but becomes downsampled if the step size was greater than one. Furthermore, the kernel may be allowed to run off the edge of the input data, in which case the missing data is assumed to be zero, and this behavior is controlled via the padding argument. As special cases, a step size of 1 and padding of 'same' will result in an output array of the same size as the input. The operation generally does not care about the presence or absence of an instance ("batch") axis, and will process any such axes, or any other extra dimensions, independently with the same kernels. Another aspect of kernels is that the input data may (and likely will) already have a feature axis, and this axis is generally treated specially by convolution operations (also known as the "channels axis" in some frameworks, after color channels in image processing). Crucially, in full convolution the kernel array has an implicit feature axis, which allows the convolution to capture patterns that extend across both the swept spatial axes and any input feature axis (if any). Alternatively, this node can also implement grouped convolution (an in-between of full and depthwise convolution), where the input and output features are partitioned into N equally-sized subsets, and the first k/N output features are derived from only the first N input features, and so forth, in increments of N, yielding a number of output features that must be divisible by N. N must be given as the feature_group_count parameter. Another feature supported by this node is dilated convolution, in which the kernel is implicitly scaled by an integer factor along each spatial axis, which allows for using a smaller kernel to cover larger patterns, and which results in higher-resolution spatial output compared to the more common alternative of applying a convolution after pooling and downsampling of the data. Generally if there were multiple feature axes in the input they will be flattened into a single feature axis placed at the end. The full output shape is first the instance axes if any, then any unspecified non-feature dimensions, then the specified "spatial" (i.e., swept-over) dimensions in the order specified, followed by a single feature axis. In image processing, each convolution is usually followed by a non-linearity, which makes the operation an actual feature detector rather than just a linear transformation. However, in signal processing, convolutions are often used to learn spatial (e.g., ICA-like) and/or temporal (e.g., FIR-type) filters, mimicking traditional signal processing pipelines, and in such uses the subsequent non-linearity, and also the optional bias parameter of the convolution, are often omitted. More Info... Version 0.2.0
Ports/Properties¶
data¶
Data to process.
- verbose name: Data
- default value: None
- port type: DataPort
- value type: AnyNumeric (can be None)
- data direction: INOUT
mask¶
Mask to apply to the weights.
- verbose name: Mask
- default value: None
- port type: DataPort
- value type: AnyArray (can be None)
- data direction: IN
w_init¶
Initializer for the weights.
- verbose name: W Init
- default value: None
- port type: DataPort
- value type: BaseNode (can be None)
- data direction: IN
b_init¶
Initializer for the bias.
- verbose name: B Init
- default value: None
- port type: DataPort
- value type: BaseNode (can be None)
- data direction: IN
w_prior¶
Optional prior distribution for the weights.
- verbose name: W Prior
- default value: None
- port type: DataPort
- value type: Distribution (can be None)
- data direction: IN
b_prior¶
Optional prior distribution for the bias.
- verbose name: B Prior
- default value: None
- port type: DataPort
- value type: Distribution (can be None)
- data direction: IN
sweep_axes¶
List and order of axes over which the convolution filter kernel is swept. If the input data are packets, this determines the order of these axes in the output data, and the order of the axes in the kernel (for plain array inputs, see end of tooltip). A kernel is a learned array that is shifted over all possible positions in the data (optionally with step size in each dimension, and optionally going past the edges of the data by half the kernel size if padding=same). For each position, the kernel is multiplied by the data in the region covered by the kernel and the resulting (elementwise) product is integrated (summed) to produce a single output score (a measure of match between the kernel and the data in that region). If the input data has an extra feature axis, the kernel will usually have an implicit extra axis to hold weights for each input feature. If the data has an instance axis, each instance will be processed separately (using the same kernels). If the input data are plain arrays, this merely determines the number of spatial axes and the names are just mnemonic and not otherwise used. This can alternatively be given as just a number to set the number of spatial dimensions, corresponding to the N in N-D convolution; for packet data, this will resolve to the last N axes in the data that are neither feature nor instance axes. This parameter is not limited to the predefined options.
- verbose name: Axes To Sweep Kernel Over (Convolve)
- default value: time
- port type: ComboPort
- value type: str (can be None)
output_features¶
Number of filter kernels (and features) to learn. This value determines the length of the feature axis in the output data (each kernel yields one output feature, representing raw feature detection score produced by that kernel). In classic deep learning, this is also called the number of output channels -- analogous to RGB color channels in a raw image, or generally meant to be an unspecific feature axis in a data array (not to be confused with spatial channels in multi-channel time series, which more commonly treated like the vertical axis in 2d image data).
- verbose name: Number Of Filters To Learn
- default value: 1
- port type: IntPort
- value type: int (can be None)
kernel_shape¶
Shape of the convolution filter kernel. This is a list of integers, one for each dimension as given in sweep axes. Can also be given as a single-element list, in which case the kernel is the same size along all of the given spatial dimensions. Note: if you make the kernel as large as the data along some axis, there is only a single valid position for the kernel along that axis (if padding=valid), and consequently the result is an inner product between the data and the kernel, or a matrix multiplication when more kernels are learned. Conversely, if you give the kernel a shape of 1 along an axis, the result is equivalent to processing each element along that axis separately using the same kernel. The latter is the same as not listing the axis in sweep axes, except that the output axis order can be controlled when specifying a 1-sized axis in sweep_axes. Which is more efficient depends on the implementation.
- verbose name: Kernel Shape
- default value: [3]
- port type: ListPort
- value type: list (can be None)
strides¶
Step size with which the kernel is swept over the data. This is a list of integers, one for each dimension as given in sweep axes. Can also be given as a single-element list, in which case the same step size is used along all of the specified spatial dimensions. A step size greater than 1 means that the kernel will be shifted by this amount between successive positions; as a result, the amount of compute is lower by this factor, and the output data along this axis will also be shorter by this factor (matching the number of positions at which the kernel is applied).
- verbose name: Step Size (Strides)
- default value: [1]
- port type: ListPort
- value type: list (can be None)
padding¶
Padding strategy for the data. This can be either 'valid' or 'same', or a custom list of padding amounts. 'valid' means no padding (i.e., the kernel will not run off the edges of the data, but the output data will be shorter along each axis according to the number of valid positions of the kernel along that axis), and 'same' means that the output will have the same shape as the input (aside from dilation and striding). Can be customized by giving a list[(low, high), ...] pairs, where low is the padding to apply before the data along each axis, and high is the padding to apply after the data along each axis. low and high can also be negative to trim the data instead of padding. If a single [(low, high)] pair is given, it is applied to all axes.
- verbose name: Padding
- default value: valid
- port type: ComboPort
- value type: str (can be None)
with_bias¶
Whether to include a bias term. If given, then for each output feature, a bias term is learned and added to the output of the convolution. This increases the flexibility of the learned model, but note that the result is no longer strictly equivalent to e.g., a learned FIR filter applied to time-series data or a learned spatial filter / matrix multiplication applied to spatial data.
- verbose name: Learn Bias Term(S)
- default value: True
- port type: BoolPort
- value type: bool (can be None)
dilations¶
Dilation (scaling) of the convolution kernel. This is a list of integers, one for each dimension as given in sweep axes. Can also be given as a single-element list, in which case the same step size is used for all of the specified spatial dimensions. This causes the kernel array to be "stretched" by this factor (or factors if multiple axes) to cover a larger region in the data without having to learn a higher-resolution (larger size) kernel. This is an alternative to the more traditional approach of first pooling the data with a step size greater than one before applying a regular (non-dilated) convolution, and can be used to, e.g., preserve the original shape and resolution of the data.
- verbose name: Dilation (Kernel Scaling)
- default value: [1]
- port type: ListPort
- value type: list (can be None)
feature_group_count¶
Number of feature groups to use. This will partition features into N equal-sized groups before processing. The length of the input and output feature axes must be divisible by this number. This is mainly an optimization to reduce the number of parameters and computation, at the expense of learning kernels that integrate only a subset of the input features, perhaps at earlier stages of the network.
- verbose name: Optional Feature Partitions
- default value: 1
- port type: IntPort
- value type: int (can be None)
w_initializer¶
Choice of weight initializer. This can either be one of the provided initializers, or the value "custom", in which case one of the Initializer nodes must be wired into the respective input port. For beginners it is recommended to stick to the defaults, since initialization of deep net layers is nuanced and can be tricky, otherwise be prepared to experiment with different choices. In general, the variance-scaling (lecun, glorot/xavier, he/kaiming) initializers are recommended, except for very simple/small layers where you may have a good default assumption as to the distribution of the weights (e.g., truncated_normal or uniform). Bias layers are typically zero-initialized. For initializers that take arguments, you can also type out the arguments positionally as in "truncated_normal(1.0,0.0)" (note reversed order of stddev, mean). The following initializers have arguments (here listed with their defaults): constant(value), those ending in normal(stddev=1, mean=0), those ending in uniform(min=0,max=1), orthogonal(scale=1,axis=-1), identity(gain=1), and variance_scaling(scale=1, "fan_in" (default)/"fan_avg"/"fan_out", "truncated_normal"(default)/"normal"/"uniform",optional-axis-indices=auto). Note that glorot and xavier are aliases for each other, and likewise he and kaiming are aliases for each other.
- verbose name: Weight Initializer
- default value: lecun_normal
- port type: ComboPort
- value type: str (can be None)
b_initializer¶
Choice of bias initializer. This can either be one of the provided initializers, or the value "custom", in which case one of the Initializer nodes must be wired into the respective input port. For beginners it is recommended to stick to the defaults, since initialization of deep net layers is nuanced and can be tricky, otherwise be prepared to experiment with different choices. In general, the variance-scaling (lecun, glorot/xavier, he/kaiming) initializers are recommended, except for very simple/small layers where you may have a good default assumption as to the distribution of the weights (e.g., truncated_normal or uniform). Bias layers are typically zero-initialized. For initializers that take arguments, you can also type out the arguments positionally as in "truncated_normal(1.0,0.0)" (note reversed order of stddev, mean). The following initializers have arguments (here listed with their defaults): constant(value), those ending in normal(stddev=1, mean=0), those ending in uniform(min=0,max=1), orthogonal(scale=1,axis=-1), identity(gain=1), and variance_scaling(scale=1, "fan_in" (default)/"fan_avg"/"fan_out", "truncated_normal"(default)/"normal"/"uniform",optional-axis-indices=auto). Note that glorot and xavier are aliases for each other, and likewise he and kaiming are aliases for each other.
- verbose name: Bias Initializer
- default value: zeros
- port type: ComboPort
- value type: str (can be None)
data_format¶
Format of the input data. This is only respected when working with plain arrays and is ignored for packet data, which always normalizes the data to 'channels_last' layout. If 'channels_last', the data is assumed to be in the format ({batch}, ..., channels). If 'channels_first', the data is assumed to be in the format ({batch}, channels, ...).
- verbose name: Array Data Format
- default value: auto
- port type: EnumPort
- value type: str (can be None)
op_precision¶
Operation precision. This is a compute performance optimization. See jax documentation for details on these options. Note that this only applies to the operation, while the storage precision may be separately configurable depending on the node in question.
- verbose name: Operation Precision
- default value: default
- port type: EnumPort
- value type: str (can be None)
layername¶
Name of the layer. Used for naming of weights.
- verbose name: Layer Name
- default value: conv
- port type: StringPort
- value type: str (can be None)
set_breakpoint¶
Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.
- verbose name: Set Breakpoint (Debug Only)
- default value: False
- port type: BoolPort
- value type: bool (can be None)
metadata¶
User-definable meta-data associated with the node. Usually reserved for technical purposes.
- verbose name: Metadata
- default value: {}
- port type: DictPort
- value type: dict (can be None)