Getting Started Guide

In this guide we will go through a simple example from start to finish. You will learn how to load data, create an iterator, setup a neural network and learn its parameters using a ranking loss function.

Loading a data set

We will load a very simple example data set in RankSVM format.

from shoelace.dataset import LtrDataset

with open('./dataset.txt', 'r') as file:
    dataset = LtrDataset.load_txt(file)

Chainer works with a concept of iterators that feed a neural network with batches of data. We need to load our data into a Learning to Rank iterator to start using it:

from shoelace.dataset import LtrIterator

iterator = LtrIterator(dataset, repeat=True, shuffle=True)

You can find more detailed information about the data set loading facilities that Shoelace provides on the Datasets section of the documentation.

Setting up a network

For our simple example we will set up a single-layer linear neural network. This is equivalent to a linear function of the input features.

from chainer import links
predictor = links.Linear(None, 1)

We encourage the reader to experiment with a wide variety of neural architectures. For more information about designing different architectures we refer you to the documentation of Chainer.

Choosing a loss function

Shoelace currently provides 3 different list-wise loss functions. For this guide we will use the ListNet loss (top-1 approximation):

from chainer import Chain
from shoelace.loss.listwise import listnet

class Ranker(Chain):
    def __call__(self, x, t):
        return listnet(self.predictor(x), t)
loss = Ranker(predictor=predictor)

Training

We now have all the pieces set up to start training our network. What follows is standard Chainer code for setting up an optimizer, updater and trainer. There are many options and choices to be made here, but they fall outside the scope of this guide. You will be able to find much more information about optimizing the network on the documentation of Chainer.

from chainer import training, optimizers
from chainer.training import extensions

# Build optimizer, updater and trainer
optimizer = optimizers.Adam()
optimizer.setup(loss)
updater = training.StandardUpdater(iterator, optimizer)
trainer = training.Trainer(updater, (40, 'epoch'))
trainer.extend(extensions.ProgressBar())

# Train neural network
trainer.run()