tracts.core.optimize_cob_sex_biased_two_steps#

optimize_cob_sex_biased_two_steps(p0, population, model_func, parameter_handler, outofbounds_fun=None, verbose_log=0, verbose_screen=10, p_dict=None, exclude_tracts_below_cM=0, maxiter=None, reset_counter=True, ad_model_autosomes='DC', ad_model_allosomes='DC', autosomes_in_step_2=True, steps=None, npts=50, print_step_header=True, return_full_likelihood=False)#

Optimizes the log-likelihood over all parameters defined by the demographic model, for a specified admixture model applied to both autosomes and allosomes. The procedure supports exactly three modes.

  1. Step 1 only: optimize only non-sex-bias parameters using autosomal data.

  2. Step 2 only: fix non-sex-bias parameters at their p0 values and optimize only sex-bias parameters using allosomal data, optionally together with autosomal data if autosomes_in_step_2 is True.

  3. Step 1 + Step 2: first run step 1, then fix non-sex-bias parameters at their step-1 estimates and optimize only sex-bias parameters as in step 2.

No other optimization-step combinations are allowed.

Parameters:

  • p0 (list) – An array of initial parameters to start the optimization.

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

  • model_func (callable) – A function that takes a parameter array and returns a dictionary of migration matrices for each population.

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

  • outofbounds_fun (callable) – A function that takes a parameter array and returns a violation score indicating how much the parameters violate the bounds.

  • cutoff (int, default:0) – The number of bins to drop at the beginning of the array. This could be achieved with masks.

  • verbose_log (int) – If greater than zero, logs optimization status every verbose iterations.

  • verbose_screen (int) – If greater than zero, prints optimization status every verbose iterations.

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

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

  • maxiter (int) – Maximum iterations to run for.

  • reset_counter (bool) – Resets the iteration counter to zero. Set to False to continue iteration count (e.g., if optimization continues from previous point).

  • ad_model_autosomes (str) – 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) – The model to use for allosomal admixture. Must be one of ‘DC’, ‘DF’, ‘H-DC’ or ‘H-DF’. Default is ‘DC’. If None (no allosomal data provided), step 2 cannot be run. If only step 2 is requested (steps=[2]), an error is raised. If both steps are requested (steps=None or steps=[1,2]), step 2 is automatically disabled with a log message.

  • autosomes_in_step_2 (bool) – If True, both autosomal and allosomal data will be used in the second optimization step. If False, only allosomal data will be used. This option is only relevant when step 2 is run. Default is True.

  • steps (list[int | str] | None) – 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).

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

  • print_step_header (bool) – If True, print the admixture-model title and step subtitle at the start of each optimization step. If False, only the iteration table header is printed. For internal use only; set automatically by run_model_multi_init() to suppress repeated headers across multiple runs within the same step. Default is True.

Returns:

By default, returns the optimal parameters found and the optimization likelihood. If return_full_likelihood is True, also returns an additional full-data likelihood. The additional likelihood is only non-None when step 2 is run with allosomal data only (autosomes_in_step_2=False), and corresponds to evaluating the final parameters on autosomal + allosomal data.

Return type:

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