codeine 0.1.0__py3-none-any.whl

codeine/translation/weights.py

@@ -0,0 +1,323 @@
+from typing import Any, Dict, Optional, Tuple, Union
+
+from codeine.translation.tables import TranslationTable
+from codeine.utils.dict import FrozenDict
+
+
+WeightDict = Dict[str, Dict[str, Union[float, int]]]
+
+
+class CodonWeights:
+    """
+    A class to store codon weights, for example codon usage information for a
+    specific organism.
+
+    Input weights are grouped by amino acid:
+
+    .. code-block:: python
+
+        {
+            'A': {'GCT': 1.0, 'GCC': 1.0, ...},
+            'R': {'CGT': 1.0, 'CGC': 1.0, ...},
+            ...
+        }
+
+    Stored weights are flat:
+
+    .. code-block:: python
+
+        {
+            'GCT': 0.25,
+            'GCC': 0.25,
+            ...
+        }
+
+    Weights are normalised per amino acid.
+    """
+
+    def __init__(
+        self,
+        weights: WeightDict,
+        rna: Optional[bool] = None,
+        table: Optional[TranslationTable] = None,
+    ) -> None:
+        """
+            Parameters
+            ----------
+            weights
+                Codon weights grouped by amino acid, for codons in the TranslationTable.
+
+                Example:
+
+                .. code-block:: python
+
+                    {
+                        'A': {'GCT': 1.0, 'GCC': 1.0, 'GCA': 1.0, 'GCG': 1.0},
+                        'R': {'CGT': 1.0, 'CGC': 1.0, 'CGA': 1.0,
+                              'CGG': 1.0, 'AGA': 1.0, 'AGG': 1.0},
+                        ...
+                    }
+
+            rna
+                Whether to use rna (default is False, i.e. use DNA).
+            """
+        self._locked = False
+
+        if table is None:
+            table = TranslationTable(rna=False if rna is None else rna)
+
+        elif rna is not None and table.rna != rna:
+            raise ValueError('table and rna specify inconsistent molecule types.')
+
+        expected_aa = set(table.aa_to_codons)
+        observed_aa = {aa.upper() for aa in weights}
+
+        missing_aa = expected_aa - observed_aa
+        if missing_aa:
+            raise ValueError(f'Missing weights for amino acid(s): {sorted(missing_aa)}')
+
+        extra_aa = observed_aa - expected_aa
+        if extra_aa:
+            raise ValueError(f'Unknown amino acid(s): {sorted(extra_aa)}')
+
+        weights_flat: Dict[str, float] = {}
+        aa_to_codons: Dict[str, Tuple[str, ...]] = {}
+
+        for aa, codon_weights in weights.items():
+            aa = aa.upper()
+
+            normalised_codon_weights = {
+                table.normalise_sequence(codon): weight
+                for codon, weight in codon_weights.items()
+            }
+
+            expected_codons = set(table.aa_to_codons[aa])
+            observed_codons = set(normalised_codon_weights.keys())
+
+            missing_codons = expected_codons - observed_codons
+            if missing_codons:
+                raise ValueError(f'Missing weights for codon(s) for amino acid {aa}: {sorted(missing_codons)}')
+
+            extra_codons = observed_codons - expected_codons
+            if extra_codons:
+                raise ValueError(f'Unknown codon(s) for amino acid {aa}: {sorted(extra_codons)}')
+
+            total = sum(normalised_codon_weights.values())
+            if total <= 0:
+                raise ValueError(f'Weights for amino acid {aa} must sum to > 0')
+
+            codons = []
+            for codon, weight in normalised_codon_weights.items():
+                if weight < 0:
+                    raise ValueError(f'Weight for codon {codon} cannot be negative')
+
+                codons.append(codon)
+                weights_flat[codon] = float(weight) / total
+
+            aa_to_codons[aa] = tuple(codons)
+
+        self.rna = table.rna
+        self.aa_to_codons = FrozenDict(aa_to_codons)
+        self.weights = FrozenDict(weights_flat)
+
+        self._locked = True
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if getattr(self, '_locked', False):
+            raise AttributeError(f'{type(self).__name__} is immutable')
+        super().__setattr__(name, value)
+
+    def __repr__(self) -> str:
+        molecule = 'RNA' if self.rna else 'DNA'
+
+        lines = [
+            f'CodonWeights',
+            f'Molecule type: {molecule}',
+            '',
+            'Weights:',
+        ]
+
+        for aa in sorted(self.aa_to_codons):
+            weights = ' '.join(
+                f'{codon}={self.weights[codon]:.3f}'
+                for codon in self.aa_to_codons[aa]
+            )
+            lines.append(f'    {aa}: {weights}')
+
+        return '\n'.join(lines)
+
+    def __getitem__(self, codon: str) -> float:
+        return self.weights[codon]
+
+    def by_aa(self, aa: str) -> Dict[str, float]:
+        """
+        Return the codon weights corresponding to a particular AA.
+
+        Parameters
+        ----------
+        aa
+            The amino acid of interest.
+
+        Returns
+        -------
+        A set of codon weights keyed by codon.
+        """
+        codons = self.aa_to_codons[aa.upper()]
+        weights = {codon: self.weights[codon] for codon in codons}
+        return weights
+
+    @classmethod
+    def uniform(cls, table: Optional[TranslationTable] = None, rna: Optional[bool] = None) -> 'CodonWeights':
+        """
+        Construct a ``CodonWeights`` object with uniform codon weights for a given translation table.
+
+        Parameters
+        ----------
+        table
+            The reference table. If blank, use the standard genetic code.
+
+        rna
+            Whether to use RNA.
+
+        Returns
+        -------
+        A uniform CodonWeights object.
+        """
+        if table is None:
+            table = TranslationTable(rna=False if rna is None else rna)
+
+        elif rna is not None and table.rna != rna:
+            raise ValueError('table and rna specify inconsistent molecule types.')
+
+        uniform_weights: WeightDict = {
+            aa: {codon: 1.0 for codon in codons}
+            for aa, codons in table.aa_to_codons.items()
+        }
+
+        return cls(uniform_weights, table=table)
+
+    @classmethod
+    def ecoli(cls, rna: Optional[bool] = None) -> 'CodonWeights':
+        """
+        Construct a ``CodonWeights`` object with codon probabilities corresponding to E. coli.
+
+        Weights are based on codon usage counts from GenScript:
+
+        https://www.genscript.com/tools/codon-frequency-table
+
+        Parameters
+        ----------
+        rna
+            Whether to use RNA.
+
+        Returns
+        -------
+        A ``CodonWeights`` object corresponding to E. Coli
+        """
+        from codeine.translation.data.weights import ECOLI_WEIGHTS
+        return cls(ECOLI_WEIGHTS, rna=rna)
+
+    @classmethod
+    def yeast(cls, rna: Optional[bool] = None) -> 'CodonWeights':
+        """
+        Construct a ``CodonWeights`` object with codon probabilities corresponding to 'yeast'.
+
+        Weights are based on codon usage counts from GenScript:
+
+        https://www.genscript.com/tools/codon-frequency-table
+
+        Parameters
+        ----------
+        rna
+            Whether to use RNA.
+
+        Returns
+        -------
+        A ``CodonWeights`` object corresponding to S. cerevisiea
+        """
+        from codeine.translation.data.weights import YEAST_WEIGHTS
+        return cls(YEAST_WEIGHTS, rna=rna)
+
+    @classmethod
+    def human(cls, rna: Optional[bool] = None) -> 'CodonWeights':
+        """
+        Construct a ``CodonWeights`` object with codon probabilities corresponding to Human.
+
+        Weights are based on codon usage counts from GenScript:
+
+        https://www.genscript.com/tools/codon-frequency-table
+
+        Parameters
+        ----------
+        rna
+            Whether to use RNA.
+
+        Returns
+        -------
+        A ``CodonWeights`` object corresponding to Human.
+        """
+        from codeine.translation.data.weights import HUMAN_WEIGHTS
+        return cls(HUMAN_WEIGHTS, rna=rna)
+
+    @classmethod
+    def mouse(cls, rna: Optional[bool] = None) -> 'CodonWeights':
+        """
+        Construct a ``CodonWeights`` object with codon probabilities corresponding to Mouse.
+
+        Weights are based on codon usage counts from GenScript:
+
+        https://www.genscript.com/tools/codon-frequency-table
+
+        Parameters
+        ----------
+        rna
+            Whether to use RNA.
+
+        Returns
+        -------
+        A ``CodonWeights`` object corresponding to Mouse.
+        """
+        from codeine.translation.data.weights import MOUSE_WEIGHTS
+        return cls(MOUSE_WEIGHTS, rna=rna)
+
+    @classmethod
+    def arabidopsis(cls, rna: Optional[bool] = None) -> 'CodonWeights':
+        """
+        Construct a ``CodonWeights`` object with codon probabilities corresponding to A. thaliana.
+
+        Weights are based on codon usage counts from GenScript:
+
+        https://www.genscript.com/tools/codon-frequency-table
+
+        Parameters
+        ----------
+        rna
+            Whether to use RNA.
+
+        Returns
+        -------
+        A ``CodonWeights`` object corresponding to Arabidopsis thaliana.
+        """
+        from codeine.translation.data.weights import ARABIDOPSIS_WEIGHTS
+        return cls(ARABIDOPSIS_WEIGHTS, rna=rna)
+
+    @classmethod
+    def drosophila(cls, rna: Optional[bool] = None) -> 'CodonWeights':
+        """
+        Construct a ``CodonWeights`` object with codon probabilities corresponding to D. melanogaster.
+
+        Weights are based on codon usage counts from GenScript:
+
+        https://www.genscript.com/tools/codon-frequency-table
+
+        Parameters
+        ----------
+        rna
+            Whether to use RNA.
+
+        Returns
+        -------
+        A ``CodonWeights`` object corresponding to Drosophila melanogaster.
+        """
+        from codeine.translation.data.weights import DROSOPHILA_WEIGHTS
+        return cls(DROSOPHILA_WEIGHTS, rna=rna)

