tracts.core

Functions

`optimize`(p0, bins, Ls, data, nsamp, model_func)	Optimizes model parameters using the BFGS method.
`optimize_bfgs`(p0, bins, Ls, data, nsamp, ...)	Optimizes model parameters using the BFGS method.
`optimize_brute_fracs2`(bins, Ls, data, nsamp, ...)	Optimize parameters to fit the model to data using the brute-force method.
`optimize_brute_multifracs`(bins, Ls, ...[, ...])	Optimizes parameters to fit the model to data using the brute-force method.
`optimize_cob`(p0, bins, Ls, data, nsamp, ...)	Optimizes model parameters using the COBYLA method.
`optimize_cob_fracs`(p0, bins, Ls, data, ...)	Optimizes parameters to fit the model to data using the COBYLA method.
`optimize_cob_fracs2`(p0, bins, Ls, data, ...)	Optimize parameters to fit the model to data using the COBYLA method.
`optimize_cob_multifracs`(p0, bins, Ls, ...[, ...])	Optimizes parameters to fit the model to data using the COBYLA method.
`optimize_cob_sex_biased`(p0, population, ...)
`optimize_slsqp`(p0, bins, Ls, data, nsamp, ...)	Optimizes model parameters using the SLSQ method.
`plotmig`(mig[, colordict, order])
`test_model_func`(model_func, parameters[, ...])	Given a demographic model function, run a few debugging tests to ensure that it behaves as expected, namely: (i) that migration matrices sum to less than one (exactly one for the last generation) and (ii) that it behaves continuously relative to time parameters.

tracts.core.optimize(p0, bins, Ls, data, nsamp, model_func, outofbounds_fun=None, cutoff=0, verbose=0, flush_delay=0.5, epsilon=0.001, gtol=1e-05, maxiter=None, full_output=True, func_args=None, fixed_params=None, ll_scale=1)

Optimizes model parameters using the BFGS method. Best suited for cases where initial values are close to the optimum, converging to a single minimum, and for parameters spanning different scales.

Parameters:

p0 – Initial parameters.
data – Spectrum with data.
model_function – Function to evaluate model spectrum. Should take arguments (params, pts).
out_of_bounds_fun (default: None) – A funtion evaluating to True if the current parameters are in a forbidden region.
cutoff (default: 0) – The number of bins to drop at the beginning of the array. This could be achieved with masks.
verbose (default: 0) – If greater than zero, print optimization status every verbose steps.
flush_delay (default: 0.5) – Standard output will be flushed once every flush_delay minutes. This is useful to avoid overloading I/O on clusters.
epsilon (default: 1e-3) – Step-size to use for finite-difference derivatives.
gtol (default: 1e-5) – Convergence criterion for optimization. For more info, see help(scipy.optimize.fmin_bfgs).
maxiter (default: None) – Maximum iterations to run for.
full_output (default: True) – If True, return full outputs as described in help(scipy.optimize.fmin_bfgs).
func_args (default: None) – List of additional arguments to model_func. It is assumed that model_func’s first argument is an array of parameters to optimize.
fixed_params (default: None) – (Not yet implemented). If not None, should be a list used to fix model parameters at particular values. For example, if the model parameters are (nu1,nu2,T,m), then fixed_params = [0.5,None,None,2] will hold nu1=0.5 and m=2. The optimizer will only change T and m. Note that the bounds lists must include all parameters. Optimization will fail if the fixed values lie outside their bounds. A full-length p0 should be passed in; values corresponding to fixed parameters are ignored.
ll_scale (default: 1) – The BFGS algorithm may fail if the initial log-likelihood is too large. Using ll_scale > 1 reduces the log-likelihood magnitude, helping the optimizer reach a reasonable region. Afterward, re-optimize with ll_scale=1.

tracts.core.optimize_bfgs(p0, bins, Ls, data, nsamp, model_func, outofbounds_fun=None, cutoff=0, verbose=0, flush_delay=0.5, epsilon=0.001, gtol=1e-05, maxiter=None, full_output=True, func_args=None, fixed_params=None, ll_scale=1)

