tracts.driver_utils.compute_remainder_params

compute_remainder_params(demographic_model, migration_matrices)

Compute derived parameters for the ‘remainder’ (dependent) ancestry in each parametrized population.

For a demographic model with n free rate parameters R_1, ..., R_{n-1} and a remainder ancestry whose rate is 1 - R_1 - ... - R_{n-1}, the remainder rate is read directly from the founding row of the migration matrix. For ParametrizedDemographySexBiased models, the sex bias of the remainder ancestry is additionally derived from the constraint that male and female founding rates must each sum to 1:

\[ \begin{align}\begin{aligned}\begin{split}r_k^{\\text{male/female}} = 1 - \\sum_{i \\neq k} r_i^{\\text{male/female}}\end{split}\\\begin{split}s_k = \\frac{r_k^{\\text{female}} - r_k^{\\text{male}}} {2\\,\\min(r_k,\\,1-r_k)}\end{split}\end{aligned}\end{align} \]

Parameters:

• demographic_model (ParametrizedDemography | ParametrizedDemographySexBiased) – The demographic model. Only these two types are accepted; any other type raises a TypeError.

• migration_matrices (dict) – Migration matrices as returned by demographic_model.get_migration_matrices(). For ParametrizedDemographySexBiased models the keys are '{population}_male' / '{population}_female'; for ParametrizedDemography models the key is the population name directly.

Returns:

For each parametrized population that has a remainder ancestry:

• '{dest_pop}_{remainder_pop}_rate' — always present; the mean founding rate (average of male and female for sex-biased models, direct value otherwise).

• '{dest_pop}_{remainder_pop}_sex_bias' — only present for ParametrizedDemographySexBiased models; nan when the remainder rate is 0 or 1.

Returns an empty dict when the model has no remainder population or when demographic_model is not a recognised demography type (e.g. a test stub).

Return type:

dict