xLearn API List
^^^^^^^^^^^^^^^^^^^^^^^^^^^

This page gives the xLearn API List for the command line, Python package, and R package.

xLearn Command Line Usage
------------------------------

For Training: ::

    xlearn_train <train_file_path> [OPTIONS]

Options: ::

  -s <type> : Type of machine learning model (default 0)
     for classification task:
         0 -- linear model (GLM)
         1 -- factorization machines (FM)
         2 -- field-aware factorization machines (FFM)
     for regression task:
         3 -- linear model (GLM)
         4 -- factorization machines (FM)
         5 -- field-aware factorization machines (FFM)
                                                                           
  -x <metric>          :  The metric can be 'acc', 'prec', 'recall', 'f1', 'auc' for classification, and
                          'mae', 'mape', 'rmsd (rmse)' for regression. On default, xLearn will not print
                          any evaluation metric information (only print loss value).                                           
                                                                                                     
  -p <opt_method>      :  Choose the optimization method, including 'sgd', adagrad', and 'ftrl'. On default,
                          xLearn uses the 'adagrad' optimization method.
                                                                                                
  -v <validate_file>   :  Path of the validation data. This option will be empty by default. In this way, 
                          xLearn will not perform validation process.
                                                                                             
  -m <model_file>      :  Path of the model dump file. On default, the model file name is 'train_file' + '.model'. 
                          If we set this value to 'none', the xLearn will not dump the model checkpoint.

  -pre <pre-model>     :  Path of the pre-trained model. This can be used for online learning. 

  -t <txt_model_file>  :  Path of the TEXT model checkpoint file. On default, we do not set this option
                          and xLearn will not dump the TEXT model.
                                                                            
  -l <log_file>        :  Path of the log file. xLearn uses '/tmp/xlearn_log.*' by default.
                                                                                      
  -k <number_of_K>     :  Number of the latent factor used by FM and FFM tasks. Using 4 by default.
                          Note that, we will get the same model size when setting k to 1 and 4.
                          This is because we use SSE instruction and the memory need to be aligned.
                          So even you assign k = 1, we still fill some dummy zeros from k = 2 to 4.
                                                                                         
  -r <learning_rate>   :  Learning rate for optimization method. Using 0.2 by default.
                          xLearn can use adaptive gradient descent (AdaGrad) for optimization problem,
                          if you choose AdaGrad method, the learning rate will be changed adaptively.
                                                                                    
  -b <lambda_for_regu> :  Lambda for L2 regular. Using 0.00002 by default. We can disable the
                          regular term by setting this value to zero.

  -alpha               :  Hyper parameters used by ftrl.
                                       
  -beta                :  Hyper parameters used by ftrl.
                                       
  -lambda_1            :  Hyper parameters used by ftrl.
                                       
  -lambda_2            :  Hyper parameters used by ftrl.     

  -u <model_scale>     :  Hyper parameter used for initialize model parameters. Using 0.66 by default.
                                                                                 
  -e <epoch_number>    :  Number of epoch for training process. Using 10 by default. Note that xLearn will perform 
                          early-stopping by default, so this value is just a upper bound.
                                                                                       
  -f <fold_number>     :  Number of folds for cross-validation (If we set --cv option). Using 5 by default.    

  -nthread <thread_number> :  Number of thread for multiple thread lock-free learning (Hogwild!).

  -block <block_size>  :  Block size for on-disk training.

  -sw <stop_window>    :  Size of stop window for early-stopping. Using 2 by default. 

  -seed <random_seed>  :  Random Seed to shuffle data set.
                                                                                     
  --disk               :  Open on-disk training for large-scale machine learning problems.
                                                                   
  --cv                 :  Open cross-validation in training tasks. If we use this option, xLearn will ignore 
                          the validation file (set by -t option). 
                                                                  
  --dis-lock-free      :  Disable lock-free training. Lock-free training can accelerate training but the result 
                          is non-deterministic. Our suggestion is that you can open this flag if the training data 
                          is big and sparse.
                                                                       
  --dis-es             :  Disable early-stopping in training. By default, xLearn will use early-stopping
                          in training process, except for training in cross-validation.
                                                                                         
  --no-norm            :  Disable instance-wise normalization. By default, xLearn will use instance-wise 
                          normalization in both training and prediction processes.

  --no-bin             :  Do not generate bin file for training and test data file.
                                                                 
  --quiet              :  Don't print any evaluation information during the training and just train the 
                          model quietly. It can accelerate the training process.

