tracts.driver_utils.OptimizationConfig

class OptimizationConfig(**data)

Bases: BaseModel

Configuration for the optimization process used in the inference.

repetitions

The number of repetitions to perform for the optimization. Defaults to 1.

Type:

int

seed

The random seed to use for the optimization.

Type:

int

maximum_iterations

The maximum number of iterations to perform for the optimization. Defaults to None, which means no limit on the number of iterations.

Type:

int | None

npts

The number of grid points to use to define the tract length histogram. Defaults to 50.

Type:

int

exclude_tracts_below_cm

The minimum tract length in centiMorgans to include in the analysis. Tracts shorter than this length will be excluded. Defaults to 1 cM.

Type:

float

fix_parameters_from_ancestry_proportions

A list of parameter names to fix based on the ancestry proportions. See online documentation for details.

Type:

List[str]

fix_parameters_by_value

A dict mapping parameter names to their corresponding user-defined fixed values. These parameters are not optimized nor computed from ancestry proportions.

Type:

dict[str, float]

unknown_labels_for_smoothing

A list of population labels for which to apply smoothing to the tract length distribution. Defaults to an empty list.

Type:

List[str]

two_steps_optimization

Whether to perform a two-step optimization process, where the first step optimizes only the non-sex-bias parameters on autosomal data and the second step optimizes sex-bias parameters using both autosomal and allosomal data. Defaults to True.

Type:

bool

use_autosomes_for_sex_bias

Whether step 2 should include autosomal data in addition to allosomal data. Defaults to False.

Type:

bool

N_cores

The number of CPU cores to use for parallel processing, when the hybrid-pedigree refinements of the DF or DC models are used. Ignored if the hybrid-pedigree refinements are not used. Defaults to 1.

Type:

int

n_reoptimizations

The number of times to repeat: fixing the sex-bias parameters at their most recently optimized values, then re-running the optimization. Defaults to 0 (not run).

Type:

int

reoptimization_likelihood_tolerance

Absolute tolerance used to decide whether a re-optimization repetition (see run_sex_bias_fixing_reoptimizations) has stopped improving the likelihood. Defaults to 1e-3.

Type:

float

rerun_optimization_on_boundaries

Whether to re-run the optimization (see run_boundary_reoptimization) when one or more sex-bias parameters have an optimal value near their +-1 boundary. Defaults to True.

Type:

bool

boundary_tol

The tolerance for determining if a parameter is at its boundary value. Defaults to 0.1.

Type:

float

near_one

The value to which a sex-bias parameter is fixed when it is near its +-1 boundary. This is used to avoid parameters getting stuck at the boundary. When a sex-bias parameter is near its +-1 boundary and gets fixed by value for the boundary re-optimization (see run_boundary_reoptimization), it is fixed at +-near_one rather than at its actual (possibly less extreme, e.g. 1 - boundary_tol) optimal value. Defaults to 0.999.

Type:

float

repetitions_likelihood_tolerance

Absolute tolerance used to decide whether a run (among the repetitions runs from different starting parameters) reached a likelihood value close to the best one. A warning is logged if only one run out of several is found to be within this tolerance of the best. Defaults to 0.5.

Type:

float

bounds_proximity_tol

Relative tolerance, as a fraction of a parameter’s admissible range (upper - lower, see bounds), used at the end of the run to decide whether a final optimal parameter value is close to a bound. Only bounds that the user narrowed below their default, type-determined value (via bounds) are checked, and only on the narrowed side (see check_optimal_params_near_bounds): a parameter sitting at its natural type boundary (e.g. a sex-bias parameter at +-1) is not flagged. Defaults to 0.05 (5% of the admissible range).

Type:

float

N_cores: int

boundary_tol: float

bounds_proximity_tol: float

fix_parameters_by_value: dict[str, float]

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

n_reoptimizations: int

near_one: float

reoptimization_likelihood_tolerance: float

repetitions_likelihood_tolerance: float

rerun_optimization_on_boundaries: bool

use_autosomes_for_sex_bias: bool