Optimizes model parameters using the BFGS method. Best suited for cases where initial values are close to the optimum, converging to a single minimum, and for parameters spanning different scales.

Parameters:

p0 – Initial parameters.
data – Spectrum with data.
model_function – Function to evaluate model spectrum. Should take arguments (params, pts).
out_of_bounds_fun (default: None) – A funtion evaluating to True if the current parameters are in a forbidden region.
cutoff (default: 0) – The number of bins to drop at the beginning of the array. This could be achieved with masks.
verbose (default: 0) – If greater than zero, print optimization status every verbose steps.
flush_delay (default: 0.5) – Standard output will be flushed once every flush_delay minutes. This is useful to avoid overloading I/O on clusters.
epsilon (default: 1e-3) – Step-size to use for finite-difference derivatives.
gtol (default: 1e-5) – Convergence criterion for optimization. For more info, see help(scipy.optimize.fmin_bfgs).
maxiter (default: None) – Maximum iterations to run for.
full_output (default: True) – If True, return full outputs as described in help(scipy.optimize.fmin_bfgs).
func_args (default: None) – List of additional arguments to model_func. It is assumed that model_func’s first argument is an array of parameters to optimize.
fixed_params (default: None) – (Not yet implemented). If not None, should be a list used to fix model parameters at particular values. For example, if the model parameters are (nu1,nu2,T,m), then fixed_params = [0.5,None,None,2] will hold nu1=0.5 and m=2. The optimizer will only change T and m. Note that the bounds lists must include all parameters. Optimization will fail if the fixed values lie outside their bounds. A full-length p0 should be passed in; values corresponding to fixed parameters are ignored.
ll_scale (default: 1) – The BFGS algorithm may fail if the initial log-likelihood is too large. Using ll_scale > 1 reduces the log-likelihood magnitude, helping the optimizer reach a reasonable region. Afterward, re-optimize with ll_scale=1.

tracts.core.optimize_brute_fracs2(bins, Ls, data, nsamp, model_func, fracs, searchvalues, outofbounds_fun=None, cutoff=0, verbose=0, flush_delay=1, full_output=True, func_args=None, fixed_params=None, ll_scale=1)

Optimize parameters to fit the model to data using the brute-force method.

Parameters:

p0 – Initial parameters.
data – Spectrum with data.
model_function – Function to evaluate model spectrum. Should take arguments (params, pts).
out_of_bounds_fun – A function evaluating to True if the current parameters are in a forbidden region.
cutoff – The number of bins to drop at the beginning of the array. This could be achieved with masks.
verbose – If > 0, print optimization status every verbose steps.
flush_delay – Standard output will be flushed once every flush_delay minutes. This is useful to avoid overloading I/O on clusters.
epsilon – Step-size to use for finite-difference derivatives.
gtol – Convergence criterion for optimization. For more info, see help(scipy.optimize.fmin_bfgs).
maxiter – Maximum iterations to run for.
full_output – If True, return full outputs as in described in help(scipy.optimize.fmin_bfgs).
func_args – Additional arguments to model_func. It is assumed that model_func’s first argument is an array of parameters to optimize.
fixed_params – (Not yet implemented) If not None, should be a list used to fix model parameters at particular values. For example, if the model parameters are (nu1,nu2,T,m), then fixed_params = [0.5,None,None,2] will hold nu1=0.5 and m=2. The optimizer will only change T and m. Note that the bounds lists must include all parameters. Optimization will fail if the fixed values lie outside their bounds. A full-length p0 should be passed in; values corresponding to fixed parameters are ignored.
ll_scale – The BFGS algorithm may fail if the initial log-likelihood is too large. Using ll_scale > 1 reduces the log-likelihood magnitude, helping the optimizer reach a reasonable region. Afterward, re-optimize with ll_scale=1.

Notes

