Package 'SNPAssayR'

Description

Scientific content is deterministic. Wall-clock/environment metadata is kept separately and does not enter ranking. All source result records are retained. No seed is required: the analytical workflows and ranking are deterministic.

Usage

assay_bundle(
  result,
  preferences = assay_preferences(),
  selected = if (length(result$candidates)) 1L else NULL
)

Arguments

Value

S3 snpassay_bundle with scientific content and separate execution record.

Examples

# Artificial coordinate fixture; three-base oligos are not laboratory designs.
s <- validate_snp(read_locus("ACGTTGAATTCAAAAAAGTC", "fixture"), 6, "G", "A")
x <- design_caps(s, restriction_enzymes()[1, , drop = FALSE],
  primer_lengths = 3, product_min = 20, product_max = 20,
  gc_range = c(0, 1), tm_range = c(-250, 100),
  max_tm_difference = 100, screening_mismatches = 0)
bundle <- assay_bundle(x)
names(bundle$scientific)

Description

Preferences are user choices, not validated biological thresholds. Ranking compares candidates within one method and locus; scores across methods are not comparable. Smaller weighted penalties are preferred, not more likely to amplify. No probability, efficiency or experimental specificity is modeled.

Usage

assay_preferences(
  weights = c(quality = 1, target = 1, copies = 1, discrimination = 1, resolution = 1,
    evidence = 1, preferences = 1),
  preferred_tm = 60,
  preferred_gc = 0.5,
  preferred_product = 200,
  available_enzymes = NULL,
  tolerance_bp = 0L,
  min_size_bp = 1L
)

Arguments

Value

A validated simple list of user preferences and fixed scale constants.

Examples

assay_preferences(weights=c(quality=2,target=1,copies=2,discrimination=1,
  resolution=1,evidence=1,preferences=1))

Description

Extract auditable coordinate features from an assay result

Usage

assay_scene(result, candidate = 1L)

Arguments

Value

S3 snpassay_scene. All coordinates are on the original locus plus axis; cleavage boundaries are explicitly distinguished from inclusive base intervals.

Examples

# Artificial coordinate fixture; three-base oligos are not laboratory designs.
s <- validate_snp(read_locus("ACGTTGAATTCAAAAAAGTC", "fixture"), 6, "G", "A")
x <- design_caps(s, restriction_enzymes()[1, , drop = FALSE],
  primer_lengths = 3, product_min = 20, product_max = 20,
  gc_range = c(0, 1), tm_range = c(-250, 100),
  max_tm_difference = 100, screening_mismatches = 0)
assay_scene(x)$features

Description

Preserves original candidate order and indices, 5-prime to 3-prime primers, plus-axis coordinates, complete fragment multiplicity and empty conditional reaction lanes. Profiles are conditional; missing bands are not genotype calls.

Usage

assay_tables(result)

Arguments

Value

Named list of data frames: primers, coordinate features, fragments, restriction sites, conditional profiles and supplied-copy screening records. The full nested result retains all detailed pair/template binding information.

Examples

# Artificial coordinate fixture; three-base oligos are not laboratory designs.
s <- validate_snp(read_locus("ACGTTGAATTCAAAAAAGTC", "fixture"), 6, "G", "A")
x <- design_caps(s, restriction_enzymes()[1, , drop = FALSE],
  primer_lengths = 3, product_min = 20, product_max = 20,
  gc_range = c(0, 1), tm_range = c(-250, 100),
  max_tm_difference = 100, screening_mismatches = 0)
assay_tables(x)$primers

Description

Extract separate theoretical size lanes from validated assay/profile objects

Usage

band_scene(result, candidate = 1L, tolerance_bp = 0L, min_size_bp = 1L)

Arguments

Value

S3 snpassay_scene with full source-linked fragments and schematic bands. Conventional ARMS preserves reaction labels; tetra includes its existing control.

Examples

profiles <- fragment_profiles(c(20, 40, 40), 100)
scene <- band_scene(profiles, min_size_bp = 30)
scene$lanes$AB$records

Description