codeine/utils/dict.py

@@ -0,0 +1,23 @@
+from collections.abc import Mapping
+from typing import Any, Iterator
+
+
+class FrozenDict(Mapping):
+    """
+    Immutable (at the shallow level) version of a dict.
+    """
+
+    def __init__(self, data: Mapping) -> None:
+        self._data = dict(data)
+
+    def __getitem__(self, key: Any) -> Any:
+        return self._data[key]
+
+    def __iter__(self) -> Iterator:
+        return iter(self._data)
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def __repr__(self) -> str:
+        return repr(self._data)

codeine/utils/display.py

@@ -0,0 +1,124 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from codeine.space.coding import ForbiddenMotif
+
+from typing import Dict, List, Sequence, Union
+
+from codeine.motifs.restriction import RestrictionSite
+
+
+CodonRestriction = Union[str, Sequence[str]]
+
+
+def format_count(n: int) -> str:
+    """
+    Format large counts in scientific notation.
+    """
+    if n < 10**9:
+        return f'{n:,}'
+
+    exponent = len(str(n)) - 1
+    mantissa = n / (10 ** exponent)
+    return f'{mantissa:.3g} × 10^{exponent}'
+
+
+def format_restrictions(
+        restrictions: Dict[int, CodonRestriction],
+        label: str = 'positions',
+        max_lines: int = 8,
+) -> List[str]:
+    """
+    Format codon restrictions or pins for repr output.
+    """
+    if not restrictions:
+        return ['    None']
+
+    items = sorted(restrictions.items())
+
+    if len(items) <= max_lines:
+        lines = []
+
+        for pos, codons in items:
+            if isinstance(codons, str):
+                codons = [codons]
+            lines.append(f'    {pos}: {" ".join(codons)}')
+
+        return lines
+
+    lines = [f'    {len(items)} {label}']
+
+    for pos, codons in items[:max_lines]:
+        if isinstance(codons, str):
+            codons = [codons]
+        lines.append(f'        {pos}: {" ".join(codons)}')
+
+    lines.append(f'        ... {len(items) - max_lines} more')
+    return lines
+
+
+def format_forbidden_motifs(
+        sequences: Sequence[str],
+        max_lines: int = 8,
+) -> List[str]:
+    """
+    Format banned sequences for repr output.
+    """
+    if not sequences:
+        return ['    None']
+
+    if len(sequences) <= max_lines:
+        return [f'    {sequence}' for sequence in sequences]
+
+    lines = [f'    {len(sequences)} sequences']
+    for sequence in sequences[:max_lines]:
+        lines.append(f'        {sequence}')
+
+    lines.append(f'        ... {len(sequences) - max_lines} more')
+    return lines
+
+
+def normalise_motif(seq: str, rna: bool) -> str:
+    """
+    Normalise a motif by uppercasing and converting to RNA/DNA as specified
+    """
+    seq = seq.upper()
+    return seq.replace('T', 'U') if rna else seq.replace('U', 'T')
+
+
+def format_forbidden_motif(motif: 'ForbiddenMotif', rna: bool) -> str:
+    """
+    Format a forbidden motif for display.
+    """
+
+    if isinstance(motif, RestrictionSite):
+        sequences = [normalise_motif(seq, rna) for seq in motif.motifs]
+        return f'{motif.name} ({", ".join(sequences)})'
+
+    return normalise_motif(motif, rna)
+
+
+def format_positions(positions) -> str:
+    """
+    Format positions nicely.
+    """
+    positions = sorted(positions)
+    if not positions:
+        return 'None'
+
+    ranges = []
+    start = prev = positions[0]
+
+    for pos in positions[1:]:
+        if pos == prev + 1:
+            prev = pos
+        else:
+            ranges.append((start, prev))
+            start = prev = pos
+
+    ranges.append((start, prev))
+
+    return ', '.join(
+        str(start) if start == end else f'{start}-{end}'
+        for start, end in ranges
+    )

