     (to-double-rowmat (repeat n 0))))
 
 (defn logistic-beta-vector
-  "return the estimated parameter vector; which is used, in turn, to
-  calculate the estimated probability of the binary label; the initial
-  beta-diff value is an arbitrarily large value."
+  "return the estimated parameter vector (persistent vector); which is
+  used, in turn, to calculate the estimated probability of the binary
+  label.  The beta vector is based on the training labels and
+  associated features collected in the feature matrix.  The output can
+  be applied to new features using `probability-calc` in this
+  namespace.
+
+  Example:
+    (def feat (to-double-matrix [[1 2] [4 5]]))
+    (def label (to-double-rowmat [1 0]))
+    (logistic-beta-vector label feat 1e-8 1e-6 250)
+       => [-49.06118492894668 34.891861487354284]
+
+  NOTES: the initial beta-diff value is an arbitrarily large value."
   [label-row feature-mat rdg-cons converge-threshold max-iter]
   (let [beta-init (initial-beta feature-mat)]
     (loop [beta beta-init

           (dec iter)
           diff))))))

(defn estimated-probabilities
  "returns the set of probabilities, after applying the parameter
  values estimated over the training data; both `label-seq` and
  `traning-features` reflect data over the training period and
  `updated-features` reflect data through some interval, which could
  be the end of the training period (for internal validataion) but is
  most likely some interval thereafter"
  [label-seq training-features updated-features]
  (let [new-beta (logistic-beta-vector
                  label-seq
                  training-features
                  1e-8
                  1e-6
                  250)]
    (probability-calc new-beta updated-features)))

(defn unpack-neighbors
  "Returns a vector containing the fields of a forma-neighbor-value."

(defn ^DoubleMatrix
  ridge-correction
  "returns a vector of corrections to the beta-update, given the
  current iteration of the information matrix and score sequence.

  NOTES: The vector a is analogous to f(rdg_cons) = a*rdg_cons + b,
  and we are interested in the correction factor that is calculated as
  follows: Let v = rdg_cons.  Then we originally assume that f(0) =
  f(v) [equivalent to no added constant along the diagnol], which may
  not be correct.  A better approximation is f(0) - b, where b = f(v)
  - a*v.  Then, correction = f(0) - b = f(v) - f(v) + a*v = a*v."
  [info-mat scores rdg-cons]
  (let [stepsize (/ rdg-cons 10)
        upperbound (+ rdg-cons stepsize)
