libffm 0.2.0

Field-aware factorization machines in Rust
Documentation

LIBFFM Rust

LIBFFM - field-aware factorization machines - in Rust

Build Status

Getting Started

LIBFFM Rust is available as a Rust library and a command line tool.

Rust Library

Installation

Add this line to your application’s Cargo.toml under [dependencies]:

libffm = "0.2"

How to Use

Prep your data in LIBFFM format

0 0:0:1 1:1:1
1 0:2:1 1:3:1

Train a model

let model = libffm::Model::train("train.ffm").unwrap();

Use a validation set and early stopping to prevent overfitting

let model = libffm::Model::params()
    .auto_stop(true)
    .train_eval("train.ffm", "valid.ffm")
    .unwrap();

Make predictions

let (predictions, loss) = model.predict("test.ffm").unwrap();

Save the model to a file

model.save("model.bin").unwrap();

Load a model from a file

let model = libffm::Model::load("model.bin").unwrap();

Training Options

let model = libffm::Model::params()
    .learning_rate(0.2)      // learning rate
    .lambda(0.00002)         // regularization parameter
    .iterations(15)          // number of iterations
    .factors(4)              // number of latent factors
    .quiet(false)            // quiet mode (no output)
    .normalization(true)     // use instance-wise normalization
    .auto_stop(false)        // stop at the iteration that achieves the best validation loss
    .on_disk(false)          // on-disk training
    .train("train.ffm");     // train or train_eval

Command Line Tool

Installation

Run:

cargo install libffm --features cli

How to Use

Prep your data in LIBFFM format

0 0:0:1 1:1:1
1 0:2:1 1:3:1

Train a model

ffm-train train.ffm model.bin

Use a validation set and early stopping to prevent overfitting

ffm-train -p valid.ffm --auto-stop train.ffm model.bin

Make predictions

ffm-predict test.ffm model.bin output.txt

Training Options

FLAGS:
        --auto-stop    Stop at the iteration that achieves the best validation loss (must be used with -p)
        --in-memory    Enable in-memory training
        --no-norm      Disable instance-wise normalization
        --quiet        Quiet mode (no output)

OPTIONS:
    -r <eta>               Set learning rate [default: 0.2]
    -k <factor>            Set number of latent factors [default: 4]
    -t <iteration>         Set number of iterations [default: 15]
    -l <lambda>            Set regularization parameter [default: 0.00002]
    -s <nr-threads>        Set number of threads [default: 1]
    -p <va-path>           Set path to the validation set

Credits

This library was ported from the LIBFFM C++ library and is available under the same license.

History

View the changelog

Contributing

Everyone is encouraged to help improve this project. Here are a few ways you can help:

To get started with development:

git clone https://github.com/ankane/libffm-rust.git
cd libffm-rust
cargo test
cargo run --bin ffm-train --features cli
cargo run --bin ffm-predict --features cli