tracts.driver_utils

Functions

_build_reoptimization_intro_message(...)	Builds the message announcing that n_reoptimizations (greater than 0) triggers an iterating re-optimization starting at the current optimal parameters, where sex-bias parameters are fixed at their optimal values, changing how step 1 is optimized.
_build_step2_skip_message(...)	Builds the message announcing that step 2 has no free sex-bias parameters to optimize, listing which fixing mechanism (ancestry proportions vs. user-provided values) accounts for each fixed sex-bias parameter.
_default_param_bounds(demographic_model, param)	Returns the default (pre-narrowing) admissible bounds for param, i.e. the bounds it would have without any user-specified narrowing from the driver's bounds section.
_get_display_param_indices(...[, steps])	Compute which parameter columns should be shown in starting-parameter tables.
_get_driver_for_reoptimization(driver_spec, ...)	Creates a new driver specification for re-optimization, using the optimal parameters from a previous optimization as the starting parameters for the new optimization.
_get_founder_event_with_remainder(...)	Returns the male-suffixed founder event for population (e.g. "X_male"), or None if there is no such founder event or it has no remainder population (i.e. it is a continuous founder event, or every source population's proportion is explicitly parametrized).
_get_optimization_subtitle(...[, steps])	Build the user-readable optimization subtitle for the active run phase.
_get_params_for_newly_explicit_population(...)	When switching the implicit population, the population that was previously implicit becomes an explicit, directly-optimized parameter in the new demographic model, with no starting value specified in the driver file (it was never optimized before, so the user never had to provide one), taken from the optimal remainder values computed at the end of the previous optimization (see compute_remainder_params).
_normalize_multi_init_result(result)	Normalize outputs from multi-initialization optimization runs.
_plot_migration_matrices(migration_matrix_f, ...)
_print_and_log(*messages)	Prints and logs each message, unconditionally.
_print_optimal_values_and_likelihood(...)	Prints the final optimal parameter values and the corresponding likelihood, along with any derived parameters for the remainder (dependent) ancestry.
_print_param_bounds_table(demographic_model)	Prints and logs a table of each model parameter's effective admissibility bounds (i.e. after any narrowing from the driver file's bounds section via parse_param_bounds has already been applied to demographic_model.model_base_params[...].bounds).
_print_run_intro(parameter_handler, ...[, ...])	Print the optimization subtitle (always) and starting-parameter table (optional) for a run.
_print_step_header_block(parameter_handler)	Print starting-parameter information before optimization runs begin.
_reorder_ancestry_proportions(...)	Permutes observed ancestry proportions computed under old_ancestor_labels so that they line up with new_ancestor_labels instead.
_save_ancestry_proportions_table(...[, ...])	Writes a fixed-width text table of observed and predicted ancestry proportions (for autosomes and, optionally, allosomes) to the output directory.
_select_full_data_likelihood(...[, announce])	When step 2 used allosomal data only (use_autosomes_for_sex_bias is False), selects the full-data (autosomal + allosomal) likelihood computed at the best run's parameters, if one was computed, and returns it in place of optimal_likelihood.
_summarize_step_results(params_found, ...[, ...])	Print per-run optimization results and select the best run.
build_boundary_reoptimization_model(...[, ...])	Builds a genetic model and driver specification identical to the given ones, except with the sex-bias parameters in boundary_fixed_param_values now fixed by value, and (if given) alternate_implicit_population as the implicit population instead of the current one.
check_final_parameters(demographic_model, ...)	Checks that the final optimal parameters are compatible will well-defined migration matrices.
check_optimal_params_near_bounds(...)	Checks whether any of the final optimal parameters is close to a user-narrowed admissible bound (see bounds/parse_param_bounds), which may indicate that the true optimum lies outside the range the user specified.
check_optimal_sex_bias_parameters_at_boundaries(...)	Checks whether the optimal sex-bias parameters have values at the border of the feasible region, up to a pre-specified tolerance.
check_population_labels(demographic_model, ...)	Validates that the population labels in the data correspond to the model population labels.
check_start_params(physical_start_params, ...)	Checks that the number of starting parameters matches the number of model parameters and prints a message about the starting parameters setup.
collapse_identical_start_params(...)	Collapse repeated identical starting-parameter sets to a single repetition.
compute_physical_start_params(driver_spec, ...)	Computes physical starting parameters to optimize from.
compute_remainder_params(demographic_model, ...)	Compute derived parameters for the 'remainder' (dependent) ancestry in each parametrized population.
get_admixture_models(driver_spec)	Validates the admixture models specified in the driver file and returns the models for autosomes and allosomes.
get_alternate_implicit_population(...)	Checks whether any of the boundary-violating sex-bias parameter names in optimal_sex_bias_at_boundaries is a derived remainder parameter (i.e. corresponds to demographic_model's current implicit population, rather than a directly-optimized sex-bias parameter).
get_ancestry_proportions(driver_spec, ...)	Computes and reports the observed ancestry proportions for a population, based on autosomal data and, if allosomes are specified in the driver file, allosomal data as well.
get_param_names_by_type(demographic_model)	Derives a demographic model's free base parameter names, split into sex-bias and non-sex-bias subsets, straight from its model_base_params.
get_predicted_ancestry_proportions(...)	Computes and logs the predicted ancestry proportions for the optimal parameters.
get_starting_ancestry_proportions(...)	Computes and logs the starting ancestry proportions for each set of starting parameters.
get_time_scaled_model_bounds(demographic_model)	Computes a function that takes in optimizer parameters, converts them to physical parameters using the model's parameter handler, and returns the violation score for those parameters.
get_time_scaled_model_func(demographic_model)	Computes a function that takes in optimizer parameters, converts them to physical parameters using the model's parameter handler, and returns the migration matrices for those parameters.
has_free_sex_bias_parameters(...)	Checks whether any sex-bias parameters are free (not fixed by ancestry proportions or value) in the demographic model.
load_demographic_model_from_driver(...[, ...])	Loads the demographic model based on the specifications in the driver file.
load_driver_file(driver_path)	Loads the driver file and validates that it contains all required parameters for the inference.
load_population(driver_path, driver_spec[, ...])	Loads the population data based on the specifications in the driver file.
locate_file_path(filename, script_dir[, ...])	Locates the file path for a given filename by searching in multiple locations.
output_simulation_data_sex_biased(...[, ...])	Creates output graphs to compare data and the theoretical tract length distribution inferred by the model.
parse_chromosomes(chromosome_spec[, chromosomes])	Parses a chromosome specification and returns a list of chromosome numbers.
parse_individual_filenames(individual_names, ...)	Parses the individual filenames based on the provided format and locates their paths.
parse_param_bounds(param_bounds, ...)	Narrows each model parameter's admissible bounds according to the "min:max" intervals given in param_bounds (typically driver_spec.bounds), mutating demographic_model.model_base_params[name].bounds in place.
parse_start_params(start_param_bounds, ...)	Produces starting parameters for optimization in physical units.
plot_admixture(ancestry_per_individual, ...)	Stacked bar chart of ancestry proportions in ADMIXTURE style.
scale_select_indices(arr, indices_to_scale)
setup_fixed_parameters(driver_spec, ...[, ...])	Sets up fixed parameters in the demographic model based on the specifications in the driver file.

Classes

InferenceConfig(**data)	Configuration for the inference process.
ModelReloadContext(script_dir, driver_path, ...)	Bundles the file-location and ancestry-proportion context needed to reload a demographic model from its driver/model YAML files (e.g. when the implicit population changes and the founder-event structure has to be re-parsed), so that functions needing this context take one parameter instead of five.
ModelsConfig(**data)	Configuration for the demographic and admixture models used in the inference.
OptimizationConfig(**data)	Configuration for the optimization process used in the inference.
OutputConfig(**data)	Configuration for the output of the inference process.
ParamBoundsConfig(**data)	Optional lower/upper admissibility bounds for model parameters, specified as "min:max" strings (same syntax as start_params interval bounds, see StartParamsConfig), e.g..
SamplesConfig(**data)	Configuration for the samples used in the inference.
StartParamsConfig(**data)	Configuration for the starting parameters used in the optimization.