PedNet 2.0.0__py3-none-any.whl

pednet/inheritance.py

@@ -0,0 +1,262 @@
+"""The mode of inheritance that best explains a family's phenotypes.
+
+For each mode (autosomal dominant or recessive, X-linked recessive or dominant), PedNet works out the probability of
+everyone's phenotype given that the proband has the disease genotype for that mode, summing over every genotype the
+rest of the family could have. Conditioning on the proband takes account of how the family came to be seen, and
+makes the answer depend little on how common the disease allele is. The penetrance isn't known, so the probability
+is averaged over a range of penetrances, and if no proband is given it is averaged over each affected person as the
+proband. With the modes' prior probabilities, Bayes' theorem then gives each mode's posterior probability.
+"""
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Sequence
+
+import numpy as np
+
+from .engine import Network
+from .models import MODE_NAMES, MODES, X_LINKED, Model, founder_prior, phenotype_factor
+from .pedigree import Pedigree
+
+# The penetrances averaged over, equally weighted, when it isn't known
+DEFAULT_PENETRANCE = (0.6, 0.8, 0.95, 0.99)
+DEFAULT_PHENOCOPY = 0.001
+LN10 = np.log(10)
+
+
+def _logsumexp(x, axis=None):
+    x = np.asarray(x, dtype=float)
+    peak = np.max(x, axis=axis, keepdims=True)
+    peak = np.where(np.isfinite(peak), peak, 0.0)
+    with np.errstate(divide='ignore'):
+        out = np.log(np.sum(np.exp(x - peak), axis=axis, keepdims=True)) + peak
+    return np.squeeze(out, axis=axis) if axis is not None else float(out.reshape(()))
+
+
+def _weights(penetrance, weights) -> np.ndarray:
+    if np.isscalar(penetrance):
+        penetrance = (float(penetrance),)
+    w = np.ones(len(penetrance)) if weights is None else np.asarray(weights, dtype=float)
+    if len(w) != len(penetrance) or np.any(w < 0) or w.sum() == 0:
+        raise ValueError('penetrance_weights must be one non-negative weight for each penetrance')
+    return w / w.sum()
+
+
+def _prior(modes, prior) -> Dict[str, float]:
+    if prior is None:
+        return {m: 1 / len(modes) for m in modes}
+    total = sum(prior.get(m, 0) for m in modes)
+    if total <= 0:
+        raise ValueError('The prior must give some probability to one of the modes')
+    return {m: prior.get(m, 0) / total for m in modes}
+
+
+def _modes(modes) -> List[str]:
+    if isinstance(modes, str):
+        modes = [m.strip() for m in modes.replace(',', ' ').split()]
+    modes = [m.upper() for m in modes]
+    for m in modes:
+        if m not in MODES:
+            raise ValueError(f'Unknown mode of inheritance {m!r}: use one of {", ".join(MODES)}')
+    return modes
+
+
+@dataclass
+class ModeEvidence:
+    mode: str
+    posterior: float
+    log10_likelihood: float
+
+    @property
+    def name(self) -> str:
+        return MODE_NAMES[self.mode]
+
+
+@dataclass
+class InheritanceResult:
+    """
+    The modes, most probable first. call is the most probable mode if its posterior probability reaches threshold,
+    and 'uncertain' otherwise. log10_likelihood is the log10 probability of the phenotypes under each mode (given
+    the proband), whose differences are log10 likelihood ratios.
+    """
+    family: str
+    modes: List[ModeEvidence]
+    call: str
+    threshold: float
+    probands: List[str]
+    notes: List[str] = field(default_factory=list)
+
+    def posterior(self, mode: str) -> float:
+        return next((m.posterior for m in self.modes if m.mode == mode), 0.0)
+
+    @property
+    def dominant(self) -> float:
+        """The probability that the condition is dominant (AD or XLD), among the modes weighed up"""
+        return self.posterior('AD') + self.posterior('XLD')
+
+    @property
+    def recessive(self) -> float:
+        """The probability that it is recessive (AR or XLR)"""
+        return self.posterior('AR') + self.posterior('XLR')
+
+    @property
+    def x_linked(self) -> float:
+        """The probability that it is X-linked (XLR or XLD)"""
+        return self.posterior('XLR') + self.posterior('XLD')
+
+    def table(self) -> List[dict]:
+        return [{'family': self.family, 'mode': m.mode, 'posterior': m.posterior, 'log10_likelihood': m.log10_likelihood}
+                for m in self.modes]
+
+    def __str__(self):
+        lines = [f'Family {self.family}: {self.call if self.call == "uncertain" else MODE_NAMES[self.call]}']
+        for m in self.modes:
+            lines.append(f'  {m.mode:4s} {m.posterior:6.3f}   ({m.name})')
+        names = {m.mode for m in self.modes}
+        if names & {'AD', 'XLD'} and names & {'AR', 'XLR'}:
+            lines.append(f'  dominant {self.dominant:.3f}, recessive {self.recessive:.3f}')
+        if names & {'XLR', 'XLD'} and names & {'AD', 'AR'}:
+            lines.append(f'  X-linked {self.x_linked:.3f}, autosomal {1 - self.x_linked:.3f}')
+        lines.extend(f'  note: {n}' for n in self.notes)
+        return '\n'.join(lines)
+
+
+def mode_log_likelihoods(pedigree: Pedigree, modes: Sequence[str] = MODES,
+                         penetrance=DEFAULT_PENETRANCE, penetrance_weights=None,
+                         phenocopy: float = DEFAULT_PHENOCOPY, allele_frequency: Optional[Dict[str, float]] = None,
+                         carrier_penetrance: Optional[float] = None, probands: Optional[Sequence[str]] = None,
+                         networks: Optional[Dict[bool, Network]] = None) -> Dict[str, float]:
+    """
+    The natural log of P(phenotypes | proband has the disease genotype, mode) for each mode, averaged over the
+    penetrances (with penetrance_weights) and over the probands (by default everyone affected).
+    """
+    modes = _modes(modes)
+    pens = (float(penetrance),) if np.isscalar(penetrance) else tuple(float(f) for f in penetrance)
+    with np.errstate(divide='ignore'):
+        log_w = np.log(_weights(pens, penetrance_weights))
+    probands = list(probands) if probands else pedigree.affected()
+    if not probands:
+        return {m: 0.0 for m in modes}
+    networks = {} if networks is None else networks
+    allele_frequency = allele_frequency or {}
+    result = {}
+    for mode in modes:
+        x = X_LINKED[mode]
+        if x not in networks:
+            networks[x] = Network(pedigree, x)
+        net = networks[x]
+        model = Model(mode, allele_frequency.get(mode), pens[0], phenocopy, carrier_penetrance)
+        F, A = len(pens), len(probands)
+        positions = [net.index(p) for p in probands]
+        with_phenotypes, without = [], []
+        for i, (kind, person) in enumerate(zip(net.kinds, pedigree.people)):
+            base = founder_prior(kind, model.allele_frequency) if net.parents[i] is None else np.ones(len(model.causal(kind)))
+            u = np.tile(base, (F * A, 1))
+            for fi, f in enumerate(pens):
+                u[fi * A:(fi + 1) * A] *= phenotype_factor(model.with_(penetrance=f), kind, person.phenotype)
+            u0 = np.tile(base, (A, 1))
+            for ai, pos in enumerate(positions):
+                if pos == i:
+                    u[ai::A] *= model.causal(kind)
+                    u0[ai] *= model.causal(kind)
+            with_phenotypes.append(u)
+            without.append(u0)
+        joint = net.log_likelihood(with_phenotypes).reshape(F, A)
+        proband_causal = net.log_likelihood(without)
+        with np.errstate(invalid='ignore'):
+            conditional = np.where(np.isfinite(proband_causal)[None, :], joint - proband_causal[None, :], -np.inf)
+        result[mode] = _logsumexp(conditional + log_w[:, None] - np.log(A))
+    return result
+
+
+def infer_mode(pedigree: Pedigree, modes: Sequence[str] = MODES, penetrance=DEFAULT_PENETRANCE,
+               penetrance_weights=None, phenocopy: float = DEFAULT_PHENOCOPY,
+               allele_frequency: Optional[Dict[str, float]] = None, carrier_penetrance: Optional[float] = None,
+               prior: Optional[Dict[str, float]] = None, proband: Optional[str] = None,
+               threshold: float = 0.8) -> InheritanceResult:
+    """
+    The posterior probability of each mode of inheritance for a pedigree.
+
+    pedigree: a Pedigree (see read_ped)
+    modes: the modes to weigh up, from 'AD', 'AR', 'XLR' and 'XLD'
+    penetrance: the penetrance, or several to average over (by default 0.6, 0.8, 0.95 and 0.99, equally weighted)
+    penetrance_weights: the weight of each penetrance, if not equal
+    phenocopy: the chance that someone without the disease genotype is affected
+    allele_frequency: the disease allele frequency for each mode, if not the defaults
+    carrier_penetrance: for X-linked recessive, the chance that a woman with one copy is affected
+    prior: the prior probability of each mode (equal by default)
+    proband: the person through whom the family was found; by default each affected person in turn
+    threshold: the posterior probability the most probable mode needs for the call not to be 'uncertain'
+    """
+    modes = _modes(modes)
+    priors = _prior(modes, prior)
+    notes = list(pedigree.notes)
+    affected = pedigree.affected()
+    if proband is not None:
+        if proband not in pedigree:
+            raise ValueError(f'{proband} is not in family {pedigree.family}')
+        if not pedigree[proband].affected:
+            notes.append(f'the proband, {proband}, is not recorded as affected')
+        probands = [proband]
+    else:
+        probands = affected
+    if not affected:
+        notes.append('no one is affected, so the phenotypes say nothing about the mode of inheritance')
+    elif len(affected) == 1:
+        notes.append('only one person is affected: a new dominant mutation, which PedNet doesn\'t model, would '
+                     'explain that as well as a recessive condition does')
+    x_needed = any(X_LINKED[m] for m in modes)
+    unknown_sex = [p.id for p in pedigree.people if p.sex == 0 and not p.placeholder]
+    if x_needed and unknown_sex:
+        notes.append(f'the sex of {", ".join(unknown_sex[:5])}{" and others" if len(unknown_sex) > 5 else ""} '
+                     'is unknown, and is taken as equally likely to be either for the X-linked modes')
+    if probands:
+        logs = mode_log_likelihoods(pedigree, modes, penetrance, penetrance_weights, phenocopy, allele_frequency,
+                                    carrier_penetrance, probands)
+    else:
+        logs = {m: 0.0 for m in modes}
+    log_post = np.array([np.log(priors[m]) + logs[m] if priors[m] > 0 else -np.inf for m in modes])
+    total = _logsumexp(log_post)
+    possible = bool(np.isfinite(total))
+    post = np.exp(log_post - total) if possible else np.array([priors[m] for m in modes])
+    if probands and not possible:
+        notes.append('none of the modes allowed can give these phenotypes with this penetrance and phenocopy rate, '
+                     'so the probabilities shown are the priors')
+    evidence = [ModeEvidence(m, float(post[k]), float(logs[m] / LN10)) for k, m in enumerate(modes)]
+    evidence.sort(key=lambda e: -e.posterior)
+    call = evidence[0].mode if probands and possible and evidence[0].posterior >= threshold else 'uncertain'
+    return InheritanceResult(pedigree.family, evidence, call, threshold, probands, notes)
+
+
+def infer_shared_mode(pedigrees, modes: Sequence[str] = MODES, penetrance=DEFAULT_PENETRANCE,
+                      penetrance_weights=None, phenocopy: float = DEFAULT_PHENOCOPY,
+                      allele_frequency: Optional[Dict[str, float]] = None, carrier_penetrance: Optional[float] = None,
+                      prior: Optional[Dict[str, float]] = None, threshold: float = 0.8) -> InheritanceResult:
+    """
+    The posterior probability of each mode of inheritance for a condition that several families share, from the
+    product of the families' likelihoods (they are taken to be unrelated, with the same mode of inheritance, though
+    not necessarily the same gene). pedigrees is a dict of family to Pedigree, as read_ped gives, or a list of
+    pedigrees; the other arguments are as for infer_mode.
+    """
+    if isinstance(pedigrees, dict):
+        pedigrees = list(pedigrees.values())
+    modes = _modes(modes)
+    priors = _prior(modes, prior)
+    totals = {m: 0.0 for m in modes}
+    notes, probands = [], []
+    for pedigree in pedigrees:
+        result = infer_mode(pedigree, modes, penetrance, penetrance_weights, phenocopy, allele_frequency,
+                            carrier_penetrance, None, None, threshold)
+        for m in result.modes:
+            totals[m.mode] += m.log10_likelihood * LN10
+        notes.extend(f'family {pedigree.family}: {n}' for n in result.notes)
+        probands.extend(result.probands)
+    log_post = np.array([np.log(priors[m]) + totals[m] if priors[m] > 0 else -np.inf for m in modes])
+    total = _logsumexp(log_post)
+    possible = bool(np.isfinite(total))
+    post = np.exp(log_post - total) if possible else np.array([priors[m] for m in modes])
+    if probands and not possible:
+        notes.append('none of the modes allowed can give these phenotypes with this penetrance and phenocopy rate, '
+                     'so the probabilities shown are the priors')
+    evidence = [ModeEvidence(m, float(post[k]), float(totals[m] / LN10)) for k, m in enumerate(modes)]
+    evidence.sort(key=lambda e: -e.posterior)
+    call = evidence[0].mode if probands and possible and evidence[0].posterior >= threshold else 'uncertain'
+    return InheritanceResult(', '.join(p.family for p in pedigrees), evidence, call, threshold, probands, notes)

