more docs

R/main_vanilla.R

@@ -10,7 +10,7 @@
 #' @param thin integer; the number of "steps" to keep as part of the output (i.e. if the user specifies 10, every 10th iteration will be kept)
 #' @param m_lowerbound double; lower limit value for the global "m" parameter; will use a reflected normal within the gradient descent algorithm to adjust any aberrant values
 #' @param m_upperbound double; upper limit value for the global "m" parameter; will use a reflected normal within the gradient descent algorithm to adjust any aberrant values
-#' @param normalize_geodist boolean; whether geographic distances between demes should be normalized (i.e. rescaled to \code{[0-1]}). Helps increase model stability at the expense of complicating the interpretation of the migration rate parameter.
+#' @param normalize_geodist boolean; whether geographic distances between demes should be normalized (i.e. Min-Max Feature Scaling: \eqn{X' = \frac{X - X_{min}}{X_{max} - X_{min}} }, which places the geodistances on the scale to \eqn{[0-1]}). Helps increase model stability at the expense of complicating the interpretation of the migration rate parameter.
 #' @param report_progress boolean; whether or not a progress bar should be shown as you iterate through steps
 #' @param return_verbose boolean; whether the inbreeding coefficients and migration rate should be returned for every iteration or
 #' only for the final iteration. User will typically not want to store every iteration, which can be memory intensive
@@ -95,6 +95,11 @@ deme_inbreeding_spcoef_vanilla <- function(discdat,
     stop("discdat dataframe cannot have missing values")
   }
 
+  # catch accidental bad F and M start
+  if ( any(round(start_params, digits = 1e200) == 0) ) {
+    warning("At least one of your start parameters is zero (or essentially zero), which will result in unstable behavior in the Gradient-Descent algorithm. Consider increasing the start parameter.")
+  }
+
   #......................
   # check for self comparisons
   #......................