tracts.core.optimize_cob_sex_biased_two_steps#

optimize_cob_sex_biased_two_steps(p0, population, genetic_model, likelihood_options=None, p_dict=None, exclude_tracts_below_cM=0, maxiter=None, reset_counter=True, 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.

  • genetic_model (GeneticModel) – Bundles the demographic model (whose parameter_handler handles parameter transformations and fixed parameters, and whose model_func/outofbounds_fun methods compute migration matrices and violation scores) with the admixture and phase-type model configuration (ad_model_autosomes, ad_model_allosomes, rho_f, rho_m, TP, N_cores) used to compute the likelihood. If ad_model_allosomes is 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.

  • likelihood_options (LikelihoodOptions | None) – Logging verbosity (verbose_log, verbose_screen) for this optimization run. Its include_autosomes/include_allosomes flags are ignored here: which data are included is determined per step (autosomes only in step 1; allosomes, and optionally autosomes per autosomes_in_step_2, in step 2). If None, defaults to LikelihoodOptions().

  • 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).

  • 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]