This optimization performs well when the starting point is reasonably close to the optimum and is most effective at converging to a single minimum. It also tends to perform better when parameters vary across different scales.

tracts.core.optimize_brute_multifracs(bins, Ls, data_list, nsamp_list, model_func, fracs_list, searchvalues, outofbounds_fun=None, cutoff=0, verbose=0, flush_delay=1, full_output=True, func_args=None, fixed_params=None, ll_scale=1)

Optimizes parameters to fit the model to data using the brute-force method.

Parameters:

p0 – Initial parameters.
data – Spectrum with data.
model_function – Function to evaluate model spectrum. Should take arguments (params, pts).
out_of_bounds_fun – A function evaluating to True if the current parameters are in a forbidden region.
cutoff – The number of bins to drop at the beginning of the array. This could be achieved with masks.
verbose – If > 0, print optimization status every verbose steps.
flush_delay – Standard output will be flushed once every flush_delay minutes. This is useful to avoid overloading I/O on clusters.
epsilon – Step-size to use for finite-difference derivatives.
gtol – Convergence criterion for optimization. For more info, see help(scipy.optimize.fmin_bfgs).
maxiter – Maximum iterations to run for.
full_output – If True, return full outputs as in described in help(scipy.optimize.fmin_bfgs).
func_args – Additional arguments to model_func. It is assumed that model_func’s first argument is an array of parameters to optimize.
fixed_params – (Not yet implemented) If not None, should be a list used to fix model parameters at particular values. For example, if the model parameters are (nu1,nu2,T,m), then fixed_params = [0.5,None,None,2] will hold nu1=0.5 and m=2. The optimizer will only change T and m. Note that the bounds lists must include all parameters. Optimization will fail if the fixed values lie outside their bounds. A full-length p0 should be passed in; values corresponding to fixed parameters are ignored.
ll_scale – The BFGS algorithm may fail if the initial log-likelihood is too large. Using ll_scale > 1 reduces the log-likelihood magnitude, helping the optimizer reach a reasonable region. Afterward, re-optimize with ll_scale=1.

Notes

This optimization performs well when the starting point is reasonably close to the optimum and is most effective at converging to a single minimum. It also tends to perform better when parameters vary across different scales.

tracts.core.optimize_cob(p0, bins, Ls, data, nsamp, model_func, outofbounds_fun=None, cutoff=0, verbose=0, flush_delay=1, epsilon=0.001, gtol=1e-05, maxiter=None, full_output=True, func_args=None, fixed_params=None, ll_scale=1, reset_counter=True, modelling_method=<class 'tracts.demography.demographic_model.DemographicModel'>)

Optimizes model parameters using the COBYLA method. Best suited for cases where initial values are close to the optimum, converging to a single minimum, and for parameters spanning different scales.

Parameters:

p0 – Initial parameters.
data – Spectrum with data.
model_function – Function to evaluate model spectrum. Should take arguments (params, pts).
out_of_bounds_fun (default: None) – A funtion evaluating to True if the current parameters are in a forbidden region.
cutoff (default: 0) – The number of bins to drop at the beginning of the array. This could be achieved with masks.
verbose (default: 0) – If greater than zero, print optimization status every verbose steps.
flush_delay (default: 0.5) – Standard output will be flushed once every flush_delay minutes. This is useful to avoid overloading I/O on clusters.
epsilon (default: 1e-3) – Step-size to use for finite-difference derivatives.
gtol (default: 1e-5) – Convergence criterion for optimization. For more info, see help(scipy.optimize.fmin_bfgs).
maxiter (default: None) – Maximum iterations to run for.
full_output (default: True) – If True, return full outputs as described in help(scipy.optimize.fmin_bfgs).
func_args (default: None) – List of additional arguments to model_func. It is assumed that model_func’s first argument is an array of parameters to optimize.
fixed_params (default: None) – (Not yet implemented). If not None, should be a list used to fix model parameters at particular values. For example, if the model parameters are (nu1,nu2,T,m), then fixed_params = [0.5,None,None,2] will hold nu1=0.5 and m=2. The optimizer will only change T and m. Note that the bounds lists must include all parameters. Optimization will fail if the fixed values lie outside their bounds. A full-length p0 should be passed in; values corresponding to fixed parameters are ignored.
ll_scale (default: 1) – The BFGS algorithm may fail if the initial log-likelihood is too large. Using ll_scale > 1 reduces the log-likelihood magnitude, helping the optimizer reach a reasonable region. Afterward, re-optimize with ll_scale=1.
reset_counter (default: True) – Resets the iteration counter to zero. Set to False to continue iteration count (e.g., if optimization continues from previous point).

