tracts.driver.run_model_multi_init#

run_model_multi_init(model_func, bound_func, population, start_params_list, population_dict, parameter_handler, max_iter=None, exclude_tracts_below_cM=0, ad_model_autosomes='DC', ad_model_allosomes='DC', npts=50, verbose_log=0, verbose_screen=0, two_steps_optimization=True, autosomes_in_step_2=True, steps=None, start_params_title=None, print_start_params_table=True, print_subtitle=True)#

Runs the model multiple times with different initial parameters.

Parameters:

  • model_func (Callable) – A function that takes parameters and returns migration matrices.

  • bound_func (Callable) – A function that calculates the violation score for the parameters.

  • population (Population) – The population object containing individual data.

  • start_params_list (list[ndarray]) – A list of initial parameter arrays to start the optimization.

  • population_dict (dict) – A dictionary mapping population labels to their corresponding indices in the model.

  • parameter_handler (FixedParametersHandler) – An object that handles parameter transformations and fixed parameters.

  • max_iter (int) – Maximum number of iterations for the optimization algorithm. Default is None, which means no limit.

  • exclude_tracts_below_cM (int) – Minimum tract length in centimorgans to exclude from analysis. Default is 0.

  • ad_model_autosomes (str, optional) – The model to use for autosomal admixture. Must be one of ‘DC’, ‘DF’, ‘M’, ‘H-DC’ or ‘H-DF’. Default is ‘DC’.

  • ad_model_allosomes (str or None, optional) – The model to use for allosomal admixture. Must be one of ‘DC’, ‘DF’, ‘H-DC’ or ‘H-DF’, or None if allosomal admixture is not to be modeled. Default is ‘DC’.

  • npts (int) – Number of bins for the tract length histogram. Default is 50.

  • verbose_log (int) – Verbosity level for logging. Default is 0 (no verbose output). If greater than 0, iterations are logged every verbose_log steps.

  • verbose_screen (int) – Verbosity level for screen prints. Default is 0 (no verbose output). If greater than 0, iterations are printed every verbose_screen steps.

  • two_steps_optimization (bool) – Whether to use a two-step optimization procedure for sex-biased models. Default is True.

  • autosomes_in_step_2 (bool) – If two_steps_optimization is True, whether both autosomal and allosomal data will be used in the second optimization step. If True, both types of data will be used. If False, only allosomal data will be used in the second step. Default is True.

  • steps (list[int | str] | None) – If two_steps_optimization is True, a list specifying which steps to run. Step 1 (non-sex-bias parameter optimization) can be denoted as 1 or ‘step1’, and step 2 (sex-bias parameter optimization) can be denoted as 2 or ‘step2’. The only allowed combinations are step 1 only, step 2 only, or both steps. Examples of valid values are [1], [‘step1’], [2], [‘step2’], [1, 2], or [‘step1’, ‘step2’]. Mixed types are allowed, but duplicate references to the same step such as [1, ‘step1’] are not. Default is None (both steps will be run).

  • start_params_title (str | None) – For internal use only. An optional title to display above the starting parameters table. If None, a default title will be generated based on the steps being run. Default is None.

  • print_start_params_table (bool) – For internal use only. Whether to print the starting parameters table. Default is True.

  • print_subtitle (bool) – For internal use only. Whether to print a subtitle message describing the optimization run. Default is True.

Returns:

A tuple containing three lists: (i) optimal parameters for each run, (ii) optimization likelihoods for each run, and (iii) optional full-data likelihoods (only populated when step 2 is run with allosomal data only).

Return type:

tuple[list[ndarray], list[float], list[float | None]]