Write Logistic Regression documentation (oneapi-src#2593)

* Initial commit

* Add newton-cg optimizer

* Create optimizers section

* Write newton-cg and logreg documentation

* Address comments

* Join logloss.rst with index.rst

cpp/oneapi/dal/algo/logistic_regression/common.hpp

@@ -31,7 +31,7 @@ namespace v1 {
 /// :capterm:`classification problem <classification>`.
 struct classification {};
 
-/// Alias tag-type for regression task.
+/// Alias tag-type for classification task
 using by_default = classification;
 } // namespace v1
 
@@ -42,9 +42,10 @@ using v1::by_default;
 
 namespace method {
 namespace v1 {
-/// Tag-type that denotes :ref:`dense batch <dense_batch>` computational method.
+/// Tag-type that denotes :ref:`dense_batch <logreg_t_math_dense_batch>` computational method.
 struct dense_batch {};
 
+/// Alias tag-type for the dense_batch method
 using by_default = dense_batch;
 } // namespace v1
 
@@ -80,6 +81,7 @@ const inline result_option_id intercept = detail::get_intercept_id();
 /// Return the coefficients to use in logistic regression
 const inline result_option_id coefficients = detail::get_coefficients_id();
 
+/// Return the number of iterations made by optimizer
 const inline result_option_id iterations_count = detail::get_iterations_count_id();
 
 } // namespace result_options
@@ -165,8 +167,8 @@ namespace v1 {
 ///                     be :expr:`method::dense_batch`.
 /// @tparam Task        Tag-type that specifies type of the problem to solve. Can
 ///                     be :expr:`task::classification`.
-/// @tparam Optimizer   Tag-type that specifies type of the optimizer used by algorithm.
-///                     Can be :expr:`optimizer::newton_cg`.
+/// @tparam Optimizer   The descriptor of the optimizer used for minimization. Can
+///                     be :expr:`newton_cg::descriptor`
 template <typename Float = float,
           typename Method = method::by_default,
           typename Task = task::by_default,
@@ -186,12 +188,14 @@ class descriptor : public detail::descriptor_base<Task> {
     using optimizer_t = Optimizer;
 
     /// Creates a new instance of the class with the given :literal:`compute_intercept`
+    /// and :literal:`C`
     explicit descriptor(bool compute_intercept = true, double C = 1.0)
             : base_t(compute_intercept,
                      C,
                      std::make_shared<detail::optimizer<optimizer_t>>(optimizer_t{})) {}
 
-    /// Creates a new instance of the class with the given :literal:`compute_intercept`
+    /// Creates a new instance of the class with the given :literal:`compute_intercept`,
+    /// :literal:`C` and :literal:`optimizer`
     explicit descriptor(bool compute_intercept, double C, const optimizer_t& optimizer)
             : base_t(compute_intercept,
                      C,

cpp/oneapi/dal/algo/logistic_regression/infer_types.hpp

@@ -37,16 +37,16 @@ using v1::infer_result_impl;
 namespace v1 {
 
 /// @tparam Task Tag-type that specifies type of the problem to solve. Can
-///              be :expr:`task::classification` or :expr:`task::search`.
+///              be :expr:`task::classification`.
 template <typename Task = task::by_default>
 class infer_input : public base {
     static_assert(detail::is_valid_task_v<Task>);
 
 public:
     using task_t = Task;
 
-    /// Creates a new instance of the class with the given :literal:`model`
-    /// and :literal:`data` property values
+    /// Creates a new instance of the class with the given :literal:`data`
+    /// and :literal:`model` property values
     infer_input(const table& data, const model<Task>& model);
 
     /// The dataset for inference $X'$
@@ -58,7 +58,7 @@ class infer_input : public base {
         return *this;
     }
 
-    /// The trained k-NN model
+    /// The trained Logistic Regression model
     /// @remark default = model<Task>{}
     const model<Task>& get_model() const;
 
@@ -76,7 +76,7 @@ class infer_input : public base {
 };
 
 /// @tparam Task Tag-type that specifies type of the problem to solve. Can
-///              be :expr:`task::regression`.
+///              be :expr:`task::classification`.
 template <typename Task = task::by_default>
 class infer_result {
     static_assert(detail::is_valid_task_v<Task>);
@@ -91,7 +91,7 @@ class infer_result {
     /// @remark default = table{}
     const table& get_responses() const;
 
-    /// The predicted responses
+    /// The predicted probabilities
     /// @remark default = table{}
     const table& get_probabilities() const;
 

cpp/oneapi/dal/algo/logistic_regression/train_types.hpp

@@ -79,8 +79,6 @@ class train_input : public base {
     /// and :literal:`responses` property values
     train_input(const table& data, const table& responses);
 
-    //train_input(const table& data);
-
     /// The training set X
     /// @remark default = table{}
     const table& get_data() const;
@@ -128,15 +126,15 @@ class train_result {
         return *this;
     }
 
-    /// Table of Logistic regression intercept
+    /// Table with Logistic Regression intercept
     const table& get_intercept() const;
 
     auto& set_intercept(const table& value) {
         set_intercept_impl(value);
         return *this;
     }
 
-    /// Table of Logistic regression coefficients
+    /// Table of Logistic Regression coefficients
     const table& get_coefficients() const;
 
     auto& set_coefficients(const table& value) {
@@ -152,7 +150,7 @@ class train_result {
         return *this;
     }
 
-    /// Table of Logistic regression coefficients with intercept
+    /// Table of Logistic Regression coefficients and intercept
     const table& get_packed_coefficients() const;
 
     auto& set_packed_coefficients(const table& value) {

cpp/oneapi/dal/algo/newton_cg/common.hpp

@@ -125,8 +125,8 @@ class descriptor : public detail::descriptor_base<Task> {
     using method_t = Method;
     using task_t = Task;
 
-    /// Creates a new instance of the class with the given :literal:`l1_regularization_coefficient`,
-    /// :literal:`l2_regularization_coefficient` and :literal:`fit_intercept` property values.
+    /// Creates a new instance of the class with the given :literal:`tol`
+    /// and :literal:`maxiter` property values.
     explicit descriptor(double tol = 1e-4, std::int64_t maxiter = 100) {
         set_tolerance(tol);
         set_max_iteration(maxiter);

docs/source/api/algorithms/index.rst

@@ -30,7 +30,9 @@ Refer to :ref:`Developer Guide <dg_algorithms>` for mathematical descriptions of
    ensembles/index.rst
    graph/index.rst
    kernel-functions/index.rst
+   logistic-regression/index.rst
    nearest-neighbors/index.rst
+   optimizers/index.rst
    objective-function/index.rst
    pairwise-distances/index.rst
    statistics/index.rst

docs/source/api/algorithms/logistic-regression/index.rst

@@ -0,0 +1,26 @@
+.. ******************************************************************************
+.. * Copyright 2023 Intel Corporation
+.. *
+.. * Licensed under the Apache License, Version 2.0 (the "License");
+.. * you may not use this file except in compliance with the License.
+.. * You may obtain a copy of the License at
+.. *
+.. *     http://www.apache.org/licenses/LICENSE-2.0
+.. *
+.. * Unless required by applicable law or agreed to in writing, software
+.. * distributed under the License is distributed on an "AS IS" BASIS,
+.. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. * See the License for the specific language governing permissions and
+.. * limitations under the License.
+.. *******************************************************************************/
+
+===================
+Logistic Regression
+===================
+
+This chapter describes programming interfaces of the Logistic Regression algorithm implemented in |short_name|.
+
+.. toctree::
+   :titlesonly:
+
+   logistic-regression.rst

docs/source/api/algorithms/logistic-regression/logistic-regression.rst

@@ -0,0 +1,143 @@
+.. ******************************************************************************
+.. * Copyright 2023 Intel Corporation
+.. *
+.. * Licensed under the Apache License, Version 2.0 (the "License");
+.. * you may not use this file except in compliance with the License.
+.. * You may obtain a copy of the License at
+.. *
+.. *     http://www.apache.org/licenses/LICENSE-2.0
+.. *
+.. * Unless required by applicable law or agreed to in writing, software
+.. * distributed under the License is distributed on an "AS IS" BASIS,
+.. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. * See the License for the specific language governing permissions and
+.. * limitations under the License.
+.. *******************************************************************************/
+
+.. highlight:: cpp
+.. default-domain:: cpp
+
+.. _api_logreg:
+
+===================
+Logistic Regression
+===================
+
+.. include:: ../../../includes/logistic-regression/logistic-regression-introduction.rst
+
+------------------------
+Mathematical formulation
+------------------------
+
+Refer to :ref:`Developer Guide: Logistic Regression <alg_logreg>`.
+
+---------------------
+Programming Interface
+---------------------
+
+All types and functions are declared in the
+``oneapi::dal::logistic_regression`` namespace and available via the inclusion of the
+``oneapi/dal/algo/logistic_regression.hpp`` header file.
+
+Result Options
+--------------
+.. onedal_class:: oneapi::dal::logistic_regression::result_option_id
+
+Descriptor
+----------
+.. onedal_class:: oneapi::dal::logistic_regression::descriptor
+
+Method Tags
+~~~~~~~~~~~
+.. onedal_tags_namespace:: oneapi::dal::logistic_regression::method
+
+Task Tags
+~~~~~~~~~
+.. onedal_tags_namespace:: oneapi::dal::logistic_regression::task
+
+Model
+-----
+.. onedal_class:: oneapi::dal::logistic_regression::model
+
+
+.. _logreg_t_api:
+
+Training :cpp:expr:`train(...)`
+--------------------------------
+
+.. _logreg_t_api_input:
+
+Input
+~~~~~
+.. onedal_class:: oneapi::dal::logistic_regression::train_input
+
+.. _logreg_t_api_result:
+
+Result
+~~~~~~
+.. onedal_class:: oneapi::dal::logistic_regression::train_result
+
+Operation
+~~~~~~~~~
+
+.. function:: template <typename Descriptor> \
+              logistic_regression::train_result train(const Descriptor& desc, \
+                                         const logistic_regression::train_input& input)
+
+   :param desc: Logistic Regression algorithm descriptor :expr:`logistic_regression::descriptor`
+   :param input: Input data for the training operation
+
+   Preconditions
+      | :expr:`input.data.has_data == true`
+      | :expr:`input.responses.data.has_data == true`
+      | :expr:`input.data.row_count == input.responses.row_count`
+      | :expr:`input.responses.column_count == 1`
+      | :expr:`desc.inverse_regularization > 0.0`
+      | :expr:`desc.class_count == 2`
+   Postconditions
+      | :expr:`result.coefficients.row_count = 1`
+      | :expr:`result.coefficients.column_count = input.data.column_count`
+      | :expr:`result.intercept.row_count = 1`
+      | :expr:`result.intercept.column_count = 1`
+      | :expr:`result.packed_coefficients.row_count = 1`
+      | :expr:`result.packed_coefficients.column_count = input.data.column_count + 1`
+
+.. _logreg_i_api:
+
+Inference :cpp:expr:`infer(...)`
+---------------------------------
+
+.. _logreg_i_api_input:
+
+Input
+~~~~~
+.. onedal_class:: oneapi::dal::logistic_regression::infer_input
+
+.. _logreg_i_api_result:
+
+Result
+~~~~~~
+.. onedal_class:: oneapi::dal::logistic_regression::infer_result
+
+Operation
+~~~~~~~~~
+
+.. function:: template <typename Descriptor> \
+              logistic_regression::infer_result infer(const Descriptor& desc, \
+                                         const logistic_regression::infer_input& input)
+
+   :param desc: Logistic Regression algorithm descriptor :expr:`logistic_regression::descriptor`
+   :param input: Input data for the inference operation
+
+   Preconditions
+      | :expr:`input.data.has_data == true`
+   Postconditions
+      | :expr:`result.responses.column_count == 1`
+      | :expr:`result.responses.row_count == input.data.row_count`
+
+
+--------
+Examples
+--------
+
+.. include:: ../../../includes/logistic-regression/logistic-regression-examples.rst

docs/source/api/algorithms/objective-function/logloss.rst

@@ -47,4 +47,4 @@ Method tags
 
 Task tags
 ~~~~~~~~~
-.. onedal_tags_namespace:: oneapi::dal::logloss_objective::task
+.. onedal_tags_namespace:: oneapi::dal::logloss_objective::task

docs/source/api/algorithms/optimizers/index.rst

@@ -0,0 +1,26 @@
+.. ******************************************************************************
+.. * Copyright 2023 Intel Corporation
+.. *
+.. * Licensed under the Apache License, Version 2.0 (the "License");
+.. * you may not use this file except in compliance with the License.
+.. * You may obtain a copy of the License at
+.. *
+.. *     http://www.apache.org/licenses/LICENSE-2.0
+.. *
+.. * Unless required by applicable law or agreed to in writing, software
+.. * distributed under the License is distributed on an "AS IS" BASIS,
+.. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. * See the License for the specific language governing permissions and
+.. * limitations under the License.
+.. *******************************************************************************/
+
+==========
+Optimizers
+==========
+
+This chapter describes the programming interfaces of optimizers implemented in |short_name|.
+
+.. toctree::
+   :titlesonly:
+
+   newton-cg.rst