disc.RdThis function estimates deme-specific inbreeding coefficients and a global migration rate from genetic and geographic distance data using an isolation-by-distance model. The model assumes that genetic similarity between samples decreases exponentially with geographic distance, modulated by deme-specific inbreeding coefficients.
disc(
discdat,
start_params = NULL,
learningrate = 0.001,
b1 = 0.9,
b2 = 0.999,
e = 1e-08,
steps = 1000,
thin = 1,
report_progress = TRUE,
return_verbose = FALSE,
diagnostics = TRUE
)dataframe; The genetic-geographic data by deme (K). Must contain columns:
smpl1, smpl2, deme1, deme2, gendist, geodist
named double vector; vector of start parameters. Names must match deme names, plus one parameter named "m" for migration rate
double; Learning rate (alpha) for gradient descent optimization. Default: 0.001
double; Exponential decay rate for first moment estimate in Adam optimizer. Default: 0.9
double; Exponential decay rate for second moment estimate in Adam optimizer. Default: 0.999
double; Small constant for numerical stability in Adam optimizer. Default: 1e-8
integer; Number of optimization steps. Default: 1000
integer; Thinning interval for stored iterations (1 = store all). Default: 1
logical; Whether to display progress bar during optimization. Default: TRUE
logical; Whether to return full optimization trajectory (TRUE) or just
logical; Whether to return diagnostics (described below) final results (FALSE). Full trajectory can be memory intensive. Default: FALSE
A list of class "DISCresult" containing:
Final_Fis: Final inbreeding coefficient estimates
Final_m: Final migration rate estimate
deme_key: Mapping of deme names to indices
cost: Final cost function value(s)
If return_verbose = TRUE, additional elements include:
fi_run: F parameter trajectory over iterations
m_run: Migration parameter trajectory
ci_gradtraj: C_i gradient trajectory
b_gradtraj: \(\beta\) gradient trajectory
m_gradtraj: Migration gradient trajectory
ci_1moment, ci_2moment: C_i parameter Adam moments
b_1moment, b_2moment: \(\beta\) parameter Adam moments
m_1moment, m_2moment: Migration parameter Adam moments
If diagnostics = TRUE, additional diagnostics elements are provided from calculate_hessian_eigen, which include:
Hessian: Hessian matrix
Eigen: Eigenvalues and eigenvectors from the Hessian
KappaH: Conditional number from Hessian matrix
The input dataframe must have exactly these column names in order:
smpl1, smpl2: Sample identifiers
deme1, deme2: Deme (location) identifiers
gendist: Pairwise genetic distance (0,1)
geodist: Pairwise geographic distance
The start_params vector must contain:
One parameter per unique deme (named with deme identifiers)
One parameter named "m" for the migration rate
All F parameters must be in (0,1) (inbreeding coefficients)
The model assumes: \(E[r_{ij}] = \frac{F_i + F_j}{2} \exp(-d_{ij}/m)\) where \(r_{ij}\) is genetic relatedness, \(F_i\) is deme i's inbreeding coefficient, \(d_{ij}\) is geographic distance, and \(m\) is the migration rate parameter.