Return type:

ndarray

tracts.core.optimize_cob_fracs(p0, bins, Ls, data, nsamp, model_func, fracs, outofbounds_fun=None, cutoff=0, verbose=0, flush_delay=1, epsilon=0.001, gtol=1e-05, maxiter=None, full_output=True, func_args=None, fixed_params=None, ll_scale=1)

Optimizes parameters to fit the model to data using the COBYLA method. This optimization performs well when the starting point is reasonably close to the optimum and is particularly effective at converging to a single minimum. It also tends to perform better when parameters vary across different scales.

Best suited for cases where initial values are close to the optimum, converging to a single minimum, and for parameters spanning different scales.

tracts.core.optimize_cob_fracs2(p0, bins, Ls, data, nsamp, model_func, fracs, outofbounds_fun=None, cutoff=0, verbose=0, flush_delay=1, epsilon=0.001, gtol=1e-05, maxiter=None, full_output=True, func_args=None, fixed_params=None, ll_scale=1, reset_counter=True)

Optimize parameters to fit the model to data using the COBYLA method.

Parameters:

p0 – Initial parameters.
data – Spectrum with data.
model_function – Function to evaluate model spectrum. Should take arguments (params, pts).
out_of_bounds_fun – A function evaluating to True if the current parameters are in a forbidden region.
cutoff – The number of bins to drop at the beginning of the array. This could be achieved with masks.
verbose – If > 0, print optimization status every verbose steps.
flush_delay – Standard output will be flushed once every flush_delay minutes. This is useful to avoid overloading I/O on clusters.
epsilon – Step-size to use for finite-difference derivatives.
gtol – Convergence criterion for optimization. For more info, see help(scipy.optimize.fmin_bfgs).
maxiter – Maximum iterations to run for.
full_output – If True, return full outputs as in described in help(scipy.optimize.fmin_bfgs).
func_args – Additional arguments to model_func. It is assumed that model_func’s first argument is an array of parameters to optimize.
fixed_params – (Not yet implemented) If not None, should be a list used to fix model parameters at particular values. For example, if the model parameters are (nu1,nu2,T,m), then fixed_params = [0.5,None,None,2] will hold nu1=0.5 and m=2. The optimizer will only change T and m. Note that the bounds lists must include all parameters. Optimization will fail if the fixed values lie outside their bounds. A full-length p0 should be passed in; values corresponding to fixed parameters are ignored.
ll_scale – The BFGS algorithm may fail if the initial log-likelihood is too large. Using ll_scale > 1 reduces the log-likelihood magnitude, helping the optimizer reach a reasonable region. Afterward, re-optimize with ll_scale=1.

Notes

This optimization performs well when the starting point is reasonably close to the optimum and is particularly effective at converging to a single minimum. It also tends to perform better when parameters vary across different scales.

tracts.core.optimize_cob_multifracs(p0, bins, Ls, data_list, nsamp_list, model_func, fracs_list, outofbounds_fun=None, cutoff=0, verbose=0, flush_delay=1, epsilon=0.001, gtol=1e-05, maxiter=None, full_output=True, func_args=None, fixed_params=None, ll_scale=1)

Optimizes parameters to fit the model to data using the COBYLA method.

Notes

