include/a/regress_linear.h

   1 /*!
   2  @file regress_linear.h
   3  @brief linear regression
   4  @details https://en.wikipedia.org/wiki/Linear_regression
   5 */
   6
   7 #ifndef LIBA_REGRESS_LINEAR_H
   8 #define LIBA_REGRESS_LINEAR_H
   9
  10 #include "a.h"
  11
  12 /*!
  13  @ingroup a_regress
  14  @addtogroup a_regress_linear linear regression
  15  @{
  16 */
  17
  18 typedef struct a_regress_linear a_regress_linear;
  19
  20 #if defined(__cplusplus)
  21 extern "C" {
  22 #endif /* __cplusplus */
  23
  24 /*!
  25  @brief initialize for linear regression
  26  @param[in,out] ctx points to an instance of linear regression
  27  @param[in] coef_p points to regression coefficients
  28  @param[in] coef_n number of regression coefficients
  29  @param[in] bias intercept
  30 */
  31 A_EXTERN void a_regress_linear_init(a_regress_linear *ctx, a_float *coef_p, a_size coef_n, a_float bias);
  32
  33 /*!
  34  @brief calculate predicted value for linear regression
  35  @param[in] ctx points to an instance of linear regression
  36  @param[in] val independent variables
  37  @return predicted value
  38 */
  39 A_EXTERN a_float a_regress_linear_eval(a_regress_linear const *ctx, a_float const *val);
  40
  41 /*!
  42  @brief calculate residuals for linear regression
  43  @param[in] ctx points to an instance of linear regression
  44  @param[in] n number of samples, x[n*coef_n], y[n], err[n]
  45  @param[in] x predictor data, specified as a numeric matrix
  46  @param[in] y response data, specified as a numeric vector
  47  @param[in,out] err residuals, specified as a numeric vector
  48 */
  49 A_EXTERN void a_regress_linear_err(a_regress_linear const *ctx, a_size n, a_float const *x, a_float const *y, a_float *err);
  50
  51 /*!
  52  @brief calculate prediction deviation from mean for linear regression
  53  @param[in] ctx points to an instance of linear regression
  54  @param[in] n number of samples, x[n*coef_n], pdm[n]
  55  @param[in] x predictor data, specified as a numeric matrix
  56  @param[in,out] pdm deviation, specified as a numeric vector
  57  @param[in] y_mean mean of response data
  58 */
  59 A_EXTERN void a_regress_linear_pdm(a_regress_linear const *ctx, a_size n, a_float const *x, a_float *pdm, a_float y_mean);
  60
  61 /*!
  62  @brief gradient descent for linear regression
  63  @param[in,out] ctx points to an instance of linear regression
  64  @param[in] input predictor data, specified as a numeric vector
  65  @param[in] error residual, specified as a numeric scalar
  66  @param[in] alpha learning rate for gradient descent
  67 */
  68 A_EXTERN void a_regress_linear_gd(a_regress_linear *ctx, a_float const *input, a_float error, a_float alpha);
  69
  70 /*!
  71  @brief stochastic gradient descent for linear regression
  72  @param[in,out] ctx points to an instance of linear regression
  73  @param[in] n number of samples, x[n*coef_n], y[n]
  74  @param[in] x predictor data, specified as a numeric matrix
  75  @param[in] y response data, specified as a numeric vector
  76  @param[in] alpha learning rate for gradient descent
  77 */
  78 A_EXTERN void a_regress_linear_sgd(a_regress_linear *ctx, a_size n, a_float const *x, a_float const *y, a_float alpha);
  79
  80 /*!
  81  @brief batch gradient descent for linear regression
  82  @param[in,out] ctx points to an instance of linear regression
  83  @param[in] n number of samples, x[n*coef_n], err[n]
  84  @param[in] x predictor data, specified as a numeric matrix
  85  @param[in] err residuals, specified as a numeric vector
  86  @param[in] alpha learning rate for gradient descent
  87 */
  88 A_EXTERN void a_regress_linear_bgd(a_regress_linear *ctx, a_size n, a_float const *x, a_float const *err, a_float alpha);
  89
  90 /*!
  91  @brief mini-batch gradient descent for linear regression
  92  @param[in,out] ctx points to an instance of linear regression
  93  @param[in] n number of samples, x[n*coef_n], y[n], err[n]
  94  @param[in] x predictor data, specified as a numeric matrix
  95  @param[in] y response data, specified as a numeric vector
  96  @param[in,out] err residuals, specified as a numeric vector
  97  @param[in] delta threshold for gradient descent value
  98  @param[in] lrmax maximum learning rate of iterations
  99  @param[in] lrmin minimum learning rate of iterations
 100  @param[in] lrtim total number of learning rate steps
 101  @param[in] epoch maximum number of epochs
 102  @param[in] batch batch size of data
 103  @return change in loss function
 104 */
 105 A_EXTERN a_float a_regress_linear_mgd(a_regress_linear *ctx, a_size n, a_float const *x, a_float const *y, a_float *err,
 106                                       a_float delta, a_float lrmax, a_float lrmin, a_size lrtim, a_size epoch, a_size batch);
 107
 108 /*!
 109  @brief zeroing for linear regression
 110  @param[in,out] ctx points to an instance of linear regression
 111 */
 112 A_EXTERN void a_regress_linear_zero(a_regress_linear *ctx);
 113
 114 #if defined(__cplusplus)
 115 } /* extern "C" */
 116 namespace a
 117 {
 118 typedef struct a_regress_linear regress_linear;
 119 } /* namespace a */
 120 #endif /* __cplusplus */
 121
 122 /*!
 123  @brief instance structure for linear regression
 124 */
 125 struct a_regress_linear
 126 {
 127     a_float *coef_p; /*!< points to regression coefficients */
 128     a_size coef_n; /*!< number of regression coefficients */
 129     a_float bias; /*!< intercept */
 130 #if defined(__cplusplus)
 131     A_INLINE void init(a_float *p, a_size n, a_float b = 0)
 132     {
 133         a_regress_linear_init(this, p, n, b);
 134     }
 135     A_INLINE a_float eval(a_float const *val) const
 136     {
 137         return a_regress_linear_eval(this, val);
 138     }
 139     A_INLINE void err(a_size n, a_float const *x, a_float const *y, a_float *err) const
 140     {
 141         a_regress_linear_err(this, n, x, y, err);
 142     }
 143     A_INLINE void pdm(a_size n, a_float const *x, a_float *pdm, a_float y_mean) const
 144     {
 145         a_regress_linear_pdm(this, n, x, pdm, y_mean);
 146     }
 147     A_INLINE void gd(a_float const *input, a_float error, a_float alpha)
 148     {
 149         a_regress_linear_gd(this, input, error, alpha);
 150     }
 151     A_INLINE void sgd(a_size n, a_float const *x, a_float const *y, a_float alpha)
 152     {
 153         a_regress_linear_sgd(this, n, x, y, alpha);
 154     }
 155     A_INLINE void bgd(a_size n, a_float const *x, a_float const *err, a_float alpha)
 156     {
 157         a_regress_linear_bgd(this, n, x, err, alpha);
 158     }
 159     A_INLINE a_float mgd(a_size n, a_float const *x, a_float const *y, a_float *err, a_float delta,
 160                          a_float lrmax, a_float lrmin, a_size lrtim, a_size epoch, a_size batch)
 161     {
 162         return a_regress_linear_mgd(this, n, x, y, err, delta, lrmax, lrmin, lrtim, epoch, batch);
 163     }
 164     A_INLINE void zero() { a_regress_linear_zero(this); }
 165 #endif /* __cplusplus */
 166 };
 167
 168 /*! @} a_regress_linear */
 169
 170 #endif /* a/regress_linear.h */