A visible size is diagnostic only when every size in the other visible profile is farther away than tolerance. Exact duplicates are ignored only for this comparison; full fragment multisets are preserved. Distinct profiles may remain indistinguishable under the tolerance or cutoff. No gel detection, migration, intensity, calibrated resolution or genotype-call claim is made.

Usage

compare_profiles(first, second, tolerance_bp = 0L, min_size_bp = 1L)

Arguments

Value

S3 snpassay_profile_comparison with visible/full diagnostic size sets, cutoff-masked differences, parameters, warnings and an arithmetic classification.

Examples

compare_profiles(c(20,40,40),100,min_size_bp=30)$classification

Description

Both allele-specific primers end at the SNP and use the same opposing conserved common primer. Reverse terminal bases are allele complements. Optional one extra substitution is explicit and identical in both allele-specific oligos outside the terminal SNP. No mismatch-extension probability or guarantee is calculated. Profiles for AA/AB/BB assume ideal discrimination; count-based compatibility screening independently retains possible non-target/copy products.

Usage

design_arms(
  snp,
  strands = c("+", "-"),
  primer_lengths = 18:24,
  additional_mismatch_position = NULL,
  additional_mismatch_bases = c("A", "C", "G", "T"),
  product_min = 80L,
  product_max = 500L,
  gc_range = c(0.2, 0.8),
  tm_range = c(45, 75),
  max_tm_difference = 5,
  sodium_molar = 0.05,
  total_strand_molar = 5e-07,
  max_candidates = 20L,
  max_specific_checks = 1000L,
  max_pair_checks = 10000L,
  max_common_primers = 200L,
  max_common_checks = 10000L,
  screening_mismatches = 2L
)

Arguments

Value

An S3 snpassay_arms list with three-primer candidates, full conditional mature products on both original alleles, intended mismatch records, separate ideal reaction profiles, sequence-compatibility screens, controls warning, parameters, deterministic search coverage and model caveats.

References

Newton et al. (1989), doi:10.1093/nar/17.7.2503.

Examples

# Artificial geometry fixture; short oligos are not laboratory recommendations.
s <- validate_snp(read_locus("ACGAAAGTC", "fixture"), 3, "G", "T")
x <- design_arms(s,strands="+",primer_lengths=3,product_min=9,product_max=9,
  gc_range=c(0,1),tm_range=c(-250,100),max_tm_difference=100)
x$candidates[[1]]$ideal_reaction_profiles

Description

Deterministically searches flanks nearest the SNP first, with lengths ascending. Primers never cover the SNP. Each intended allele product is reconstructed from its full outer binding coordinates and completely digested. Candidates require different natural sites AND different exact fragment-size band sets. All internal sites are retained, including additional nondiagnostic sites. Search limits are explicit; a limited search cannot establish absence. These are computational candidates, not experimentally validated assays.

Usage

design_caps(
  snp,
  enzymes = restriction_enzymes(),
  primer_lengths = 18:24,
  product_min = 80L,
  product_max = 500L,
  gc_range = c(0.2, 0.8),
  tm_range = c(45, 75),
  max_tm_difference = 5,
  sodium_molar = 0.05,
  total_strand_molar = 5e-07,
  max_candidates = 20L,
  max_pair_checks = 10000L,
  max_primer_candidates = 200L,
  max_primer_checks = 10000L,
  screening_mismatches = 1L,
  min_band_difference = 0L
)

Arguments

Value

An S3 snpassay_caps list with candidate summary, detailed primer evaluations, reconstructed products, complete digests, supplied-copy risk screening, parameters, rejected-pair counts, search coverage and caveats.

Examples

# Artificial geometry fixture; short primers are not laboratory recommendations.
x <- validate_snp(read_locus("ACGTTGAATTCAAAAAAGTC", "fixture"), 6, "G", "A")
design_caps(x, restriction_enzymes()[1, ], primer_lengths=3,
  product_min=20, product_max=20, gc_range=c(0,1), tm_range=c(-250,100),
  max_tm_difference=100, screening_mismatches=0)$summary

Description

Creates a new SNP-spanning restriction site in one reconstructed allele using exactly one intentional primer substitution outside the SNP. Requires complete digest band-set difference; a local motif alone never certifies a candidate. Site-removal-only strategies, multiple substitutions, tails and overlapping primers are excluded. Search caps retain uncertainty, not proof of absence.

