Update working for convergence commands and documentation

dadi_cli/__main__.py

@@ -1248,14 +1248,14 @@ def add_inference_argument(parser):
         default=0,
         type=_check_positive_int,
         dest="check_convergence",
-        help="Start checking for convergence after a chosen number of optimizations. Stop optimization runs when convergence criteria are reached. BestFit results file will be call <output_prefix>.InferDM.bestfits. Convergence not checked by default.",
+        help="Start checking for convergence after a chosen number of optimizations. Optimization runs will stop early if convergence criteria are reached. BestFit results file will be call <output_prefix>.InferDM.bestfits. Convergence not checked by default.",
     )
     parser.add_argument(
         "--force-convergence",
         default=0,
         type=_check_positive_int,
         dest="force_convergence",
-        help="Start checking for convergence after a chosen number of optimizations. Only stop optimization once convergence criteria is reached. BestFit results file will be call <output_prefix>.InferDM.bestfits. Convergence not checked by default.",
+        help="Start checking for convergence after a chosen number of optimizations. Optimization runs will continue until convergence criteria is reached (--optimizations flag will be ignored). BestFit results file will be call <output_prefix>.InferDM.bestfits. Convergence not checked by default.",
     )
     parser.add_argument(
         "--work-queue",

docs/userguide/demog.md

@@ -58,7 +58,7 @@ Because there is randomness built into `dadi-cli` for where the starting paramet
 
 When using `BestFit`, users can adjust the criteria for convergence. By default optimizations are considered convergent if there are two other optimizations with a log-likelihood within 0.01% units of the optimization with the best log-likelihood. This criteria can be adjusted using the `--delta-ll` option and passing in the percentage difference in decimal form (so the default is 0.0001, rather than 0.01). Generally a higher `--delta-ll` can result in a false positive convergence, but this is dependent on the data being used (for example, the sample size can have a big effect on the size of the log-likelihood). Optimizations in the bestfit file will be ordered by log-likelihood and should be examined closely for similarity of parameter values in convergent fits.
 
-Finally, if users have experience with the data they are using, they can use the `--check-convergence` or `--force-convergence` option in `InferDM`. The `--check-convergence` option will run `BestFit` after a specified number of optimization to check for convergence and stop running optimizations once convergence is reached. For example `--check-convergence 10` will run 10 optimizations and then start checking for convergence. The `--force-convergence` option will constantly add new optimization runs until convergence is reached. When using `--check-convergence` or `--force-convergence` users can also use `--delta-ll` to change the convergence criteria. Users can use the output files from `InferDM` or `BestFit` as a starting point for the inital parameters with the `--bestfit-p0-file` flag and passing in the file you want to use. The starting parameters will be randomly chosen from the top ten fits and perturbed.
+Finally, if users have experience with the data they are using, they can use the `--check-convergence` or `--force-convergence` option in `InferDM`. The `--check-convergence` option will run `BestFit` after a specified number of optimizations to check for convergence and stop running optimizations if convergence is reached. For example, `--check-convergence 10` will run 10 optimizations and then start checking for convergence. Optimization runs will stop before the requested number of `--optimizations` if convergence is met. The `--force-convergence` option will constantly add new optimization runs until convergence is reached, ignoring `--optimization`. When using `--check-convergence` or `--force-convergence` users can also use `--delta-ll` to change the convergence criteria. Users can use the output files from `InferDM` or `BestFit` as a starting point for the inital parameters with the `--bestfit-p0-file` flag and passing in the file they want to use. The starting parameters will be randomly chosen from the top ten fits and perturbed.
 
 Sometimes parameters may be close to the boundaries. Users should be cautious and test increasing the boundaries to examine whether these boundaries would affect the results significantly. The best fit parameters are shown below mirroring the bestfits file. The first column is the log-likelihood, then the corresponding to these parameters, and the last column is the population-scaled mutation rate of the synonymous SNPs.