numo-liblinear 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7db70ba7431ce52aa9530d3d340a6dce5a616daa
-  data.tar.gz: ce1a99b9082477922ed35768de8467b514d36541
+  metadata.gz: 3bf71a14ccac359b6dffce32a5a5d3c784ef9efa
+  data.tar.gz: 6af9f95c6b28c11b06fc0b10628a37e9397564c5
 SHA512:
-  metadata.gz: 79e9cbacea54a665ddb971da7b08fd3a43d159a0314715d0aecbf5c19b3b3c95adca6f8b29217c354348d9d8417b9c14742a8d1a5f2debd2db51dd92c32007d5
-  data.tar.gz: 96a37fde1a15d9a79d7c2bbf374691e8358b42afadf1df58ac1097a6af1bc52ebcd5e6b43601e5ec15582fc79e9b430c20bc39b42503083c0991066b34d9bbbc
+  metadata.gz: 18e64c5d487cab2636216425e45fd8eeaefa0f14026068d3678f0d8d643aea00acf867aa64ba510a62d4c343408a9e22bace2a0347a7b7aba7ddd872f2bbc579
+  data.tar.gz: 43e16f69a931aab7a45163f1909e307f3334ef88f4e45ed79e5513b288804d5c0dfcbb92ef79642bb7c40e70bcdffe6f47548a2cad10351da3585dd48f0a84db

data/CHANGELOG.md

@@ -1,2 +1,6 @@
+# 0.2.0
+- Add valation of method parameters.
+- Several documentation improvements.
+
 # 0.1.0
 - First release.

data/README.md

