> ## Documentation Index > Fetch the complete documentation index at: https://proto.evodesign.org/docs/llms.txt > Use this file to discover all available pages before exploring further. # Random Nucleotide Sampling > Random Nucleotide Sampling fills the masked positions of a DNA or RNA sequence with random bases drawn from an IUPAC ambiguity-code pool. Positions can be marked directly with `_` or selected automatically by a masking strategy, and the substitution alphabet is set by a single IUPAC code: `N` for any base, `R` for purines, `S` for strong pairs, and so on. It runs on CPU with no model and no external dependencies, and serves as an unbiased random baseline for sequence-design and library-generation workflows.
Random Nucleotide Sampling
Proto
**License:** Random Nucleotide Sampling is open source and free for academic and commercial use under an MIT license. Please refer to [the license](https://github.com/evo-design/proto-tools) for full terms.

Proto is not affiliated with Proto. This toolkit is open source and builds on the implementation produced by this organization. Product names, logos, and trademarks are the property of their respective owners.

evo-design/proto-tools/proto\_tools/tools/mutagenesis/random\_nucleotide
View source
Open Notebook
Open notebook
Random Nucleotide Sampling
Toolkit contributors
| Function | Description | | | -------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `run_random_nucleotide_sample()` | Sample nucleotide sequences by filling masked positions with random bases from an IUPAC substitut... | Docs Source | ## Background Random Nucleotide Sampling performs random mutagenesis at the nucleotide level: it takes a DNA or RNA sequence, determines which positions are designable, and replaces each with a base drawn uniformly from a chosen IUPAC degenerate-base pool. It generates nucleotide diversity without any learned model, the simplest possible baseline against which model-guided generators can be compared. Internally, designable positions are either the `_` characters already present in the input or, when none are present, positions chosen by the configured masking strategy. Each masked position is filled independently by drawing one base uniformly at random from the pool that the IUPAC code expands to: `N` expands to A/C/G/T, `R` to A/G, `S` to G/C, and so on. Sampling is uniform within the pool, with no frequency weighting. When the input is RNA, sampled `T` bases are converted to `U`. With a fixed seed the output is deterministic. This tool is original proto-tools code maintained by [Proto](https://github.com/evo-design/proto-tools). ## Tools
### Random Nucleotide Sampling (`random-nucleotide-sample`) Fills every masked position in each input sequence with a random base from the configured IUPAC substitution pool, returning one filled sequence per input. #### API Reference
Source DNA or RNA sequences, possibly containing `_` at positions to mutate. Accepts a single string or a list.
Source Controls which positions to mask for sampling. Position-selection method. Always `"random"` for this tier (uniform selection, no model). Exact number of positions to mask per sequence. Fraction of designable positions to mask (e.g. 0.15 for \~15%). 1-indexed positions that must NOT be masked. Applied uniformly to all sequences. IUPAC ambiguity code defining the nucleotide pool for substitutions. `"N"` = any base (ACGT); `"R"` = purines (AG); `"Y"` = pyrimidines (CT); etc. Available options: `N`, `R`, `Y`, `S`, `W`, `K`, `M`, `B`, `D`, `H`, `V` How to interpret input sequences. `"auto"` detects DNA vs RNA by presence of U; `"dna"` or `"rna"` forces the type. Available options: `auto`, `dna`, `rna` Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`. Device to run the tool on. Maximum execution time in seconds. `None` waits indefinitely. Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.
Source One sampled sequence per input, in input order. Nucleotide sequence with masked positions filled by random bases.
#### Applications Use this to build randomized nucleotide libraries: degenerate positions in promoters, ribosome binding sites, UTRs, or coding regions for directed-evolution and combinatorial-screening campaigns. It also serves as an unbiased random baseline for judging whether a model-guided generator produces better-than-chance sequences. #### Usage Tips * **`substitution_scheme` (default `N`) sets the substitution alphabet.** `N` allows any base for maximum diversity; restrict it to bias the library, for example `R` for purines (A/G), `S` for strong pairs (G/C), or `W` for weak pairs (A/T). * **`_` masks override the masking strategy.** If an input already contains `_`, exactly those positions are filled and `masking_strategy` is ignored; remove the `_` characters to let the strategy choose positions instead. * **`sequence_type` (default `auto`) controls RNA handling.** `auto` treats the sequence as RNA only when it contains `U`; force it with `dna` or `rna`. In RNA mode sampled `T` bases are written as `U`, so set `rna` explicitly when the input is fully masked. * **`masking_strategy.fixed_positions` are 1-indexed.** Positions listed there are never mutated; they are specified using 1-based indexing to match biological residue selection conventions. * **Set `seed` for reproducibility.** Sampling is otherwise nondeterministic; a fixed seed makes the filled sequences reproducible across runs.
## Toolkit Notes These apply to every Random Nucleotide Sampling tool in this toolkit (`random-nucleotide-sample`). * **Runs on CPU.** The sampler is pure Python with no model and no external dependencies; execution is near-instant. * **Deterministic only with a seed.** Without a `seed` the filled positions differ every run; set one when you need reproducible libraries. **Example notebook:** See the [full working example](https://github.com/evo-design/proto-tools/blob/47e34afa5ea240a3b406e323dc38aa5dc85f223e/proto_tools/tools/mutagenesis/random_nucleotide/examples/example.ipynb) for a copy-paste-ready walkthrough. ## Infrastructure Guides The following guides cover how to run tools efficiently and at scale. Keep a tool's model warm across calls instead of reloading it every invocation. How GPUs are allocated to tools and how to target specific devices. Fan a batch of inputs out across multiple GPUs.