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 QGraph
s 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!