Get Started: Add a Classifier

Documentation Get Started
1

Overview

In the previous section you use a Guild file to define a train operation. In this section, you enhance the project by adding a real-world classifier.

You cover:

Download Classifier Script

Download plot_iris_exercise.py and save it to the guild-start directory.

The script, which is adapted from scikit-learn SVM Exercise, trains a model on the Iris benchmark data set.

The guild-start directory should look like this:

guild-start
archived-runs
guild.yml
plot_iris_exercise.py
train.py

Add iris-svm Model to guild.yml

In the guild-start directory, modify guild.yml by adding the iris-svn model below.

The final modified guild.yml should be:

- model: sample
  description: A sample model
  operations:
    train:
      description: Sample training script
      main: train
      flags-import: all
      output-scalars: '(\key): (\value)'

- model: iris-svm
  description: Iris classifier using a support vector machine (SVM)
  operations:
    train:
      description: Train SVM model on Iris data set
      main: plot_iris_exercise
      flags:
        kernel:
          description: SVM kernel type
          default: rbf
          choices: [linear, poly, rbf]
        test_split:
          description: Percentage of examples held out for test
          default: 0.2
        random_seed:
          description: Seed used for shuffling data
          default: 0
        degree:
          description: Degree of the poly kernel function
          default: 3
        gamma:
          description: Kernel coefficient for rbf and poly
          default: 10
      output-scalars:
        train_accuracy: 'Train accuracy: (\value)'
        test_accuracy: 'Test accuracy: (\value)'

guild.yml after adding iris-svm model

The file defines two models: sample and iris-svm. The sample model provides the train operation from the previous step. The iris-svm is a new model, which you add in this section.

Highlight Use models to group related sets of operations. Models generally correspond to the structures that you train and test with data, though you’re free to define models for other purposes. For more information, see Models.

The Guild file format changes from a mapping of operations, known as operation only format, to a list of top-level objects, known as full format. Guild supports these two formats to accommodate different requirements. Use operation only format when starting to keep your Guild file as simple as possible. Migrate to full format as needed to support more configuration.

Below is a description of the iris-svm:train attributes.
description A description of the operation.
main The Python module that implements the operation.
flags A mapping of flag name to flag definition. Each flag provides a description, which is used in help text, and a default value. The kernel flag defines a list of valid choices—one for each supported kernel. For more information, see Flags.
output-scalars Patterns used to capture output scalars. In this case, the capture patterns are different from those of sample:train. This accommodates the different output generated by the module.

Highlight Rather than require changes to plot_iris_exercise.py to support Guild-specific output patterns, you change guild.yml. This keeps your project source code independent of external tooling.

Verify that the operations are available:

guild ops

iris-svm:train  Train SVM model on Iris data set
sample:train    Generate a sample loss

Note guild ops is a shortened alias for guild operations.

If you don’t see iris-svm:fit in the list, verify that guild.yml is the same as above and that you’re running the command from the guild-start directory.

Show the project models:

guild models

iris-svm  Iris classifier using a support vector machine (SVM)
sample    A sample model

Show help for the project:

guild help
Output 
OVERVIEW

    You are viewing help for operations defined in the current directory.

    To run an operation use 'guild run OPERATION' where OPERATION is one
    of options listed below. If an operation is associated with a model,
    include the model name as MODEL:OPERATION.

    To list available operations, run 'guild operations'.

    Set operation flags using 'FLAG=VALUE' arguments to the run command.
    Refer to the operations below for a list of supported flags.

    For more information on running operations, try 'guild run --help'.
    For general information, try 'guild --help'.

MODELS

    iris-svm

      Iris classifier using a support vector machine (SVM)

      Operations:

        train
          Train SVM model on Iris data set

          Flags:
            degree       Degree of the poly kernel function (default is 3)
            gamma        Kernel coefficient for rbf and poly (default is 10)
            kernel       SVM kernel type (default is rbf)

                         Choices:  linear, poly, rbf

            random_seed  Seed used for shuffling data (default is 0)
            test_split   Percentage of examples held out for test (default is 0.2)

    sample

      A sample model

      Operations:

        train
          Sample training script

          Flags:
            noise  (default is 0.1)
            x      (default is 0.1)

Highlight Use a Guild file to document your project capabilities to help others use it effectively.

Create a Guild Environment

In this section, you create a project-specific environment to keep project libraries and runs separate from other projects. For more information, see Environments.

