NAME

       mlpack_logistic_regression - l2-regularized logistic regression and prediction

SYNOPSIS

        mlpack_logistic_regression [-h] [-v]

DESCRIPTION

       An  implementation of L2-regularized logistic regression using either the L-BFGS optimizer
       or SGD (stochastic gradient descent). This solves the regression problem

         y = (1 / 1 + e^-(X * b))

       where y takes values 0 or 1.

       This program allows loading a logistic regression model from a file  (-i)  or  training  a
       logistic  regression  model  given  training  data  (-t), or both those things at once. In
       addition, this program allows classification on a test dataset  (-T)  and  will  save  the
       classification results to the given output file (-o). The logistic regression model itself
       may be saved with a file specified using the -m option.

       The training data given with the -t option should have class labels as its last  dimension
       (so,  if  the  training  data  is  in  CSV  format,  labels  should  be  the last column).
       Alternately, the -l (--labels_file) option may be used  to  specify  a  separate  file  of
       labels.

       When  a  model  is  being  trained,  there are many options. L2 regularization (to prevent
       overfitting) can be specified with the -l option, and the  optimizer  used  to  train  the
       model  can  be  specified  with  the  --optimizer  option.   Available  options  are 'sgd'
       (stochastic  gradient  descent),  'lbfgs'  (the  L-BFGS  optimizer),  and  'minibatch-sgd'
       (minibatch  stochastic  gradient  descent).   There  are  also  various parameters for the
       optimizer;  the  --max_iterations  parameter  specifies  the  maximum  number  of  allowed
       iterations,  and  the  --tolerance (-e) parameter specifies the tolerance for convergence.
       For the SGD and mini-batch SGD optimizers, the --step_size  parameter  controls  the  step
       size  taken  at  each  iteration  by  the  optimizer. The batch size for mini-batch SGD is
       controlled with the --batch_size (-b) parameter. If the objective function for  your  data
       is  oscillating  between  Inf  and  0, the step size is probably too large. There are more
       parameters for the optimizers, but the C++ interface must be used to access these.

       For SGD, an iteration refers to a single point,  and  for  mini-batch  SGD,  an  iteration
       refers  to  a  single  batch.  So  to  take  a  single  pass  over  the  dataset with SGD,
       --max_iterations should be set to the number of points in the dataset.

       Optionally, the model can be used to predict the responses  for  another  matrix  of  data
       points,  if  --test_file  is  specified.  The  --test_file option can be specified without
       --input_file, so long as an existing logistic regression model is given with --model_file.
       The  output  predictions  from  the logistic regression model are stored in the file given
       with --output_predictions.

       This implementation of logistic regression does not support the general  multi-class  case
       but instead only the two-class case. Any responses must be either 0 or 1.

OPTIONAL INPUT OPTIONS

       --batch_size (-b) [int]
              Batch size for mini-batch SGD. Default value

              50.

                  --decision_boundary  (-d)  [double]  Decision  boundary  for prediction; if the
                  logistic function for a point is less than the boundary, the class is taken  to
                  be 0; otherwise, the class is 1. Default value 0.5.

       --help (-h)
              Default help info.

       --info [string]
              Get  help  on  a  specific module or option.  Default value ''.  --input_model_file
              (-m) [string] File containing existing model (parameters).  Default value ''.

       --labels_file (-l) [string]
              A file containing labels (0 or 1) for the points in the training set  (y).  Default
              value ''.

       --lambda (-L) [double]
              L2-regularization parameter for training.  Default value 0.

       --max_iterations (-n) [int]
              Maximum iterations for optimizer (0 indicates no limit). Default value 10000.

       --optimizer (-O) [string]
              Optimizer to use for training ('lbfgs' or ’sgd'). Default value 'lbfgs'.

       --step_size (-s) [double]
              Step size for SGD and mini-batch SGD optimizers.  Default value 0.01.

       --test_file (-T) [string]
              File containing test dataset. Default value ’'.

       --tolerance (-e) [double]
              Convergence  tolerance  for  optimizer.  Default value 1e-10.  --training_file (-t)
              [string] A file containing the training set (the matrix of predictors, X).  Default
              value ''.

       --verbose (-v)
              Display  informational  messages  and the full list of parameters and timers at the
              end of execution.

       --version (-V)
              Display the version of mlpack.

OPTIONAL OUTPUT OPTIONS

       --output_file (-o) [string]
              If --test_file is specified, this file is where the predictions for  the  test  set
              will  be  saved.  Default value ''.  --output_model_file (-M) [string] File to save
              trained     logistic     regression     model     to.     Default     value     ''.
              --output_probabilities_file (-p) [string] If --test_file is specified, this file is
              where the class probabilities for the test set will be saved. Default value ''.

ADDITIONAL INFORMATION

ADDITIONAL INFORMATION

       For further information, including relevant papers, citations,  and  theory,  For  further
       information,  including  relevant papers, citations, and theory, consult the documentation
       found at http://www.mlpack.org or included with your consult the  documentation  found  at
       http://www.mlpack.org  or  included  with  your  DISTRIBUTION  OF MLPACK.  DISTRIBUTION OF
       MLPACK.

                                                     mlpack_logistic_regression(16 November 2017)