d.rel.conn.dists.func {ConnMatTools}

Functions for estimating the probability distribution for relative connectivity given a pair of distributions for scores for marked and unmarked individuals

Description

These functions return functions that calculate the probability density function (d.rel.conn.dists.func), the probability distribution function (aka the cumulative distribution function; p.rel.conn.dists.func) and the quantile function (q.rel.conn.dists.func) for relative connectivity given a set of observed score values, distributions for unmarked and marked individuals, and an estimate of the fraction of all eggs marked at the source site, p.

Usage

d.rel.conn.dists.func(
  obs,
  d.unmarked,
  d.marked,
  p = 1,
  N = max(100, min(5000, 2 * length(obs))),
  prior.shape1 = 0.5,
  prior.shape2 = prior.shape1,
  prior.func = function(phi) dbeta(phi, prior.shape1, prior.shape2),
  ...
)

p.rel.conn.dists.func(
  obs,
  d.unmarked,
  d.marked,
  p = 1,
  N = max(100, min(5000, 2 * length(obs))),
  prior.shape1 = 0.5,
  prior.shape2 = prior.shape1,
  prior.func = function(phi) dbeta(phi, prior.shape1, prior.shape2),
  ...
)

q.rel.conn.dists.func(
  obs,
  d.unmarked,
  d.marked,
  p = 1,
  N = max(100, min(5000, 2 * length(obs))),
  prior.shape1 = 0.5,
  prior.shape2 = prior.shape1,
  prior.func = function(phi) dbeta(phi, prior.shape1, prior.shape2),
  ...
)

Arguments

obs

Vector of observed score values for potentially marked individuals

d.unmarked

A function representing the PDF of unmarked individuals. Must be normalized so that it integrates to 1 for the function to work properly.

d.marked

A function representing the PDF of marked individuals. Must be normalized so that it integrates to 1 for the function to work properly.

p

Fraction of individuals (i.e., eggs) marked in the source population. Defaults to 1.

N

number of steps between 0 and 1 at which to approximate likelihood function as input to approxfun. Defaults to 2*length(obs) so long as that number is comprised between 100 and 5000.

prior.shape1

First shape parameter for Beta distributed prior. Defaults to 0.5.

prior.shape2

Second shape parameter for Beta distributed prior. Defaults to being the same as prior.shape1.

prior.func

Function for prior distribution. Should take one parameter, phi, and return a probability. Defaults to function(phi) dbeta(phi,prior.shape1,prior.shape2). If this is specified, then inputs prior.shape1 and prior.shape2 are ignored.

...

Additional arguments for the integrate function.

Details

The normalization of the probability distribution is carried out using a simple, fixed-step trapezoidal integration scheme. By default, the number of steps between relative connectivity values of 0 and 1 defaults to 2*length(obs) so long as that number is comprised between 100 and 5000.

Value

A function that takes one argument (the relative connectivity for d.rel.conn.dists.func and p.rel.conn.dists.func; the quantile for q.rel.conn.dists.func) and returns the probability density, cumulative probability or score value, respectively. The returned function accepts both vector and scalar input values.

Functions

• d.rel.conn.dists.func: Returns a function that is PDF for relative connectivity

• p.rel.conn.dists.func: Returns a function that is cumulative probability distribution for relative connectivity

• q.rel.conn.dists.func: Returns a function that is quantile function for relative connectivity

Author(s)

David M. Kaplan [e-mail]

References

Kaplan DM, Cuif M, Fauvelot C, Vigliola L, Nguyen-Huu T, Tiavouane J and Lett C (in press) Uncertainty in empirical estimates of marine larval connectivity. ICES Journal of Marine Science. doi:10.1093/icesjms/fsw182.

See Also

Other connectivity estimation: d.rel.conn.beta.prior(), d.rel.conn.finite.settlement(), d.rel.conn.multinomial.unnorm(), d.rel.conn.multiple(), d.rel.conn.unif.prior(), dual.mark.transmission(), optim.rel.conn.dists(), r.marked.egg.fraction()

Examples

library(ConnMatTools)
data(damselfish.lods)

# Histograms of simulated LODs
l <- seq(-1,30,0.5)
h.in <- hist(damselfish.lods$in.group,breaks=l)
h.out <- hist(damselfish.lods$out.group,breaks=l)

# PDFs for marked and unmarked individuals based on simulations
d.marked <- stepfun.hist(h.in)
d.unmarked <- stepfun.hist(h.out)

# Fraction of adults genotyped at source site
p.adults <- 0.25

# prior.shape1=1 # Uniform prior
prior.shape1=0.5 # Jeffreys prior

# Fraction of eggs from one or more genotyped parents
p <- dual.mark.transmission(p.adults)$p

# PDF for relative connectivity
D <- d.rel.conn.dists.func(damselfish.lods$real.children,
                           d.unmarked,d.marked,p,
                           prior.shape1=prior.shape1)

# Estimate most probable value for relative connectivity
phi.mx <- optim.rel.conn.dists(damselfish.lods$real.children,
                                    d.unmarked,d.marked,p)$phi

# Estimate 95% confidence interval for relative connectivity
Q <- q.rel.conn.dists.func(damselfish.lods$real.children,
                           d.unmarked,d.marked,p,
                           prior.shape1=prior.shape1)

# Plot it up
phi <- seq(0,1,0.001)
plot(phi,D(phi),type="l",
     xlim=c(0,0.1),
     main="PDF for relative connectivity",
     xlab=expression(phi),
     ylab="Probability density")

abline(v=phi.mx,col="green",lty="dashed")
abline(v=Q(c(0.025,0.975)),col="red",lty="dashed")