General utilities for deep neural network framework chainer.
It contains well-usable network training interface for general neural networks and visualizer class for Convolution neural network.
Minimum requirements:
- Python 2.7 or 3.4 later (This has 2 and 3 compatibility)
- Chainer(>= 1.2.0) and minimum dependencies
- cv2: opencv python interface (Visualizer)
- matplotlib (Visualizer)
python setup.py install
This software is released under MIT License.
For more details about license, refer to 'LICENSE'.
You only need to DO define network, forwarding rules.
And then, enjoy your deeeep neural network power with train and test.
from libdnn import Classifier
import chainer
import chainer.functions as F
import chainer.optimizers as Opt
# declare network structure
model = chainer.FunctionSet(
l1 = .....,
# Specify layer construction as you like
)
# define feedforward calculation
def forward(self, x):
h = F.relu(self.model.l1(x))
...
y = self.model.Lout(h)
return y
# Generate instance (GPGPU enabled)
network = Classifier(model, gpu=0)
# Override instance forward method
network.set_forward(forward)
# Some operation to import data
# training
error_on_train, accuracy_on_train = network.train(train_data, target)
# test
error_on_test, accuracy_on_test = network(test_data, target)
print(accuracy_on_test)
# save trained network parameters
network.save_param('network.param.npy')Visualizer class provides filter visualization on your trained network.
from libdnn import Classifier
import libdnn.Visualizer as V
# define CNN and train it
# SOME CODES
# define forwarding function that returns specified layer output
def output(self, x, layer):
h = network.conv1(x)
if layer == 1:
return h
h = F.max_pooling_2d(F.relu(h), 2)
h = ...
network.set_output(output)
# instance
imager = V.Visualizer(network)
# view all filters on matplotlib.pyplot.imshow
imager.plot_filters('conv1')
# write filter to image file
imager.write_filters('conv1', path='./filter_img', identifier='img_', type='bmp')
# view layer activation by all filters
imager.plot_output(data[:2], layer=1)
# write activation to image files
imager.write_output(data, layer=2, path='./output_img', identifier='l2_', type='bmp')There are 3 types of network templates according to neural network object, Classification, Regression, and AutoEncoder tasks.
Each class has almost same interfaces like below.
For more detailed usage, please refer to examples.
__init__(self, model, gpu=-1)
1 argument model is neccesary.
model expects instance of chainer.FunctionSet (Neural network structure)
gpu is optional. if gpu >= 0 is True, most network culculation will be processed by CUDA computation.
If you want to use GPGPU, set gpu as your CUDA device ID.
@abstructmethod forward(self, x, train)
It is pure virtual function, you must override this method on instance or subclass/derivered class by set_forward.
3 arguments needed, self is a magic variable, x, is chainer.Variable instance and train is training stage flag (some networks e.g. AutoEncoder needed is this is training input or not).
Define feedforward computation as you like. and it must return output of neural network(isa chainer.Variable).
You needn't to care about gpu, it will be automatically converted properly.
set_forward(self, func)
This method will override NNBase.forward as specified feedforward function.
1 argument, isa function is needed.
@abstructmethod output(self, x, layer)
It it also pure virtual function, that must be Overridden by set_output. It is only used for visualization layer output images in Visualizer class.
If you won't use these features, it will be unnecessary.
3 arguments is needed, self is a magic variable, x, isa chainer.Variable instance, layer is a layer specification flag (that you use in your implementation).
This will be similar to forward function in most case. But do NOT reuse as forward function because of interference CUDA optimization.
set_forward(self, func)
This method will override NNBase.output as specified feedforward function.
1 argument, isa function is needed. You needn't to care about use GPU whether or not.
set_loss_function(self, func, param={})
1 argument func is neccesary.
This expects loss function object in chainer.functions.
param is optional. This expects dictionary that specifies loss function parameters.
If you didn't specify loss function by this method, it will be set in network definition automatically.
set_optimizer(self, optimizer, param={})
1 argument optimizer is neccesary.
This expects optimizer function object in chainer.optimiers.
param is optional. This expects dictionary that specifies optimizer parameter like {lr: 0.01, rho: 0.9}.
If you didn't specify optimizer function by this method, in most cases, network will use chainer.optimizers.Adam by default.
train(self, x_data, y_data, batchsize=100, action=(lambda: None))
2 arguments x_data, y_data are necessary.
x_data : training data, y_data: target value, isa numpy.array;
batchsize is a number of minibatch training.(defalut 100)
action expects function object. This will be called on end of minibatch training each time.
It returns error and accuracy ratio for training data.
test(self, x_data, y_data, action=(lambda: None))
It returns error and accuracy ratio for test data to validate training result.
save_param(self, dst)
1 argument dst is optional that specifies destination.
It will be './network.param.npy' by default.
load_param(self, src)
1 argument src is optional that specifies source file.
It will be './network.param.npy' same as save_param by default.
StackedAutoencoder class has a little bit different interface for layerwise training.
It require to define extra forwarding function that is following some rules like below;
It has too much sugered interface, please refer to example (./examples/mnist/SdA.py)
set_order(self, encl, decl)
2 arguments, encl, decl are neccesary.
These are tuple of layer names ordered by forward flow.
@abstructmethod encode(self, x, layer, train)
@abstructmethod decode(self, x, layer, train)
It is pure virtual function, you must override this method on instance or
subclass/derivered class by set_encode / set_decode like forwarding function.
3 arguments needed, self is a magic variable, x, is chainer.Variable instance.
layer, isa integer specifies forwarding depth. Define encode function like
if layer == 0:
return x
some calculation for x
if layer == 1:
return xlayer starts at 0, and increment when 1 layer deeper.
Decoding function decode has same requirement,
but it starts at maxinum number in encoding function encode and
each forwarding rules has a little bit strange interface like
if not train or layer == N: # N is a maxinum depth
x = F.sigmoid(self.model.decN(x)) # decode layerwiseForwarding(encode input, and get decoded one) function forward will be defined by these
encode/decode rules automatically.
set_encode(self, func)
set_decode(self, func)
This method will override encode/decode function.
1 argument, isa function is needed.
Visualizer.__init__(self, model)
1 argument model is necessary.
model expects NNBase instance that is defined as CNN.
Visualizer.convert_filters(self, layer, height, width)
DO call this method before other ~~_filters methods.
1 argument layer is necessary. layer expects a name of layer that you declared network construction.
height, width is optional. If you didn't specify, filter size will be auto-detected(same as kernel size).
In most cases, you needn't specify these value explicitly.
Visualizer.plot_filters(self, layer, shape, T, title, interpolation)
View all filters on matplotlib.
This will break program running by default.
1 argument layer is neccesary. layer expects a name of layer that you declared network definition.
shape and T are optinal. They will be required by needs of fully-connected layer Visualization
(e.g. fully-connected autoencoder).
shape expect tuple object. It is a filter size specification like (height, width).
And if T is True, layer weights will transposed (for decoding layers).
title is optional. By default, each filter has a title like filter_xxx,
but it often overlap on another filter images.
If you needn't to show titles, set T=False.
interpolation is optional. If interpolation == True, it enable pixel interpolation to filter visualization.
It will be set to False by default.
Visualizer.write_filters(self, layer, path='./', identifier='img', type='bmp', shape, T)
1 argument layer is necessary, same as plot_filters.
path is a path to store images. It will store current directory by default.
identifier is a identifier(prefix) of image files. like 'idenfier_00xxx.jpg'
type is a image data format. It will be Windows Bitmap Image format by default.
We recommend you to use uncompressed formats(e.g. bmp, tiff, pgm etc.)
shape, T are same as plot_filters.
Visualizer.save_raw_filter(self, dst)
For maestri of MATLAB.
1 argument dst, a path to save dir is neccesary.
And also need convert_filters in advance.
Visualizer.plot_output(self, x, layer)
View layer activations on (trained) network with matplotlib for inputs x.
2 arguments is neccesary.
x is a images that you want to see derivered one.
layer is a layer specification flag that you used on output method.
This shows all filtered images (number of images: x.shape[0]) * (number of output channels). Watch out for it.
Visualizer.write_output(self, x, layer, path, identifier, type)
2 arguments, x, layer are necessary same as plot_output above.
path is a path to store images. It will store current directory by default.
identifier is a identifier(prefix) of image files. like 'idenfier_(imagenum)_f(filternum).jpg'
type is a image data format. It will be Windows Bitmap Image format by default.
Visualizer.write_activation(self, x, layer, path, identifier, type)
It has only one difference from write_output that is source image would be expected only one. (shape dim = 3)
It requires parameters same as write_output.
Aiga SUZUKI<[email protected]>