Usage

design_dcaps(
  snp,
  enzymes = restriction_enzymes(),
  primer_lengths = 18:24,
  primer_gaps = 0:3,
  min_mismatch_from_3prime = 2L,
  product_min = 80L,
  product_max = 500L,
  gc_range = c(0.2, 0.8),
  tm_range = c(45, 75),
  max_tm_difference = 5,
  sodium_molar = 0.05,
  total_strand_molar = 5e-07,
  max_candidates = 20L,
  max_design_checks = 10000L,
  max_pair_checks = 10000L,
  max_common_primers = 200L,
  max_common_checks = 10000L,
  screening_mismatches = 1L,
  min_band_difference = 0L
)

Arguments

Value

An S3 snpassay_dcaps list containing detailed candidates and summary, both mature products, intentional edits, full digests, original-template specificity risk screens, quality warnings, parameters and search coverage.

References

Neff et al. (1998), doi:10.1046/j.1365-313X.1998.00124.x; Neff et al. (2002), doi:10.1016/S0168-9525(02)02820-2.

Examples

# Artificial geometry fixture; short primers are not laboratory recommendations.
s <- validate_snp(read_locus("ACGGACTTCAAAGTC", "fixture"), 9, "C", "G")
design_dcaps(s,restriction_enzymes()[1,],primer_lengths=c(3,8),
  primer_gaps=0,product_min=15,product_max=15,gc_range=c(0,1),
  tm_range=c(-250,100),max_tm_difference=100)$summary

Description

Combines independently designed forward and reverse ARMS candidates. Outer primers must lie strictly outside the opposing inner primer intervals. Both assignments of alleles to inner orientations are considered. All six unordered primer pairs are screened on original alleles and supplied comparison copies. AA/AB/BB profiles assume successful control amplification and ideal allele discrimination. Size separation is a user-selected arithmetic filter, not a prediction of gel resolution. No experimental amplification is inferred. Shared product_min and product_max bounds apply to all three intended products, including the outer control. All six risk screens independently cover products from 1 to 10000 bp, including products outside the design range.

Usage

design_tetra_arms(
  snp,
  min_size_difference = 20L,
  max_candidates = 20L,
  pool_size = 20L,
  max_combinations = 1000L,
  ...
)

Arguments

Value

S3 snpassay_tetra object with four primers, three intended products, all six interaction/compatibility assessments and conditional genotype profiles.

Examples

# Artificial coordinate fixture; short oligos are not laboratory designs.
s <- validate_snp(read_locus("ACGTCAGTACGATCGTACGTTAGCGATCGA", "fixture"),
  14, "C", "A")
x <- design_tetra_arms(s, primer_lengths = 3,
  product_min = 12, product_max = 25, gc_range = c(0, 1),
  tm_range = c(-250, 150), max_tm_difference = 200,
  min_size_difference = 1, pool_size = 2, max_candidates = 1)
x$candidates[[1]]$intended_products

Description

Split a linear strand axis at complete-digest cut boundaries

Usage

digest_fragments(length_bp, cut_boundaries = integer())

Arguments

Value

An S3 snpassay_fragments list with positive fragment lengths, inclusive base intervals, internal cuts, terminal boundaries and input cuts.

Examples

digest_fragments(100, c(20,60))$fragments

Description

Draw a source-linked scientific scene using base R graphics

Usage

draw_scene(scene)

Arguments

Value

Invisibly the input scene. Uses an accessible color palette plus text, symbols and arrow orientation; band strokes have uniform width.

Examples

scene <- band_scene(fragment_profiles(c(20, 40, 40), 100))
draw_scene(scene)

Description

Uses SantaLucia (1998), Table 2 and equations 3 and 8, with a contribution from each terminal base pair, automatic self-complementarity detection, and sodium correction to entropy. The model assumes an unphosphorylated, perfectly matched DNA duplex, two-state melting and salt-independent enthalpy. No magnesium, dNTP or mismatch correction is applied. This is not a PCR annealing-temperature prescription. Sequence interaction scores are geometric screens, not free energies or amplification probabilities.