pednet/models.py

@@ -0,0 +1,209 @@
+"""Modes of inheritance, and the genotype probabilities they give.
+
+Each person's genotype at the locus is a variable with a few states. For an autosomal locus these are the number of
+copies of the alternate (disease) allele, 0, 1 or 2 (kind "A"). On the X chromosome a man has one copy, 0 or 1
+(kind "M"), and a woman two (kind "F"). Someone of unknown sex who has no children has the man's two states and the
+woman's three, each equally likely beforehand (kind "U"); a parent's sex is always known from their role.
+"""
+from dataclasses import dataclass, replace
+from functools import lru_cache
+from typing import Dict, Optional
+
+import numpy as np
+
+MODES = ('AD', 'AR', 'XLR', 'XLD')
+MODE_NAMES = {'AD': 'autosomal dominant', 'AR': 'autosomal recessive',
+              'XLR': 'X-linked recessive', 'XLD': 'X-linked dominant'}
+X_LINKED = {'AD': False, 'AR': False, 'XLR': True, 'XLD': True}
+
+# the number of copies of the alternate allele in each state, and whether the state is a man's
+ALT_COPIES = {'A': (0, 1, 2), 'M': (0, 1), 'F': (0, 1, 2), 'U': (0, 1, 0, 1, 2)}
+IS_MALE = {'A': (None, None, None), 'M': (True, True), 'F': (False, False, False),
+           'U': (True, True, False, False, False)}
+
+# Default disease allele frequencies. The mode of inheritance is judged given that the proband carries the disease
+# genotype, which makes the results depend little on these, as long as the allele is rare.
+DEFAULT_FREQUENCY = {'AD': 1e-4, 'AR': 1e-3, 'XLR': 5e-4, 'XLD': 1e-4}
+
+
+def domain(kind: str) -> int:
+    return len(ALT_COPIES[kind])
+
+
+@dataclass(frozen=True)
+class Model:
+    """
+    A mode of inheritance with its parameters:
+
+    mode: 'AD', 'AR', 'XLR' or 'XLD'
+    allele_frequency: the disease allele's frequency in the population
+    penetrance: the chance that someone with the disease genotype is affected
+    phenocopy: the chance that someone without it is affected all the same
+    carrier_penetrance: for XLR only, the chance that a woman with one copy is affected (by default the phenocopy rate)
+    """
+    mode: str
+    allele_frequency: Optional[float] = None
+    penetrance: float = 0.95
+    phenocopy: float = 0.001
+    carrier_penetrance: Optional[float] = None
+
+    def __post_init__(self):
+        if self.mode not in MODES:
+            raise ValueError(f'Unknown mode of inheritance {self.mode!r}: use one of {", ".join(MODES)}')
+        if self.allele_frequency is None:
+            object.__setattr__(self, 'allele_frequency', DEFAULT_FREQUENCY[self.mode])
+        for name in ('allele_frequency', 'penetrance', 'phenocopy'):
+            value = getattr(self, name)
+            if not 0 <= value <= 1:
+                raise ValueError(f'{name} must be between 0 and 1, not {value}')
+
+    def with_(self, **changes) -> 'Model':
+        return replace(self, **changes)
+
+    @property
+    def x_linked(self) -> bool:
+        return X_LINKED[self.mode]
+
+    def kinds(self):
+        return ('M', 'F', 'U') if self.x_linked else ('A',)
+
+    def affected_probability(self, kind: str) -> np.ndarray:
+        """P(affected) for each state of a genotype of this kind"""
+        f, p = self.penetrance, self.phenocopy
+        h = p if self.carrier_penetrance is None else self.carrier_penetrance
+        if self.mode == 'AD':
+            return np.array([p, f, f])
+        if self.mode == 'AR':
+            return np.array([p, p, f])
+        male = np.array([p, f])
+        female = np.array([p, h, f]) if self.mode == 'XLR' else np.array([p, f, f])
+        return {'M': male, 'F': female, 'U': np.concatenate([male, female])}[kind]
+
+    def causal(self, kind: str) -> np.ndarray:
+        """Which states of a genotype of this kind are the disease genotype (as 1.0 or 0.0)"""
+        if self.mode == 'AD':
+            return np.array([0., 1., 1.])
+        if self.mode == 'AR':
+            return np.array([0., 0., 1.])
+        male = np.array([0., 1.])
+        female = np.array([0., 0., 1.]) if self.mode == 'XLR' else np.array([0., 1., 1.])
+        return {'M': male, 'F': female, 'U': np.concatenate([male, female])}[kind]
+
+
+def founder_prior(kind: str, q) -> np.ndarray:
+    """
+    The genotype probabilities of someone with no parents in the pedigree, in Hardy-Weinberg proportions.
+    q may be a single allele frequency or an array of them (one per batch), giving shape (batch, states).
+    """
+    q = np.asarray(q, dtype=float)
+    p = 1 - q
+    diploid = np.stack([p * p, 2 * p * q, q * q], axis=-1)
+    haploid = np.stack([p, q], axis=-1)
+    if kind in ('A', 'F'):
+        return diploid
+    if kind == 'M':
+        return haploid
+    return np.concatenate([0.5 * haploid, 0.5 * diploid], axis=-1)
+
+
+def phenotype_factor(model: Model, kind: str, phenotype: int) -> np.ndarray:
+    """P(the person's phenotype) for each state: 2 affected, 1 unaffected, anything else unknown"""
+    affected = model.affected_probability(kind)
+    if phenotype == 2:
+        return affected
+    if phenotype == 1:
+        return 1 - affected
+    return np.ones(domain(kind))
+
+
+def genotype_factor(kind: str, alt_copies: Optional[int], error_rate: float = 1e-4) -> np.ndarray:
+    """
+    P(the observed genotype) for each state, allowing for genotyping errors. alt_copies is the number of copies of the
+    alternate allele called (0, 1 or 2), or None if the person wasn't genotyped.
+
+    A call one copy out (a heterozygote called homozygous, or the other way) happens with probability error_rate,
+    and one two copies out (a homozygote called the other homozygote) with probability error_rate squared, so that a
+    rare variant called homozygous in two affected siblings isn't put down to two errors. A man's X-chromosome call
+    counts as the alternate allele if it has any copy of it; calling his allele when he doesn't have it is a single
+    error, and missing it when he does is a double one, since he has nothing else at that position.
+    """
+    states = ALT_COPIES[kind]
+    if alt_copies is None:
+        return np.ones(len(states))
+    return np.array([call_probability(copies, male, alt_copies, error_rate)
+                     for copies, male in zip(states, IS_MALE[kind])])
+
+
+@lru_cache(maxsize=None)
+def genotype_table(kind: str, error_rate: float) -> np.ndarray:
+    """
+    genotype_factor for every call, as rows: not genotyped, then 0, 1 and 2 copies called, to be indexed by
+    call_codes. The table is shared, so it is read-only.
+    """
+    table = np.stack([genotype_factor(kind, called, error_rate) for called in (None, 0, 1, 2)])
+    table.flags.writeable = False
+    return table
+
+
+def call_codes(variants, person_id: str) -> np.ndarray:
+    """Each variant's genotype call in one person as a row of genotype_table: 0 if not genotyped, else copies + 1"""
+    return np.array([0 if g is None else min(int(g), 2) + 1
+                     for g in (v.genotypes.get(person_id) for v in variants)], dtype=np.intp)
+
+
+def call_probability(copies: int, male: Optional[bool], called: int, error_rate: float) -> float:
+    """
+    The chance of a genotype call of called copies of the alternate allele from someone with copies of it, for a
+    man's X chromosome (male True) or a pair of chromosomes (see genotype_factor)
+    """
+    e = error_rate
+    if male:
+        if called >= 1:
+            return 1 - e * e if copies == 1 else e
+        return 1 - e if copies == 0 else e * e
+    off = abs(called - copies)
+    if off == 0:
+        return 1 - 2 * e if copies == 1 else 1 - e - e * e
+    return e if off == 1 else e * e
+
+
+def _passes(copies: int) -> float:
+    """The chance that a parent with this many copies passes one on (a man passes his X to every daughter)"""
+    return copies / 2
+
+
+def transmission(kind: str) -> np.ndarray:
+    """
+    P(child's state | father's state, mother's state), as an array indexed [child, father, mother].
+    For an autosomal locus all three are of kind A. On the X chromosome, the father is of kind M and the mother of
+    kind F, and the child of the kind given (M a son, F a daughter, U unknown sex).
+    """
+    if kind == 'A':
+        t = np.zeros((3, 3, 3))
+        for f in range(3):
+            for m in range(3):
+                a, b = _passes(f), _passes(m)
+                t[2, f, m] = a * b
+                t[1, f, m] = a * (1 - b) + (1 - a) * b
+                t[0, f, m] = (1 - a) * (1 - b)
+        return t
+    son = np.zeros((2, 2, 3))
+    daughter = np.zeros((3, 2, 3))
+    for h in range(2):
+        for m in range(3):
+            b = _passes(m)
+            son[1, h, m], son[0, h, m] = b, 1 - b
+            # a daughter has her father's only X, and one of her mother's two
+            daughter[h + 1, h, m] += b
+            daughter[h, h, m] += 1 - b
+    if kind == 'M':
+        return son
+    if kind == 'F':
+        return daughter
+    return np.concatenate([0.5 * son, 0.5 * daughter], axis=0)
+
+
+def default_models(modes=MODES, penetrance: float = 0.95, phenocopy: float = 0.001,
+                   allele_frequency: Optional[Dict[str, float]] = None) -> Dict[str, Model]:
+    allele_frequency = allele_frequency or {}
+    return {m: Model(m, allele_frequency.get(m), penetrance, phenocopy) for m in modes}