For Prediction: ::

    xlearn_predict <test_file_path> <model_file_path> [OPTIONS]

Options: ::

  -o <output_file>     :  Path of the output file. On default, this value will be set to 'test_file' + '.out'
                                                      
  -l <log_file_path>   :  Path of the log file. xLearn uses '/tmp/xlearn_log' by default.  

  -nthread <thread number> :  Number of thread for multiple thread lock-free learning (Hogwild!).

  -block <block_size>      :  Block size fot on-disk prediction. 

  --sign                   :  Converting output result to 0 and 1.

  --sigmoid                :  Converting output result to 0 ~ 1 (probability).

  --disk                   :  On-disk prediction.

  --no-norm                :  Disable instance-wise normalization. By default, xLearn will use instance-wise 
                              normalization in both training and prediction processes.

xLearn Python API
------------------------------

API List: ::

    import xlearn as xl      # Import xlearn package

    xl.hello()               # Say hello to user

    # This part is for data
    # X is features data, can be pandas DataFrame or numpy.ndarray,
    # y is label, default None, can be pandas DataFrame\Series, array or list,
    # filed_map is field map of features, default None, can be pandas DataFrame\Series, array or list
    dmatrix = xl.DMatrix(X, y, field_map)  

    model = create_linear()  #  Create linear model.

    model = create_fm()      #  Create factorization machines.

    model = create_ffm()     #  Create field-aware factorization machines.

    model.show()             #  Show model information.

    model.fit(param, "model_path")   #  Train model.

    model.cv(param)    # Perform cross-validation.
    
    # Users can choose one of this two
    model.predict("model_path", "output_path")  # Perform prediction, output result to file, return None.
    model.predict("model_path")                 # Perform prediction, return result by numpy.ndarray. 
    
    # Users can choose one of this two
    model.setTrain("data_path")      #  Set training data from file for xLearn.
    model.setTrain(dmatrix)          #  Set training data from DMatrix for xLearn.
    
    # Users can choose one of this two
    # note: this type of validate must be same as train
    # that is, set train from file, must set validate from file
    model.setValidate("data_path")   #  Set validation data from file for xLearn.
    model.setValidate(dmatrix)       #  Set validation data from DMatrix for xLearn.
    
    # Users can choose one of this two
    model.setTest("data_path")       #  Set test data from file for xLearn.
    model.setTest(dmatrix)           #  Set test data from DMatrix for xLearn.

    model.setQuiet()    #  Set xlearn to train model quietly.

    model.setOnDisk()   #  Set xlearn to use on-disk training.

    model.setNoBin()    # Do not generate bin file for training and test data.

    model.setSign()     # Convert prediction to 0 and 1.

    model.setSigmoid()  # Convert prediction to (0, 1).

    model.disableNorm() # Disable instance-wise normalization.

    model.disableLockFree()   # Disable lock-free training.

    model.disableEarlyStop()  # Disable early-stopping.

Parameter List: ::

    task     : {'binary',  # Binary classification
                'reg'}     # Regression

    metric   : {'acc', 'prec', 'recall', 'f1', 'auc',   # for classification
                'mae', 'mape', 'rmse', 'rmsd'}  # for regression

    lr       : float value  # learning rate

    lambda   : float value  # regular lambda

    k        : int value    # latent factor for fm and ffm

    init     : float value  # model initialize

    alpha    : float value  # hyper parameter for ftrl

    beta     : float value  # hyper parameter for ftrl

    lambda_1 : float value  # hyper parameter for ftrl

    lambda_2 : float value  # hyper parameter for ftrl

    nthread  : int value    # the number of CPU cores

    epoch    : int vlaue    # number of epoch

    fold     : int value    # number of fold for cross-validation

    opt      : {'sgd', 'agagrad', 'ftrl'}  # optimization method

    stop_window : Size of stop window for early-stopping.

    block_size : int value  # block size for on-disk training

xLearn R API
------------------------------

xLearn R API page is coming soon.