Usage

evaluate_primer(primer, sodium_molar = 0.05, total_strand_molar = 5e-07)

Arguments

Value

An S3 snpassay_primer list with length, GC fraction, Tm (Celsius), decomposed enthalpy/entropy terms, parameters, sequence scores and caveats.

References

SantaLucia J Jr (1998). doi:10.1073/pnas.95.4.1460.

Examples

evaluate_primer("ACGTTGCAACGTTGCAACGT")$tm_celsius

Description

Writes a new directory transactionally; refuses overwrite. No external zip command is required. RDS retains scientific nested data and replay request; CSVs are presentation tables, not substitutes for the complete RDS object.

Usage

export_assay(bundle, directory, figure_formats = "pdf")

Arguments

Value

Invisibly the exported absolute directory. All files get an MD5 manifest for accidental-change checking, not cryptographic authenticity.

Examples

# Artificial coordinate fixture; three-base oligos are not laboratory designs.
s <- validate_snp(read_locus("ACGTTGAATTCAAAAAAGTC", "fixture"), 6, "G", "A")
x <- design_caps(s, restriction_enzymes()[1, , drop = FALSE],
  primer_lengths = 3, product_min = 20, product_max = 20,
  gc_range = c(0, 1), tm_range = c(-250, 100),
  max_tm_difference = 100, screening_mismatches = 0)
bundle <- assay_bundle(x)
destination <- tempfile("snpassay-export-")
export_assay(bundle, destination, figure_formats = character())
list.files(destination)
unlink(destination, recursive = TRUE)

Description

Export a scene using supported local R devices

Usage

export_scene(scene, file, width = 10, height = 7, res = 300L)

Arguments

Value

Invisibly the absolute output path. Unsupported SVG/PNG devices produce an informative error; no compulsory external binary or online renderer.

Examples

scene <- band_scene(fragment_profiles(c(20, 40, 40), 100))
path <- tempfile(fileext = ".pdf")
export_scene(scene, path)
file.exists(path)
unlink(path)

Description

All coordinates refer to the supplied plus-reference sequence, one-based inclusive. A plus site has its 3-prime coordinate at end; a minus site at start. Mismatch position 1 from the 3-prime end is terminal. Ambiguous windows are reported separately and never treated as definite matches. Full-length ungapped sites only; no tails, indels or extension model.

Usage

find_binding_sites(primer, template, max_mismatches = 0L)

Arguments

Value

An S3 snpassay_binding list containing typed sites, skipped ambiguous windows, exact inputs, tolerance and screening limitations.

Examples

find_binding_sites("ACG", "ACGAAACGT")$sites

Description

For each outer base pair, reports the longest contiguous inward complementary stem that retains at least min_loop unpaired bases. Nested stems may appear separately. No bulges, mismatched stems or thermodynamic stability are modeled.

Usage

find_hairpins(primer, min_loop = 3L, min_stem = 2L)

Arguments

Value

A list with a typed stem table and explicit geometry parameters.

Examples

find_hairpins("GCGAAACGC")$stems

Description

Retains every input fragment, including repeats. AB concatenates one theoretical product profile from each allele; counts do not imply genomic dosage, DNA mass, band intensity or amplification efficiency. For digests, pass complete fragment length vectors from simulate_digest(). For PCR products, profiles must already encode the stated ideal allele-discrimination assumptions. Separate conventional ARMS reactions must remain separate and must not be concatenated into one lane.

Usage

fragment_profiles(reference_fragments, alternative_fragments)

Arguments

Value

S3 snpassay_profiles with full AA/AB/BB size lists and allele-labelled source records. Assumes an isolated biallelic locus and complete theoretical inputs.

Examples

fragment_profiles(c(20,40,40),100)$profiles

Description

Groups ascending sizes against each group's smallest member, so the group's full span cannot exceed tolerance. No transitive chaining or mobility model. Exact equal sizes comigrate in this size-only schematic; nonzero tolerance is an explicit arithmetic grouping preference, never measured gel resolution.

Usage

group_bands(sizes, tolerance_bp = 0L, min_size_bp = 1L)

