Package 'discent'

Identify Deme Inbreeding Spatial Coefficients in Continuous Space (Vanilla)

Description

The purpose of this statistic is to identify an inbreeding coefficient, or degree of relatedness, for a given location in discrete space. We assume that locations in spaces can be represented as "demes," such that multiple individuals live in the same deme (i.e. samples are sourced from the same location). The expected pairwise relationship between two individuals, or samples, is dependent on the each sample's deme's inbreeding coefficient and the geographic distance between the demes. The program assumes a symmetric distance matrix.

Usage

deme_inbreeding_spcoef_vanilla(
  discdat,
  start_params = NULL,
  lambda = 0.1,
  learningrate = 0.001,
  m_lowerbound = 0,
  m_upperbound = Inf,
  b1 = 0.9,
  b2 = 0.999,
  e = 1e-08,
  steps = 1000,
  thin = 1,
  normalize_geodist = TRUE,
  report_progress = TRUE,
  return_verbose = FALSE
)

Arguments

discdat	dataframe; The genetic-geographic data by deme (K)
start_params	named double vector; vector of start parameters.
lambda	double; A quadratic L2 explicit regularization, or penalty, parameter on "m" parameter. Note, lambda is a scalar such that: $\lambda m^2$.
learningrate	double; alpha parameter for how much each "step" is weighted in the gradient descent
m_lowerbound	double; lower limit value for the global "m" parameter; any "m" value encounter less than the lower bound will be replaced by the lower bound
m_upperbound	double; upper limit value for the global "m" parameter; any "m" value encounter greater than the upper bound will be replaced by the upper bound
b1	double; exponential decay rates for the first moment estimate in the Adam optimization algorithm
b2	double; exponential decay rates for the second moment estimate in the Adam optimization algorithm
e	double; epsilon (error) for stability in the Adam optimization algorithm
steps	integer; the number of steps as we move down the gradient
thin	integer; the number of steps to keep as part of the output (i.e. if the user specifies 10, every 10th iteration will be kept)
normalize_geodist	boolean; whether geographic distances between demes should be normalized (i.e. Min-Max Feature Scaling: $X' = \frac{X - X_{min}}{X_{max} - X_{min}}$, which places the geodistances on the scale to $[0-1]$). Helps increase model stability at the expense of complicating the interpretation of the migration rate parameter.
report_progress	boolean; whether or not a progress bar should be shown as you iterate through steps
return_verbose	boolean; whether the inbreeding coefficients and migration rate should be returned for every iteration or only for the final iteration. User will typically not want to store every iteration, which can be memory intensive

Details

The gen.geo.dist dataframe must be named with the following columns: "smpl1"; "smpl2"; "deme1"; "deme2"; "gendist"; "geodist"; which corresponds to: Sample 1 Name; Sample 2 Name; Sample 1 Location; Sample 2 Location; Pairwise Genetic Distance; Pairwise Geographpic Distance. Note, the order of the columns do not matter but the names of the columns must match.

The start_params vector names must match the cluster names (i.e. clusters must be have a name that we can match on for the starting relatedness paramerts). In addition, you must provide a start parameter for "m".

Note: We have implemented coding decisions to not allow the "f" inbreeding coefficients to be negative by using a logit transformation internally in the code.

Gradient descent is performed using the Adam (adaptive moment estimation) optimization approach. Default values for moment decay rates, epsilon, and learning rates are taken from DP Kingma, 2014.

The "vanilla" method does not attempt to optimize start parameters.

---

Simulated Identity by Descent from Isolation by Distance

Description

Simulated Identity by Descent from Isolation by Distance

Usage

IBD_simulation_data

Format

A dataframe with 45 rows and 6 columns:

smpl1, smpl2

Placeholder sample names

deme1, deme2

Placeholder discrete demes

gendist

Simulated genetic distances based on identity by descent

geodist

Simulated geographic distances

Source

A toy dataset generated by basic simulation assuming an exponential relationship between relatedness and geographic distance. Data is not representative or generalizable but is simply meant to be used as input for various tests and function explanations

---

Check if DISCresult S3 Class

Description

Overload is: function for determining if object is of class DISCresult

Usage

is.vanillaDISCresult(x)

Arguments

x	DISC result from deme_inbreeding_spcoef function

---

print DISCresult S3 Class

Description

overload print() function to print summary only

Usage

## S3 method for class 'vanillaDISCresult'
print(x, ...)

Arguments

x	DISC result from deme_inbreeding_spcoef function
...	further arguments passed to or from other methods.

---

Summary of DISCresult S3 Class

Description

overload summary() function.

Usage

## S3 method for class 'vanillaDISCresult'
summary(object, ...)

Arguments

object	DISCresult Simulation
...	further arguments passed to or from other methods.

---

Tidy Out Sim Method

Description

Method assignment

Usage

tidyout(x)

Arguments

x	DISC result from deme_inbreeding_spcoef function

---

Tidy Out Sim

Description

Function for taking output of SIR NE and lifting it over

Usage

## S3 method for class 'vanillaDISCresult'
tidyout(x)

Arguments

x	DISC result from deme_inbreeding_spcoef function

---