 
 (defn ^DoubleMatrix
   beta-increment
-  "increment beta without ridge correction; NOTE: cannot refactor
-  DoubleMatrix/eye since it changes in memory, i.e., jBLAS objects
-  don't behave like clojure data structures"
+  "returns a DoubleMatrix row vector to increment the parameter
+  vector, based on the information matrix.  The increment does not
+  include a correction for the addition of a ridge factor.
+
+  Example:
+    (def beta (to-double-rowmat [0 0]))
+    (def feat (to-double-matrix [[1 2] [4 5]]))
+    (def label (to-double-rowmat [1 0]))
+    (def score (score-seq beta label feat))
+    (def info (info-matrix beta feat))
+    (beta-increment info score 1e-2)
+     => #<DoubleMatrix [-3.8961038961039076; 2.7449822904368464]>
+
+  NOTE: cannot refactor DoubleMatrix/eye since it changes in memory,
+  i.e., jBLAS objects don't behave like clojure data structures"
   [info-mat scores rdg-cons]
   (let [num-features (.rows info-mat)
         rdg-mat (.muli (DoubleMatrix/eye (int num-features)) (double rdg-cons))

    (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."
  [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 unpack-neighbors
  "Returns a vector containing the fields of a forma-neighbor-value."