codeine/utils/sampling.py

@@ -0,0 +1,90 @@
+import bisect
+import random
+
+from typing import Any, Sequence, Optional, Union
+
+
+Seedable = Union[None, int, float, str, bytes, bytearray]
+
+
+class Sampler:
+    """
+    A precomputed sampler to speed up weighted sampling.
+    """
+    def __init__(self,
+                 items: Sequence[Any],
+                 weights: Sequence[Union[int, float]] = None,
+                 seed: Optional[Seedable] = None,
+                 rng: Optional[random.Random] = None,
+                 ):
+        """
+        Constructor for the Sampler class.
+
+        Parameters
+        ----------
+        items
+            The items from which to sample.
+        weights
+            The weights assigned to the items.
+        seed
+            Seed used to initialise a random number generator on this Sampler.
+        rng
+            Pre-constructed random number generator to use for sampling.
+
+        """
+        if len(items) == 0:
+            raise ValueError('Items cannot be empty.')
+
+        if weights is None:
+            weights = [1] * len(items)
+
+        if len(items) != len(weights):
+            raise ValueError('Items and weights must have same length.')
+
+        if any(weight < 0 for weight in weights):
+            raise ValueError('Weights cannot be negative.')
+
+        if seed is not None and rng is not None:
+            raise ValueError('Provide either seed or rng, not both.')
+
+        total = sum(weights)
+        if total <= 0:
+            raise ValueError('Weights must sum to a positive number.')
+
+        self.items = tuple(items)
+        self._single = len(items) == 1
+
+        if not self._single:
+
+            if rng is None:
+                if seed is not None:
+                    rng = random.Random(seed)
+                else:
+                    rng = random.Random()
+
+            self._rng = rng
+
+            cumulative = []
+            running = 0
+
+            for weight in weights:
+                running += weight
+                cumulative.append(running / total)
+
+            self._cumulative = cumulative
+
+    def sample(self):
+        """
+        Sample the items according to the stored weights.
+        If there is only one item, just return that.
+
+        Returns
+        -------
+        The sampled item.
+        """
+        if self._single:
+            return self.items[0]
+        else:
+            r = self._rng.random()
+            i = bisect.bisect_left(self._cumulative, r)
+            return self.items[i]