Arguments

Value

S3 snpassay_bands containing full fragment records, displayed groups, hidden records and explicit parameters. Multiplicity is not intensity.

Examples

group_bands(c(20,40,40),min_size_bp=30)$bands

Description

Aligns primer A with the reverse complement of B at every overlapping offset. Offset zero aligns their first displayed bases; positive offsets shift the reverse-complemented B right. Reports contiguous complementary runs, including runs ending at A's 3-prime base and starting at reverse-complemented B's first base (B's 3-prime base). Bulges and internal gaps are not modeled.

Usage

primer_interactions(primer_a, primer_b)

Arguments

Value

A list with every offset score and maxima; sequence scores only.

Examples

primer_interactions("AAAA", "TTTT")$longest_run

Description

Filters malformed candidate geometry, primer evaluations, terminal SNPs and digest records; exclusions retain original indices and reasons. Repeated IDs are rejected. Score is the sum of weight times seven disclosed penalties; ascending original index breaks ties. It is a within-result preference index, not an assay success probability, allele specificity guarantee or cross-method comparison. Zero weights ignore a criterion but never erase its evidence.

Usage

rank_assays(result, preferences = assay_preferences())

Arguments

Value

S3 snpassay_ranking with sorted components, contributions, exclusions, weights, formula and limitations; original result is never reordered.

Examples

# Artificial coordinate fixture; three-base oligos are not laboratory designs.
s <- validate_snp(read_locus("ACGTTGAATTCAAAAAAGTC", "fixture"), 6, "G", "A")
x <- design_caps(s, restriction_enzymes()[1, , drop = FALSE],
  primer_lengths = 3, product_min = 20, product_max = 20,
  gc_range = c(0, 1), tm_range = c(-250, 100),
  max_tm_difference = 100, screening_mismatches = 0)
ranking <- rank_assays(x)
ranking$components

Description

Whitespace removal and uppercasing are explicitly recorded. IUPAC ambiguity is retained and reported; gaps and RNA bases are rejected. FASTA identifiers are the first whitespace-delimited header tokens and must be unique. All records are validated; multiple records require explicit selection. No file paths are opened implicitly: join readLines(path) with newline characters. Comparison sequences are unaligned and confer no specificity evidence. Limits are 10000 bases per sequence, 50 FASTA records and 50 comparisons.

Usage

read_locus(sequence, locus_id, record = NULL, comparison_sequences = NULL)

Arguments

Value

A simple S3 snpassay_locus list with normalized sequence, normalization provenance, ambiguity positions, comparisons and metadata.

Examples

locus <- read_locus("acgt", "artificial_example")
locus$normalization

Description

Primers are full-length, untailed and nonoverlapping, with the SNP strictly between them. The forward sequence replaces the product's left endpoint; the reverse complement of the reverse primer replaces its right endpoint. Rejects SNP coverage, ambiguous product bases and more than one substitution in total. These are conditional mature-product sequences, not observed PCR.

Usage

reconstruct_amplicon(
  snp,
  forward_primer,
  reverse_primer,
  forward_start,
  reverse_start
)

Arguments

Value

An S3 snpassay_amplicon list with both full reconstructed sequences, primer/template mismatch positions, strand-aware edits and provenance.

Examples

# Artificial geometry fixture, not laboratory primer recommendations.
s <- validate_snp(read_locus("ACGGACTTCAAAGTC", "fixture"), 9, "C", "G")
reconstruct_amplicon(s, "ACGGAATT", "GAC", 1, 13)$reference_sequence

Description

Rerun the saved design request with installed R functions

Usage

replay_assay(bundle)

Arguments

Value

Fresh assay result; no code strings are evaluated and no files/network are opened. Version mismatch fails rather than silently claiming reproducibility.

Examples

# Artificial coordinate fixture; three-base oligos are not laboratory designs.
s <- validate_snp(read_locus("ACGTTGAATTCAAAAAAGTC", "fixture"), 6, "G", "A")
x <- design_caps(s, restriction_enzymes()[1, , drop = FALSE],
  primer_lengths = 3, product_min = 20, product_max = 20,
  gc_range = c(0, 1), tm_range = c(-250, 100),
  max_tm_difference = 100, screening_mismatches = 0)
bundle <- assay_bundle(x)
identical(replay_assay(bundle), x)

Description

Twenty independently assembled entries support one palindromic recognition motif and one symmetric double-strand cut within it. Offset p means cutting after p bases from the motif's left edge on the displayed plus-reference axis. Both strand offsets use this same axis; the minus strand runs 3-prime to 5-prime on the display. No buffers, activity models or database code are copied.

Usage

restriction_enzymes()

Value

A data frame with motifs, both cut offsets, source URLs/dates and version.

Examples

restriction_enzymes()

Description

Includes overlapping matches. A palindromic motif is scanned once on the plus axis to avoid counting the same double-strand site twice. Every matched window must be canonical DNA; ambiguous template windows are separately unresolved, even at a degenerate motif position. Cuts are boundary coordinates 0..N.

Usage

restriction_sites(sequence, enzyme)

Arguments

Value

An S3 snpassay_restriction_sites list with all sites, both strand cuts, overhang metadata, ambiguity and verification scope.

Examples

restriction_sites("AGAATTCT", "EcoRI")$sites

Description

Supports the DNA IUPAC alphabet with R/Y, K/M, B/V and D/H complement pairs and self-complementary S, W and N. No case or whitespace changes are made: import unnormalized input with read_locus() first.

Usage

reverse_complement(sequence)

Arguments

Value

An uppercase character string in reverse-complement orientation.

Examples

reverse_complement("ACGTRYN")

Description

Launch the offline SNPAssayR interface

Usage

run_app(port = NULL, launch.browser = interactive())

Arguments

Value

The value returned invisibly by shiny::runApp() when the session ends.

Examples

if (interactive()) run_app()

Description

Enumerates both assignments of the two primers to inward-facing plus/minus sites. Binding intervals must not overlap. Product length is outer end minus outer start plus one. Reports full-length untailed product geometry only; no product reconstruction, indels, genome search or amplification guarantee. Limits apply separately to each template; reaching max_products is conservatively flagged as truncated even if it could coincide with the last possible product.

Usage

screen_primer_pair(
  primer1,
  primer2,
  locus,
  max_mismatches = 0L,
  product_min = 1L,
  product_max = 10000L,
  max_products = 1000L,
  max_pair_checks = 100000L
)

Arguments

Value

An S3 snpassay_pair_screen list with per-template sites/products, coverage, potential cross-amplification flags and separate specificity states.

Examples

x <- read_locus("ACGAAAAAGTC", "artificial", comparison_sequences = c(copy = "ACGAAAAAGTC"))
screen_primer_pair("ACG", "GAC", x)$potential_cross_amplification

Description

Retains all recognition sites and both strand cuts. Fragment lengths use the displayed plus-strand boundary convention, retaining multiplicity. No actual digestion efficiency, end-flank requirement, methylation or star activity is modeled. Ambiguous product bases are rejected rather than assumed digestible.

Usage

simulate_digest(sequence, enzyme)

Arguments

Value

An S3 snpassay_digest list with product, enzyme, sites, full fragments, exact size-only band set, verification status and model caveats.

Examples

simulate_digest("AGAATTCT", "EcoRI")$fragments

Description

Shiny and bslib are optional dependencies required only for the interface. Installed local assets are used; no remote service, font or genome is fetched. Analyses delegate to the same four public design APIs as console workflows. Input and design edits invalidate prior results and downloads. Example presets include a synthetic 550 bp teaching locus and short geometry fixtures; none establishes laboratory performance.

Usage

snpassay_app()

Value

A Shiny application object; run_app() starts a local session.

Examples

if (interactive() && requireNamespace("shiny", quietly=TRUE) &&
    requireNamespace("bslib", quietly=TRUE)) snpassay_app()

Description

Validate one biallelic SNP in a locus

Usage

validate_snp(locus, position, ref, alt)

Arguments

Value

A snpassay_snp list containing the locus, SNP and reconstructed reference/alternative sequences. This does not predict amplification.

Examples

validate_snp(read_locus("ACGT", "artificial_example"), 2, "C", "T")