@@ -1,7 +1,9 @@
 # Numo::Liblinear
 
 [![Build Status](https://travis-ci.org/yoshoku/numo-liblinear.svg?branch=master)](https://travis-ci.org/yoshoku/numo-liblinear)
+[![Gem Version](https://badge.fury.io/rb/numo-liblinear.svg)](https://badge.fury.io/rb/numo-liblinear)
 [![BSD 3-Clause License](https://img.shields.io/badge/License-BSD%203--Clause-orange.svg)](https://github.com/yoshoku/numo-liblinear/blob/master/LICENSE.txt)
+[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](https://www.rubydoc.info/gems/numo-liblinear/0.2.0)
 
 Numo::Liblinear is a Ruby gem binding to the [LIBLINEAR](https://www.csie.ntu.edu.tw/~cjlin/liblinear/) library.
 LIBLINEAR is one of the famous libraries for large-scale regularized linear classification and regression.

data/ext/numo/liblinear/liblinearext.c

@@ -12,10 +12,13 @@ void print_null(const char *s) {}
  * Train the model according to the given training data.
  *
  * @overload train(x, y, param) -> Hash
+ *   @param x [Numo::DFloat] (shape: [n_samples, n_features]) The samples to be used for training the model.
+ *   @param y [Numo::DFloat] (shape: [n_samples]) The labels or target values for samples.
+ *   @param param [Hash] The parameters of a model.
  *
- * @param x [Numo::DFloat] (shape: [n_samples, n_features]) The samples to be used for training the model.
- * @param y [Numo::DFloat] (shape: [n_samples]) The labels or target values for samples.
- * @param param [Hash] The parameters of a model.
+ * @raise [ArgumentError] If the sample array is not 2-dimensional, the label array is not 1-dimensional,
+ *   the sample array and label array do not have the same number of samples, or
+ *   the hyperparameter has an invalid value, this error is raised.
  * @return [Hash] The model obtained from the training procedure.
  */
 static
@@ -24,6 +27,9 @@ VALUE numo_liblinear_train(VALUE self, VALUE x_val, VALUE y_val, VALUE param_has
   struct problem* problem;
   struct parameter* param;
   struct model* model;
+  narray_t* x_nary;
+  narray_t* y_nary;
+  char* err_msg;
   VALUE model_hash;
 
   if (CLASS_OF(x_val) != numo_cDFloat) {
@@ -39,9 +45,32 @@ VALUE numo_liblinear_train(VALUE self, VALUE x_val, VALUE y_val, VALUE param_has
     y_val = nary_dup(y_val);
   }
 
+  GetNArray(x_val, x_nary);
+  GetNArray(y_val, y_nary);
+  if (NA_NDIM(x_nary) != 2) {
+    rb_raise(rb_eArgError, "Expect samples to be 2-D array.");
+    return Qnil;
+  }
+  if (NA_NDIM(y_nary) != 1) {
+    rb_raise(rb_eArgError, "Expect label or target values to be 1-D arrray.");
+    return Qnil;
+  }
+  if (NA_SHAPE(x_nary)[0] != NA_SHAPE(y_nary)[0]) {
+    rb_raise(rb_eArgError, "Expect to have the same number of samples for samples and labels.");
+    return Qnil;
+  }
+
   param = rb_hash_to_parameter(param_hash);
   problem = dataset_to_problem(x_val, y_val);
 
+  err_msg = check_parameter(problem, param);
+  if (err_msg) {
+    xfree_problem(problem);
+    xfree_parameter(param);
+    rb_raise(rb_eArgError, "Invalid LIBLINEAR parameter is given: %s", err_msg);
+    return Qnil;
+  }
+
   set_print_string_function(print_null);
   model = train(problem, param);
   model_hash = model_to_rb_hash(model);
@@ -58,11 +87,14 @@ VALUE numo_liblinear_train(VALUE self, VALUE x_val, VALUE y_val, VALUE param_has
  * The predicted labels or values in the validation process are returned.
  *
  * @overload cv(x, y, param, n_folds) -> Numo::DFloat
+ *   @param x [Numo::DFloat] (shape: [n_samples, n_features]) The samples to be used for training the model.
+ *   @param y [Numo::DFloat] (shape: [n_samples]) The labels or target values for samples.
+ *   @param param [Hash] The parameters of a model.
+ *   @param n_folds [Integer] The number of folds.
  *
- * @param x [Numo::DFloat] (shape: [n_samples, n_features]) The samples to be used for training the model.
- * @param y [Numo::DFloat] (shape: [n_samples]) The labels or target values for samples.
- * @param param [Hash] The parameters of a model.
- * @param n_folds [Integer] The number of folds.
+ * @raise [ArgumentError] If the sample array is not 2-dimensional, the label array is not 1-dimensional,
+ *   the sample array and label array do not have the same number of samples, or
+ *   the hyperparameter has an invalid value, this error is raised.
  * @return [Numo::DFloat] (shape: [n_samples]) The predicted class label or value of each sample.
  */
 static
@@ -72,6 +104,9 @@ VALUE numo_liblinear_cross_validation(VALUE self, VALUE x_val, VALUE y_val, VALU
   size_t t_shape[1];
   VALUE t_val;
   double* t_pt;
+  narray_t* x_nary;
+  narray_t* y_nary;
+  char* err_msg;
   struct problem* problem;
   struct parameter* param;
 
@@ -88,9 +123,32 @@ VALUE numo_liblinear_cross_validation(VALUE self, VALUE x_val, VALUE y_val, VALU
     y_val = nary_dup(y_val);
   }
 
+  GetNArray(x_val, x_nary);
+  GetNArray(y_val, y_nary);
+  if (NA_NDIM(x_nary) != 2) {
+    rb_raise(rb_eArgError, "Expect samples to be 2-D array.");
+    return Qnil;
+  }
+  if (NA_NDIM(y_nary) != 1) {
+    rb_raise(rb_eArgError, "Expect label or target values to be 1-D arrray.");
+    return Qnil;
+  }
+  if (NA_SHAPE(x_nary)[0] != NA_SHAPE(y_nary)[0]) {
+    rb_raise(rb_eArgError, "Expect to have the same number of samples for samples and labels.");
+    return Qnil;
+  }
+
   param = rb_hash_to_parameter(param_hash);
   problem = dataset_to_problem(x_val, y_val);
 
+  err_msg = check_parameter(problem, param);
+  if (err_msg) {
+    xfree_problem(problem);
+    xfree_parameter(param);
+    rb_raise(rb_eArgError, "Invalid LIBLINEAR parameter is given: %s", err_msg);
+    return Qnil;
+  }
+
   t_shape[0] = problem->l;
   t_val = rb_narray_new(numo_cDFloat, 1, t_shape);
   t_pt = (double*)na_get_pointer_for_write(t_val);
@@ -109,10 +167,11 @@ VALUE numo_liblinear_cross_validation(VALUE self, VALUE x_val, VALUE y_val, VALU
  * Predict class labels or values for given samples.
  *
  * @overload predict(x, param, model) -> Numo::DFloat
+ *   @param x [Numo::DFloat] (shape: [n_samples, n_features]) The samples to calculate the scores.
+ *   @param param [Hash] The parameters of the trained model.
+ *   @param model [Hash] The model obtained from the training procedure.
  *
- * @param x [Numo::DFloat] (shape: [n_samples, n_features]) The samples to calculate the scores.
- * @param param [Hash] The parameters of the trained model.
- * @param model [Hash] The model obtained from the training procedure.
+ * @raise [ArgumentError] If the sample array is not 2-dimensional, this error is raised.
  * @return [Numo::DFloat] (shape: [n_samples]) The predicted class label or value of each sample.
  */
 static
@@ -137,7 +196,13 @@ VALUE numo_liblinear_predict(VALUE self, VALUE x_val, VALUE param_hash, VALUE mo
   if (!RTEST(nary_check_contiguous(x_val))) {
     x_val = nary_dup(x_val);
   }
+
   GetNArray(x_val, x_nary);
+  if (NA_NDIM(x_nary) != 2) {
+    rb_raise(rb_eArgError, "Expect samples to be 2-D array.");
+    return Qnil;
+  }
+
   param = rb_hash_to_parameter(param_hash);
   model = rb_hash_to_model(model_hash);
   model->param = *param;
@@ -173,10 +238,11 @@ VALUE numo_liblinear_predict(VALUE self, VALUE x_val, VALUE param_hash, VALUE mo
  * Calculate decision values for given samples.
  *
  * @overload decision_function(x, param, model) -> Numo::DFloat
+ *   @param x [Numo::DFloat] (shape: [n_samples, n_features]) The samples to calculate the scores.
+ *   @param param [Hash] The parameters of the trained model.
+ *   @param model [Hash] The model obtained from the training procedure.
  *
- * @param x [Numo::DFloat] (shape: [n_samples, n_features]) The samples to calculate the scores.
- * @param param [Hash] The parameters of the trained model.
- * @param model [Hash] The model obtained from the training procedure.
+ * @raise [ArgumentError] If the sample array is not 2-dimensional, this error is raised.
  * @return [Numo::DFloat] (shape: [n_samples, n_classes]) The decision value of each sample.
  */
 static
@@ -203,7 +269,13 @@ VALUE numo_liblinear_decision_function(VALUE self, VALUE x_val, VALUE param_hash
   if (!RTEST(nary_check_contiguous(x_val))) {
     x_val = nary_dup(x_val);
   }
+
   GetNArray(x_val, x_nary);
+  if (NA_NDIM(x_nary) != 2) {
+    rb_raise(rb_eArgError, "Expect samples to be 2-D array.");
+    return Qnil;
+  }
+
   param = rb_hash_to_parameter(param_hash);
   model = rb_hash_to_model(model_hash);
   model->param = *param;
@@ -270,10 +342,11 @@ VALUE numo_liblinear_decision_function(VALUE self, VALUE x_val, VALUE param_hash
  * The method supports only the logistic regression.
  *
  * @overload predict_proba(x, param, model) -> Numo::DFloat
+ *   @param x [Numo::DFloat] (shape: [n_samples, n_features]) The samples to predict the class probabilities.
+ *   @param param [Hash] The parameters of the trained Logistic Regression model.
+ *   @param model [Hash] The model obtained from the training procedure.
  *
- * @param x [Numo::DFloat] (shape: [n_samples, n_features]) The samples to predict the class probabilities.
- * @param param [Hash] The parameters of the trained Logistic Regression model.
- * @param model [Hash] The model obtained from the training procedure.
+ * @raise [ArgumentError] If the sample array is not 2-dimensional, this error is raised.
  * @return [Numo::DFloat] (shape: [n_samples, n_classes]) Predicted probablity of each class per sample.
  */
 static
@@ -292,6 +365,12 @@ VALUE numo_liblinear_predict_proba(VALUE self, VALUE x_val, VALUE param_hash, VA
   int n_samples;
   int n_features;
 
+  GetNArray(x_val, x_nary);
+  if (NA_NDIM(x_nary) != 2) {
+    rb_raise(rb_eArgError, "Expect samples to be 2-D array.");
+    return Qnil;
+  }
+
   param = rb_hash_to_parameter(param_hash);
   model = rb_hash_to_model(model_hash);
   model->param = *param;
@@ -304,7 +383,6 @@ VALUE numo_liblinear_predict_proba(VALUE self, VALUE x_val, VALUE param_hash, VA
     if (!RTEST(nary_check_contiguous(x_val))) {
       x_val = nary_dup(x_val);
     }
-    GetNArray(x_val, x_nary);
 
     /* Initialize some variables. */
     n_samples = (int)NA_SHAPE(x_nary)[0];
@@ -343,17 +421,26 @@ VALUE numo_liblinear_predict_proba(VALUE self, VALUE x_val, VALUE param_hash, VA
 /**
  * Load the parameters and model from a text file with LIBLINEAR format.
  *
- * @param filename [String] The path to a file to load.
+ * @overload load_model(filename) -> Array
+ *   @param filename [String] The path to a file to load.
+ *
+ * @raise [IOError] This error raises when failed to load the model file.
  * @return [Array] Array contains the parameters and model.
  */
 static
 VALUE numo_liblinear_load_model(VALUE self, VALUE filename)
 {
-  struct model* model = load_model(StringValuePtr(filename));
+  char* filename_ = StringValuePtr(filename);
+  struct model* model = load_model(filename_);
   VALUE res = rb_ary_new2(2);
   VALUE param_hash = Qnil;
   VALUE model_hash = Qnil;
 
+  if (model == NULL) {
+    rb_raise(rb_eIOError, "Failed to load file '%s'", filename_);
+    return Qnil;
+  }
+
   if (model) {
     param_hash = parameter_to_rb_hash(&(model->param));
     model_hash = model_to_rb_hash(model);
@@ -371,26 +458,33 @@ VALUE numo_liblinear_load_model(VALUE self, VALUE filename)
  * Note that the save_model saves only the parameters necessary for estimation with the trained model.
  *
  * @overload save_model(filename, param, model) -> Boolean
+ *   @param filename [String] The path to a file to save.
+ *   @param param [Hash] The parameters of the trained model.
+ *   @param model [Hash] The model obtained from the training procedure.
  *
- * @param filename [String] The path to a file to save.
- * @param param [Hash] The parameters of the trained model.
- * @param model [Hash] The model obtained from the training procedure.
+ * @raise [IOError] This error raises when failed to save the model file.
  * @return [Boolean] true on success, or false if an error occurs.
  */
 static
 VALUE numo_liblinear_save_model(VALUE self, VALUE filename, VALUE param_hash, VALUE model_hash)
 {
+  char* filename_ = StringValuePtr(filename);
   struct parameter* param = rb_hash_to_parameter(param_hash);
   struct model* model = rb_hash_to_model(model_hash);
   int res;
 
   model->param = *param;
-  res = save_model(StringValuePtr(filename), model);
+  res = save_model(filename_, model);
 
   xfree_model(model);
   xfree_parameter(param);
 
-  return res < 0 ? Qfalse : Qtrue;
+  if (res < 0) {
+    rb_raise(rb_eIOError, "Failed to save file '%s'", filename_);
+    return Qfalse;
+  }
+
+  return Qtrue;
 }
 
 void Init_liblinearext()

data/lib/numo/liblinear/version.rb

@@ -3,6 +3,6 @@
 module Numo
   module Liblinear
     # The version of Numo::Liblienar you are using.
-    VERSION = '0.1.0'
+    VERSION = '0.2.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: numo-liblinear
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - yoshoku
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-07-26 00:00:00.000000000 Z
+date: 2019-08-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: numo-narray