kfn.go

package mlpackgo

/*
#cgo CFLAGS: -I./capi -Wall
#cgo LDFLAGS: -L. -lmlpack_go_kfn
#include <capi/kfn.h>
#include <stdlib.h>
*/
import "C" 

import "gonum.org/v1/gonum/mat" 

type KfnOptionalParam struct {
    Algorithm string
    Epsilon float64
    InputModel *kfnModel
    K int
    LeafSize int
    Percentage float64
    Query *mat.Dense
    RandomBasis bool
    Reference *mat.Dense
    Seed int
    TreeType string
    TrueDistances *mat.Dense
    TrueNeighbors *mat.Dense
    Verbose bool
}

func KfnOptions() *KfnOptionalParam {
  return &KfnOptionalParam{
    Algorithm: "dual_tree",
    Epsilon: 0,
    InputModel: nil,
    K: 0,
    LeafSize: 20,
    Percentage: 1,
    Query: nil,
    RandomBasis: false,
    Reference: nil,
    Seed: 0,
    TreeType: "kd",
    TrueDistances: nil,
    TrueNeighbors: nil,
    Verbose: false,
  }
}

/*
  This program will calculate the k-furthest-neighbors of a set of points. You
  may specify a separate set of reference points and query points, or just a
  reference set which will be used as both the reference and query set.

  For example, the following will calculate the 5 furthest neighbors of
  eachpoint in input and store the distances in distances and the neighbors in
  neighbors: 
  
  // Initialize optional parameters for Kfn().
  param := mlpack.KfnOptions()
  param.K = 5
  param.Reference = input
  
  distances, neighbors, _ := mlpack.Kfn(param)
  
  The output files are organized such that row i and column j in the neighbors
  output matrix corresponds to the index of the point in the reference set which
  is the j'th furthest neighbor from the point in the query set with index i. 
  Row i and column j in the distances output file corresponds to the distance
  between those two points.

  Input parameters:

   - Algorithm (string): Type of neighbor search: 'naive', 'single_tree',
        'dual_tree', 'greedy'.  Default value 'dual_tree'.
   - Epsilon (float64): If specified, will do approximate furthest
        neighbor search with given relative error. Must be in the range [0,1). 
        Default value 0.
   - InputModel (kfnModel): Pre-trained kFN model.
   - K (int): Number of furthest neighbors to find.  Default value 0.
   - LeafSize (int): Leaf size for tree building (used for kd-trees, vp
        trees, random projection trees, UB trees, R trees, R* trees, X trees,
        Hilbert R trees, R+ trees, R++ trees, and octrees).  Default value 20.
   - Percentage (float64): If specified, will do approximate furthest
        neighbor search. Must be in the range (0,1] (decimal form). Resultant
        neighbors will be at least (p*100) % of the distance as the true
        furthest neighbor.  Default value 1.
   - Query (mat.Dense): Matrix containing query points (optional).
   - RandomBasis (bool): Before tree-building, project the data onto a
        random orthogonal basis.
   - Reference (mat.Dense): Matrix containing the reference dataset.
   - Seed (int): Random seed (if 0, std::time(NULL) is used).  Default
        value 0.
   - TreeType (string): Type of tree to use: 'kd', 'vp', 'rp', 'max-rp',
        'ub', 'cover', 'r', 'r-star', 'x', 'ball', 'hilbert-r', 'r-plus',
        'r-plus-plus', 'oct'.  Default value 'kd'.
   - TrueDistances (mat.Dense): Matrix of true distances to compute the
        effective error (average relative error) (it is printed when -v is
        specified).
   - TrueNeighbors (mat.Dense): Matrix of true neighbors to compute the
        recall (it is printed when -v is specified).
   - Verbose (bool): Display informational messages and the full list of
        parameters and timers at the end of execution.

  Output parameters:

   - distances (mat.Dense): Matrix to output distances into.
   - neighbors (mat.Dense): Matrix to output neighbors into.
   - outputModel (kfnModel): If specified, the kFN model will be output
        here.

 */
func Kfn(param *KfnOptionalParam) (*mat.Dense, *mat.Dense, kfnModel) {
  params := getParams("kfn")
  timers := getTimers()

  disableBacktrace()
  disableVerbose()
  // Detect if the parameter was passed; set if so.
  if param.Algorithm != "dual_tree" {
    setParamString(params, "algorithm", param.Algorithm)
    setPassed(params, "algorithm")
  }

  // Detect if the parameter was passed; set if so.
  if param.Epsilon != 0 {
    setParamDouble(params, "epsilon", param.Epsilon)
    setPassed(params, "epsilon")
  }

  // Detect if the parameter was passed; set if so.
  if param.InputModel != nil {
    setKFNModel(params, "input_model", param.InputModel)
    setPassed(params, "input_model")
  }

  // Detect if the parameter was passed; set if so.
  if param.K != 0 {
    setParamInt(params, "k", param.K)
    setPassed(params, "k")
  }

  // Detect if the parameter was passed; set if so.
  if param.LeafSize != 20 {
    setParamInt(params, "leaf_size", param.LeafSize)
    setPassed(params, "leaf_size")
  }

  // Detect if the parameter was passed; set if so.
  if param.Percentage != 1 {
    setParamDouble(params, "percentage", param.Percentage)
    setPassed(params, "percentage")
  }

  // Detect if the parameter was passed; set if so.
  if param.Query != nil {
    gonumToArmaMat(params, "query", param.Query)
    setPassed(params, "query")
  }

  // Detect if the parameter was passed; set if so.
  if param.RandomBasis != false {
    setParamBool(params, "random_basis", param.RandomBasis)
    setPassed(params, "random_basis")
  }

  // Detect if the parameter was passed; set if so.
  if param.Reference != nil {
    gonumToArmaMat(params, "reference", param.Reference)
    setPassed(params, "reference")
  }

  // Detect if the parameter was passed; set if so.
  if param.Seed != 0 {
    setParamInt(params, "seed", param.Seed)
    setPassed(params, "seed")
  }

  // Detect if the parameter was passed; set if so.
  if param.TreeType != "kd" {
    setParamString(params, "tree_type", param.TreeType)
    setPassed(params, "tree_type")
  }

  // Detect if the parameter was passed; set if so.
  if param.TrueDistances != nil {
    gonumToArmaMat(params, "true_distances", param.TrueDistances)
    setPassed(params, "true_distances")
  }

  // Detect if the parameter was passed; set if so.
  if param.TrueNeighbors != nil {
    gonumToArmaUmat(params, "true_neighbors", param.TrueNeighbors)
    setPassed(params, "true_neighbors")
  }

  // Detect if the parameter was passed; set if so.
  if param.Verbose != false {
    setParamBool(params, "verbose", param.Verbose)
    setPassed(params, "verbose")
    enableVerbose()
  }

  // Mark all output options as passed.
  setPassed(params, "distances")
  setPassed(params, "neighbors")
  setPassed(params, "output_model")

  // Call the mlpack program.
  C.mlpackKfn(params.mem, timers.mem)

  // Initialize result variable and get output.
  var distancesPtr mlpackArma
  distances := distancesPtr.armaToGonumMat(params, "distances")
  var neighborsPtr mlpackArma
  neighbors := neighborsPtr.armaToGonumUmat(params, "neighbors")
  var outputModel kfnModel
  outputModel.getKFNModel(params, "output_model")
  // Clean memory.
  cleanParams(params)
  cleanTimers(timers)
  // Return output(s).
  return distances, neighbors, outputModel
}