Create requirements.txt

Guild uses requirements.txt to install required packages when creating an environment.

In the guild-start project directory, create a file named requirements.txt that specifies the Python packages required by the project. For this project, the file should be:

matplotlib
scikit-learn

requirements.txt — specifies Python packages required by the project

Your project directory should look like this:

guild-start
archived-runs
guild.yml
plot_iris_exercise.py
requirements.txt
train.py

Initialize the Environment

Having adding requirements.txt to the project, initialize a new environment in the project using guild init:

guild init

Guild prompts with the environment settings. Press Enter to create the environment.

Guild initializes a virtual environment in the project under a venv subdirectory.

Your project directory should look like this:

guild-start
archived-runs
guild.yml
plot_iris_exercise.py
requirements.txt
train.py
venv

Activate the Environment

To use an environment, you activate it within each terminal session that uses it.

If you’re running Linux, macOS, or POSIX compliant shell, activate the environment by running:

source guild-env

If you’re running Windows, activate the environment by running:

venv\Scripts\activate.bat

Note You can always use the traditional method of activating a virtual environment created with guild init. Guild environments are standard Python virtual environments.

When you activate an environment, Guild uses the environment Python runtime and installed libraries. Guild also stores runs within the environment.

Use guild check to confirm that Guild uses the activated environment:

guild check

Note the location of guild_home — it should be located under the project directory in venv/.guild.

List the current runs:

guild runs

The list is empty because you haven’t generated any runs in current environment.

Train the Classifier

In the activated environment, run the iris-svm:train operation:

guild run iris-svm:train

You are about to run iris-svm:train
  degree: 3
  gamma: 10
  kernel: rbf
  random_seed: 0
  test_split: 0.2
Continue? (Y/n)

Press Enter to start the operation.

Guild runs the operation, which is implemented by the plot_iris_exercise module.

Guild uses the default flag values defined for the operation in guild.yml, which you define above.

View Results

List files generated by the run:

guild ls

~/guild-start/venv/.guild/runs/c564a767a188438282b925389de45e40:
  plot.png

In addition to fitting a model and printing accuracy results, the operation generates a plot showing classification results of the Iris test data set.

Open the plot using the default application for your system:

guild open -p plot.png

Guild opens the plot generate by iris-svm:train, which shows how test samples are classified.

classifier-plot
classifier-plot640×628 54.5 KB

Viewing plot.png on Linux using Xviewer

Use an alternative program to open a file by specifying the --cmd option. For example, to open plot.png in GIMP, use:

guild open -p plot.png --cmd gimp

Specify the program used to open a file with --cmd (this example requires that GIMP be installed)

Highlight Guild integrates with your favorite tools, rather than attempt to replace them.

Experiment with Different Kernels

Run mnist-svm:train again using each the other SVM kernels:

guild run iris-svm:train kernel='[linear,poly]'

You are about to run iris-svm:train as a batch (2 trials)
  degree: 3
  gamma: 10
  kernel: [linear, poly]
  random_seed: 0
  test_split: 0.2
Continue? (Y/n)

Press Enter to confirm.

Guild runs iris-svm:train twice — once for each specified kernel.

Compare Runs

Use guild compare to compare results:

guild compare

Use the right arrow key to move the cursor to view values for test_accuracy. Note that the linear kernel performs better the other two, at least with the default hyperparameters.

Press q to exit Guild Compare.

Compare run plots using TensorBoard:

guild tensorboard --tab images

Guild starts TensorBoard and opens the Images tab. TensorBoard shows each plot generated by the three runs. To improve image quality, select Show actual image size in the upper-left of the display.

classifier-tb
classifier-tb1900×460 79.4 KB

Compare run-generated images using TensorBoard

Highlight Guild automatically shows run-generated images in TensorBoard so you don’t need to log them as summaries. This is a useful way to compare run plots and other images side-by-side.

Return to the command terminal and press Ctrl-C to stop TensorBoard.

Summary

In this section you add iris-svm to your project. The model defines a train operation, which runs the Python module plot_iris_exercise to fit a support vector machine to the Iris data set.

Congratulations — you completed this introduction to Guild AI!

Highlights In this introduction, you cover fundamental concepts and practices:

Now that you’re familiar with Guild, try using it for your own work.

Use Guild in a Project

2

A post was split to a new topic: Typo in Get Started: Add a Classifier