tracts.driver_utils

Helper functions and driver-file configuration classes (SamplesConfig, ModelsConfig, OptimizationConfig, OutputConfig, InferenceConfig, etc., all pydantic models) supporting tracts.driver’s run_tracts() pipeline: loading and validating the driver YAML file, loading the population and demographic model it specifies, and producing the output files and plots (output_simulation_data_sex_biased()) once optimization is complete.

Functions

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_population_colors(pop_names)	Assigns a colorblind-friendly color to each population, for use in output plots.
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.
save_ancestry_table(ancestor_labels, ...[, ...])	Writes a fixed-width text table of observed and predicted per-population values (for autosomes and, optionally, allosomes) to the output directory.
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.