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
1 2 3 4 5 6 7 8 9 10 11 12 13 14  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 
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.func 
Function for prior distribution. Should take one
parameter, 
... 
Additional arguments for the 
Details
The normalization of the probability distribution is carried out using a
simple, fixedstep 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 dmkaplan2000@gmail.com
References
Kaplan DM, Cuif M, Fauvelot C, Vigliola L, NguyenHuu 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45  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")
