Skip to content

Commit 9e48358

Browse files
smasongarrisonsmasongarrison
committed
tided up vignette
1 parent 8e55539 commit 9e48358

6 files changed

Lines changed: 157 additions & 79 deletions

File tree

‎R/computeRelatedness.R‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ calculateRelatedness <- function(
7878
#' @param obsR Numeric. Observed correlation between the two groups. Must be between -1 and 1.
7979
#' @param aceA Numeric. Proportion of variance attributable to additive genetic variance. Must be between 0 and 1. Default is 0.9.
8080
#' @param aceC Numeric. Proportion of variance attributable to shared environmental variance. Must be between 0 and 1. Default is 0.
81-
#' @param sharedC Numeric. Proportion of shared environment shared between the two individuals. Must be between 0 and 1. Default is 0.
81+
#' @param sharedC Numeric. Proportion of shared environment shared between the two individuals. Must be between 0 (no shared environment) and 1 (completely shared environment). Default is 0.
8282
#'
8383
#' @return
8484
#' Numeric. The calculated relatedness coefficient (`est_r`).

‎man/inferRelatedness.Rd‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎vignettes/analyticrelatedness.Rmd‎

Lines changed: 37 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -17,40 +17,68 @@ options(rmarkdown.html_vignette.check_title = FALSE)
1717

1818
# Introduction
1919

20-
This vignette demonstrates analytic methods for determining relatedness in a pedigree. The relatedness coefficient is a measure of the genetic overlap between two individuals. In the simplest terms, it quantifies the genetic overlap between two individuals. The relatedness coefficient ranges from 0 to 1, with 1 indicating a perfect genetic match (which occurs when comparing an individual to themselves, their identical twin, or their clone), whereas 0 indicates no genetic overlap. We introduce two functions: `calculateRelatedness` and `inferRelatedness`, which allow users to compute and infer the relatedness coefficient, respectively.
20+
This vignette demonstrates how to quantify relatedness using two functions from the `BGmisc` package:
21+
- `calculateRelatedness` computes the relatedness coefficient based on known genealogical structure, and
22+
- `inferRelatedness` infers the relatedness coefficient from observed phenotypic correlations under a fixed ACE model.
2123

22-
## Loading Required Libraries
2324

24-
```{r setup}
25-
library(BGmisc)
26-
```
25+
The relatedness coefficient \( r \) indexes the proportion of alleles shared identically by descent (IBD) between two individuals. This value ranges from 0 (no shared alleles by descent) to 1 (a perfect genetic match, which occurs when comparing an individual to themselves, their identical twin, or their clone). Values can be interpreted in the context of standard relationships: e.g., full siblings are expected to have \( r = 0.5 \), half siblings \( r = 0.25 \), and first cousins \( r = 0.125 \).
2726

28-
## Calculating Relatedness Coefficient
27+
# Calculating Relatedness Coefficient
2928

30-
The `calculateRelatedness` function offers a method to compute the relatedness coefficient based on shared ancestry, as described by Wright (1922). This function utilizes the formula:
29+
The `calculateRelatedness` function offers a method to compute the relatedness coefficient based on shared ancestry. The function computes \( r \) based on generational distance to one or more shared ancestors, according to Wright's (1922) formulation:
3130

3231
\[
3332
r_{bc} = \sum \left(\frac{1}{2}\right)^{n+n'+1} (1+f_a)
3433
\]
3534

36-
Where \( n \) and \( n' \) represent the number of generations back of common ancestors the pair share.
35+
Here, \( n \) and \( n' \) are the number of generations from each descendant to a common ancestor \( a \), and \( f_a \) is the inbreeding coefficient of \( a \), assumed to be zero unless specified otherwise.
3736

3837

3938
```{r}
39+
library(BGmisc)
4040
# Example usage:
4141
# For full siblings, the relatedness coefficient is expected to be 0.5:
4242
calculateRelatedness(generations = 1, full = TRUE)
4343
# For half siblings, the relatedness coefficient is expected to be 0.25:
4444
calculateRelatedness(generations = 1, full = FALSE)
4545
```
4646

47+
48+
These examples illustrate how relatedness changes based on whether the siblings share both parents (full) or only one (half). When `full = TRUE`, each sibling is one generation from the shared pair of parents, yielding `r=0.5`. When `full = FALSE`, they share only one parent, yielding `r=0.25`.
49+
4750
# Inferring Relatedness Coefficient
4851

49-
The `inferRelatedness` function is designed to infer the relatedness coefficient between two groups based on the observed correlation between their additive genetic variance and shared environmental variance. This function leverages the `ACE` framework.
52+
The `inferRelatedness` function solves for the relatedness coefficient \( r \) implied by an observed phenotypic correlation under a fixed ACE variance decomposition. Specifically, it inverts the equation:
53+
54+
\[
55+
\text{obsR} = r \cdot a^2 + \text{sharedC} \cdot c^2
56+
\]
57+
58+
to obtain:
59+
60+
\[
61+
r = \frac{\text{obsR} - \text{sharedC} \cdot c^2}{a^2}
62+
\]
63+
64+
where:
65+
- `obsR` is the observed phenotypic correlation between two individuals or groups.
66+
- `aceA` and `aceC` represent the proportions of variance due to additive genetic and shared environmental influences, respectively.
67+
- `sharedC` is the shared-environment analog to the relatedness coefficient: it indicates what proportion of the shared environmental variance applies to this pair (e.g., 1 for siblings raised together, 0 for siblings raised apart).
5068

5169
```{r}
5270
# Example usage:
5371
# Infer the relatedness coefficient:
5472
inferRelatedness(obsR = 0.5, aceA = 0.9, aceC = 0, sharedC = 0)
5573
```
5674

75+
76+
In this example, the observed correlation is 0.5, and no shared environmental variance is assumed. Given that additive genetic variance accounts for 90% of trait variance, the inferred relatedness coefficient is approximately 0.556. This reflects the proportion of genetic overlap that would be required to produce the observed similarity under these assumptions.
77+
78+
79+
```{r}
80+
# Now assume shared environment is fully shared:
81+
inferRelatedness(obsR = 0.5, aceA = 0.45, aceC = 0.45, sharedC = 1)
82+
```
83+
84+
In this case, the observed phenotypic correlation is still 0.5, and both additive genetic and shared environmental components are assumed to explain 45% of the variance. Because the shared environment is fully shared between individuals (sharedC = 1), much of the observed similarity is attributed to C, leaving only a small portion attributable to genetic relatedness. The function returns an inferred relatedness coefficient of approximately 0.11 — that is, the amount of additive genetic overlap required (under this model) to produce the remaining unexplained correlation after accounting for shared environmental similarity.

‎vignettes/analyticrelatedness.html‎

Lines changed: 83 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@
6060
}
6161
@media print {
6262
pre > code.sourceCode { white-space: pre-wrap; }
63-
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
63+
pre > code.sourceCode > span { display: inline-block; text-indent: -5em; padding-left: 5em; }
6464
}
6565
pre.numberSource code
6666
{ counter-reset: source-line 0; }
@@ -343,50 +343,96 @@ <h1 class="title toc-ignore">Calculating and Inferring Relatedness
343343

344344
<div id="introduction" class="section level1">
345345
<h1>Introduction</h1>
346-
<p>This vignette demonstrates analytic methods for determining
347-
relatedness in a pedigree. The relatedness coefficient is a measure of
348-
the genetic overlap between two individuals. In the simplest terms, it
349-
quantifies the genetic overlap between two individuals. The relatedness
350-
coefficient ranges from 0 to 1, with 1 indicating a perfect genetic
351-
match (which occurs when comparing an individual to themselves, their
352-
identical twin, or their clone), whereas 0 indicates no genetic overlap.
353-
We introduce two functions: <code>calculateRelatedness</code> and
354-
<code>inferRelatedness</code>, which allow users to compute and infer
355-
the relatedness coefficient, respectively.</p>
356-
<div id="loading-required-libraries" class="section level2">
357-
<h2>Loading Required Libraries</h2>
358-
<div class="sourceCode" id="cb1"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb1-1"><a href="#cb1-1" tabindex="-1"></a><span class="fu">library</span>(BGmisc)</span></code></pre></div>
346+
<p>This vignette demonstrates how to quantify relatedness using two
347+
functions from the <code>BGmisc</code> package: -
348+
<code>calculateRelatedness</code> computes the relatedness coefficient
349+
based on known genealogical structure, and -
350+
<code>inferRelatedness</code> infers the relatedness coefficient from
351+
observed phenotypic correlations under a fixed ACE model.</p>
352+
<p>The relatedness coefficient <span class="math inline">\(r\)</span>
353+
indexes the proportion of alleles shared identically by descent (IBD)
354+
between two individuals. This value ranges from 0 (no shared alleles by
355+
descent) to 1 (a perfect genetic match, which occurs when comparing an
356+
individual to themselves, their identical twin, or their clone). Values
357+
can be interpreted in the context of standard relationships: e.g., full
358+
siblings are expected to have <span class="math inline">\(r =
359+
0.5\)</span>, half siblings <span class="math inline">\(r =
360+
0.25\)</span>, and first cousins <span class="math inline">\(r =
361+
0.125\)</span>.</p>
359362
</div>
360-
<div id="calculating-relatedness-coefficient" class="section level2">
361-
<h2>Calculating Relatedness Coefficient</h2>
363+
<div id="calculating-relatedness-coefficient" class="section level1">
364+
<h1>Calculating Relatedness Coefficient</h1>
362365
<p>The <code>calculateRelatedness</code> function offers a method to
363-
compute the relatedness coefficient based on shared ancestry, as
364-
described by Wright (1922). This function utilizes the formula:</p>
366+
compute the relatedness coefficient based on shared ancestry. The
367+
function computes <span class="math inline">\(r\)</span> based on
368+
generational distance to one or more shared ancestors, according to
369+
Wright’s (1922) formulation:</p>
365370
<p><span class="math display">\[
366371
r_{bc} = \sum \left(\frac{1}{2}\right)^{n+n&#39;+1} (1+f_a)
367372
\]</span></p>
368-
<p>Where <span class="math inline">\(n\)</span> and <span class="math inline">\(n&#39;\)</span> represent the number of
369-
generations back of common ancestors the pair share.</p>
370-
<div class="sourceCode" id="cb2"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb2-1"><a href="#cb2-1" tabindex="-1"></a><span class="co"># Example usage:</span></span>
371-
<span id="cb2-2"><a href="#cb2-2" tabindex="-1"></a><span class="co"># For full siblings, the relatedness coefficient is expected to be 0.5:</span></span>
372-
<span id="cb2-3"><a href="#cb2-3" tabindex="-1"></a><span class="fu">calculateRelatedness</span>(<span class="at">generations =</span> <span class="dv">1</span>, <span class="at">full =</span> <span class="cn">TRUE</span>)</span>
373-
<span id="cb2-4"><a href="#cb2-4" tabindex="-1"></a><span class="co">#&gt; [1] 0.5</span></span></code></pre></div>
374-
<div class="sourceCode" id="cb3"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb3-1"><a href="#cb3-1" tabindex="-1"></a><span class="co"># For half siblings, the relatedness coefficient is expected to be 0.25:</span></span>
375-
<span id="cb3-2"><a href="#cb3-2" tabindex="-1"></a><span class="fu">calculateRelatedness</span>(<span class="at">generations =</span> <span class="dv">1</span>, <span class="at">full =</span> <span class="cn">FALSE</span>)</span>
376-
<span id="cb3-3"><a href="#cb3-3" tabindex="-1"></a><span class="co">#&gt; [1] 0.25</span></span></code></pre></div>
377-
</div>
373+
<p>Here, <span class="math inline">\(n\)</span> and <span class="math inline">\(n&#39;\)</span> are the number of generations from
374+
each descendant to a common ancestor <span class="math inline">\(a\)</span>, and <span class="math inline">\(f_a\)</span> is the inbreeding coefficient of
375+
<span class="math inline">\(a\)</span>, assumed to be zero unless
376+
specified otherwise.</p>
377+
<div class="sourceCode" id="cb1"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb1-1"><a href="#cb1-1" tabindex="-1"></a><span class="fu">library</span>(BGmisc)</span>
378+
<span id="cb1-2"><a href="#cb1-2" tabindex="-1"></a><span class="co"># Example usage:</span></span>
379+
<span id="cb1-3"><a href="#cb1-3" tabindex="-1"></a><span class="co"># For full siblings, the relatedness coefficient is expected to be 0.5:</span></span>
380+
<span id="cb1-4"><a href="#cb1-4" tabindex="-1"></a><span class="fu">calculateRelatedness</span>(<span class="at">generations =</span> <span class="dv">1</span>, <span class="at">full =</span> <span class="cn">TRUE</span>)</span>
381+
<span id="cb1-5"><a href="#cb1-5" tabindex="-1"></a><span class="co">#&gt; [1] 0.5</span></span>
382+
<span id="cb1-6"><a href="#cb1-6" tabindex="-1"></a><span class="co"># For half siblings, the relatedness coefficient is expected to be 0.25:</span></span>
383+
<span id="cb1-7"><a href="#cb1-7" tabindex="-1"></a><span class="fu">calculateRelatedness</span>(<span class="at">generations =</span> <span class="dv">1</span>, <span class="at">full =</span> <span class="cn">FALSE</span>)</span>
384+
<span id="cb1-8"><a href="#cb1-8" tabindex="-1"></a><span class="co">#&gt; [1] 0.25</span></span></code></pre></div>
385+
<p>These examples illustrate how relatedness changes based on whether
386+
the siblings share both parents (full) or only one (half). When
387+
<code>full = TRUE</code>, each sibling is one generation from the shared
388+
pair of parents, yielding <code>r=0.5</code>. When
389+
<code>full = FALSE</code>, they share only one parent, yielding
390+
<code>r=0.25</code>.</p>
378391
</div>
379392
<div id="inferring-relatedness-coefficient" class="section level1">
380393
<h1>Inferring Relatedness Coefficient</h1>
381-
<p>The <code>inferRelatedness</code> function is designed to infer the
382-
relatedness coefficient between two groups based on the observed
383-
correlation between their additive genetic variance and shared
384-
environmental variance. This function leverages the <code>ACE</code>
385-
framework.</p>
386-
<div class="sourceCode" id="cb4"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb4-1"><a href="#cb4-1" tabindex="-1"></a><span class="co"># Example usage:</span></span>
387-
<span id="cb4-2"><a href="#cb4-2" tabindex="-1"></a><span class="co"># Infer the relatedness coefficient:</span></span>
388-
<span id="cb4-3"><a href="#cb4-3" tabindex="-1"></a><span class="fu">inferRelatedness</span>(<span class="at">obsR =</span> <span class="fl">0.5</span>, <span class="at">aceA =</span> <span class="fl">0.9</span>, <span class="at">aceC =</span> <span class="dv">0</span>, <span class="at">sharedC =</span> <span class="dv">0</span>)</span>
389-
<span id="cb4-4"><a href="#cb4-4" tabindex="-1"></a><span class="co">#&gt; [1] 0.5555556</span></span></code></pre></div>
394+
<p>The <code>inferRelatedness</code> function solves for the relatedness
395+
coefficient <span class="math inline">\(r\)</span> implied by an
396+
observed phenotypic correlation under a fixed ACE variance
397+
decomposition. Specifically, it inverts the equation:</p>
398+
<p><span class="math display">\[
399+
\text{obsR} = r \cdot a^2 + \text{sharedC} \cdot c^2
400+
\]</span></p>
401+
<p>to obtain:</p>
402+
<p><span class="math display">\[
403+
r = \frac{\text{obsR} - \text{sharedC} \cdot c^2}{a^2}
404+
\]</span></p>
405+
<p>where: - <code>obsR</code> is the observed phenotypic correlation
406+
between two individuals or groups. - <code>aceA</code> and
407+
<code>aceC</code> represent the proportions of variance due to additive
408+
genetic and shared environmental influences, respectively. -
409+
<code>sharedC</code> is the shared-environment analog to the relatedness
410+
coefficient: it indicates what proportion of the shared environmental
411+
variance applies to this pair (e.g., 1 for siblings raised together, 0
412+
for siblings raised apart).</p>
413+
<div class="sourceCode" id="cb2"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb2-1"><a href="#cb2-1" tabindex="-1"></a><span class="co"># Example usage:</span></span>
414+
<span id="cb2-2"><a href="#cb2-2" tabindex="-1"></a><span class="co"># Infer the relatedness coefficient:</span></span>
415+
<span id="cb2-3"><a href="#cb2-3" tabindex="-1"></a><span class="fu">inferRelatedness</span>(<span class="at">obsR =</span> <span class="fl">0.5</span>, <span class="at">aceA =</span> <span class="fl">0.9</span>, <span class="at">aceC =</span> <span class="dv">0</span>, <span class="at">sharedC =</span> <span class="dv">0</span>)</span>
416+
<span id="cb2-4"><a href="#cb2-4" tabindex="-1"></a><span class="co">#&gt; [1] 0.5555556</span></span></code></pre></div>
417+
<p>In this example, the observed correlation is 0.5, and no shared
418+
environmental variance is assumed. Given that additive genetic variance
419+
accounts for 90% of trait variance, the inferred relatedness coefficient
420+
is approximately 0.556. This reflects the proportion of genetic overlap
421+
that would be required to produce the observed similarity under these
422+
assumptions.</p>
423+
<div class="sourceCode" id="cb3"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb3-1"><a href="#cb3-1" tabindex="-1"></a><span class="co"># Now assume shared environment is fully shared:</span></span>
424+
<span id="cb3-2"><a href="#cb3-2" tabindex="-1"></a><span class="fu">inferRelatedness</span>(<span class="at">obsR =</span> <span class="fl">0.5</span>, <span class="at">aceA =</span> <span class="fl">0.45</span>, <span class="at">aceC =</span> <span class="fl">0.45</span>, <span class="at">sharedC =</span> <span class="dv">1</span>)</span>
425+
<span id="cb3-3"><a href="#cb3-3" tabindex="-1"></a><span class="co">#&gt; [1] 0.1111111</span></span></code></pre></div>
426+
<p>In this case, the observed phenotypic correlation is still 0.5, and
427+
both additive genetic and shared environmental components are assumed to
428+
explain 45% of the variance. Because the shared environment is fully
429+
shared between individuals (sharedC = 1), much of the observed
430+
similarity is attributed to C, leaving only a small portion attributable
431+
to genetic relatedness. The function returns an inferred relatedness
432+
coefficient of approximately 0.11 — that is, the amount of additive
433+
genetic overlap required (under this model) to produce the remaining
434+
unexplained correlation after accounting for shared environmental
435+
similarity.</p>
390436
</div>
391437

392438

‎vignettes/modelingrelatedness.Rmd‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: "Modeling and Relatedness"
2+
title: "Modeling variance components"
33
output: rmarkdown::html_vignette
44
vignette: >
55
%\VignetteIndexEntry{modelingandrelatedness}
@@ -75,6 +75,7 @@ identifyComponentModel(
7575
E = diag(1, 2)
7676
)
7777
```
78+
7879
As you can see, the model is not identified. We need to add an additional group so that we have sufficient information. Let us add the rest of the classical twin model, in this case DZ twins.
7980

8081
```{r}

0 commit comments

Comments
 (0)