This optimization performs well when the starting point is reasonably close to the optimum and is particularly effective at converging to a single minimum. It also tends to perform better when parameters vary across different scales.

tracts.core.optimize_cob_sex_biased(p0, population, model_func, outofbounds_fun=None, cutoff=0, verbose=0, flush_delay=1, epsilon=0.001, gtol=1e-05, p_dict=None, exclude_tracts_below_cM=0, maxiter=None, full_output=True, func_args=None, fixed_params=None, ll_scale=1, reset_counter=True, modelling_method=<class 'tracts.phase_type_distribution.PhTDioecious'>, ad_model_autosomes='DC', ad_model_allosomes='DC', npts=50)

Return type:: tuple[ndarray, float]

tracts.core.optimize_slsqp(p0, bins, Ls, data, nsamp, model_func, outofbounds_fun=None, cutoff=0, bounds=None, verbose=0, flush_delay=1, epsilon=0.001, gtol=1e-05, maxiter=None, full_output=True, func_args=None, fixed_params=None, ll_scale=1, reset_counter=True)

Optimizes model parameters using the SLSQ method.

Parameters:

p0 – Initial parameters.
data – Spectrum with data.
model_function – Function to evaluate model spectrum. Should take arguments (params, pts).
out_of_bounds_fun (default: None) – A funtion evaluating to True if the current parameters are in a forbidden region.
cutoff (default: 0) – The number of bins to drop at the beginning of the array. This could be achieved with masks.
verbose (default: 0) – If greater than zero, print optimization status every verbose steps.
flush_delay (default: 0.5) – Standard output will be flushed once every flush_delay minutes. This is useful to avoid overloading I/O on clusters.
epsilon (default: 1e-3) – Step-size to use for finite-difference derivatives.
gtol (default: 1e-5) – Convergence criterion for optimization. For more info, see help(scipy.optimize.fmin_bfgs).
maxiter (default: None) – Maximum iterations to run for.
full_output (default: True) – If True, return full outputs as described in help(scipy.optimize.fmin_bfgs).
func_args (default: None) – List of additional arguments to model_func. It is assumed that model_func’s first argument is an array of parameters to optimize.
fixed_params (default: None) – (Not yet implemented). If not None, should be a list used to fix model parameters at particular values. For example, if the model parameters are (nu1,nu2,T,m), then fixed_params = [0.5,None,None,2] will hold nu1=0.5 and m=2. The optimizer will only change T and m. Note that the bounds lists must include all parameters. Optimization will fail if the fixed values lie outside their bounds. A full-length p0 should be passed in; values corresponding to fixed parameters are ignored.
ll_scale (default: 1) – The BFGS algorithm may fail if the initial log-likelihood is too large. Using ll_scale > 1 reduces the log-likelihood magnitude, helping the optimizer reach a reasonable region. Afterward, re-optimize with ll_scale=1.

Notes

Best suited for cases where initial values are close to the optimum, converging to a single minimum, and for parameters spanning different scales.

tracts.core.plotmig(mig, colordict=None, order=None)

tracts.core.test_model_func(model_func, parameters, fracs_list=None, time_params=True, time_scale=100)

Given a demographic model function, run a few debugging tests to ensure that it behaves as expected, namely: (i) that migration matrices sum to less than one (exactly one for the last generation) and (ii) that it behaves continuously relative to time parameters.

Parameters:

model_func – A migration model. It takes in parameters and outputs a migration matrix.
parameters – Parameters for which the model will be tested.
fracs_list (default: None) – Parameters required by some demographic models corresponding to the observed proportion of ancestry from each source population.
time_params (default: True) – If True, test all parameters for continuity as if they were time parameters. If a list of boolean values of the same length of parameters, only test parameters corresponding to True values.
time_scale (default: 100) – The scaling of the time variables: time (in generations) = time_parameter*time_scale. This is used to test continuity around integer values.

Return type:

Violation score (negative means that a violation has occurred) and the migration matrix value.