tracts.driver.run_boundary_reoptimization#

run_boundary_reoptimization(driver_spec, reload_context, optimal_sex_bias_at_boundaries, genetic_model, optimal_params, optimal_likelihood, remainder_params, population, likelihood_options)#

Repeatedly re-optimizes while one or more sex-bias parameters have an optimal value at a +-1 boundary. Each iteration: all boundary-hitting sex-bias parameters that are directly optimized (present in model_base_params) are fixed by value (at +-near_one) for the re-optimization. A boundary hit on the implicit population’s derived sex-bias parameter cannot be fixed this way; instead, this tries to switch to a different explicit source population (from the same founder event) whose sex-bias parameter is not itself at a boundary, and use that as the implicit population instead (see get_alternate_implicit_population).

After each re-optimization, if the likelihood has not improved over the state before that iteration, the loop stops immediately, printing/logging a message stating so, and the state from before that iteration (the original input, if this was the first iteration) is returned. Otherwise, the improvement is kept and, unless no sex-bias parameter remains free to fix (all have already been fixed by value), the newly-updated optimal parameters are checked again for boundary hits: if any (previously free) sex-bias parameter is now at a boundary too, the loop repeats to fix and re-optimize those as well. The loop otherwise stops once no sex-bias parameter is at a boundary any more, or if neither of the two fixing mechanisms above applies (e.g. the boundary hit is on the implicit population and no alternate is available).

Each re-optimization resumes from the previous optimization’s result: all starting parameters are pinned to their previous optimal value (no resampling), so there is a single repetition, and (as in run_sex_bias_fixing_reoptimizations) it runs with print_run_details=False to keep its console output brief.

Parameters:

  • driver_spec (InferenceConfig) – The current driver-file configuration.

  • reload_context (ModelReloadContext) – File-location and ancestry-proportion context needed to reload the demographic model from the model YAML file, used only if the implicit population is changed.

  • optimal_sex_bias_at_boundaries (list[str]) – Parameter names near their +-1 boundary, as returned by check_optimal_sex_bias_parameters_at_boundaries.

  • genetic_model (GeneticModel) – The current genetic model. Its demographic model’s parameter names are derived directly (see get_param_names_by_type) rather than passed in separately.

  • optimal_params (ndarray) – The current optimal parameters (physical units), before this re-optimization.

  • optimal_likelihood (float) – The current optimal likelihood, before this re-optimization.

  • remainder_params (dict) – The remainder (derived) parameters computed from optimal_params, as returned by compute_remainder_params. Used, if the implicit population is changed, to set starting values for the population that was previously implicit and is now explicit.

  • population (Population) – The population object containing the data to fit.

  • likelihood_options (LikelihoodOptions) – Logging verbosity for this run.

Returns:

The driver spec and genetic model, the optimal parameters and likelihood, and reload_context.autosome_proportions/allosome_proportions realigned to the population order of the returned genetic model’s demographic model (see _reorder_ancestry_proportions): switching the implicit population reorders demographic_model.population_indices (the implicit population is always placed last; see ParametrizedDemography(SexBiased).load_from_YAML) – all reflecting the last iteration whose re-optimization improved the likelihood, or the original input if none did (including if no iteration was ever attempted).

Return type:

tuple[InferenceConfig, GeneticModel, np.ndarray, float, np.ndarray, np.ndarray | list]