Quick Start

by: Kevin Broløs & Tom Jelen
(Feyn version 1.4 or newer)

A Feyn tour around the block

Welcome to this quick guided tour. We'll get you set up and taking advantage of your shiny new QLattice in no time.

Installation

Feyn is a Python library available for installation using pip, for your favourite OS (if your favourite is either OS X 10.14+, Windows, or Linux).

richard@feyn:~$ pip3 install feyn

Once installed, go to your preferred Python environment and follow along with this example.

Connect to your QLattice

You're going to need access to a QLattice to get started. Don't have one? Sign up!

import feyn

qlattice = feyn.QLattice(url = "<URL to your qlattice>", api_token="<Your API token>")

Here's a guide on how to get your URL and API token.

Load an example dataset

To introduce the core concepts of building a Feyn graph, we will pick a simple classification problem from sklearn, and load it with pandas.

import sklearn.datasets
import pandas as pd
from feyn.tools import split

breast_cancer = sklearn.datasets.load_breast_cancer()
input_columns = breast_cancer.feature_names

# Load into a pandas dataframe
data = pd.DataFrame(breast_cancer.data, columns=input_columns)
data['target'] = pd.Series(breast_cancer.target)

# Split into train & test
train, test = split(data, ratio=(0.67, 0.33))

Communicating with the QLattice

Starting out, the QLattice won't know your problem domain or have any concept of what features to connect. We teach it this by fitting QGraphs and updating the QLattice with the best model(s). The QGraph is an endless collection of possible graphs describing the relationship between your inputs and output.

So, to get started, we'll have to define our problem type as either a regression or classification problem. For this one, we'll get a classifier, using the names of your input features and target output.

# Get a QGraph of graphs between your inputs and output from the remote QLattice.
qgraph = qlattice.get_classifier(data.columns, output='target')

You'll see the classifier is just a QGraph that knows how to treat the output node. Now you have a QGraph that's ready to fit your problem, and the QLattice will start generating graphs that relate to your problem.

How to fit your QGraph

Everytime you fit the graphs in your QGraph, it'll filter out the useless graphs and pull some fresh ones from the QLattice automatically.

A single fit looks like this:

# Now fit a subset of the QGraph with your local data
qgraph.fit(train)

While this might, for simple cases, come up with a good solution already, you should run this iteratively and update the QLattice with the best graph(s). This will teach the QLattice about what best describes your problem based on your learnings, and narrow the search space of the QLattice. This allows it to get better at suggesting new useful graphs.

An update loop could look like this:

no_updates = 10

for _ in range(no_updates):
    # Fit a subset of the QGraph with your local data.
    qgraph.fit(train)

    # Select the best performing graphs from our fitted QGraph
    best_graphs = qgraph.best()

    # Feed the experience back to the QLattice so it gets smarter for subsequent calls.
    qlattice.update(best_graphs)

Repeat until convergence happens - just as you would in regular machine learning applications.

Notice, that while the QLattice lives remotely on the Abzu cluster, it never sees your local data. You train locally, and the resulting structure of the graphs is what is transmitted to the QLattice.

Evaluate

Finally, use the resulting single graph and evaluate the results on the test dataset. Here, we explicitly state the input columns, but Feyn would also filter away the target column if it was included (as it's not being used as input to the graph). Nifty, huh?

# Selection of best graph
best_graph = best_graphs[0]

predictions = best_graph.predict(test[input_columns])

# Round off the results to discretize to 0 or 1 for classification.
predictions = predictions.round()

feyn.plots.plot_confusion_matrix(y_true=test['target'],
                            y_pred=predictions,
                            title="Evaluation Results")

However the same code is wrapped up in the following method:

best_graph.plot_confusion_matrix(test)

Of course we've got way more in store for you, so take a dive off the deep end of the pool with the rest of our documentation, starting with an introduction to the basic workflow!

Introduction to the basic workflow →